@ulysses-ai/create-workspace 0.23.2-beta.0 → 0.23.3-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulysses-ai/create-workspace",
-  "version": "0.23.2-beta.0",
+  "version": "0.23.3-beta.0",
   "description": "A workspace convention for Claude Code: sessions, handoffs, and shared context as files in git",
   "keywords": [
     "claude",

package/template/_claude/scripts/migrate-sessions.mjs

@@ -47,14 +47,24 @@
 //                 worktree holds uncommitted changes (an edited session.md
 //                 counts) unless --allow-uncommitted says leave them be,
 //                 and when a worktree tip holds commits no remote backs
-//                 (they exist only on this machine) unless --allow-unbacked
+//                 on a branch or under a drain/{session}/* tag (they
+//                 exist only on this machine) unless --allow-unbacked
 //                 records that the operator saw the counts and declined
 //                 the backup.
+//   --remove-shell
+//                 remove an ORPHAN_SHELL session folder — no worktree,
+//                 nothing but empty directories, re-verified empty at
+//                 removal time; anything else refuses, touching nothing
 //   --enable-task-model
 //                 flip workspace.sessionModel to "task" (accepts a task
-//                 worktree root — the one mode allowed off the launcher)
+//                 worktree root — the one mode allowed off the launcher;
+//                 --launcher <root> counts the remaining sessions from
+//                 the launcher when --root is that worktree)
 //
-// NOTHING HERE DELETES. Draining a session means taking it out of the
+// NOTHING HERE DELETES — with one deliberate exception: --remove-shell,
+// whose target is a folder provably empty of files and symlinks
+// (re-verified at removal time, so a plain directory tree is all it can
+// ever lose). Draining a session otherwise means taking it out of the
 // active lifecycle, not destroying it. An earlier design tore sessions
 // down behind a "prove it is safe to delete" check; four independent
 // reviews each found a new place git keeps state that the check missed
@@ -80,7 +90,7 @@
 // reasons: [...]} and exits 1; any other error goes to stderr and exits 2.
 
 import {
-  readFileSync, writeFileSync, existsSync, readdirSync, lstatSync, statSync, mkdirSync, renameSync, readlinkSync,
+  readFileSync, writeFileSync, existsSync, readdirSync, lstatSync, statSync, mkdirSync, renameSync, readlinkSync, rmSync,
 } from 'node:fs';
 import { realpathSync } from 'node:fs';
 import { join, resolve, relative, dirname, sep, isAbsolute } from 'node:path';
@@ -633,6 +643,7 @@ function inspectWorktree(gitFn, rootDir, kind, repo, wtPath, fetchState) {
     repo,
     path: relative(rootDir, realPath(wtPath)),
     branch,
+    head,
     dirty: dirtyRecords.length,
     ahead: aheadCount(gitFn, wtPath, range),
     lastOwnCommit: lastOwnCommitIso(gitFn, wtPath, range),
@@ -1066,9 +1077,12 @@ function remoteQualifies(safety, repoDir, remote) {
 
 // Every branch and tag a remote holds, mapped by commit sha. Other
 // advertised refs (HEAD, a forge's refs/pull/N/*) are ephemeral and never
-// count. No refspec pattern: patterns silently drop the peeled ^{} lines,
-// which are the ones comparable with commit tips. A failed or timed-out
-// query returns null (unknown) — it proves nothing.
+// count. No refspec pattern: some git versions drop the peeled ^{} lines
+// under a pattern, and those lines are the ones comparable with commit
+// tips (drainTagSafety below does use one — it must name a single
+// session's tags — and compensates by peeling locally instead of trusting
+// the peel line). A failed or timed-out query returns null (unknown) — it
+// proves nothing.
 function remoteRefs(safety, repoDir, remote) {
   const key = `${repoDir}\0${remote}`;
   if (safety.lsCache.has(key)) return safety.lsCache.get(key);
@@ -1101,6 +1115,75 @@ function tipSafety(safety, repoDir, sha) {
   return { safe: false };
 }
 
+// The archive gate's tag half: --backup --remote is what puts
+// drain/{session}/{branch-slug} tags on remotes, so the gate must count its
+// own backup or the documented "backup, then archive" path always refuses.
+// A tip is backed by tag when a qualifying remote holds a
+// drain/{session}/* tag whose peeled commit CONTAINS the tip — the tip
+// itself (what the backup tagged) or any descendant. The query narrows to
+// the session with a refspec pattern AND every returned line is re-checked
+// against `refs/tags/drain/{session}/` after stripping a trailing `^{}` —
+// the pattern is the query, the prefix is the answer's meaning, and a tag
+// like drain/{session}-suffix/… must never satisfy the other session's
+// gate. A session name containing glob metacharacters (* ? [ ]) has no
+// honest pattern — git forbids those characters in ref names anyway, so no
+// drain tag can exist for it — and is refused up front rather than escaped
+// into meaning something else. The peel is resolved locally
+// (cat-file/merge-base peel tag objects; the backup run left the tag
+// object in the local store), which keeps the check fetch-free and never
+// dependent on the peeled ^{} line: current git returns it under a
+// pattern, older gits drop it (the reason remoteRefs above avoids
+// patterns), and the plain line answers either way once the object is
+// local. Without the object nothing can be verified and the tip counts as
+// not backed. A local-only tag proves nothing — the remote is asked
+// directly — and a failed or timed-out query is reported as a blocker and
+// counts as not backed (the safe direction: an unreachable remote cannot
+// vouch for anything).
+function drainTagSafety(safety, session, wtPath, tip) {
+  const blockers = [];
+  if (/[*?[\]]/.test(session)) {
+    blockers.push(`cannot build a drain-tag pattern for session name "${session}" (it contains glob metacharacters, which git forbids in ref names — no drain tag can exist for it)`);
+    return { backed: false, remote: null, tag: null, blockers };
+  }
+  const out = { backed: false, remote: null, tag: null, blockers };
+  const prefix = `refs/tags/drain/${session}/`;
+  const pattern = `${prefix}*`;
+  for (const remote of safety.remotes(wtPath)) {
+    if (!remoteQualifies(safety, wtPath, remote)) continue;
+    const res = safety.gitFn('git', ['-C', wtPath, 'ls-remote', '--tags', remote, pattern], netOpts(LS_REMOTE_TIMEOUT_MS));
+    if (res.error || res.status !== 0) {
+      // "timed out" only when spawnSync actually timed out; anything else
+      // carries its own message (or git's stderr).
+      const detail = res.error
+        ? (res.error.code === 'ETIMEDOUT'
+          ? `timed out after ${LS_REMOTE_TIMEOUT_MS / 1000}s`
+          : String(res.error.message || res.error))
+        : (String(res.stderr || '').trim() || 'ls-remote failed');
+      out.blockers.push(`could not reach remote "${remote}" (${detail})`);
+      continue;
+    }
+    for (const line of okLines(res)) {
+      const [sha, ref] = line.trim().split(/\s+/);
+      // Explicit session filter: strip the peel suffix first, so both line
+      // kinds are held to the same `drain/{session}/` prefix.
+      const bare = ref && ref.endsWith('^{}') ? ref.slice(0, -3) : ref;
+      if (!sha || !ref || !bare.startsWith(prefix)) continue;
+      if (sha === tip) {
+        out.backed = true; out.remote = remote; out.tag = bare.slice('refs/tags/'.length);
+        break;
+      }
+      const commit = `${sha}^{commit}`; // no-op for a peel line, peels a plain tag-object sha
+      const known = run(safety.gitFn, wtPath, ['cat-file', '-e', commit]).status === 0;
+      if (known && run(safety.gitFn, wtPath, ['merge-base', '--is-ancestor', tip, commit]).status === 0) {
+        out.backed = true; out.remote = remote; out.tag = bare.slice('refs/tags/'.length);
+        break;
+      }
+    }
+    if (out.backed) break;
+  }
+  return out;
+}
+
 function makeSafety(gitFn, rootDir) {
   const safety = {
     gitFn,
@@ -1793,11 +1876,13 @@ function repairAndVerify(gitFn, owned, worktreePaths, prunableBefore) {
  * session.md counts (unless allowUncommitted: they would ride along
  * fine, but they deserve a decision: commit them to the session branch,
  * or explicitly accept archiving them mid-edit); or a worktree tip holds
- * commits no remote backs — they exist only on this machine, and the
- * archive is safe for them but the moment it is deleted they are gone
+ * commits no remote backs — on a branch, or under a drain/{session}/* tag
+ * the backup step pushed there — so they exist only on this machine, and
+ * the archive is safe for them but the moment it is deleted they are gone
  * (unless allowUnbacked, the operator's recorded decline after seeing
  * the per-repo counts; the refusal names them, and a successful archive
- * that carried unbacked tips reports them in `unbacked`). Also refused
+ * reports tips those tags backed in `backedByTag` and tips that rode
+ * along unbacked in `unbacked`). Also refused
  * when the archive directory is a symlink or resolves outside the
  * workspace. If anything fails after the rename, the folder is renamed
  * back and repaired, and the result reports the verified state.
@@ -1873,10 +1958,15 @@ function archiveSession(root, { session, allowUncommitted = false, allowUnbacked
   // own call. A tip whose commits no remote backs (the inventory's
   // `unbacked` evidence, recomputed here at archive time) exists only on
   // this machine, so the archive moves only once a remote holds every
-  // such tip — the backup step's push mode --remote with an allow — or
-  // after --allow-unbacked records that the operator saw these counts and
-  // declined it. allowUnbacked still reports what rode along.
+  // such tip — on a branch, or under a drain/{session}/* tag the backup
+  // step's push mode put there — or after --allow-unbacked records that
+  // the operator saw these counts and declined the backup. allowUnbacked
+  // still reports what rode along.
   const unbacked = [];
+  const backedByTag = [];
+  const tagBlockers = [];
+  const wtInfos = [];
+  const safety = makeSafety(gitFn, rootDir);
   for (const f of found) {
     const wtPath = f.rel === '.' ? folder : join(folder, f.rel);
     const info = inspectWorktree(
@@ -1884,12 +1974,25 @@ function archiveSession(root, { session, allowUncommitted = false, allowUnbacked
       f.owner.repo === WORKSPACE_REPO ? 'workspace' : 'project',
       f.owner.repo, wtPath, null,
     );
-    if (info.ahead > 0 && !info.backedBy) unbacked.push(info);
+    wtInfos.push(info);
+    if (!(info.ahead > 0) || info.backedBy) continue;
+    const tag = info.head
+      ? drainTagSafety(safety, session, wtPath, info.head)
+      : { backed: false, remote: null, tag: null, blockers: [] };
+    if (tag.backed) {
+      backedByTag.push({ repo: info.repo, branch: info.branch, commits: info.ahead, tag: tag.tag, remote: tag.remote });
+      continue;
+    }
+    for (const b of tag.blockers) {
+      tagBlockers.push(`${repoLabel(info)}: the drain-tag check did not clear — ${b} — treated as not backed; resolve it or decide with --allow-unbacked`);
+    }
+    unbacked.push(info);
   }
   if (unbacked.length > 0 && !allowUnbacked) {
     reasons.push(
       ...unbacked.map((wt) => unbackedMessage(gitFn, rootDir, wt)),
-      `${unbacked.length} worktree tip(s) above hold commits that exist only on this machine — this clears only when a remote holds them (--backup --remote with the operator's allow pushes backup tags there), or re-run with --allow-unbacked once the operator has seen these counts and explicitly declined the backup`,
+      ...tagBlockers,
+      `${unbacked.length} worktree tip(s) above hold commits that exist only on this machine — this clears only when a remote holds them (a pushed branch, or --backup --remote with the operator's allow pushing backup tags there), or re-run with --allow-unbacked once the operator has seen these counts and explicitly declined the backup`,
     );
   }
   if (reasons.length > 0) return { refused: true, reasons };
@@ -1929,19 +2032,60 @@ function archiveSession(root, { session, allowUncommitted = false, allowUnbacked
     return { refused: true, reasons: [...problems, state] };
   }
 
+  // The archived worktrees keep their branches checked out, so those names
+  // stay taken until the archive is deleted — the result says so, naming
+  // them, so the next task that wants one of those names learns why not.
+  const heldBranches = [...new Set(wtInfos.map((w) => w.branch).filter(Boolean))];
   return {
     session,
     archived: true,
     from: relative(rootDir, folder),
     to: relative(rootDir, dest),
     worktrees: at(dest).map((m) => ({ repo: m.owner.repo, path: relative(rootDir, m.path) })),
+    // Tips the backup's drain tags cover on a remote — backed, just not on
+    // a branch.
+    ...(backedByTag.length > 0 ? { backedByTag } : {}),
     // What the operator accepted riding along unbacked — the same
     // repos and counts the refusal would have named.
     ...(unbacked.length > 0 ? { unbacked: unbacked.map((wt) => ({ repo: wt.repo, branch: wt.branch, commits: wt.ahead })) } : {}),
-    warnings: scan.outwardLinks.map((l) => `relative symlink ${relative(rootDir, join(dest, relative(folder, l)))} pointed outside the session and no longer resolves after the move — it was kept as-is`),
+    ...(heldBranches.length > 0 ? {
+      heldBranches,
+      note: `the archived worktrees keep ${heldBranches.join(', ')} checked out — a new task cannot reuse ${heldBranches.length === 1 ? 'that branch name' : 'those branch names'} until the archive is deleted`,
+    } : {}),
+    warnings: [
+      ...scan.outwardLinks.map((l) => `relative symlink ${relative(rootDir, join(dest, relative(folder, l)))} pointed outside the session and no longer resolves after the move — it was kept as-is`),
+      ...tagBlockers,
+    ],
   };
 }
 
+// The one thing this script removes: an ORPHAN_SHELL — a session folder
+// with no worktree left in it and nothing but empty directories, verified
+// EMPTY AT REMOVAL TIME, not at inventory time. The inventory's `empty`
+// flag is evidence a shell was empty when read; anything that appeared
+// since (a stray file, a symlink, a .git marker) means the folder is
+// content now, and content is archive's to keep, never removal's to
+// delete. A refusal touches nothing.
+function removeShell(root, { session, cwd = process.cwd() } = {}) {
+  const rootDir = resolveRoot(root);
+  if (!isSessionSegment(session)) {
+    throw new Error(`session name must be a single path segment not starting with ".", got: ${session}`);
+  }
+  const sessionsDir = sessionsDirOf(rootDir);
+  const { folder, refusal } = sessionFolderGuards(rootDir, sessionsDir, session, cwd);
+  if (refusal) return refusal;
+  if (!shellIsEmpty(folder)) {
+    return {
+      refused: true,
+      reasons: [
+        `session "${session}" holds files or symlinks, not just empty directories — nothing was removed; archive it instead (--archive keeps everything) or reconcile manually`,
+      ],
+    };
+  }
+  rmSync(folder, { recursive: true, force: true });
+  return { session, removed: true, from: relative(rootDir, folder) };
+}
+
 // The launcher root is the main worktree of the workspace repo; every
 // other checkout is a linked worktree. Acting modes require the
 // launcher; --enable-task-model is the exception (it edits workspace.json
@@ -1958,11 +2102,39 @@ function isLinkedWorktree(gitFn, rootDir) {
  * Switch the workspace to the task model: flip workspace.sessionModel to
  * "task", keeping every other key untouched. From the launcher this also
  * reports the remaining sessions; from a task worktree (the S6 flow)
- * there is no sessions directory to read — remainingSessions is null and
- * the note says where the real list comes from.
+ * there is no sessions directory to read — pass `launcher` (CLI
+ * `--launcher <root>`) to count them from the launcher anyway, or get
+ * remainingSessions null with a note saying where the real list comes
+ * from. The launcher is validated before anything is edited: it must be
+ * the launcher of the SAME repository as --root (a different workspace's
+ * launcher would happily count that workspace's sessions), and a --root
+ * that is itself the launcher needs no launcher — only the same root
+ * spelled again is accepted.
  */
-function enableTaskModel(root, { gitFn = spawnSync } = {}) {
+function enableTaskModel(root, { gitFn = spawnSync, launcher = null } = {}) {
   const rootDir = resolveRoot(root);
+  // Validate and resolve the launcher BEFORE editing anything: a wrong
+  // launcher would report a wrong count, and the switch must not land
+  // only to have the run die on the flag afterwards.
+  const linked = isLinkedWorktree(gitFn, rootDir);
+  let launcherDir = null;
+  if (launcher) {
+    launcherDir = resolveRoot(launcher);
+    if (isLinkedWorktree(gitFn, launcherDir)) {
+      throw new Error(`--launcher must be the workspace launcher (its own root), not a linked worktree: ${launcherDir}`);
+    }
+    const rootCommon = commonDirOf(gitFn, rootDir);
+    const launcherCommon = commonDirOf(gitFn, launcherDir);
+    if (!rootCommon || !launcherCommon) {
+      throw new Error(`could not determine the repository of ${!rootCommon ? rootDir : launcherDir} (git rev-parse --git-common-dir failed) — refusing to guess at --launcher`);
+    }
+    if (rootCommon !== launcherCommon) {
+      throw new Error(`--launcher ${launcherDir} belongs to a different repository than --root ${rootDir} — name this workspace's own launcher`);
+    }
+    if (!linked && rootDir !== launcherDir) {
+      throw new Error(`--root ${rootDir} is not a task worktree, so --launcher has nothing to add (got ${launcherDir}) — omit it, or point --root at the switch worktree`);
+    }
+  }
   const cfgPath = join(rootDir, 'workspace.json');
   let cfg;
   try {
@@ -1975,14 +2147,13 @@ function enableTaskModel(root, { gitFn = spawnSync } = {}) {
   // file's house format.
   cfg.workspace = { ...(cfg.workspace || {}), sessionModel: 'task' };
   writeFileSync(cfgPath, `${JSON.stringify(cfg, null, 2)}\n`);
-  const linked = isLinkedWorktree(gitFn, rootDir);
-  return linked
-    ? {
-      sessionModel: 'task',
-      remainingSessions: null,
-      note: 'run from a task worktree — remaining sessions come from --inventory at the launcher root',
-    }
-    : { sessionModel: 'task', remainingSessions: listSessionNames(rootDir) };
+  if (!linked) return { sessionModel: 'task', remainingSessions: listSessionNames(rootDir) };
+  if (launcherDir) return { sessionModel: 'task', remainingSessions: listSessionNames(launcherDir) };
+  return {
+    sessionModel: 'task',
+    remainingSessions: null,
+    note: 'run from a task worktree — pass --launcher <launcher root> to count the remaining sessions from it, or run --inventory at the launcher root',
+  };
 }
 
 // Human-readable inventory rendering for stderr — the operator's table;
@@ -2037,12 +2208,13 @@ function renderTable(result) {
   return `${lines.join('\n')}\n`;
 }
 
-const MODE_FLAGS = new Set(['--inventory', '--backup', '--archive', '--enable-task-model']);
+const MODE_FLAGS = new Set(['--inventory', '--backup', '--archive', '--enable-task-model', '--remove-shell']);
 const VALUE_FLAGS = new Map([
   ['--root', 'root'],
   ['--session', 'session'],
   ['--active-days', 'activeDays'],
   ['--remote-allow', 'remoteAllow'], // repeatable: <repo>=<remote>
+  ['--launcher', 'launcher'], // --enable-task-model only: count sessions from here
 ]);
 const BOOL_FLAGS = new Map([
   ['--dry-run', 'dryRun'],
@@ -2060,6 +2232,7 @@ function parseArgs(argv) {
     session: null,
     activeDays: null,
     remoteAllow: [],
+    launcher: null,
     dryRun: false,
     remote: false,
     remoteAllowAll: false,
@@ -2088,12 +2261,15 @@ function parseArgs(argv) {
     }
     throw new Error(`unknown argument: ${a}`);
   }
-  if (!args.mode) throw new Error('one of --inventory, --backup, --archive, --enable-task-model is required');
-  if ((args.mode === 'backup' || args.mode === 'archive') && !args.session) {
+  if (!args.mode) throw new Error('one of --inventory, --backup, --archive, --enable-task-model, --remove-shell is required');
+  if ((args.mode === 'backup' || args.mode === 'archive' || args.mode === 'remove-shell') && !args.session) {
     throw new Error(`--${args.mode} requires --session`);
   }
-  if (args.session != null && args.mode !== 'backup' && args.mode !== 'archive') {
-    throw new Error('--session is only valid with --backup or --archive');
+  if (args.session != null && args.mode !== 'backup' && args.mode !== 'archive' && args.mode !== 'remove-shell') {
+    throw new Error('--session is only valid with --backup, --archive or --remove-shell');
+  }
+  if (args.launcher != null && args.mode !== 'enable-task-model') {
+    throw new Error('--launcher is only valid with --enable-task-model');
   }
   if (args.session != null && !isSessionSegment(args.session)) {
     throw new Error(`--session must be a single path segment, got: ${args.session}`);
@@ -2156,8 +2332,10 @@ function main() {
       allowUncommitted: args.allowUncommitted,
       allowUnbacked: args.allowUnbacked,
     });
+  } else if (args.mode === 'remove-shell') {
+    out = removeShell(rootDir, { session: args.session });
   } else {
-    out = enableTaskModel(rootDir);
+    out = enableTaskModel(rootDir, { launcher: args.launcher });
   }
   process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
   if (out && out.refused) {
@@ -2181,4 +2359,4 @@ if (isMainModule(import.meta.url)) {
   }
 }
 
-export { inventory, backupSession, archiveSession, enableTaskModel, classify, parseArgs };
+export { inventory, backupSession, archiveSession, removeShell, enableTaskModel, classify, parseArgs };

package/template/_claude/scripts/trackers/gitlab-issues.mjs

@@ -134,13 +134,23 @@ export function createGitlabAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
     return issue;
   }
 
+  // `glab issue create` prints the new issue's URL: older GitLab/glab says
+  // /-/issues/N, newer says /-/work_items/N (issues became work items
+  // under the hood) — the number is the same iid either way. If neither
+  // shape appears the issue still WAS created (glab exited 0 and the
+  // server accepted it), so the error must say so and carry glab's output
+  // — otherwise the caller retries and duplicates the issue.
   async function createIssue({ title, body = '', labels = [], milestone = null }) {
     const args = ['issue', 'create', '--repo', repo, '--title', title, '--description', body, '--yes'];
     if (labels.length > 0) args.push('--label', labels.join(','));
     if (milestone) args.push('--milestone', milestone);
     const stdout = glab(args);
-    const m = stdout.match(/\/-\/issues\/(\d+)/);
-    if (!m) throw new Error(`Could not parse issue number from: ${stdout.trim()}`);
+    const m = stdout.match(/\/-\/(?:issues|work_items)\/(\d+)/);
+    if (!m) {
+      throw new Error(
+        `glab issue create succeeded, but the new issue's number could not be parsed from its output `
+        + `— the issue WAS created; do NOT retry (a retry would create a duplicate). glab output: ${stdout.trim()}`);
+    }
     return getIssue(`gl:${m[1]}`);
   }
 
@@ -162,7 +172,11 @@ export function createGitlabAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
 
   // The canonical URL for an issue — what a cross-forge reference needs
   // (a `group/sub#N` reference cannot resolve on a GitHub PR), minted from
-  // the same host/repo every other URL here is built from.
+  // the same host/repo every other URL here is built from. `/-/issues/N`
+  // stays the link form even though GitLab now serves issues at work_items
+  // URLs — those links still resolve — and every method but createIssue
+  // takes `gl:N` ids rather than parsing glab's printed URLs, so this is
+  // the only other place the URL shape is chosen, deliberately.
   function issueUrl(issueId) {
     const num = parseIssueNumber(issueId);
     return `https://${host}/${repo}/-/issues/${num}`;

package/template/_claude/skills/migrate-sessions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migrate-sessions
-description: Migrate this workspace from the session lifecycle to the task lifecycle — inventory old work sessions, decide each one with the operator, finish or archive them (empty orphan shells only: remove), and switch workspace.json to the task model. Runs only inside the current workspace; the script never deletes anything.
+description: Migrate this workspace from the session lifecycle to the task lifecycle — inventory old work sessions, decide each one with the operator, finish or archive them (empty orphan shells only: remove), and switch workspace.json to the task model. Runs only inside the current workspace; the script deletes nothing but verified-empty orphan shells.
 ---
 
 # Migrate Sessions
@@ -40,11 +40,11 @@ For each session, lay out its evidence and ask the operator which way to go. Nev
      ```bash
      node .claude/scripts/migrate-sessions.mjs --backup --session {name} --remote
      ```
-     With no allow flag this pushes nothing and exits non-zero, listing per repo the tag and the exact URL(s) it would push to. Approve against the push URL, not the fetch URL: a remote whose push URL differs from its fetch URL shows both, and the script refuses to push there on `--remote-allow-all` — only an explicit `--remote-allow {repo}={remote}` naming it proceeds. Walk the operator through every URL and ask per repo. **Never push backup tags to a remote the operator does not own — a third-party upstream, a read-only mirror, an unfamiliar push URL; pushing `drain/*` tags there publishes the session's commits somewhere foreign.** On yes for repos they do own, re-run adding `--remote-allow {repo}={remote}` per repo (`.` is the workspace repo; `--remote-allow-all` only when every listed URL is their own) and show what was pushed. Declining the push is fine — the archive still keeps everything locally — but the decline must be explicit: step 3's `--archive` refuses while any tip holds commits no remote backs, and proceeds only with `--allow-unbacked`, the operator's recorded no after seeing the counts.
-  3. **Archive after an explicit yes naming the session:** `node .claude/scripts/migrate-sessions.mjs --archive --session {name}` (add `--allow-unbacked` only as the decline recorded in step 2). The whole session folder moves to `{sessions}/.archived/{name}--{timestamp}/` and git's worktree links are repaired to follow it — every commit, uncommitted edit, untracked or ignored file, and embedded repository comes along. If the move or the repair fails, the session is put back and the result says whether every link was verified. The session's branches stay checked out in the archived worktrees, so a new task cannot reuse those branch names until the archive is deleted. The archive refuses, touching nothing, when a directory in the folder cannot be read, when the folder holds a worktree of a repository outside this workspace, when it holds a submodule checkout (its link cannot be repaired), or when a worktree tip holds commits no remote backs — that refusal names each repo and its commit count, exactly the backup decision step 2 deferred; it clears only when a remote holds the tips (a pushed backup), or with `--allow-unbacked`. Surface any refusal's reason; for a submodule the options are Finish or Keep. Relay any `warnings` (relative symlinks that pointed outside the session no longer resolve after the move), and when the result reports `unbacked` entries, say plainly that those commits now exist only on this machine.
-- **Remove** (only an ORPHAN_SHELL the inventory marked empty — no worktree, nothing but empty directories, so there is nothing to archive). The command re-verifies emptiness itself and refuses, touching nothing, if any file or symlink has appeared since the inventory; a refusal means switch to Archive:
+     With no allow flag this pushes nothing and exits non-zero, listing per repo the tag and the exact URL(s) it would push to. Approve against the push URL, not the fetch URL: a remote whose push URL differs from its fetch URL shows both, and the script refuses to push there on `--remote-allow-all` — only an explicit `--remote-allow {repo}={remote}` naming it proceeds. Walk the operator through every URL and ask per repo. **Never push backup tags to a remote the operator does not own — a third-party upstream, a read-only mirror, an unfamiliar push URL; pushing `drain/*` tags there publishes the session's commits somewhere foreign.** On yes for repos they do own, re-run adding `--remote-allow {repo}={remote}` per repo (`.` is the workspace repo; `--remote-allow-all` only when every listed URL is their own) and show what was pushed. Declining the push is fine — the archive still keeps everything locally — but the decline must be explicit: step 3's `--archive` counts what this step pushed (a tip is backed when a remote holds it on a branch or under a `drain/{session}/*` tag), so `--allow-unbacked` is needed only when the operator declined the backup — pass it only on their explicit yes naming the session, after showing them the counts.
+  3. **Archive after an explicit yes naming the session:** `node .claude/scripts/migrate-sessions.mjs --archive --session {name}` (add `--allow-unbacked` only as the decline recorded in step 2). The whole session folder moves to `{sessions}/.archived/{name}--{timestamp}/` and git's worktree links are repaired to follow it — every commit, uncommitted edit, untracked or ignored file, and embedded repository comes along. If the move or the repair fails, the session is put back and the result says whether every link was verified. The session's branches stay checked out in the archived worktrees, so a new task cannot reuse those branch names until the archive is deleted — the result names them (`heldBranches`). The archive refuses, touching nothing, when a directory in the folder cannot be read, when the folder holds a worktree of a repository outside this workspace, when it holds a submodule checkout (its link cannot be repaired), or when a worktree tip holds commits no remote backs on a branch or under a pushed `drain/{session}/*` tag — that refusal names each repo and its commit count, exactly the backup decision step 2 deferred; it clears only when the backup pushed the tips somewhere a remote holds them, or with `--allow-unbacked`. Surface any refusal's reason; for a submodule the options are Finish or Keep. Relay any `warnings` (relative symlinks that pointed outside the session no longer resolve after the move; a drain-tag check that did not clear, with the reason — an unreachable remote, a session name the pattern cannot express), report tips the result lists under `backedByTag` as backed by their drain tag, and when the result reports `unbacked` entries, say plainly that those commits now exist only on this machine.
+- **Remove** (only an ORPHAN_SHELL the inventory marked empty — no worktree, nothing but empty directories, so there is nothing to archive). The scripted removal re-verifies emptiness itself and refuses, touching nothing, if any file or symlink has appeared since the inventory; a refusal means switch to Archive:
   ```bash
-  node -e "const fs=require('fs');const p=process.argv[1];const empty=d=>fs.readdirSync(d,{withFileTypes:true}).every(e=>e.isDirectory()&&empty(d+'/'+e.name));if(!empty(p)){console.error(p+' is not empty — left alone');process.exit(1)}fs.rmSync(p,{recursive:true});console.log('removed empty shell '+p)" work-sessions/{name}
+  node .claude/scripts/migrate-sessions.mjs --remove-shell --session {name}
   ```
 - **Keep** (typical for ACTIVE, and the only sane answer for UNKNOWN) — leave it; it completes later under the session lifecycle. A kept session cannot be converted to a task in place — no converter exists, and the lifecycles keep their state differently (a session folder with a tracker vs. a branch with a chat-record entry). The supported equivalent: finish the session (merge it) and start the remaining work as a task, or keep it under the session lifecycle until it is done. Do not improvise a conversion by hand.
 
@@ -58,26 +58,33 @@ The switch procedure:
    ```bash
    node .claude/scripts/task-worktree.mjs --root . --create --repo . --branch chore/enable-task-model
    ```
-2. Run the switch against that worktree (the one mode that accepts a linked-worktree root — it only edits `workspace.json`):
+2. Run the switch against that worktree (the one mode that accepts a linked-worktree root — it only edits `workspace.json`), passing the launcher so the remaining-session count comes back with the result:
    ```bash
-   node .claude/scripts/migrate-sessions.mjs --enable-task-model --root .claude/worktrees/chore-enable-task-model
+   node .claude/scripts/migrate-sessions.mjs --enable-task-model --root .claude/worktrees/chore-enable-task-model --launcher .
    ```
-3. Land the change the way any task lands. A forge-hosted remote (GitHub, GitLab) means a PR/MR through `task-pr.mjs` — the launcher's default branch is protected on a real forge, so landing directly on it is not an option anyway. Commit in the worktree, write a short PR body (what changed, how it was verified) to a scratch file under `workspace-scratchpad/`, then create, ask before merging, and pull the launcher after the merge:
+3. Land the change the way any task lands. A forge-hosted remote (GitHub, GitLab) means a PR/MR through `task-pr.mjs` — the launcher's default branch is protected on a real forge, so landing directly on it is not an option anyway. Commit in the worktree, write a short PR body (what changed, how it was verified) to a scratch file under `workspace-scratchpad/`, and create the PR:
    ```bash
    node .claude/scripts/task-pr.mjs --create --root . --branch chore/enable-task-model \
      --repo . --body-file .=workspace-scratchpad/switch-pr.md --out workspace-scratchpad/switch-prs.json
-   node .claude/scripts/task-pr.mjs --merge --root . --prs workspace-scratchpad/switch-prs.json
    ```
-   Only a workspace whose repo has no remote at all (`git -C . remote -v` empty) lands locally — commit in the worktree, fast-forward the launcher's default branch, remove the worktree:
+   Only a workspace whose repo has no remote at all (`git -C . remote -v` empty) lands locally — commit in the worktree and leave the landing to step 4:
    ```bash
    git -C .claude/worktrees/chore-enable-task-model add workspace.json
    git -C .claude/worktrees/chore-enable-task-model commit -m "chore: switch to the task lifecycle"
-   git -C . merge --ff-only chore/enable-task-model
-   node .claude/scripts/task-worktree.mjs --root . --remove --repo . --branch chore/enable-task-model --delete-branch
    ```
+4. **Ask the operator before merging** — a step of its own, not a clause inside step 3, because a one-line diff is still the launcher's default branch and "it's only a one-line change" is not permission. Ask exactly: "The task-model switch is ready to merge into the launcher's default branch. Merge it now?" Only an explicit yes merges; on yes:
+   - forge remote — merge the PR, then pull the launcher:
+     ```bash
+     node .claude/scripts/task-pr.mjs --merge --root . --prs workspace-scratchpad/switch-prs.json
+     ```
+   - no remote — fast-forward the launcher's default branch, then remove the worktree:
+     ```bash
+     git -C . merge --ff-only chore/enable-task-model
+     node .claude/scripts/task-worktree.mjs --root . --remove --repo . --branch chore/enable-task-model --delete-branch
+     ```
    Either way the launcher root never commits to its default branch directly. A workspace with neither a remote nor a tracker can use the task model's local mode (gh:173); until that ships, recommend such workspaces stay on sessions.
 
-The switch output reports `remainingSessions: null` when run from the worktree — the real remaining-sessions list comes from a separate `--inventory` at the launcher root. Remaining sessions are fine either way: they keep resuming and completing under the session lifecycle after the switch.
+With `--launcher .` the switch output reports `remainingSessions` from the launcher even though `--root` is the switch worktree (which has no `work-sessions/` to read; without the flag the result is `remainingSessions: null` with a note pointing at a separate `--inventory` at the launcher root). Remaining sessions are fine either way: they keep resuming and completing under the session lifecycle after the switch.
 
 ## 4. Verify