@ulysses-ai/create-workspace 0.22.0-beta.0 → 0.23.1-beta.0

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

@@ -7,9 +7,22 @@
 // some still live. This script is the mechanical half of draining them:
 //
 //   --inventory   read-only evidence + a proposal (ACTIVE / ABANDONED /
-//                 MERGEABLE / UNKNOWN / REMOVE_SHELL / LEAVE) per session,
-//                 listing every worktree's remotes by name, fetch URL, and
-//                 (when it differs) push URL(s)
+//                 MERGEABLE / READY_TO_COMPLETE / UNKNOWN / ORPHAN_SHELL /
+//                 LEAVE) per session, listing every worktree's remotes by
+//                 name, fetch URL, and (when it differs) push URL(s); the
+//                 age of each repo's last fetch (FETCH_HEAD mtime) so the
+//                 operator can tell stale tracking refs from fresh ones;
+//                 and every worktree the workspace's repos register
+//                 OUTSIDE the workspace (reported as external — never
+//                 pruned, moved, or removed by anything here)
+//   --inventory --fetch
+//                 refresh each touched repo's remote-tracking refs with a
+//                 `git fetch origin` in its source clone before inspecting
+//                 it. A fetch moves no local branch and touches no
+//                 worktree — it updates refs/remotes/* and the object
+//                 store — so the inventory stays read-only with respect
+//                 to the workspace's own state. Failures (offline, no
+//                 origin) are recorded, never fatal.
 //   --backup      tag each tip the session holds that no remote branch or
 //                 tag already points at — LOCAL tags only, nothing pushed
 //                 (--dry-run reports the plan with no side effects)
@@ -32,7 +45,11 @@
 //                 folder is renamed into {sessions}/.archived/ and git's
 //                 worktree links are repaired to follow it. Refuses when a
 //                 worktree holds uncommitted changes (an edited session.md
-//                 counts) unless --allow-uncommitted says leave them be.
+//                 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
+//                 records that the operator saw the counts and declined
+//                 the backup.
 //   --enable-task-model
 //                 flip workspace.sessionModel to "task" (accepts a task
 //                 worktree root — the one mode allowed off the launcher)
@@ -86,6 +103,7 @@ const DAY_MS = 24 * 60 * 60 * 1000;
 // refuse rather than guess.
 const LS_REMOTE_TIMEOUT_MS = 15000;
 const PUSH_TIMEOUT_MS = 60000;
+const FETCH_TIMEOUT_MS = 60000;
 
 function netOpts(timeoutMs) {
   return { encoding: 'utf8', timeout: timeoutMs, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } };
@@ -512,6 +530,51 @@ function dirtyContentMtimeMs(gitFn, wtPath, kind) {
   return newest;
 }
 
