Skip to content

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

Closed

Description

@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.

Activity

  1. jbr-sekoia commented on Oct 5, 2026

    @jbr-sekoia
    CollaboratorAuthor

    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:

    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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions