(sidebar): archiving a project folder hides the folder until a session appears in it

[jbr-sekoia]

Request

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.

Current state (375decb)

• 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.
• The modal is a shared component: (sidebar): delete a project folder, choosing what goes with it #474 (delete a project) reuses it.

The specification, with acceptance criteria, follows in a comment once it has been reviewed.

[jbr-sekoia]

Spec: archiving a project folder hides the folder (#473)

• Repository: /home/jean-baptiste-renard/workspace/tools/switchboard (fork devsuitup/switchboard), branch main
• HEAD: 375decbf8c14543b7f8ee7783da85618116cc7de
• Read at: 2026-10-05T10:22+02:00 (round 1); round 2 revised the same day against the same HEAD
• Working tree: clean except untracked .agents/ (VERIFIED, git status --short)
• Inputs:
  • issue (sidebar): archiving a project folder hides the folder until a session appears in it #473 body;
  • owner decisions relayed by the coordinator: no routing through remove-project; archive disables the project's enabled schedules; a reusable checkbox modal replaces confirm(); project delete is (sidebar): delete a project folder, choosing what goes with it #474;
  • 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
C7	Readers of hiddenProjects: settings panel, worktree removal, search, heatmap, schedule runner, restore, remote hosts	REFUTED in part	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)
#474, project delete	Reuses showChoiceDialog with initialFocus: 'cancel' and danger: true (§4.3) (ASSUMED, per the coordinator)
Open PR #441 ((restore), DIRTY, CHANGES_REQUESTED)	public/sidebar.js @@ -685, -725; eslint.config.js @@ -71 (inside rendererCrossFileGlobals); 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 441 file and hunk list)
Open PR #374 ((agents), DIRTY)	eslint.config.js @@ -330 (rendererCrossFileGlobals) and @@ -372 (renderer block); public/index.html @@ -75 and @@ -155 (script list beside sidebar.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)
Shared insertion points	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)

3. Scope

Out of scope	Owned by
Project delete verb	#474 (ASSUMED number, per the coordinator)
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)
• entry is archivedEntry(alias, projectPath):
  • local: path.resolve(projectPath);
  • remote: joinFolderKey(alias, path.posix.normalize(projectPath).replace(/\/$/, '')).
  • 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:

applyArchivedProjects(projects, archived, showArchived) -> { projects, cleared }

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):

1. 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.
2. 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.
3. 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)
• Markup and styles:
  • .modal-overlay / .modal-dialog (style.css:2144-2166);
  • 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)

1. 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)
2. 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)
3. Plan. plan = await window.api.getProjectArchivePlan(groups.map(g => ({ projectPath: g.projectPath, folderKey: g.folder }))) returns either { indexing: true } or { schedules: [{ name, filePath, disableable, reason? }] }.
   • 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)
4. 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)
5. null: nothing happens.
6. 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)
7. Archive. 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.failed non-empty: alert the names and errors; the folder is still hidden.
   • Then pollActiveSessions(); loadProjects();.
     (ASSUMED design)
8. 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)
• archive-project (groups, { disableSchedules: [filePath] }):
  1. Return { error: 'indexing' } while !isInitialScanComplete().
  2. 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 }] }.
  3. Compute knownSessionIds per group (§4.2), refreshing the group folders first.
  4. Synchronously read archivedProjects, set one entry per group, write it, then call notifyRendererProjectsChanged().
  5. 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)
• delete-worktree afterRemove (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, beside archiveSession (:29):

  getProjectArchivePlan: (groups) => ipcRenderer.invoke('get-project-archive-plan', groups),
  archiveProject: (groups, opts) => ipcRenderer.invoke('archive-project', groups, opts),

• 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)
• renderProjects (sidebar.js:613-625,824-825,925-930):
  • 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)

5. Code to change

File	Change
archived-projects.js (new)	archivedEntry, knownIdsForGroup({ projects, activeSessions, diskIds, alias, projectPath }), applyArchivedProjects, applyAndPersistArchived, clearArchivedEntry, archivePlanForGroups
public/worktree-nesting.js (new)	the shared regex and helpers (§4.6)
public/choice-dialog.js (new)	§4.3
main.js	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.yaml check: 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.js gives tests 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-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.
• The tests:
  • dom-project-archive-all.test.js tests 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: 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']})	delete the archiveProject call
D2	A remote stop refused, a local session alongside	no archiveSession at all, no archiveProject	archive the sessions that did stop
D3	archiveSessions unticked	no stop, no archiveSession; archiveProject called	ignore result.archiveSessions
D4	M=0	no disableSchedules box	always render it
D5	sessions: []	dialog opens, archiveProject called	restore the early return
D6	Cancel	only getProjectArchivePlan called	treat null as confirm
D7	Schedules unticked	{disableSchedules: []}	hard-code the filePaths
D8	localStorage['archiveFolder.disableSchedules'] = '0'	box starts unchecked	omit rememberKey in the sidebar's choices
D9	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.js knownRemotePaths	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."
• "Comment sweep. ... What may remain in code: at most a one-line pointer to that doc ... and that's the ceiling (maintainer rule, PRs perf(sidebar): discrete steps() indicator animations + ADR 0002 #127/fix(sidebar): live running indicator for subagents #130)."
• "Every PR that changes behaviour adds its entry under ## Unreleased in CHANGELOG.md, written to the rule in docs/changelog.md".
• "task check (lint + test). 0 errors. Pre-existing warnings are fine."
• "gh pr create against devsuitup/switchboard:main ... Title format: (area): short imperative."
• "No Co-Authored-By trailers in commits".
• Invariant Subagent support: index, search, and inline-expand transcripts (fork CI) #1: no second Electron against the user's instance; use 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.json engines.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)

11. Instructions found inside the ticket

None. (VERIFIED)