+// === S2(d): fetch freshness ===
+//
+// ahead/behind and the content counts compare against tracking refs
+// (refs/remotes/origin/*) that only move on a fetch — in a quiet workspace
+// they can be weeks stale, and every count derived from them inherits the
+// staleness. FETCH_HEAD's mtime is the cheapest honest proxy for "when did
+// that last happen". FETCH_HEAD is per git-dir (a linked worktree has its
+// own), so this reads the SOURCE CLONE's copy — the same place --fetch
+// refreshes — keeping the reported age and the refresh the same file.
+function lastFetchMs(gitFn, repoDir) {
+  const res = run(gitFn, repoDir, ['rev-parse', '--git-path', 'FETCH_HEAD']);
+  if (res.status !== 0) return null;
+  try {
+    return statSync(resolve(repoDir, String(res.stdout).trim())).mtimeMs;
+  } catch {
+    return null; // never fetched (or an unreadable file) — age unknown
+  }
+}
+
+function describeFetchAge(ageMs) {
+  if (ageMs == null) return 'never (no FETCH_HEAD)';
+  const hours = ageMs / 3600000;
+  if (hours < 1) return 'less than an hour ago';
+  if (hours < 48) return `${Math.max(1, Math.round(hours))} hour(s) ago`;
+  return `${Math.max(2, Math.round(hours / 24))} day(s) ago`;
+}
+
+// --fetch refreshes one repo's remote-tracking refs: `git fetch origin` in
+// the source clone, nothing else. A fetch moves no local branch and
+// touches no worktree, so the inventory stays read-only with respect to
+// the workspace's own state; a repo without an origin is skipped, and a
+// failure (offline, unreachable, timed out) is a recorded outcome, never
+// a crash — the counts just keep their old staleness warning.
+function runFetch(gitFn, repoDir, repo) {
+  if (!remotesOf(gitFn, repoDir).includes('origin')) {
+    return { repo, status: 'skipped', detail: 'no origin remote' };
+  }
+  const res = gitFn('git', ['-C', repoDir, 'fetch', 'origin'], netOpts(FETCH_TIMEOUT_MS));
+  if (res.error || res.status !== 0) {
+    const detail = res.error ? `timed out after ${FETCH_TIMEOUT_MS / 1000}s` : String(res.stderr || '').trim();
+    return { repo, status: 'failed', detail };
+  }
+  return { repo, status: 'ok' };
+}
+
 // === Session shape ===
 
 function readTracker(wsDir) {
@@ -524,12 +587,20 @@ function readTracker(wsDir) {
     const rawRepos = fields.repos;
     const repos = Array.isArray(rawRepos) ? rawRepos.map(String)
       : rawRepos == null || rawRepos === '' ? [] : [String(rawRepos)];
+    // A chat session with ended: null may still be open — session-start
+    // records one per chat and session-end fills ended in. Counting them
+    // is the raw material for the chat-open flag; whether the count means
+    // "a chat may be working here right now" is decided against the
+    // session's recency in inspectSession, not here.
+    const chats = Array.isArray(fields.chatSessions) ? fields.chatSessions : [];
+    const openChats = chats.filter((c) => c && typeof c === 'object' && (c.ended == null || c.ended === '')).length;
     return {
       status: typeof fields.status === 'string' ? fields.status : null,
       workItem: typeof fields.workItem === 'string' ? fields.workItem : null,
       branch: typeof fields.branch === 'string' ? fields.branch : null,
       updated: fields.updated != null ? String(fields.updated) : null,
       repos,
+      openChats,
     };
   } catch {
     // An unparseable tracker is evidence about the tracker, not the
@@ -541,8 +612,16 @@ function readTracker(wsDir) {
 // One worktree of a session — the workspace worktree (repo ".") or one
 // nested project worktree (repo = its directory name under repos/).
 // A session's workspace branch and its code are different things, so
-// each is reported on its own line.
-function inspectWorktree(gitFn, rootDir, kind, repo, wtPath) {
+// each is reported on its own line. fetchState (present only under
+// --fetch) refreshes the repo's tracking refs in its source clone before
+// anything derived from them is computed, once per repo per run.
+function inspectWorktree(gitFn, rootDir, kind, repo, wtPath, fetchState) {
+  const repoDir = kind === 'workspace' ? rootDir : join(rootDir, 'repos', repo);
+  if (fetchState && !fetchState.attempts.has(repoDir)) {
+    fetchState.attempts.set(repoDir, runFetch(gitFn, repoDir, kind === 'workspace' ? WORKSPACE_REPO : repo));
+  }
+  const now = fetchState ? fetchState.now : Date.now();
+  const fetchedMs = lastFetchMs(gitFn, repoDir);
   const branch = currentBranch(gitFn, wtPath);
   const defaultBranch = defaultBranchFor(rootDir, repo, gitFn);
   const range = ownRange(gitFn, wtPath, defaultBranch);
@@ -560,6 +639,8 @@ function inspectWorktree(gitFn, rootDir, kind, repo, wtPath) {
     base,
     defaultBranch,
     reflogAt: reflogTs(gitFn, wtPath),
+    lastFetch: fetchedMs != null ? new Date(fetchedMs).toISOString() : null,
+    fetchAgeMs: fetchedMs != null ? Math.max(0, now - fetchedMs) : null,
     remotes: {},
     backedBy: null,
   };
@@ -607,14 +688,18 @@ function collectSessionWorktrees(gitFn, rootDir, folder) {
  * Pure classifier: given a session's computed metrics, return its
  * proposal and the human-readable reasons for it. No activity signal at
  * all → UNKNOWN (never ABANDONED — absence of evidence is not
- * abandonment). Active-ness is lastActivity within N days, or any dirty
- * worktree with lastActivity within 2N days. Everything else splits on
- * whether real content survives — committed content files, uncommitted
- * content paths, or project commits mean MERGEABLE; artifact-only,
- * clean, and quiet means ABANDONED. A session that fits neither (e.g.
- * uncommitted project changes on a stale session) falls to MERGEABLE —
- * real uncommitted work is content, and the dirty warning carries the
- * caution.
+ * abandonment). A session with activity but no session.md →
+ * READY_TO_COMPLETE: /complete-work strips the tracker before its final
+ * steps, so live worktrees without one mean the completion stopped
+ * partway — finishing it (or archiving it as abandoned mid-flight, the
+ * operator's call) beats resuming it as ordinary work. Active-ness is
+ * lastActivity within N days, or any dirty worktree with lastActivity
+ * within 2N days. Everything else splits on whether real content
+ * survives — committed content files, uncommitted content paths, or
+ * project commits mean MERGEABLE; artifact-only, clean, and quiet means
+ * ABANDONED. A session that fits neither (e.g. uncommitted project
+ * changes on a stale session) falls to MERGEABLE — real uncommitted
+ * work is content, and the dirty warning carries the caution.
  */
 function classify(session, activeDays, now = Date.now()) {
   const ws = session.worktrees.find((w) => w.kind === 'workspace') || null;
@@ -629,6 +714,16 @@ function classify(session, activeDays, now = Date.now()) {
       reasons: ['no activity signal — no session commits, no reflog entries, no content-dirty files, no tracker updated date'],
     };
   }
+  if (session.trackerStripped) {
+    return {
+      proposal: 'READY_TO_COMPLETE',
+      reasons: [
+        `last activity ${session.lastActivity}`,
+        'no session.md tracker — /complete-work strips it before its final steps, so live worktrees without one are a session stopped mid-completion',
+        'finish it with /complete-work, or archive it if the operator knows it was abandoned there',
+      ],
+    };
+  }
   if (within(activeDays)) {
     return { proposal: 'ACTIVE', reasons: [`last activity ${session.lastActivity} is within ${activeDays} days`] };
   }
@@ -675,6 +770,7 @@ function classify(session, activeDays, now = Date.now()) {
 
 function collectWarnings(gitFn, rootDir, worktrees, active, trackerBranch) {
   const warnings = [];
+  const staleFetchReported = new Set(); // once per repo — one FETCH_HEAD serves every worktree
   for (const wt of worktrees) {
     if (wt.kind === 'workspace' && wt.branchDrift) {
       warnings.push({
@@ -709,25 +805,91 @@ function collectWarnings(gitFn, rootDir, worktrees, active, trackerBranch) {
         repo: wt.repo,
       });
     }
+    // The remote states come from live ls-remote queries, but ahead/behind
+    // and the content counts ride on tracking refs frozen at the last
+    // fetch. Past a day that deserves a flag before anyone trusts the
+    // numbers — and the flag names the two ways to refresh them.
+    if ((wt.fetchAgeMs == null || wt.fetchAgeMs > DAY_MS) && !staleFetchReported.has(wt.repo)) {
+      staleFetchReported.add(wt.repo);
+      warnings.push({
+        kind: 'stale-fetch',
+        message: `${repoLabel(wt)}: last fetch ${describeFetchAge(wt.fetchAgeMs)} — commits-ahead and content counts use tracking refs from then; fetch the repo first, or re-run with --inventory --fetch`,
+        repo: wt.repo,
+        fetchAgeMs: wt.fetchAgeMs,
+      });
+    }
   }
   return warnings;
 }
 
-function inspectSession(gitFn, rootDir, sessionsDir, name, activeDays, now) {
+// Is a shell folder provably empty — every entry a directory, every
+// directory readable, no files and no symlinks anywhere? Symlinks count
+// as content (they may point at anything), and an unreadable directory
+// means emptiness cannot be proven. "Removable" must be provably safe,
+// not probably safe: the inventory answer is what the operator's removal
+// step is checked against, and it re-verifies at removal time anyway.
+function shellIsEmpty(folder) {
+  let empty = true;
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      empty = false;
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) { // files, symlinks, anything else
+        empty = false;
+        continue;
+      }
+      walk(join(dir, entry.name));
+    }
+  };
+  walk(folder);
+  return empty;
+}
+
+function inspectSession(gitFn, rootDir, sessionsDir, name, activeDays, now, fetchState) {
   const folder = join(sessionsDir, name);
   const wsDir = join(folder, 'workspace');
   if (!existsSync(join(wsDir, '.git'))) {
-    const reason = existsSync(wsDir)
+    const shape = existsSync(wsDir)
       ? `workspace/ at ${relative(rootDir, wsDir)} is not a git worktree (empty shell)`
       : `no workspace worktree at ${relative(rootDir, folder)}${sep}workspace`;
-    return { name, kind: 'broken', proposal: 'REMOVE_SHELL', reasons: [reason] };
+    const empty = shellIsEmpty(folder);
+    return {
+      name,
+      kind: 'broken',
+      empty,
+      proposal: 'ORPHAN_SHELL',
+      reasons: [
+        shape,
+        empty
+          ? 'the folder holds only empty directories — an orphan shell left by a session whose worktrees were already torn down; removable once re-verified empty at removal time (see the skill)'
+          : 'the folder holds files with no worktree left to own them — archive it with --archive (which keeps them) or reconcile manually',
+      ],
+    };
   }
 
   const tracker = readTracker(wsDir);
+  // A missing tracker and an unreadable one are different facts: absence is
+  // the /complete-work strip step's signature (a session stopped
+  // mid-completion), while an unparseable file is tracker damage the
+  // operator should hear about. Neither ever crashes the inspection.
+  const trackerStripped = !existsSync(join(wsDir, 'session.md'));
+  // The tracker file's own mtime: a chat resuming the session rewrites
+  // session.md (the session-start hook registers it in chatSessions), so a
+  // fresh mtime is live-chat evidence even when no commit or reflog entry
+  // followed. It feeds only the chat-open question below, never
+  // lastActivity — an uncommitted tracker edit is bookkeeping, not work
+  // (same line dirtyContentMtimeMs draws).
+  let trackerMtimeMs = null;
+  try { trackerMtimeMs = statSync(join(wsDir, 'session.md')).mtimeMs; } catch { /* absent or unreadable — no signal */ }
   const rawWorktrees = collectSessionWorktrees(gitFn, rootDir, folder);
   const worktrees = rawWorktrees
     .filter((w) => w.kind !== 'foreign')
-    .map((w) => inspectWorktree(gitFn, rootDir, w.kind, w.repo, w.path));
+    .map((w) => inspectWorktree(gitFn, rootDir, w.kind, w.repo, w.path, fetchState));
   const wsWt = worktrees.find((w) => w.kind === 'workspace');
   if (wsWt && tracker) {
     wsWt.trackerBranch = tracker.branch;
@@ -754,13 +916,52 @@ function inspectSession(gitFn, rootDir, sessionsDir, name, activeDays, now) {
   }
   consider(tracker?.updated ?? null);
 
-  const { proposal, reasons } = classify({ name, worktrees, lastActivity }, activeDays, now);
+  const { proposal, reasons } = classify({ name, worktrees, lastActivity, trackerStripped }, activeDays, now);
   const warnings = collectWarnings(gitFn, rootDir, worktrees, proposal === 'ACTIVE', tracker?.branch ?? null);
+  // A chat with no recorded end only means "may still be open" while
+  // something in the session is also recent: session-end misses often
+  // enough (a crashed chat, a skipped hook) that an entry sitting on a
+  // session idle for months is a stale record, not a live chat. Recency is
+  // the newest of the session's own activity signals (lastActivity —
+  // own-branch commits, reflog, dirty content, the tracker's updated
+  // field) and the tracker file's mtime. When no signal can establish
+  // either answer, the cautious reading stands.
+  let chatOpen = false;
+  let chatIdleDays = null;
+  if (tracker && tracker.openChats > 0) {
+    const newestChatSignal = Math.max(
+      Number.isFinite(lastMs) ? lastMs : -Infinity,
+      trackerMtimeMs ?? -Infinity,
+    );
+    if (!Number.isFinite(newestChatSignal) || now - newestChatSignal <= activeDays * DAY_MS) {
+      chatOpen = true;
+      warnings.push({
+        kind: 'chat-open',
+        message: `${tracker.openChats} chat session(s) recorded with no end time — a chat may still be working in this session; confirm with the operator before archiving it`,
+      });
+    } else {
+      chatIdleDays = Math.floor((now - newestChatSignal) / DAY_MS);
+      warnings.push({
+        kind: 'chat-open-idle',
+        info: true,
+        idleDays: chatIdleDays,
+        message: `${tracker.openChats} chat session(s) recorded with no end time, but nothing in the session has moved for ${chatIdleDays} day(s) — the end was most likely never recorded; treat the chat as closed unless the operator knows otherwise`,
+      });
+    }
+  }
+  if (!trackerStripped && !tracker) {
+    warnings.push({
+      kind: 'tracker-unreadable',
+      message: 'session.md exists but could not be parsed — status, work item and chat evidence are missing; the worktree evidence still stands',
+    });
+  }
   return {
     name,
     kind: 'session',
     status: tracker?.status ?? null,
     workItem: tracker?.workItem ?? null,
+    chatOpen,
+    ...(chatIdleDays != null ? { chatIdleDays } : {}),
     lastActivity,
     proposal,
     reasons,
@@ -769,15 +970,42 @@ function inspectSession(gitFn, rootDir, sessionsDir, name, activeDays, now) {
   };
 }
 
+// Registered worktrees of the workspace's own repositories that live
+// OUTSIDE the workspace root — a scratch checkout in tmp, a directory on
+// another drive, someone's working copy. They belong to no session, so
+// they are reported at the top level rather than under one, and nothing
+// in this script ever prunes, moves, or removes them: `git worktree
+// prune` is the one command that could silently drop their records, and
+// no mode here runs it for real (archive's prune checks are --dry-run).
+function externalWorktreesOf(gitFn, rootDir) {
+  const out = [];
+  for (const owned of workspaceRepos(rootDir)) {
+    const listed = registeredWorktrees(gitFn, owned.dir);
+    if (listed === null) {
+      out.push({ repo: owned.repo, error: `could not list worktrees of ${relative(rootDir, owned.dir) || 'the workspace repo'}` });
+      continue;
+    }
+    for (const p of listed) {
+      if (!insideRoot(rootDir, p)) out.push({ repo: owned.repo, path: p });
+    }
+  }
+  return out;
+}
+
 /**
  * Read-only inventory of every session under the workspace's sessions
  * directory. The proposal each session gets is a proposal — the note in
  * the result says so, and the skill says so again to the operator.
  * Symlinked entries are reported as foreign (LEAVE) and never followed.
+ * `fetch: true` (CLI --fetch) refreshes each touched repo's tracking
+ * refs first; the result records what the refresh did per repo. Worktrees
+ * the workspace's repos register outside the root are listed as external
+ * — evidence for the operator, never something to act on.
  */
-function inventory(root, { activeDays = 14, gitFn = spawnSync, now = Date.now() } = {}) {
+function inventory(root, { activeDays = 14, gitFn = spawnSync, now = Date.now(), fetch = false } = {}) {
   const rootDir = resolveRoot(root);
   const sessionsDir = sessionsDirOf(rootDir);
+  const fetchState = fetch ? { attempts: new Map(), now } : null;
   const sessions = listSessionEntries(rootDir).map((entry) => (
     entry.foreign
       ? {
@@ -786,13 +1014,15 @@ function inventory(root, { activeDays = 14, gitFn = spawnSync, now = Date.now()
         proposal: 'LEAVE',
         reasons: ['entry is a symlink, not a session directory — never followed; reconcile manually'],
       }
-      : inspectSession(gitFn, rootDir, sessionsDir, entry.name, activeDays, now)
+      : inspectSession(gitFn, rootDir, sessionsDir, entry.name, activeDays, now, fetchState)
   ));
   return {
     root: rootDir,
     activeDays,
     note: 'Proposals are proposals — inventory evidence only; the operator decides each session.',
     sessions,
+    externalWorktrees: externalWorktreesOf(gitFn, rootDir),
+    ...(fetch ? { fetch: [...fetchState.attempts.values()] } : {}),
   };
 }
 
@@ -1562,12 +1792,17 @@ function repairAndVerify(gitFn, owned, worktreePaths, prunableBefore) {
  * find; a worktree holds uncommitted or untracked changes — an edited
  * 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 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.
+ * 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
+ * (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
+ * 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.
  */
-function archiveSession(root, { session, allowUncommitted = false, gitFn = spawnSync, cwd = process.cwd(), now = Date.now() } = {}) {
+function archiveSession(root, { session, allowUncommitted = false, allowUnbacked = false, gitFn = spawnSync, cwd = process.cwd(), now = Date.now() } = {}) {
   const rootDir = resolveRoot(root);
   if (!isSessionSegment(session)) {
     throw new Error(`session name must be a single path segment not starting with ".", got: ${session}`);
@@ -1633,6 +1868,30 @@ function archiveSession(root, { session, allowUncommitted = false, gitFn = spawn
       }
     }
   }
+  // Unpushed commits ride along safely too — but "safely" holds only as
+  // long as the archive exists, and deleting it later is the operator's
+  // 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.
+  const unbacked = [];
+  for (const f of found) {
+    const wtPath = f.rel === '.' ? folder : join(folder, f.rel);
+    const info = inspectWorktree(
+      gitFn, rootDir,
+      f.owner.repo === WORKSPACE_REPO ? 'workspace' : 'project',
+      f.owner.repo, wtPath, null,
+    );
+    if (info.ahead > 0 && !info.backedBy) 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`,
+    );
+  }
   if (reasons.length > 0) return { refused: true, reasons };
 
   const archiveDir = join(sessionsDir, '.archived');
@@ -1676,6 +1935,9 @@ function archiveSession(root, { session, allowUncommitted = false, gitFn = spawn
     from: relative(rootDir, folder),
     to: relative(rootDir, dest),
     worktrees: at(dest).map((m) => ({ repo: m.owner.repo, path: relative(rootDir, m.path) })),
+    // 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`),
   };
 }
@@ -1731,14 +1993,19 @@ function renderTable(result) {
   ];
   for (const s of result.sessions) {
     lines.push('');
-    lines.push(`${s.name}  ${s.kind === 'broken' ? 'broken shell' : s.kind === 'foreign' ? 'foreign entry' : s.proposal}` +
-      (s.kind === 'broken' || s.kind === 'foreign' ? '' : `  (status ${s.status ?? '—'}, last activity ${s.lastActivity ?? '—'}, work item ${s.workItem ?? '—'})`));
+    const header = s.kind === 'broken'
+      ? `ORPHAN_SHELL — ${s.empty ? 'only empty directories' : 'holds files, no worktree'}`
+      : s.kind === 'foreign' ? 'foreign entry' : s.proposal;
+    const detail = s.kind === 'broken' || s.kind === 'foreign'
+      ? ''
+      : `  (status ${s.status ?? '—'}, last activity ${s.lastActivity ?? '—'}, work item ${s.workItem ?? '—'}${s.chatOpen ? ', chat open?' : s.chatIdleDays != null ? `, chat: no end recorded (idle ${s.chatIdleDays}d)` : ''})`;
+    lines.push(`${s.name}  ${header}${detail}`);
     for (const w of s.worktrees || []) {
       const remotes = Object.entries(w.remotes)
         .map(([r, v]) => describeRemote(r, v))
         .join(' ') || 'no remotes';
       const extra = w.kind === 'workspace' ? `  content:${w.contentFiles}` : '';
-      lines.push(`    ${w.kind === 'workspace' ? '(workspace)' : w.repo}  ${w.branch ?? 'detached'}  ahead:${w.ahead ?? '?'} dirty:${w.dirty}${extra}  [${remotes}]`);
+      lines.push(`    ${w.kind === 'workspace' ? '(workspace)' : w.repo}  ${w.branch ?? 'detached'}  ahead:${w.ahead ?? '?'} dirty:${w.dirty}${extra}  fetch:${describeFetchAge(w.fetchAgeMs)}  [${remotes}]`);
       // The state bracket alone is ambiguous — "origin:none" says the remote
       // holds no copy of this branch, not that there is no origin. The URL
       // line settles it: name = exact URL for every configured remote, plus
@@ -1756,7 +2023,16 @@ function renderTable(result) {
       }
     }
     for (const r of s.reasons || []) lines.push(`    · ${r}`);
-    for (const w of s.warnings || []) lines.push(`    ! ${w.message}`);
+    // `!` marks something to act on; an entry carrying info: true is
+    // context (a stale record explained, not a live risk).
+    for (const w of s.warnings || []) lines.push(`    ${w.info ? 'i' : '!'} ${w.message}`);
+  }
+  if (Array.isArray(result.externalWorktrees) && result.externalWorktrees.length > 0) {
+    lines.push('');
+    lines.push('external worktrees (registered outside this workspace — never prune, move, or remove them):');
+    for (const e of result.externalWorktrees) {
+      lines.push(e.error ? `    repo "${e.repo}": ${e.error}` : `    repo "${e.repo}"  ${e.path}`);
+    }
   }
   return `${lines.join('\n')}\n`;
 }
@@ -1773,6 +2049,8 @@ const BOOL_FLAGS = new Map([
   ['--remote', 'remote'],
   ['--remote-allow-all', 'remoteAllowAll'],
   ['--allow-uncommitted', 'allowUncommitted'],
+  ['--allow-unbacked', 'allowUnbacked'],
+  ['--fetch', 'fetch'],
 ]);
 
 function parseArgs(argv) {
@@ -1786,6 +2064,8 @@ function parseArgs(argv) {
     remote: false,
     remoteAllowAll: false,
     allowUncommitted: false,
+    allowUnbacked: false,
+    fetch: false,
   };
   const rest = argv.slice(2);
   for (let i = 0; i < rest.length; i += 1) {
@@ -1824,6 +2104,9 @@ function parseArgs(argv) {
     if (!Number.isInteger(n) || n <= 0) throw new Error('--active-days must be a positive integer');
     args.activeDays = n;
   }
+  if (args.fetch && args.mode !== 'inventory') {
+    throw new Error('--fetch is only valid with --inventory');
+  }
   if (args.remote && args.mode !== 'backup') {
     throw new Error('--remote is only valid with --backup');
   }
@@ -1837,6 +2120,9 @@ function parseArgs(argv) {
   if (args.allowUncommitted && args.mode !== 'archive') {
     throw new Error('--allow-uncommitted is only valid with --archive');
   }
+  if (args.allowUnbacked && args.mode !== 'archive') {
+    throw new Error('--allow-unbacked is only valid with --archive');
+  }
   if (args.dryRun && args.mode !== 'backup') {
     throw new Error('--dry-run is only valid with --backup');
   }
@@ -1854,7 +2140,7 @@ function main() {
   let out;
   let code = 0;
   if (args.mode === 'inventory') {
-    out = inventory(rootDir, { activeDays: args.activeDays ?? 14 });
+    out = inventory(rootDir, { activeDays: args.activeDays ?? 14, fetch: args.fetch });
     process.stderr.write(renderTable(out));
   } else if (args.mode === 'backup') {
     out = backupSession(rootDir, {
@@ -1865,7 +2151,11 @@ function main() {
       dryRun: args.dryRun,
     });
   } else if (args.mode === 'archive') {
-    out = archiveSession(rootDir, { session: args.session, allowUncommitted: args.allowUncommitted });
+    out = archiveSession(rootDir, {
+      session: args.session,
+      allowUncommitted: args.allowUncommitted,
+      allowUnbacked: args.allowUnbacked,
+    });
   } else {
     out = enableTaskModel(rootDir);
   }