You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
(sidebar): archiving a project folder hides the folder until a session appears in it #473
Archiving a project folder in the sidebar archives every session in it, and also hides the folder itself. The folder comes back, as the same project with its settings, when it is added again or when a new session appears in it. Until then it stays hidden.
The folder's archive button (public/sidebar.js:875, handler at :1087) stops then archives each top-level session of the project; the folder stays in the sidebar, empty or showing only archived sessions.
A separate mechanism hides a project: remove-project (main.js:741) adds it to global.hiddenProjects, which the scans skip (main.js:1273/:1303, :1456/:1474). Adding the project again removes it from the list (main.js:708, main.js:883).
A hidden project stays hidden when a new session is created in it: the scans skip its sessions, whatever their age.
Wanted
The folder's archive action, once its sessions are archived, hides the folder. It is the same project: same folder key and settings, nothing deleted.
The folder reappears when it is added again (existing path), or when a session appears in it after it was archived: a new transcript, or a session started from Switchboard or from the CLI in that directory.
Archived sessions stay archived when the folder reappears.
Decisions taken
The archive button opens a modal with checkboxes instead of a confirm(): archive the project's sessions (checked by default; running ones are stopped first), and disable its enabled schedules (shown only when there is one, checked by default). Hiding the folder is the action itself, not a box. Each box remembers its last state.
Archiving does not go through remove-project, which deletes the project's settings, cache, search index and schedule registration. An archived folder keeps all of them.
A disabled schedule creates no session, so it cannot bring the folder back. Schedules stay disabled when the folder reappears; whether to re-enable them is an open question in the specification.
review 1 (spec-archive-folder.review-1.md, 14 findings) and review 2 (spec-archive-folder.review-2.md, 7 findings) and review 3 (spec-archive-folder.review-3.md, 2 findings);
settled answers: Q1 = (a); Q2 = no (still to be confirmed by the owner).
1. Claims, re-measured at HEAD
#
Claim
Status
Evidence
C1
The folder archive button is at public/sidebar.js:875 and its handler at :1087
STILL PRESENT
archiveGroupBtn is created at sidebar.js:875-879 with title Archive all sessions. The handler (:1087-1114) filters on !s.parentSessionId && !s.archived (:1090) and returns early when that list is empty (:1091). It asks through confirm() (:1101), then loops stopBeforeArchive → archiveSession (:1102-1111). A failed stop calls continue (:1104-1107). VERIFIED
C2
After the archive the folder stays, empty or showing only archived sessions
STILL PRESENT
The scratchpad probe probe.js prints showArchived false groups 1 sessions [0] and showArchived true groups 1 sessions [1]. The empty group comes from the empty-directory loop (session-cache.js:532-573), and the renderer draws an empty project (sidebar.js:662). VERIFIED
C3
remove-project (main.js:741) adds the project to global.hiddenProjects
STILL PRESENT
main.js:741-760 writes the alias-qualified entry. It also runs deleteCachedFolder, deleteSearchFolder, deleteSetting('project:'+projectPath) and scheduleProjects().remove(projectPath) (:753-756). VERIFIED
C4
"The scans skip hidden projects at main.js:1273/1303 and 1456/1474"
REFUTED as worded
Those lines are get-memories (:1271-1303) and get-work-files (:1454-1474). The session list hides projects through isProjectHidden (session-cache.js:425-428), used at :468, :558 and :582. VERIFIED
C5
Adding the project again unhides it (main.js:708, main.js:883)
PARTLY REFUTED
:708-711 is add-project and matches the bare path only. :883-889 is delete-worktree's afterRemove, not a re-add. VERIFIED
C6
A new session in a hidden project stays hidden
STILL PRESENT
session-cache.js:468 and :582 skip every row of a hidden project, whatever its age. VERIFIED
Readers exist only in session-cache.js:425-582 and main.js:708,745,883-887,1273,1456. settings-panel.js:684-692 and sidebar.js:1163-1171 call removeProject; they do not read the list. The settings panel has no project list. VERIFIED
C8
Archiving a session writes nothing to disk except the DB
VERIFIED
main.js:2215-2219 calls setArchived, which is stmts.upsertArchived.run (db.js:537-539).
C9
Resuming an archived session unarchives it
REFUTED
setArchived/archiveSession is called only from main.js:2217 and sidebar.js:1110,1211,1409. VERIFIED
C10
The renderer nests worktree groups by path alone, across hosts, and never draws a worktree group outside its parent
VERIFIED
worktreeMap is keyed on parentPath only (sidebar.js:614-625); if (worktreeSet.has(project.projectPath)) continue; (:824-825); worktree groups are drawn only inside the parent loop (:925-930). A worktree group whose parent path is not in the list is therefore drawn nowhere.
2. Boundary
Item
Owner / state
This work
The folder archive verb (parent + nested worktree groups); the archived-project state; the reappearance rule; disabling schedules at archive time; the reusable checkbox modal; alias-aware worktree nesting in the sidebar (owner decisions via the coordinator, review 1 #1) (VERIFIED as relayed)
remove-project / Hide Project
Unchanged. Its callers stay settings-panel.js:684-692 and sidebar.js:1163-1171 (VERIFIED)
Whoever lands second resolves these by hand: rendererCrossFileGlobals in eslint.config.js; the script list in public/index.html near sidebar.js (:153-157); the eval list in test/dom-setup.js:144-151; ## Unreleased in CHANGELOG.md; docs/settings.md "Stored without a field" (:93-99, #374 edits :46) (VERIFIED for the locations)
Landing order
None forced: no hunk overlaps this spec's edit sites (sidebar.js:613-625,824-825,875-879,925-930,1087-1114; dialogs.js:322-327; main.js:701-711,883-889,1079-1129). The insertion lists above are textual neighbours and need a rebase, not a design change (ASSUMED)
Changing remove-project/Hide Project, including its docs claim "No file is deleted" while main.js:755 deletes project:<path>
a separate issue (VERIFIED for the gap)
An explicit "unarchive folder" control
not requested (issue body) (VERIFIED)
Re-enabling schedules on reappearance
Q2, default no (ASSUMED)
Grid view
unchanged: it renders from openSessions (grid-view.js:358,508) (VERIFIED)
Memory / Work Files tabs
unchanged: they filter on hiddenProjects only (main.js:1303,1474); an archived project's schedule files stay listed in Memory (main.js:1348-1355), which is where they are re-enabled (VERIFIED)
Slug-group archive (sidebar.js:1200-1215) and its skip-on-failure semantics
unchanged (VERIFIED as a separate handler)
folderId(projectPath) collisions for the same path on two hosts (sidebar.js:831)
pre-existing; a separate issue (ASSUMED)
Sessions created by the CLI on a remote host that the mirror has not fetched yet
not detectable at archive time; they count as new (§4.2) (VERIFIED: remote rows come only from the mirror)
4. Behaviour
4.1 State: archivedProjects
Its own settings row (db.js:731-735), not inside global: { [entry]: { archivedAt: <ISO>, knownSessionIds: [<id>...] } }. (ASSUMED design)
A bare entry matches only the local group, unlike bare hiddenProjects entries, which match every host (session-cache.js:424-428).
(ASSUMED design; VERIFIED for joinFolderKey, main.js:493)
Not hiddenProjects: remove-project deletes settings, cache, search rows and the schedule registration (C3), and a hidden project never reappears (C6). (VERIFIED)
Not inside global: global is read on every buildProjectsFromCache call (session-cache.js:434), and the settings form merges it on save (settings-panel.js:606-608). (VERIFIED)
Every read-modify-write of archivedProjects is synchronous: getSetting, the change and setSetting run with no await between them, in archive-project, get-projects, add-project and delete-worktree. (ASSUMED design; get-projects is async, main.js:1079, but its body has no await before return, VERIFIED main.js:1079-1129)
Persistence: SQLite survives a restart. Restore needs nothing new: sessionMap is filled from both getProjects(false) and getProjects(true) (app.js:1111-1120, dedup:1090-1099), and an archived folder stays in the true payload (§4.2). (VERIFIED for sessionMap)
4.2 Visibility rule
The rule is a pure function in a new module archived-projects.js, so node:test can run it without Electron:
get-projects calls applyAndPersistArchived(projects, showArchived, { getSetting, setSetting }) on the output of mergePlaceholderSessions(buildProjectsFromCache(showArchived)) (main.js:1125). That function writes setSetting('archivedProjects', …) only when cleared is non-empty. (ASSUMED design)
Steps, for each group G with entry = archivedEntry(G.remoteAlias, G.projectPath) (ASSUMED rule):
Own reappearance.G reappears when entry is in archived and G holds a session s with:
!s.parentSessionId;
!s.archived;
!knownSessionIds.includes(s.sessionId).
The entry goes into cleared.
Through a nested worktree. Let parent = worktreeParentPath(G.projectPath), from the shared module of §4.6. If parent is set, P = archivedEntry(G.remoteAlias, parent) is in archived, and G is visible after step 1 (not archived, or just cleared), then P goes into cleared too, so the parent header comes back to hold G. This also covers a worktree group that first appears after the archive. Children of a cleared parent are not cleared: they stay archived and hidden until they get their own new session.
Hidden groups. A group whose entry remains in archived is dropped when showArchived === false and kept when showArchived === true. Under Show archived the folder shows, and search finds its sessions: search renders from cachedAllProjects (app.js:641-645).
knownSessionIds is computed main-side by archive-project at archive time. It is the union of:
(a) every top-level session id of the group in mergePlaceholderSessions(buildProjectsFromCache(true)): archived rows, injected plain terminals and remote placeholders;
(b) every key of activeSessions, and its realSessionId when set, whose entry matches the group:
projectPath matches after the same normalisation;
host === alias for a remote group, no host for a local one;
this includes a Switchboard session started with --session-id that has no transcript yet (main.js:2603, entry fields at main.js:2739-2753; remote entries at main.js:2384-2398);
(c) the basenames without .jsonl of the *.jsonl files found on disk in every folder of the group, after refreshFolder of each.
The folders of the group are:
the distinct row.folder of getAllCached() rows whose projectPath and alias match the group;
plus G.folder;
each resolved with resolveFolderDir (session-cache.js:61-66) and kept only when it exists on disk. refreshFolder on a missing folder deletes its cached rows (session-cache.js:125-128).
(ASSUMED design; VERIFIED for each cited behaviour)
Why ids rather than a timestamp:
created is the first message timestamp or the file's birth time (read-session-file.js:263,280). Whether a fork copies old timestamps is NOT VERIFIABLE here.
modified grows on a resume.
The set also covers the case where the sessions box is unchecked.
Event in an archived folder
Result
New CLI session (new transcript, new id)
Reappears, entry cleared (ASSUMED rule)
New session from Switchboard, local or remote, once its transcript exists
Reappears (ASSUMED rule)
Switchboard session pending at archive time (sessions box unchecked)
Stays hidden: its id is in knownSessionIds (b). While pending, loadProjects re-injects it into a synthetic group (app.js:1124-1146), so the folder shows until the session ends or is archived (VERIFIED for the re-injection; ASSUMED for the consequence)
Switchboard session started after the archive, still pending
Shown by the renderer's synthetic group; the entry is cleared once its transcript is indexed (ASSUMED rule)
Fork running at archive time whose realSessionId is assigned only after the archive (session-transitions.js:404-415)
Reappears when that transcript is indexed. Accepted residual: the real id did not exist at archive time (VERIFIED for the late assignment)
New plain terminal in the directory
Reappears (ASSUMED rule)
Fork of an archived session
Reappears (ASSUMED rule)
Resume of an archived session
Stays hidden: known id, still archived (C9)
Resume of a session left unarchived
Stays hidden: known id (ASSUMED rule)
Unarchiving a session from Show archived
Stays hidden: known id (ASSUMED rule)
New subagent
Stays hidden: parentSessionId set (ASSUMED rule)
New session in a nested worktree
Clears the worktree's entry and its parent's (step 2) (ASSUMED rule)
A remote session on the host not yet mirrored at archive time
Counts as new once mirrored; the folder reappears (VERIFIED: remote rows come only from the mirror; ASSUMED for the consequence)
A schedule left enabled fires
Reappears: the pre-seeded transcript has a new id (schedule-runner.js:342-360); a disabled schedule creates no session (:317) (VERIFIED)
Add Project on the folder, typed with or without a trailing slash
Reappears: add-project calls clearArchivedEntry(null, projectPath), which normalises with path.resolve (§4.5) (ASSUMED design)
delete-worktree on an archived worktree path
Entry cleared (§4.5) (ASSUMED design)
Orphan subagents
Hidden with the folder, never archived (ASSUMED rule)
Cold scan (initial scan incomplete), folder not yet in cache_meta
Shown, empty, under its best-effort decoded path until its folder is indexed. The decoded path does not match the entry, and nothing is cleared, so the folder hides again once indexed. Accepted residual: do not match on the folder key to "fix" it (VERIFIED for the decode, session-cache.js:534-549; reindex drops the marker, db.js:344-352)
4.3 The checkbox modal: public/choice-dialog.js
Loading:
in public/index.html, before sidebar.js;
showChoiceDialog added to rendererCrossFileGlobals (eslint.config.js:26);
evaluated by test/dom-setup.js before sidebar.js (:144-149).
(VERIFIED for the locations)
the header of showTouchedInfo (touched-files-view.js:135-165);
the actions .new-session-actions / .new-session-cancel-btn, as in showDeleteWorktreeDialog;
with danger, the confirm button takes .delete-worktree-confirm-btn (sidebar.js:1782).
(VERIFIED for the classes)
API:
showChoiceDialog({
title,// string (textContent)
message,// string | string[] — one <p> per line (textContent)
choices,// [{ id, label, checked, rememberKey? }]
confirmLabel,// string
cancelLabel ='Cancel',
initialFocus ='confirm',// 'confirm' | 'cancel'
danger =false,// destructive styling on confirm
returnFocus,// element focused on close})// -> Promise<null | { [id]: boolean }>
Behaviour (ASSUMED design; VERIFIED for the patterns copied from touched-files-view.js:150-165):
Initial state of a box. With rememberKey, localStorage[rememberKey] ('1'/'0') when present, else checked. A box without rememberKey neither reads nor writes localStorage.
Confirm. Writes each rememberKey box; Cancel writes nothing.
Cancel. Escape, an overlay click, the close button and Cancel resolve null.
Enter. On one of the dialog's own buttons (confirm, Cancel, close), the listener calls preventDefault() then event.target.click(), so Enter does what that button does: Enter on Cancel cancels. On a checkbox it does nothing. Anywhere else in the dialog it confirms. The dialog handles it itself rather than relying on native activation, which jsdom does not perform for a key event (VERIFIED: node scratchpad/jsdom-enter-probe.js against the repository's jsdom 29.1.1 prints {"jsdom":"29.1.1","clicks":0,"cbChange":0,"checked":false,"submits":0}).
Focus. Tab and Shift+Tab cycle inside the dialog. Focus starts on initialFocus and returns to returnFocus on close.
Keydown listener. Capture phase, with stopImmediatePropagation on Escape.
Text. All text goes through textContent.
Re-entry. A call while a dialog is open resolves null.
4.4 The folder archive flow (handler at sidebar.js:1087)
Groups.groups = [parent, ...children], read from cachedAllProjects, never from the list that was rendered. During a search, refreshSidebar renders a projection: groups without a match are removed and sessions are narrowed to the matches (app.js:641-660, narrowSessionsToSearch at sidebar.js:483), and rebindSidebarEvents receives that same projection (sidebar.js:1062). (VERIFIED)
parent is the cachedAllProjects entry with the clicked header's (remoteAlias || null, projectPath).
No match: the header and the caches are out of sync. The handler calls loadProjects() and returns: no dialog, no stop, no other IPC. It never falls back to the rendered project. (ASSUMED decision, per the coordinator)
children are the cachedAllProjects entries with the same alias and worktreeParentPath(child.projectPath) === parent.projectPath (§4.6).
Why cachedAllProjects rather than cachedProjects: it is a superset. It still holds a child that is already archived, which is dropped from cachedProjects by §4.2 step 3, and the !s.archived filter in step 2 gives the same count either way.
Precedent: the sidebar already reads both caches at sidebar.js:1331; they are declared cross-file globals (eslint.config.js:88-89) and test/dom-setup.js:97-98 seeds them. (VERIFIED)
Sessions.sessions = top-level, unarchived sessions of every group in groups (the :1090 filter, applied per group), whatever the active search or filters. The early return at :1091 is removed. (ASSUMED decision)
On indexing, show alert('Switchboard is still indexing sessions. Archive the folder once indexing has finished.') and stop.
M is the number of disableable schedules.
(ASSUMED design)
Dialog.showChoiceDialog with:
title Archive <shortName>?;
message lines:
The folder is hidden from the sidebar until it is added again or a new session starts in it.;
one line per non-disableable schedule, <name> stays enabled: <reason>;
when children is non-empty, Its N worktree(s) are archived with it.;
choices:
archiveSessions: Archive the N session(s), plus — running ones are stopped first (on <aliases>) when remote sessions must be stopped; shown when N > 0; checked: true; rememberKey: 'archiveFolder.archiveSessions';
disableSchedules: Disable the M enabled schedule(s): <names>; shown when M > 0; checked: true; rememberKey: 'archiveFolder.disableSchedules';
confirmLabel: 'Archive folder', initialFocus: 'confirm', returnFocus: archiveGroupBtn.
(ASSUMED wording; boxes and defaults are owner decisions)
null: nothing happens.
All-or-nothing stop, when archiveSessions is checked:
first stopBeforeArchive every session of every group, continuing past a refusal, so that every session that can be stopped is stopped;
if any stop fails, surface each failure (surfaceStopFailure), call pollActiveSessions(); loadProjects(); and stop: no archiveSession, no archiveProject, no schedule touched;
sessions already stopped stay stopped;
only when all stops succeed, call archiveSession(id, 1) for each.
This differs on purpose from the slug-group button, which skips and goes on. (ASSUMED decision, per the coordinator)
res.failed non-empty: alert the names and errors; the folder is still hidden.
Then pollActiveSessions(); loadProjects();.
(ASSUMED design)
Every box unchecked. No stop, no archive, no schedule write; the groups are hidden; running sessions keep running, and their ids are known (§4.2 b). (owner's recommendation)
4.5 Main side
get-project-archive-plan (groups). Returns { indexing: true } while !isInitialScanComplete() (main.js:155,1090). Otherwise it returns { schedules: archivePlanForGroups(groups, { registered: scheduleProjects().list(), scan: (p) => scanSchedules(log, [p]), realpath: fs.realpathSync, parseFolderKey }) }. archivePlanForGroups lives in archived-projects.js. For each group:
a remote group, or a local one whose path.resolve(projectPath) is not in registered (the registry stores path.resolve values, schedule-runner.js:213-228), contributes nothing;
otherwise each scanned schedule whose realpath(filePath) throws (the file vanished after the scan) is dropped from the plan: it is no longer a schedule. Each remaining one is disableable only when scheduleFileUnlinked(projectPath, filePath) holds; else reason: 'linked file or directory'. That helper, scheduleFileUnlinked(projectRoot, filePath, realpath = fs.realpathSync) in schedule-runner.js, is the single rule for the plan and for disableScheduleFile: realpath(filePath) === path.join(realpath(projectRoot), '.claude', 'commands', path.basename(filePath)). It returns false on any realpath error and never throws. It means no link below the project root. A symlinked file, commands or .claude directory fails it (schedule-runner.js:307-311 reads through links). A link above the root, such as a symlinked home, ~/workspace, or macOS /tmp and /var, passes.
(VERIFIED for the sources; ASSUMED design)
Return { error: 'indexing' } while !isInitialScanComplete().
Recompute the plan. Disable only fresh.filter(s => s.disableable && disableSchedules.includes(s.filePath)), with disableScheduleFile. A schedule created after the dialog opened is not touched. A confirmed file that vanished before the re-scan is absent from it and is simply not disabled. One that vanishes between the re-scan and the write fails the helper, and disableScheduleFile returns { ok: false }, reported in failed; nothing throws. Collect { disabled: [name], failed: [{ name, error }] }.
Compute knownSessionIds per group (§4.2), refreshing the group folders first.
Synchronously read archivedProjects, set one entry per group, write it, then call notifyRendererProjectsChanged().
Never call deleteSetting, deleteCachedFolder, deleteSearchFolder or scheduleProjects().remove.
(ASSUMED design)
disableScheduleFile(filePath, { projectRoot, rewrite } = {}) in schedule-runner.js, exported with scheduleFileUnlinked (:551). It writes the mechanism the scheduler already reads: meta.enabled === 'false' (:317), documented at docs/automation.md:42. Its only existing writer is the creator template (schedule-ipc.js:43). (VERIFIED)
Refuses ({ ok: false, error }) unless scheduleFileUnlinked(projectRoot, filePath): the same rule as the plan, so a schedule offered as disableable is never refused for a link. archive-project passes the group's projectPath as projectRoot.
Default rewrite(content) walks the front-matter lines with the same state machine as parseFrontmatter (schedule-runner.js:14-48, currentKey logic) and replaces every line the parser reads as the top-level enabled key with enabled: false. A probe showed that the parser reads enabled: true as top-level when no block key is open ({"enabled":"true",…}), and keeps the last of duplicate lines. When no line is read as enabled, it inserts enabled: false as the first front-matter line. That covers enabled: true\r, which the parser ignores (probe: {"cron":"* * * * *"}). (VERIFIED, probe via node -e on parseFrontmatter)
Post-check before writing: parseFrontmatter(next).meta.enabled === 'false', meta.cron unchanged and body unchanged. Otherwise it refuses and leaves the file as is.
Atomic write: a temp file in the same directory with the original mode, then rename.
The file is in the user's repository (<project>/.claude/commands/), so it can leave a working-tree diff in a tracked file. The dialog names the schedules. (VERIFIED for the location)
add-project (main.js:701): clearArchivedEntry(getSetting, setSetting, null, projectPath), with path.resolve on both sides. The hiddenProjects unhide at :708 is unchanged. (ASSUMED design)
session-cache.js is unchanged, so the ctx.db allow-list (main.js:480-485, test/main-ctx-db-wiring.test.js) needs no edit. (VERIFIED for the guard)
4.6 Worktree nesting, shared and alias-aware
New public/worktree-nesting.js, exported to both sides with the module.exports guard used by public/setting-defaults.js:37-38 (required by main.js:74). (VERIFIED for the precedent)
It exports SIDEBAR_WORKTREE_RE (the regex now local at sidebar.js:614, /^(.+?)\/\.claude\/worktrees\/([^/]+)\/?$/), worktreeParentPath(projectPath) and worktreeName(projectPath).
It is required by archived-projects.js and loaded before sidebar.js in index.html and dom-setup.js.
The main-side WORKTREE_PATH_RE (main.js:819, three forms) is not used here: the rule must follow what the sidebar draws. (VERIFIED for the difference)
worktreeMap and worktreeSet are keyed on (remoteAlias || '') + '|' + path;
a worktree group is nested, and skipped at top level, only when a group with the same alias and the parent path is in projects;
otherwise it is drawn as an ordinary top-level group.
This removes the cross-host nesting (C10), so a local parent's archive never covers another host's worktree. A worktree group with no listed parent was drawn nowhere and is now visible. (ASSUMED design; VERIFIED for the current behaviour)
two IPC handlers; add-project, delete-worktree, get-projects
schedule-runner.js
disableScheduleFile, exported
preload.js
two bridges
public/sidebar.js
archive handler :1087-1114; button title Archive folder (:877); alias-aware nesting
public/dialogs.js
knownRemotePaths reads cachedAllProjects (:322-327), so an archived remote path is still suggested in the remote launch dialog (review #14)
public/index.html, test/dom-setup.js
load worktree-nesting.js and choice-dialog.js before sidebar.js
eslint.config.js
showChoiceDialog, SIDEBAR_WORKTREE_RE, worktreeParentPath and worktreeName in rendererCrossFileGlobals (:26). A producer block for public/worktree-nesting.js, modelled on public/subagent-timing.js's block (eslint.config.js:512-535): globals.browser, module: 'writable', and its three globals set to 'off', so no-undef accepts the module.exports footer and no-redeclare does not flag the definitions. choice-dialog.js needs no block: like utils.js, which produces escapeHtml (:104), it has no footer (VERIFIED for the blocks)
public/style.css
checkbox rows in .modal-dialog, if needed
All rows are ASSUMED design, at locations VERIFIED above.
6. Docs to update
docs/session-browser.md (VERIFIED for the locations):
header-button row :51;
"Pin and archive" :149-158: the dialog, the two boxes, all-or-nothing on stop failures, the reappearance rule, Show archived reveals the folder;
beside Hide Project :62-64: archive versus hide;
the "Sessions run in a git worktree" paragraph (:66-67): worktree groups of another host, or without a listed repository, show at top level.
docs/automation.md:42 and :148: archiving a folder writes enabled: false into its schedule files; they stay disabled when the folder reappears (Q2); linked schedule files are not changed. (VERIFIED for the locations)
docs/settings.md "Stored without a field" (:93-99): archivedProjects. (VERIFIED for the location)
.ai/contexts/session-cache.md: an "Archived projects" section (rule, snapshot sources, step 2, differences from hiddenProjects); the new tests in "If you change this, also check" (:1505). (ASSUMED placement)
.ai/contexts/schedule-runner.md: disableScheduleFile and its single caller. (ASSUMED)
CHANGELOG.md## Unreleased, written to the rule in docs/changelog.md (VERIFIED for the rule):
### New: - **Archive folder** on a project header opens a dialog that archives the folder's sessions and disables its enabled schedules, each optional, and hides the folder with its worktrees. The folder comes back, with its settings, when you add it again or a new session starts in it. (#473)
### Fixed: - Worktree folders from another host, or whose repository is not listed, show in the sidebar instead of being nested under the wrong folder or not shown at all. (#473)
7. Acceptance criteria
Each file passes with node --test <file> (0 failed); the gate is task check (Taskfile.yamlcheck: deps: [test, lint]) with 0 errors. (VERIFIED for the Taskfile)
None of the mutations was run, because the code does not exist yet.
Fixture rules (the CI matrix runs ubuntu-latest and windows-2022, Node 20 and 22, .github/workflows/test.yml:91-97) (VERIFIED):
Every archivedProjects key in a fixture is built through archivedEntry(alias, path), never written as a literal. On Windows path.resolve('/r') is D:\r on a runner whose current drive is D:, so a literal '/r' key never matches.
Every test that creates a symlink (A18 symlink sub-case, B4, B10, B12) uses the repository's guard try { fs.symlinkSync(...) } catch { t.skip('cannot create a symlink on this machine') } (test/scan-md-files.test.js:30-33, test/run-schedule-now-target.test.js:71). (VERIFIED)
Seeding: every migrated test and D1-D13 set ctx.window.cachedAllProjects to the fixtures they pass to renderProjects. Without it the lookup of §4.4 step 1 finds no match and the handler aborts (D15). test/dom-setup.js:97-98 seeds []. (VERIFIED for the seed)
Migrated tests:
They drive the modal through a helper answerChoiceDialog(ctx, { confirm = true, uncheck = [] }) in test/dom-setup.js. It waits for .modal-overlay, unticks the named boxes and clicks the confirm or cancel button.
Their API stubs return { schedules: [] } for getProjectArchivePlan.
dom-sidebar-stop-before-archive.test.js:133,151 (alias named or not);
:166, whose assertion changes from "the other proceeds" to: stopSession called for s2 although r1 was refused first; no archiveSession; no archiveProject. Mutation: return at the first refusal (it leaves s2 running).
(VERIFIED for the use of confirm and the Proxy at dom-project-archive-all.test.js:9-19)
A. test/archived-projects.test.js (pure)
#
Case
Pass
Mutation that reddens only it
A1
Archived local group, only known ids, showArchived=false
absent, cleared=[]
keep the group in the drop branch
A2
Same, showArchived=true
present
drop regardless of showArchived
A3
New top-level, unarchived id
present, cleared=[entry]
omit cleared.push(entry)
A4
Known id with archived: 0
absent
drop the !known.has(id) condition
A5
New id with parentSessionId
absent
drop the !s.parentSessionId condition
A6
New id with archived: 1
absent
drop the !s.archived condition
298
Entry planificator::/srv/x; groups local, planificator, otherhost at /srv/x
planificator absent, the other two present
compute the entry from projectPath only
A8
Bare entry /srv/x; remote planificator/srv/x
remote present
match a bare entry on every host
A9
knownIdsForGroup: archived rows, a terminal, a placeholder, a subagent
all top-level ids, no subagent id
filter archived rows out
A10
knownIdsForGroup: an activeSessions entry of the group with no row, and one with realSessionId
both ids included
omit the activeSessions source
A11
knownIdsForGroup: diskIds holding an id with no row
included
omit the diskIds source
A12
Parent /r and child /r/.claude/worktrees/w archived; the child gets a new id
both present, cleared holds both
remove step 2
A13
Parent /r archived; a new, never-archived child group /r/.claude/worktrees/w with a session
parent present, cleared
apply step 2 only to children with an entry
A14
Local parent /r archived; visible child at planificator/r/.claude/worktrees/w
parent absent
ignore the alias in step 2
A15
Parent cleared through its own new id; archived child with known ids only
child absent
clear children when a parent is cleared
A16
applyAndPersistArchived with one reappearing group
setSetting('archivedProjects', …) called once without that entry; with nothing cleared, not called
delete the setSetting call
A17
clearArchivedEntry(null, '/srv/x/') on stored /srv/x
entry removed
compare without path.resolve
A18
archivePlanForGroups: remote group; unregistered local; registered given as /p/; symlinked commands dir; plain file
[], [], listed, disableable:false with a reason, disableable:true
drop the alias check / path.resolve / the realpath check (one mutation per sub-assertion, each in its own test())
A19
scheduleFileUnlinked with a realpath stub that throws ENOENT; archivePlanForGroups whose stub throws for one of two scanned files
helper returns false, does not throw; the plan lists only the other file
let the helper propagate the error
B. test/schedule-disable.test.js (tmp dir)
#
Case
Pass
Mutation
B1
enabled: true
enabled: false, other bytes unchanged, scanSchedules(null,[dir]) is []
write enabled: true
B2
No enabled line
inserted first; scanSchedules is []
remove the insert branch
B3
cli: block with an indented enabled: x
indented line unchanged, top-level line inserted
treat every ^\s*enabled: line as top-level
B4
Symlinked file
{ ok: false }, target unchanged, link still a link
remove the realpath check
B5
Mode 0o640
mode unchanged
create the temp file without the mode
B6
enabled: true with no open block
scanSchedules is []
match only unindented lines
B7
Two top-level enabled lines, last true
scanSchedules is []
replace the first line only
B8
enabled: true\r inside LF front matter
scanSchedules is []
replace that line instead of inserting
B9
Inode before and after
inode differs
writeFileSync in place
B10
Symlinked commands directory
{ ok: false }, the linked target unchanged
compare realpath of the directory only
B11
Injected rewrite returning the content unchanged
{ ok: false }, file unchanged
remove the post-check
B12
Project reached through a linked ancestor (<tmp>/link -> <tmp>/real, project <tmp>/link/p)
disabled, scanSchedules is []
replace the rule with realpath(filePath) !== path.resolve(filePath)
C. test/dom-choice-dialog.test.js
#
Case
Pass
Mutation
C1
Confirm with box b unticked
{a: true, b: false}; localStorage['k.b'] === '0'
skip setItem on confirm
C2
Reopen
b starts unchecked
ignore rememberKey at init
C3
Escape
null, overlay gone, focus on returnFocus, localStorage unchanged
drop returnFocus.focus()
C4
Escape and a document listener registered by the test
listener not called
drop stopImmediatePropagation
C5
Label containing <img onerror>
no img in the dialog
label through innerHTML
C6
Tab from the last control
focus on the first
drop the Tab wrap
C7
Box without rememberKey, confirmed unchecked
localStorage.length unchanged; reopen starts on checked
persist under id
C8
keydown Enter with focus on Cancel
resolves null, no box written
treat Enter on any button as confirm
C9
initialFocus: 'cancel', danger: true
Cancel focused; confirm has .delete-worktree-confirm-btn
ignore initialFocus
C10
message: ['l1', 'l2']
two <p>
join the lines into one node
D. test/dom-project-archive-folder.test.js
#
Case
Pass
Mutation
D1
Both boxes, M=1
archiveSession for ['s-top-1'], then one archiveProject([{projectPath, folderKey}], {disableSchedules: ['/p/.claude/commands/schedule-a.md']})
Parent /r and same-alias child /r/.claude/worktrees/w
archiveProject receives both groups; the child's session archived
pass [project] only
D10
Stop refused in the child
nothing archived in either group; the parent's running session was stopped too
stop-check the parent's sessions only
D11
Plan {indexing: true}
alert called, no dialog, no further IPC
ignore plan.indexing
D12
Local /r and planificator/r/.claude/worktrees/w
the worktree drawn at top level, not inside /r's group
key worktreeMap on path only
D13
/r/.claude/worktrees/w with no /r group
drawn at top level
put every regex match in worktreeSet
D14
cachedAllProjects holds parent /r (sessions a, b, unarchived) and child /r/.claude/worktrees/w (session c); the rendered list is the search projection of /r narrowed to a, with no child
the label counts 3; archiveSession for a, b, c; archiveProject receives both groups
read groups and sessions from the rendered list
D15
cachedAllProjects is []; the rendered header is /r
no dialog, loadProjects called, no other IPC (no getProjectArchivePlan, stopSession or archiveSession)
fall back to the rendered project when nothing matches
E. test/archive-project-wiring.test.js (source text of main.js/preload.js/dialogs.js, the pattern of test/remove-project-folder-key.test.js)
#
Case
Pass
Mutation
E1
archive-project body
none of deleteSetting(, deleteCachedFolder(, deleteSearchFolder(, .remove(
add deleteSetting('project:' + …)
E2
add-project body
calls clearArchivedEntry(
remove it
E3
get-projects body
applyAndPersistArchived( with showArchived
pass false
E4
preload.js
both bridges forward groups and opts
drop opts
E5
delete-worktree body
calls clearArchivedEntry(
remove it
E6
archive-project and get-project-archive-plan bodies
call isInitialScanComplete()
remove the check in archive-project
E7
archive-project body
no await between getSetting('archivedProjects') and setSetting('archivedProjects'
insert an await
E8
dialogs.jsknownRemotePaths
reads cachedAllProjects
revert to cachedProjects
F. Static gate
npx eslint . gives 0 errors. Mutation: remove showChoiceDialog from rendererCrossFileGlobals. no-undef: error applies to public/**/*.js (eslint.config.js:360-371). (VERIFIED)
G. Live check
task test-pr PR=<n> (docs/testing-a-pr.md):
archive a folder with a schedule, restart: still hidden, the schedule file reads enabled: false;
run claude in the directory: the folder reappears, archived sessions under Show archived;
Enter on Cancel cancels.
(ASSUMED; needs the isolated instance)
8. Constraints the implementer inherits
Copied from .ai/shared-guidelines.md (VERIFIED):
"Default value for a setting | SETTING_DEFAULTS in setting-defaults.js — never a literal at the call site". The box defaults are UI state in localStorage, not settings (ASSUMED).
"Escape HTML in renderer | escapeHtml() (cross-file global)".
"Renderer tests use jsdom via test/dom-setup.js + vm.runInContext to evaluate public/*.js in isolation."
"Pitfall: installSpies: false is required when the eval defines functions you also spy on — function declarations from eval overwrite property spies."
Must not break (VERIFIED as existing tests): test/session-cache-hidden-alias.test.js, test/remove-project-folder-key.test.js, test/main-ctx-db-wiring.test.js, test/schedule-catch-up.test.js, test/dom-archived-parent-subagents.test.js, test/session-cache-projects.test.js, test/build-projects-cold-scan-fallback.test.js, test/dom-file-panel-touched.test.js, test/derive-project-path.test.js.
Conventions: package.jsonengines.node >=20 <23; test: node scripts/run-tests.js; pretest: npm run lint. No pyproject.toml applies. (VERIFIED)
9. Whether this fits one go
It fits one dispatch at the edge:
3 new modules;
6 edited production files;
5 new test files and 2 migrated ones.
Two things force a second round: the review loop, and §7.G, which needs an isolated live instance for focus, styling and a real claude run. If it has to be split, the cut is the alias-aware nesting with D12-D13, which can land first on its own. (ASSUMED)
10. Open questions
Q2 (owner). Do schedules disabled by the archive come back on when the folder reappears? Default in this spec: no. They stay enabled: false, and the user re-enables them from the file, which Memory lists (main.js:1348-1355). A CLI session reappearing must not silently restart cron jobs, and the file does not record which false came from the archive. A yes needs archivedProjects[entry].disabledSchedules and a write on reappearance. (ASSUMED; pending owner confirmation)
Settled:
Q1 = (a), written into §4.2 step 2, §4.4 steps 1-6 and §4.6;
the settings panel has no project list (C7);
archiving writes no transcript (C8);
resume does not unarchive (C9);
the grid ignores the project list;
search sees archived folders through cachedAllProjects.
(VERIFIED)
Activity
jbr-sekoia commentedon Oct 5, 2026
Spec: archiving a project folder hides the folder (#473)
/home/jean-baptiste-renard/workspace/tools/switchboard(forkdevsuitup/switchboard), branchmain375decbf8c14543b7f8ee7783da85618116cc7de.agents/(VERIFIED,git status --short)remove-project; archive disables the project's enabled schedules; a reusable checkbox modal replacesconfirm(); project delete is (sidebar): delete a project folder, choosing what goes with it #474;spec-archive-folder.review-1.md, 14 findings) and review 2 (spec-archive-folder.review-2.md, 7 findings) and review 3 (spec-archive-folder.review-3.md, 2 findings);1. Claims, re-measured at HEAD
public/sidebar.js:875and its handler at:1087archiveGroupBtnis created atsidebar.js:875-879with titleArchive all sessions. The handler (:1087-1114) filters on!s.parentSessionId && !s.archived(:1090) and returns early when that list is empty (:1091). It asks throughconfirm()(:1101), then loopsstopBeforeArchive→archiveSession(:1102-1111). A failed stop callscontinue(:1104-1107). VERIFIEDprobe.jsprintsshowArchived false groups 1 sessions [0]andshowArchived true groups 1 sessions [1]. The empty group comes from the empty-directory loop (session-cache.js:532-573), and the renderer draws an empty project (sidebar.js:662). VERIFIEDremove-project(main.js:741) adds the project toglobal.hiddenProjectsmain.js:741-760writes the alias-qualified entry. It also runsdeleteCachedFolder,deleteSearchFolder,deleteSetting('project:'+projectPath)andscheduleProjects().remove(projectPath)(:753-756). VERIFIEDmain.js:1273/1303and1456/1474"get-memories(:1271-1303) andget-work-files(:1454-1474). The session list hides projects throughisProjectHidden(session-cache.js:425-428), used at:468,:558and:582. VERIFIEDmain.js:708,main.js:883):708-711isadd-projectand matches the bare path only.:883-889isdelete-worktree'safterRemove, not a re-add. VERIFIEDsession-cache.js:468and:582skip every row of a hidden project, whatever its age. VERIFIEDhiddenProjects: settings panel, worktree removal, search, heatmap, schedule runner, restore, remote hostssession-cache.js:425-582andmain.js:708,745,883-887,1273,1456.settings-panel.js:684-692andsidebar.js:1163-1171callremoveProject; they do not read the list. The settings panel has no project list. VERIFIEDmain.js:2215-2219callssetArchived, which isstmts.upsertArchived.run(db.js:537-539).setArchived/archiveSessionis called only frommain.js:2217andsidebar.js:1110,1211,1409. VERIFIEDworktreeMapis keyed onparentPathonly (sidebar.js:614-625);if (worktreeSet.has(project.projectPath)) continue;(:824-825); worktree groups are drawn only inside the parent loop (:925-930). A worktree group whose parent path is not in the list is therefore drawn nowhere.2. Boundary
remove-project/ Hide Projectsettings-panel.js:684-692andsidebar.js:1163-1171(VERIFIED)showChoiceDialogwithinitialFocus: 'cancel'anddanger: true(§4.3) (ASSUMED, per the coordinator)(restore), DIRTY, CHANGES_REQUESTED)public/sidebar.js@@ -685, -725;eslint.config.js@@ -71 (insiderendererCrossFileGlobals);public/style.css@@ -1005;.ai/contexts/session-cache.md@@ -98;public/settings-panel.js@@ -247;public/app.js;CHANGELOG.md; tests (VERIFIED,gh pr diff 441file and hunk list)(agents), DIRTY)eslint.config.js@@ -330 (rendererCrossFileGlobals) and @@ -372 (renderer block);public/index.html@@ -75 and @@ -155 (script list besidesidebar.js);test/dom-setup.js@@ -171 (eval list);preload.js@@ -20, -125;main.js@@ -1690, -2328..-2936;public/sidebar.js@@ -1493;public/dialogs.js@@ -585;public/style.css(11 hunks, none at 2135-2170);public/settings-panel.js@@ -42;public/stop-session-ui.js;docs/settings.md@@ -46;CHANGELOG.md(VERIFIED,gh pr diff 374)rendererCrossFileGlobalsineslint.config.js; the script list inpublic/index.htmlnearsidebar.js(:153-157); the eval list intest/dom-setup.js:144-151;## UnreleasedinCHANGELOG.md;docs/settings.md"Stored without a field" (:93-99, #374 edits:46) (VERIFIED for the locations)sidebar.js:613-625,824-825,875-879,925-930,1087-1114;dialogs.js:322-327;main.js:701-711,883-889,1079-1129). The insertion lists above are textual neighbours and need a rebase, not a design change (ASSUMED)3. Scope
remove-project/Hide Project, including its docs claim "No file is deleted" whilemain.js:755deletesproject:<path>openSessions(grid-view.js:358,508) (VERIFIED)hiddenProjectsonly (main.js:1303,1474); an archived project's schedule files stay listed in Memory (main.js:1348-1355), which is where they are re-enabled (VERIFIED)sidebar.js:1200-1215) and its skip-on-failure semanticsfolderId(projectPath)collisions for the same path on two hosts (sidebar.js:831)4. Behaviour
4.1 State:
archivedProjectssettingsrow (db.js:731-735), not insideglobal:{ [entry]: { archivedAt: <ISO>, knownSessionIds: [<id>...] } }. (ASSUMED design)entryisarchivedEntry(alias, projectPath):path.resolve(projectPath);joinFolderKey(alias, path.posix.normalize(projectPath).replace(/\/$/, '')).hiddenProjectsentries, which match every host (session-cache.js:424-428).(ASSUMED design; VERIFIED for
joinFolderKey,main.js:493)hiddenProjects:remove-projectdeletes settings, cache, search rows and the schedule registration (C3), and a hidden project never reappears (C6). (VERIFIED)global:globalis read on everybuildProjectsFromCachecall (session-cache.js:434), and the settings form merges it on save (settings-panel.js:606-608). (VERIFIED)archivedProjectsis synchronous:getSetting, the change andsetSettingrun with noawaitbetween them, inarchive-project,get-projects,add-projectanddelete-worktree. (ASSUMED design;get-projectsisasync,main.js:1079, but its body has noawaitbeforereturn, VERIFIEDmain.js:1079-1129)sessionMapis filled from bothgetProjects(false)andgetProjects(true)(app.js:1111-1120,dedup:1090-1099), and an archived folder stays in thetruepayload (§4.2). (VERIFIED forsessionMap)4.2 Visibility rule
The rule is a pure function in a new module
archived-projects.js, so node:test can run it without Electron:get-projectscallsapplyAndPersistArchived(projects, showArchived, { getSetting, setSetting })on the output ofmergePlaceholderSessions(buildProjectsFromCache(showArchived))(main.js:1125). That function writessetSetting('archivedProjects', …)only whenclearedis non-empty. (ASSUMED design)Steps, for each group
Gwithentry = archivedEntry(G.remoteAlias, G.projectPath)(ASSUMED rule):Greappears whenentryis inarchivedandGholds a sessionswith:!s.parentSessionId;!s.archived;!knownSessionIds.includes(s.sessionId).The entry goes into
cleared.parent = worktreeParentPath(G.projectPath), from the shared module of §4.6. Ifparentis set,P = archivedEntry(G.remoteAlias, parent)is inarchived, andGis visible after step 1 (not archived, or just cleared), thenPgoes intoclearedtoo, so the parent header comes back to holdG. This also covers a worktree group that first appears after the archive. Children of a cleared parent are not cleared: they stay archived and hidden until they get their own new session.archivedis dropped whenshowArchived === falseand kept whenshowArchived === true. Under Show archived the folder shows, and search finds its sessions: search renders fromcachedAllProjects(app.js:641-645).knownSessionIdsis computed main-side byarchive-projectat archive time. It is the union of:mergePlaceholderSessions(buildProjectsFromCache(true)): archived rows, injected plain terminals and remote placeholders;activeSessions, and itsrealSessionIdwhen set, whose entry matches the group:projectPathmatches after the same normalisation;host === aliasfor a remote group, nohostfor a local one;--session-idthat has no transcript yet (main.js:2603, entry fields atmain.js:2739-2753; remote entries atmain.js:2384-2398);.jsonlof the*.jsonlfiles found on disk in every folder of the group, afterrefreshFolderof each.The folders of the group are:
row.folderofgetAllCached()rows whose projectPath and alias match the group;G.folder;resolveFolderDir(session-cache.js:61-66) and kept only when it exists on disk.refreshFolderon a missing folder deletes its cached rows (session-cache.js:125-128).(ASSUMED design; VERIFIED for each cited behaviour)
Why ids rather than a timestamp:
createdis the first message timestamp or the file's birth time (read-session-file.js:263,280). Whether a fork copies old timestamps is NOT VERIFIABLE here.modifiedgrows on a resume.knownSessionIds(b). While pending,loadProjectsre-injects it into a synthetic group (app.js:1124-1146), so the folder shows until the session ends or is archived (VERIFIED for the re-injection; ASSUMED for the consequence)realSessionIdis assigned only after the archive (session-transitions.js:404-415)parentSessionIdset (ASSUMED rule)schedule-runner.js:342-360); a disabled schedule creates no session (:317) (VERIFIED)add-projectcallsclearArchivedEntry(null, projectPath), which normalises withpath.resolve(§4.5) (ASSUMED design)delete-worktreeon an archived worktree pathcache_metasession-cache.js:534-549; reindex drops the marker,db.js:344-352)4.3 The checkbox modal:
public/choice-dialog.jspublic/index.html, beforesidebar.js;showChoiceDialogadded torendererCrossFileGlobals(eslint.config.js:26);test/dom-setup.jsbeforesidebar.js(:144-149).(VERIFIED for the locations)
.modal-overlay/.modal-dialog(style.css:2144-2166);showTouchedInfo(touched-files-view.js:135-165);.new-session-actions/.new-session-cancel-btn, as inshowDeleteWorktreeDialog;danger, the confirm button takes.delete-worktree-confirm-btn(sidebar.js:1782).(VERIFIED for the classes)
touched-files-view.js:150-165):rememberKey,localStorage[rememberKey]('1'/'0') when present, elsechecked. A box withoutrememberKeyneither reads nor writeslocalStorage.rememberKeybox; Cancel writes nothing.null.preventDefault()thenevent.target.click(), so Enter does what that button does: Enter on Cancel cancels. On a checkbox it does nothing. Anywhere else in the dialog it confirms. The dialog handles it itself rather than relying on native activation, which jsdom does not perform for a key event (VERIFIED:node scratchpad/jsdom-enter-probe.jsagainst the repository's jsdom 29.1.1 prints{"jsdom":"29.1.1","clicks":0,"cbChange":0,"checked":false,"submits":0}).initialFocusand returns toreturnFocuson close.stopImmediatePropagationon Escape.textContent.null.4.4 The folder archive flow (handler at
sidebar.js:1087)groups = [parent, ...children], read fromcachedAllProjects, never from the list that was rendered. During a search,refreshSidebarrenders a projection: groups without a match are removed and sessions are narrowed to the matches (app.js:641-660,narrowSessionsToSearchatsidebar.js:483), andrebindSidebarEventsreceives that same projection (sidebar.js:1062). (VERIFIED)parentis thecachedAllProjectsentry with the clicked header's(remoteAlias || null, projectPath).loadProjects()and returns: no dialog, no stop, no other IPC. It never falls back to the renderedproject. (ASSUMED decision, per the coordinator)childrenare thecachedAllProjectsentries with the same alias andworktreeParentPath(child.projectPath) === parent.projectPath(§4.6).cachedAllProjectsrather thancachedProjects: it is a superset. It still holds a child that is already archived, which is dropped fromcachedProjectsby §4.2 step 3, and the!s.archivedfilter in step 2 gives the same count either way.sidebar.js:1331; they are declared cross-file globals (eslint.config.js:88-89) andtest/dom-setup.js:97-98seeds them. (VERIFIED)sessions= top-level, unarchived sessions of every group ingroups(the:1090filter, applied per group), whatever the active search or filters. The early return at:1091is removed. (ASSUMED decision)plan = await window.api.getProjectArchivePlan(groups.map(g => ({ projectPath: g.projectPath, folderKey: g.folder })))returns either{ indexing: true }or{ schedules: [{ name, filePath, disableable, reason? }] }.indexing, showalert('Switchboard is still indexing sessions. Archive the folder once indexing has finished.')and stop.(ASSUMED design)
showChoiceDialogwith:Archive <shortName>?;The folder is hidden from the sidebar until it is added again or a new session starts in it.;<name> stays enabled: <reason>;childrenis non-empty,Its N worktree(s) are archived with it.;archiveSessions:Archive the N session(s), plus— running ones are stopped first (on <aliases>)when remote sessions must be stopped; shown when N > 0;checked: true;rememberKey: 'archiveFolder.archiveSessions';disableSchedules:Disable the M enabled schedule(s): <names>; shown when M > 0;checked: true;rememberKey: 'archiveFolder.disableSchedules';confirmLabel: 'Archive folder',initialFocus: 'confirm',returnFocus: archiveGroupBtn.(ASSUMED wording; boxes and defaults are owner decisions)
null: nothing happens.archiveSessionsis checked:stopBeforeArchiveevery session of every group, continuing past a refusal, so that every session that can be stopped is stopped;surfaceStopFailure), callpollActiveSessions(); loadProjects();and stop: noarchiveSession, noarchiveProject, no schedule touched;archiveSession(id, 1)for each.This differs on purpose from the slug-group button, which skips and goes on. (ASSUMED decision, per the coordinator)
res = await window.api.archiveProject(groupsArg, { disableSchedules: result.disableSchedules ? plan.schedules.filter(s => s.disableable).map(s => s.filePath) : [] }).res.error === 'indexing': same alert as step 3.res.failednon-empty:alertthe names and errors; the folder is still hidden.pollActiveSessions(); loadProjects();.(ASSUMED design)
4.5 Main side
get-project-archive-plan (groups). Returns{ indexing: true }while!isInitialScanComplete()(main.js:155,1090). Otherwise it returns{ schedules: archivePlanForGroups(groups, { registered: scheduleProjects().list(), scan: (p) => scanSchedules(log, [p]), realpath: fs.realpathSync, parseFolderKey }) }.archivePlanForGroupslives inarchived-projects.js. For each group:path.resolve(projectPath)is not inregistered(the registry storespath.resolvevalues,schedule-runner.js:213-228), contributes nothing;realpath(filePath)throws (the file vanished after the scan) is dropped from the plan: it is no longer a schedule. Each remaining one isdisableableonly whenscheduleFileUnlinked(projectPath, filePath)holds; elsereason: 'linked file or directory'. That helper,scheduleFileUnlinked(projectRoot, filePath, realpath = fs.realpathSync)inschedule-runner.js, is the single rule for the plan and fordisableScheduleFile:realpath(filePath) === path.join(realpath(projectRoot), '.claude', 'commands', path.basename(filePath)). It returnsfalseon anyrealpatherror and never throws. It means no link below the project root. A symlinked file,commandsor.claudedirectory fails it (schedule-runner.js:307-311reads through links). A link above the root, such as a symlinked home,~/workspace, or macOS/tmpand/var, passes.(VERIFIED for the sources; ASSUMED design)
archive-project (groups, { disableSchedules: [filePath] }):{ error: 'indexing' }while!isInitialScanComplete().fresh.filter(s => s.disableable && disableSchedules.includes(s.filePath)), withdisableScheduleFile. A schedule created after the dialog opened is not touched. A confirmed file that vanished before the re-scan is absent from it and is simply not disabled. One that vanishes between the re-scan and the write fails the helper, anddisableScheduleFilereturns{ ok: false }, reported infailed; nothing throws. Collect{ disabled: [name], failed: [{ name, error }] }.knownSessionIdsper group (§4.2), refreshing the group folders first.archivedProjects, set one entry per group, write it, then callnotifyRendererProjectsChanged().deleteSetting,deleteCachedFolder,deleteSearchFolderorscheduleProjects().remove.(ASSUMED design)
disableScheduleFile(filePath, { projectRoot, rewrite } = {})inschedule-runner.js, exported withscheduleFileUnlinked(:551). It writes the mechanism the scheduler already reads:meta.enabled === 'false'(:317), documented atdocs/automation.md:42. Its only existing writer is the creator template (schedule-ipc.js:43). (VERIFIED){ ok: false, error }) unlessscheduleFileUnlinked(projectRoot, filePath): the same rule as the plan, so a schedule offered as disableable is never refused for a link.archive-projectpasses the group'sprojectPathasprojectRoot.rewrite(content)walks the front-matter lines with the same state machine asparseFrontmatter(schedule-runner.js:14-48,currentKeylogic) and replaces every line the parser reads as the top-levelenabledkey withenabled: false. A probe showed that the parser readsenabled: trueas top-level when no block key is open ({"enabled":"true",…}), and keeps the last of duplicate lines. When no line is read asenabled, it insertsenabled: falseas the first front-matter line. That coversenabled: true\r, which the parser ignores (probe:{"cron":"* * * * *"}). (VERIFIED, probe vianode -eonparseFrontmatter)parseFrontmatter(next).meta.enabled === 'false',meta.cronunchanged and body unchanged. Otherwise it refuses and leaves the file as is.rename.<project>/.claude/commands/), so it can leave a working-tree diff in a tracked file. The dialog names the schedules. (VERIFIED for the location)add-project(main.js:701):clearArchivedEntry(getSetting, setSetting, null, projectPath), withpath.resolveon both sides. ThehiddenProjectsunhide at:708is unchanged. (ASSUMED design)delete-worktreeafterRemove(main.js:883):clearArchivedEntry(…, null, normalizedPath). (ASSUMED design)get-projects(main.js:1125):return annotateRemoteAttachable(applyAndPersistArchived(mergePlaceholderSessions(buildProjectsFromCache(showArchived)), showArchived, { getSetting, setSetting })). (ASSUMED design)preload.js, besidearchiveSession(:29):session-cache.jsis unchanged, so thectx.dballow-list (main.js:480-485,test/main-ctx-db-wiring.test.js) needs no edit. (VERIFIED for the guard)4.6 Worktree nesting, shared and alias-aware
public/worktree-nesting.js, exported to both sides with themodule.exportsguard used bypublic/setting-defaults.js:37-38(required bymain.js:74). (VERIFIED for the precedent)SIDEBAR_WORKTREE_RE(the regex now local atsidebar.js:614,/^(.+?)\/\.claude\/worktrees\/([^/]+)\/?$/),worktreeParentPath(projectPath)andworktreeName(projectPath).archived-projects.jsand loaded beforesidebar.jsinindex.htmlanddom-setup.js.WORKTREE_PATH_RE(main.js:819, three forms) is not used here: the rule must follow what the sidebar draws. (VERIFIED for the difference)renderProjects(sidebar.js:613-625,824-825,925-930):worktreeMapandworktreeSetare keyed on(remoteAlias || '') + '|' + path;projects;5. Code to change
archived-projects.js(new)archivedEntry,knownIdsForGroup({ projects, activeSessions, diskIds, alias, projectPath }),applyArchivedProjects,applyAndPersistArchived,clearArchivedEntry,archivePlanForGroupspublic/worktree-nesting.js(new)public/choice-dialog.js(new)main.jsadd-project,delete-worktree,get-projectsschedule-runner.jsdisableScheduleFile, exportedpreload.jspublic/sidebar.js:1087-1114; button titleArchive folder(:877); alias-aware nestingpublic/dialogs.jsknownRemotePathsreadscachedAllProjects(:322-327), so an archived remote path is still suggested in the remote launch dialog (review #14)public/index.html,test/dom-setup.jsworktree-nesting.jsandchoice-dialog.jsbeforesidebar.jseslint.config.jsshowChoiceDialog,SIDEBAR_WORKTREE_RE,worktreeParentPathandworktreeNameinrendererCrossFileGlobals(:26). A producer block forpublic/worktree-nesting.js, modelled onpublic/subagent-timing.js's block (eslint.config.js:512-535):globals.browser,module: 'writable', and its three globals set to'off', sono-undefaccepts themodule.exportsfooter andno-redeclaredoes not flag the definitions.choice-dialog.jsneeds no block: likeutils.js, which producesescapeHtml(:104), it has no footer (VERIFIED for the blocks)public/style.css.modal-dialog, if neededAll rows are ASSUMED design, at locations VERIFIED above.
6. Docs to update
docs/session-browser.md(VERIFIED for the locations)::51;:149-158: the dialog, the two boxes, all-or-nothing on stop failures, the reappearance rule, Show archived reveals the folder;:62-64: archive versus hide;:66-67): worktree groups of another host, or without a listed repository, show at top level.docs/automation.md:42and:148: archiving a folder writesenabled: falseinto its schedule files; they stay disabled when the folder reappears (Q2); linked schedule files are not changed. (VERIFIED for the locations)docs/settings.md"Stored without a field" (:93-99):archivedProjects. (VERIFIED for the location).ai/contexts/session-cache.md: an "Archived projects" section (rule, snapshot sources, step 2, differences fromhiddenProjects); the new tests in "If you change this, also check" (:1505). (ASSUMED placement).ai/contexts/schedule-runner.md:disableScheduleFileand its single caller. (ASSUMED)CHANGELOG.md## Unreleased, written to the rule indocs/changelog.md(VERIFIED for the rule):### New:- **Archive folder** on a project header opens a dialog that archives the folder's sessions and disables its enabled schedules, each optional, and hides the folder with its worktrees. The folder comes back, with its settings, when you add it again or a new session starts in it. (#473)### Fixed:- Worktree folders from another host, or whose repository is not listed, show in the sidebar instead of being nested under the wrong folder or not shown at all. (#473)7. Acceptance criteria
Each file passes with
node --test <file>(0 failed); the gate istask check(Taskfile.yamlcheck: deps: [test, lint]) with 0 errors. (VERIFIED for the Taskfile)Baseline at HEAD:
node --test test/dom-project-archive-all.test.js test/session-cache-hidden-alias.test.js test/dom-sidebar-stop-before-archive.test.jsgivestests 22, pass 22, fail 0(Node v24.21.0;engines.node >=20 <23). (VERIFIED)None of the mutations was run, because the code does not exist yet.
Fixture rules (the CI matrix runs
ubuntu-latestandwindows-2022, Node 20 and 22,.github/workflows/test.yml:91-97) (VERIFIED):archivedProjectskey in a fixture is built througharchivedEntry(alias, path), never written as a literal. On Windowspath.resolve('/r')isD:\ron a runner whose current drive is D:, so a literal'/r'key never matches.try { fs.symlinkSync(...) } catch { t.skip('cannot create a symlink on this machine') }(test/scan-md-files.test.js:30-33,test/run-schedule-now-target.test.js:71). (VERIFIED)Seeding: every migrated test and D1-D13 set
ctx.window.cachedAllProjectsto the fixtures they pass torenderProjects. Without it the lookup of §4.4 step 1 finds no match and the handler aborts (D15).test/dom-setup.js:97-98seeds[]. (VERIFIED for the seed)Migrated tests:
answerChoiceDialog(ctx, { confirm = true, uncheck = [] })intest/dom-setup.js. It waits for.modal-overlay, unticks the named boxes and clicks the confirm or cancel button.{ schedules: [] }forgetProjectArchivePlan.dom-project-archive-all.test.jstests 1, 2 and 3 (:28,46,73): counts, subagents untouched, re-render;dom-sidebar-stop-before-archive.test.js:133,151(alias named or not);:166, whose assertion changes from "the other proceeds" to:stopSessioncalled fors2althoughr1was refused first; noarchiveSession; noarchiveProject. Mutation: return at the first refusal (it leavess2running).(VERIFIED for the use of
confirmand the Proxy atdom-project-archive-all.test.js:9-19)A.
test/archived-projects.test.js(pure)showArchived=falsecleared=[]showArchived=trueshowArchivedcleared=[entry]cleared.push(entry)archived: 0!known.has(id)conditionparentSessionId!s.parentSessionIdconditionarchived: 1!s.archivedconditionplanificator::/srv/x; groups local,planificator,otherhostat/srv/xplanificatorabsent, the other two presentprojectPathonly/srv/x; remoteplanificator/srv/xknownIdsForGroup: archived rows, a terminal, a placeholder, a subagentknownIdsForGroup: anactiveSessionsentry of the group with no row, and one withrealSessionIdactiveSessionssourceknownIdsForGroup:diskIdsholding an id with no rowdiskIdssource/rand child/r/.claude/worktrees/warchived; the child gets a new idclearedholds both/rarchived; a new, never-archived child group/r/.claude/worktrees/wwith a session/rarchived; visible child atplanificator/r/.claude/worktrees/wapplyAndPersistArchivedwith one reappearing groupsetSetting('archivedProjects', …)called once without that entry; with nothing cleared, not calledsetSettingcallclearArchivedEntry(null, '/srv/x/')on stored/srv/xpath.resolvearchivePlanForGroups: remote group; unregistered local; registered given as/p/; symlinkedcommandsdir; plain file[],[], listed,disableable:falsewith a reason,disableable:truepath.resolve/ the realpath check (one mutation per sub-assertion, each in its owntest())scheduleFileUnlinkedwith arealpathstub that throwsENOENT;archivePlanForGroupswhose stub throws for one of two scanned filesfalse, does not throw; the plan lists only the other fileB.
test/schedule-disable.test.js(tmp dir)enabled: trueenabled: false, other bytes unchanged,scanSchedules(null,[dir])is[]enabled: trueenabledlinescanSchedulesis[]cli:block with an indentedenabled: x^\s*enabled:line as top-level{ ok: false }, target unchanged, link still a link0o640enabled: truewith no open blockscanSchedulesis[]enabledlines, lasttruescanSchedulesis[]enabled: true\rinside LF front matterscanSchedulesis[]writeFileSyncin placecommandsdirectory{ ok: false }, the linked target unchangedrealpathof the directory onlyrewritereturning the content unchanged{ ok: false }, file unchanged<tmp>/link -> <tmp>/real, project<tmp>/link/p)scanSchedulesis[]realpath(filePath) !== path.resolve(filePath)C.
test/dom-choice-dialog.test.jsbunticked{a: true, b: false};localStorage['k.b'] === '0'setItemon confirmbstarts uncheckedrememberKeyat initnull, overlay gone, focus onreturnFocus,localStorageunchangedreturnFocus.focus()stopImmediatePropagation<img onerror>imgin the dialoginnerHTMLrememberKey, confirmed uncheckedlocalStorage.lengthunchanged; reopen starts oncheckedidnull, no box writteninitialFocus: 'cancel',danger: true.delete-worktree-confirm-btninitialFocusmessage: ['l1', 'l2']<p>D.
test/dom-project-archive-folder.test.jsarchiveSessionfor['s-top-1'], then onearchiveProject([{projectPath, folderKey}], {disableSchedules: ['/p/.claude/commands/schedule-a.md']})archiveProjectcallarchiveSessionat all, noarchiveProjectarchiveSessionsuntickedarchiveSession;archiveProjectcalledresult.archiveSessionsdisableSchedulesboxsessions: []archiveProjectcalledgetProjectArchivePlancallednullas confirm{disableSchedules: []}localStorage['archiveFolder.disableSchedules'] = '0'rememberKeyin the sidebar's choices/rand same-alias child/r/.claude/worktrees/warchiveProjectreceives both groups; the child's session archived[project]only{indexing: true}alertcalled, no dialog, no further IPCplan.indexing/randplanificator/r/.claude/worktrees/w/r's groupworktreeMapon path only/r/.claude/worktrees/wwith no/rgroupworktreeSetcachedAllProjectsholds parent/r(sessionsa,b, unarchived) and child/r/.claude/worktrees/w(sessionc); the rendered list is the search projection of/rnarrowed toa, with no childarchiveSessionfora,b,c;archiveProjectreceives both groupsgroupsand sessions from the rendered listcachedAllProjectsis[]; the rendered header is/rloadProjectscalled, no other IPC (nogetProjectArchivePlan,stopSessionorarchiveSession)projectwhen nothing matchesE.
test/archive-project-wiring.test.js(source text ofmain.js/preload.js/dialogs.js, the pattern oftest/remove-project-folder-key.test.js)archive-projectbodydeleteSetting(,deleteCachedFolder(,deleteSearchFolder(,.remove(deleteSetting('project:' + …)add-projectbodyclearArchivedEntry(get-projectsbodyapplyAndPersistArchived(withshowArchivedfalsepreload.jsgroupsandoptsoptsdelete-worktreebodyclearArchivedEntry(archive-projectandget-project-archive-planbodiesisInitialScanComplete()archive-projectarchive-projectbodyawaitbetweengetSetting('archivedProjects')andsetSetting('archivedProjects'awaitdialogs.jsknownRemotePathscachedAllProjectscachedProjectsF. Static gate
npx eslint .gives 0 errors. Mutation: removeshowChoiceDialogfromrendererCrossFileGlobals.no-undef: errorapplies topublic/**/*.js(eslint.config.js:360-371). (VERIFIED)G. Live check
task test-pr PR=<n>(docs/testing-a-pr.md):enabled: false;claudein the directory: the folder reappears, archived sessions under Show archived;(ASSUMED; needs the isolated instance)
8. Constraints the implementer inherits
Copied from
.ai/shared-guidelines.md(VERIFIED):SETTING_DEFAULTSinsetting-defaults.js— never a literal at the call site". The box defaults are UI state inlocalStorage, not settings (ASSUMED).escapeHtml()(cross-file global)".test/dom-setup.js+vm.runInContextto evaluatepublic/*.jsin isolation."installSpies: falseis required when the eval defines functions you also spy on — function declarations from eval overwrite property spies."## UnreleasedinCHANGELOG.md, written to the rule in docs/changelog.md".task check(lint + test). 0 errors. Pre-existing warnings are fine."gh pr createagainstdevsuitup/switchboard:main... Title format:(area): short imperative."Co-Authored-Bytrailers in commits".task dev/task test-pr.Must not break (VERIFIED as existing tests):
test/session-cache-hidden-alias.test.js,test/remove-project-folder-key.test.js,test/main-ctx-db-wiring.test.js,test/schedule-catch-up.test.js,test/dom-archived-parent-subagents.test.js,test/session-cache-projects.test.js,test/build-projects-cold-scan-fallback.test.js,test/dom-file-panel-touched.test.js,test/derive-project-path.test.js.Conventions:
package.jsonengines.node >=20 <23;test: node scripts/run-tests.js;pretest: npm run lint. Nopyproject.tomlapplies. (VERIFIED)9. Whether this fits one go
It fits one dispatch at the edge:
Two things force a second round: the review loop, and §7.G, which needs an isolated live instance for focus, styling and a real
clauderun. If it has to be split, the cut is the alias-aware nesting with D12-D13, which can land first on its own. (ASSUMED)10. Open questions
Q2 (owner). Do schedules disabled by the archive come back on when the folder reappears? Default in this spec: no. They stay
enabled: false, and the user re-enables them from the file, which Memory lists (main.js:1348-1355). A CLI session reappearing must not silently restart cron jobs, and the file does not record whichfalsecame from the archive. A yes needsarchivedProjects[entry].disabledSchedulesand a write on reappearance. (ASSUMED; pending owner confirmation)Settled:
cachedAllProjects.(VERIFIED)
11. Instructions found inside the ticket
None. (VERIFIED)
(sidebar): cover the archive wiring and keep hidden repositories' wor…
(sidebar): pin the settings writes and hide pending sessions of hidde…
(sidebar): archiving a project folder hides it until a session appear…