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

package/package.json

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

package/template/_claude/scripts/classify-update.mjs

@@ -67,11 +67,25 @@
 //                (machine-local), paths under .claude/worktrees/, and entries
 //                of workspace.json → workspace.localFiles (array of
 //                .claude/-relative paths or globs for files this workspace
-//                owns) (gh:180)
+//                owns) (gh:180). Two markers refine the per-file offer
+//                (gh:190): `{ file, referencedBy }` — a removed hook that a
+//                workspace-only settings.json entry still registers (the
+//                config-diff paths); the skill removes file and settings
+//                entry together. `{ file, userOwned: true }` — no baseline
+//                entry, so the template never shipped it: the workspace's
+//                own, offered a workspace.localFiles entry, not deletion.
 //   staleTests — *.test.mjs files under .claude/ with no payload counterpart.
 //                The npm tarball ships no tests, so these came from a dev
 //                checkout and are never updated by /workspace-update; the
 //                skill offers to remove them (tests live in the template repo)
+//   implicitDefaults — workspace.json keys whose ABSENCE carried a default
+//                in the version being upgraded FROM but not in the payload's:
+//                canonicalBudgetBytes meant a 40960-byte budget when absent
+//                from v0.15.0-beta.1 until v0.19.0-beta.0 made it opt-in
+//                (absent since means off; before v0.15 there was no budget).
+//                An upgrade from inside that window into a workspace.json
+//                without the key reports { key, value, reason } so the skill
+//                writes the value explicitly (gh:190).
 //
 // Plus `hasBaseline`: whether a usable baseline was found, `baselineSource`
 // (which file it came from) and `baselineReconstructed`. The default
@@ -103,10 +117,15 @@
 //                     present as `updated` again next time; see
 //                     template-baseline.mjs. Throws rather than writing an
 //                     empty baseline.
-//   --merge-claude-md print CLAUDE.md with the payload's CLAUDE.md.tmpl
-//                     merged in: template lines updated, the workspace's own
-//                     lines (custom skill entries, sections) kept. The skill
-//                     shows the diff against the current file before writing.
+//   --merge-claude-md print JSON { claudeMd, missingIncludes }: CLAUDE.md
+//                     with the payload's CLAUDE.md.tmpl merged in — template
+//                     lines updated, the workspace's own lines (custom skill
+//                     entries, sections) kept — plus the `@{path}` include
+//                     lines the merged file carries whose targets don't
+//                     exist at the root (machine-local local-only-* targets
+//                     exempt). The skill shows the diff against the current
+//                     file before writing, and asks on each missing include
+//                     instead of leaving it dangling (gh:190).
 
 import {
   existsSync,
@@ -118,6 +137,7 @@ import {
 import { basename, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gitIgnoredPaths } from './build-workspace-context.mjs';
+import { compareVersions } from '../lib/registry-check.mjs';
 import {
   BASELINE_PATH,
   RECONSTRUCTED_BASELINE_NAME,
@@ -354,6 +374,47 @@ export function resolveBaseline({ root, payload, baseline = null }) {
   return { baseline: null, source: null };
 }
 
+/**
+ * workspace.json keys whose absence carried a default in the version being
+ * upgraded FROM but not in the payload's. The canonical budget existed as an
+ * implicit default only between v0.15.0-beta.1 (gh:97, which introduced it:
+ * absent meant a 40960-byte budget) and v0.19.0-beta.0 (gh:164, which made
+ * it opt-in: absent means off since). Before v0.15 there was no budget at
+ * all, so a workspace upgrading from there also has none to preserve —
+ * reporting the key would turn trimming ON. Only an upgrade from inside
+ * that window into a workspace.json that never wrote the key reports it,
+ * and the skill writes the explicit value and says so (gh:190).
+ */
+const CANONICAL_BUDGET_INTRODUCED = '0.15.0-beta.1';
+const CANONICAL_BUDGET_OPT_IN = '0.19.0-beta.0';
+const CANONICAL_BUDGET_DEFAULT = 40960;
+
+function implicitDefaults(absRoot, absPayload) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(absPayload, '.manifest.json'), 'utf8'));
+  } catch {
+    return []; // no manifest — the payload path is wrong; nothing to infer
+  }
+  const { fromVersion } = manifest;
+  if (typeof fromVersion !== 'string' || fromVersion === 'unknown') return [];
+  if (compareVersions(fromVersion, CANONICAL_BUDGET_INTRODUCED) < 0) return [];
+  if (compareVersions(fromVersion, CANONICAL_BUDGET_OPT_IN) >= 0) return [];
+  let config;
+  try {
+    config = JSON.parse(readFileSync(join(absRoot, 'workspace.json'), 'utf8'));
+  } catch {
+    return []; // no workspace.json to preserve a default in
+  }
+  const ws = config?.workspace && typeof config.workspace === 'object' ? config.workspace : null;
+  if (!ws || Object.prototype.hasOwnProperty.call(ws, 'canonicalBudgetBytes')) return [];
+  return [{
+    key: 'canonicalBudgetBytes',
+    value: CANONICAL_BUDGET_DEFAULT,
+    reason: `absent meant a ${CANONICAL_BUDGET_DEFAULT}-byte canonical budget before v0.19 and means off since — write the value explicitly or trimming silently stops`,
+  }];
+}
+
 export function classifyUpdate({ root, payload, baseline: baselineArg = null }) {
   const absRoot = resolve(root);
   const absPayload = resolve(payload ?? join(absRoot, '.workspace-update'));
@@ -376,6 +437,7 @@ export function classifyUpdate({ root, payload, baseline: baselineArg = null })
     activated: [],
     removed: [],
     staleTests: [],
+    implicitDefaults: [],
     hasBaseline: baseline !== null,
     baselineSource: source,
     baselineReconstructed: baseline !== null && baseline.reconstructed === true,
@@ -451,11 +513,71 @@ export function classifyUpdate({ root, payload, baseline: baselineArg = null })
       continue;
     }
     if (isOwnedByWorkspace(rel, localFiles)) continue;
-    result.removed.push(rel);
+    // No baseline record means the template never shipped the file here —
+    // the workspace's own, not a template removal. Marked so the skill
+    // offers a workspace.localFiles entry instead of deletion; only a real
+    // baseline can prove the negative. An activated optional rule is the
+    // exception: the baseline records its .skip twin, which proves the
+    // template shipped it, so its removal stays plain (gh:190).
+    const templateShipped = typeof baseline?.files[rel] === 'string'
+      || (rel.startsWith('.claude/rules/') && rel.endsWith('.md')
+        && typeof baseline?.files[`${rel}.skip`] === 'string');
+    if (baseline && !templateShipped) {
+      result.removed.push({ file: rel, userOwned: true });
+    } else {
+      result.removed.push(rel);
+    }
   }
+  linkRemovedHooks(result, absRoot);
+  result.implicitDefaults = implicitDefaults(absRoot, absPayload);
   return result;
 }
 
+/**
+ * A removed hook that a workspace-only settings.json entry still registers
+ * must not be deleted while its registration stays: mark the removal with
+ * `referencedBy` — the config-diff paths (`settings.json hooks.{Event}`) —
+ * so the skill removes the file and the settings entry together (gh:190).
+ * References are looked for where the config diff shows the workspace
+ * holding what the payload doesn't: `arrays[].workspaceOnly` elements and
+ * `workspaceOnly` keys (whose value is read from its settings.json).
+ */
+function linkRemovedHooks(result, absRoot) {
+  const settings = result.config.find((c) => c.path === '.claude/settings.json');
+  if (!settings || settings.notInstalled || settings.unparseable) return;
+  const removedHooks = result.removed.filter(
+    (entry) => typeof entry === 'string' && entry.startsWith('.claude/hooks/'),
+  );
+  if (removedHooks.length === 0) return;
+  let wsHooks = null;
+  try {
+    const wsSettings = JSON.parse(readFileSync(join(absRoot, '.claude', 'settings.json'), 'utf8'));
+    if (isPlainObject(wsSettings?.hooks)) wsHooks = wsSettings.hooks;
+  } catch {
+    return; // the config entry already flagged it unparseable
+  }
+  for (let i = 0; i < result.removed.length; i++) {
+    const rel = result.removed[i];
+    if (typeof rel !== 'string' || !rel.startsWith('.claude/hooks/')) continue;
+    const referencedBy = [];
+    for (const arr of settings.arrays) {
+      if (arr.path.startsWith('hooks/') && arr.workspaceOnly.some((el) => JSON.stringify(el).includes(rel))) {
+        referencedBy.push(`settings.json ${arr.path.split('/').join('.')}`);
+      }
+    }
+    for (const path of settings.workspaceOnly) {
+      if (!path.startsWith('hooks/')) continue;
+      const event = wsHooks && wsHooks[path.split('/')[1]];
+      if (event !== undefined && JSON.stringify(event).includes(rel)) {
+        referencedBy.push(`settings.json ${path.split('/').join('.')}`);
+      }
+    }
+    if (referencedBy.length > 0) {
+      result.removed[i] = { file: rel, referencedBy };
+    }
+  }
+}
+
 // ---------- CLAUDE.md merge ----------
 
 /**
@@ -606,6 +728,25 @@ function writeBaselineMode(args) {
   }, null, 2) + '\n');
 }
 
+/**
+ * `@{path}` include lines in a CLAUDE.md body whose target file does not
+ * exist at the workspace root. Machine-local targets (`local-only-*`
+ * basenames) are expected absent on machines that never wrote them — the
+ * same exemption the maintenance audit gives those imports — so they never
+ * report. The include-line shape mirrors context-footprint's resolveImports:
+ * a line whose trimmed content is exactly `@` plus a path.
+ */
+function missingIncludes(absRoot, text) {
+  const missing = [];
+  for (const rawLine of text.split(/\r?\n/)) {
+    const m = /^@(\S+)$/.exec(rawLine.trim());
+    if (!m) continue;
+    if (m[1].split('/').pop().startsWith('local-only-')) continue;
+    if (!existsSync(resolve(absRoot, m[1]))) missing.push(m[1]);
+  }
+  return missing;
+}
+
 function mergeClaudeMdMode(args) {
   const absRoot = resolve(args.root);
   const absPayload = resolvePayload(args);
@@ -623,7 +764,14 @@ function mergeClaudeMdMode(args) {
   const next = readFileSync(tmplPath, 'utf8').replace(/\{\{project-name\}\}/g, name);
   const claudeMdPath = join(absRoot, 'CLAUDE.md');
   const current = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, 'utf8') : '';
-  process.stdout.write(mergeClaudeMd(current, next));
+  const claudeMd = mergeClaudeMd(current, next);
+  // The gained-@include check is deterministic, not something to eyeball in
+  // the diff: every include line whose target is absent here is reported so
+  // the skill asks (stub or omit) instead of writing it silently (gh:190).
+  process.stdout.write(JSON.stringify({
+    claudeMd,
+    missingIncludes: missingIncludes(absRoot, claudeMd),
+  }, null, 2) + '\n');
 }
 
 function main() {

package/template/_claude/scripts/maintenance-audit.mjs

@@ -25,7 +25,11 @@
 //                         of the git common dir), while the worktree's own
 //                         branch is only named in an info line and its dirty
 //                         tracked tree is skipped as info: in-flight work, not
-//                         drift (gh:183)
+//                         drift (gh:183). The launcher's
+//                         .claude/skills/workspace-update/ modification an
+//                         --upgrade leaves when its content equals the staged
+//                         payload's is the expected bootstrap, reported as
+//                         info, never a dirty-tree warning (gh:190)
 //   5. auto-files       — workspace-context catalogs current (the same
 //                         semantics as build-workspace-context.mjs --check)
 //   6. budget           — always-loaded context within
@@ -82,6 +86,7 @@ import {
   readIgnorePrefixes,
   isIgnored,
 } from './build-workspace-context.mjs';
+import { hashBytes } from './template-baseline.mjs';
 import { refreshIfStale } from '../lib/freshness.mjs';
 import { parseSessionContent } from '../lib/session-frontmatter.mjs';
 
@@ -157,7 +162,10 @@ export async function runAudit({
   // array — a structural delimiter, never a byte that could appear in the
   // values (NUL separators made git treat this file as binary).
   const seenFindings = new Set();
-  const add = (section, severity, file, message) => {
+  // opts.noFromUpdate: expected-absent findings (a machine-local import
+  // missing inside a task worktree) stay ambient info even when their file
+  // is on the --changed list — the update did not cause them (gh:190).
+  const add = (section, severity, file, message, opts = {}) => {
     const key = JSON.stringify([section, severity, file, message]);
     if (seenFindings.has(key)) return;
     seenFindings.add(key);
@@ -166,7 +174,7 @@ export async function runAudit({
       severity,
       file,
       message,
-      ...(changedSet.has(file) ? { fromUpdate: true } : {}),
+      ...(changedSet.has(file) && !opts.noFromUpdate ? { fromUpdate: true } : {}),
     });
   };
 
@@ -323,7 +331,10 @@ export async function runAudit({
       const posix = toPosix(spec);
       const base = posix.split('/').pop();
       if (base.startsWith('local-only-')) {
-        add('cross-reference', 'info', 'CLAUDE.md', `@${posix} is absent — machine-local, expected on other machines`);
+        // Machine-local files never materialize inside a task worktree (the
+        // update flow audits from one), so this is ambient, never something
+        // the update caused (gh:190).
+        add('cross-reference', 'info', 'CLAUDE.md', `@${posix} is absent — machine-local, expected on other machines`, { noFromUpdate: true });
       } else if (posix === 'CODEBASE.md') {
         add('cross-reference', 'info', 'CLAUDE.md', '@CODEBASE.md is absent — optional stub, /workspace-init generates it on request');
       } else if (isAutoFileRel(posix, wcDir)) {
@@ -379,6 +390,9 @@ export async function runAudit({
       return relToWC.split('/').includes('archive');
     };
 
+    // Resolved lifecycles are closed out, not defects — however many there
+    // are, they surface as ONE info line, not one per file (gh:190).
+    const resolvedFiles = [];
     for (let i = 0; i < files.length; i++) {
       const rel = rels[i];
       if (ignored.has(rel) || isHistorical(rel)) continue;
@@ -435,12 +449,17 @@ export async function runAudit({
         }
       }
       if (f.lifecycle === 'resolved') {
-        add('frontmatter', 'info', rel, 'lifecycle resolved — confirm /complete-work has processed it');
+        resolvedFiles.push(rel);
       }
       if ('confidence' in f && !['high', 'medium', 'low'].includes(f.confidence)) {
         add('frontmatter', 'warning', rel, `confidence '${f.confidence}' is not one of high, medium, low`);
       }
     }
+    if (resolvedFiles.length > 0) {
+      const names = resolvedFiles.slice(0, 3).map((rel) => rel.split('/').pop());
+      add('frontmatter', 'info', wcDir,
+        `${resolvedFiles.length} lifecycle resolved file(s) — confirm /complete-work has processed them (${names.join(', ')}${resolvedFiles.length > 3 ? ', …' : ''})`);
+    }
   })();
 
   // ---------- 4. git state ----------
@@ -463,11 +482,31 @@ export async function runAudit({
         add('git', 'warning', '.',
           `launcher is on branch '${gitInfo.launcherBranch}' — it stays on its default branch ('${gitInfo.defaultBranch}')`);
       }
+      // --upgrade replaces the launcher's workspace-update skill before the
+      // payload is applied, and the merged PR delivers the same content back:
+      // a modification that equals the staged payload's copy is the expected
+      // bootstrap, not drift — info, and out of the dirty warning (gh:190).
+      const porcelainPath = (line) => line.slice(line.indexOf(' ') + 1).split(' -> ')[0];
       const launcherDirty = gitInfo.launcherPorcelain.filter((l) => !l.startsWith('??'));
-      if (launcherDirty.length > 0) {
-        const paths = launcherDirty.slice(0, 5).map((l) => l.slice(l.indexOf(' ') + 1).replace(/ -> /, ' → '));
+      const bootstrap = launcherDirty.filter((l) => {
+        const p = porcelainPath(l);
+        if (!p.startsWith('.claude/skills/workspace-update/')) return false;
+        try {
+          return hashBytes(readFileSync(join(gitInfo.launcherRoot, p)))
+            === hashBytes(readFileSync(join(gitInfo.launcherRoot, '.workspace-update', p)));
+        } catch {
+          return false; // no staged payload copy to compare against
+        }
+      });
+      if (bootstrap.length > 0) {
+        add('git', 'info', '.',
+          "launcher's .claude/skills/workspace-update/ replaced by --upgrade (matches the staged payload) — expected until the update merges");
+      }
+      const drift = launcherDirty.filter((l) => !bootstrap.includes(l));
+      if (drift.length > 0) {
+        const paths = drift.slice(0, 5).map((l) => l.slice(l.indexOf(' ') + 1).replace(/ -> /, ' → '));
         add('git', 'warning', '.',
-          `launcher has ${launcherDirty.length} tracked file(s) with uncommitted changes: ${paths.join(', ')}${launcherDirty.length > 5 ? ', …' : ''}`);
+          `launcher has ${drift.length} tracked file(s) with uncommitted changes: ${paths.join(', ')}${drift.length > 5 ? ', …' : ''}`);
       }
       add('git', 'info', '.',
         'uncommitted-changes check skipped — the worktree is expected to carry in-flight changes');

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

@@ -45,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)
@@ -585,8 +589,9 @@ function readTracker(wsDir) {
       : 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 how the inventory flags "a chat may be working in this session
-    // right now" before anyone proposes archiving it.
+    // 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 {
@@ -873,6 +878,14 @@ function inspectSession(gitFn, rootDir, sessionsDir, name, activeDays, now, fetc
   // 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')
@@ -905,11 +918,36 @@ function inspectSession(gitFn, rootDir, sessionsDir, name, activeDays, now, fetc
 
   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) {
-    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`,
-    });
+    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({
@@ -922,7 +960,8 @@ function inspectSession(gitFn, rootDir, sessionsDir, name, activeDays, now, fetc
     kind: 'session',
     status: tracker?.status ?? null,
     workItem: tracker?.workItem ?? null,
-    chatOpen: tracker ? tracker.openChats > 0 : false,
+    chatOpen,
+    ...(chatIdleDays != null ? { chatIdleDays } : {}),
     lastActivity,
     proposal,
     reasons,
@@ -1753,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}`);
@@ -1824,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');
@@ -1867,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`),
   };
 }
@@ -1927,7 +1998,7 @@ function renderTable(result) {
       : 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?' : ''})`;
+      : `  (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)
@@ -1952,7 +2023,9 @@ 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('');
@@ -1976,6 +2049,7 @@ const BOOL_FLAGS = new Map([
   ['--remote', 'remote'],
   ['--remote-allow-all', 'remoteAllowAll'],
   ['--allow-uncommitted', 'allowUncommitted'],
+  ['--allow-unbacked', 'allowUnbacked'],
   ['--fetch', 'fetch'],
 ]);
 
@@ -1990,6 +2064,7 @@ function parseArgs(argv) {
     remote: false,
     remoteAllowAll: false,
     allowUncommitted: false,
+    allowUnbacked: false,
     fetch: false,
   };
   const rest = argv.slice(2);
@@ -2045,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');
   }
@@ -2073,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);
   }

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

@@ -22,29 +22,33 @@ Read-only. Present the stderr table plus each session's proposal with its reason
 Three more kinds of evidence change what you propose:
 
 - **Fetch age** — every worktree line ends `fetch:…` with the age of its repo's last fetch, and anything over a day draws a `stale-fetch` warning: the commits-ahead and content counts ride on tracking refs frozen at that fetch. Tell the operator to fetch first, or re-run with `--inventory --fetch`, which fetches each touched source clone before inspecting it. A fetch is read-only with respect to the workspace's own state — it moves no local branch and touches no worktree, only refs/remotes/* and the object store — and a repo with no origin or an unreachable one is recorded as skipped or failed, never fatal.
-- **Open chats** — `chat open?` on a session (with a `chat-open` warning) means its tracker records a chat session with no `ended:` — a chat may still be working in it. Confirm with the operator before proposing Archive.
+- **Open chats** — `chat open?` on a session (with a `chat-open` warning) means its tracker records a chat session with no `ended:` AND the session shows activity within the active window (14 days by default) — a chat may still be working in it; confirm with the operator before proposing Archive. An open-chat entry on a session with nothing recent is a stale record, not a live chat — session-end misses often enough (a crashed chat, a skipped hook) — so it shows as `chat: no end recorded (idle {N}d)` with an informational `chat-open-idle` entry instead. Only the recent kind changes what Archive means.
 - **External worktrees** — a trailing section lists worktrees the workspace's repos register outside the workspace root (a scratch checkout in tmp, a directory elsewhere). They belong to no session: nothing in this migration prunes, moves, or removes them, and you never should either — including by hand, because `git worktree prune` has no path filter and would drop their records.
 
 ## 2. Decide per session, with the operator — one at a time
 
 For each session, lay out its evidence and ask the operator which way to go. Never infer the decision from the proposal. The options:
 
-- **Finish** (typical for MERGEABLE, and the default offer for READY_TO_COMPLETE — a session `/complete-work` stopped partway through: tracker already stripped, worktrees still live, branch often already pushed) — resume it with `/start-work` (its walk lists sessions by their tracker, so a stripped one will not appear — name it and re-create a minimal tracker from the inventory's branch/repos before continuing), then run `/complete-work`; its own merge confirmation applies there. But if the inventory shows a **diverged** remote for that session, say so *before* the operator chooses Finish: `/complete-work`'s plain push will be rejected, and pushing the rewritten history needs `--force-with-lease` — which you run only on the operator's explicit yes naming the branch. Never force silently.
+- **Finish** (typical for MERGEABLE, and the default offer for READY_TO_COMPLETE — a session `/complete-work` stopped partway through: tracker already stripped, worktrees still live, branch often already pushed) — finish it from **this same chat**, the launcher chat. A new chat is not needed and would not work: `/complete-work` finds a session from the launcher only when this chat's id is registered in that session's `chatSessions`, and `/start-work`'s resume flow is what registers it. In this chat:
+  1. Run `/start-work` and pick the session to resume it. (A READY_TO_COMPLETE session has no tracker, and `/start-work`'s walk lists sessions by their tracker, so it will not appear — name it and re-create a minimal tracker from the inventory's `branch`/`repos` first, then resume.)
+  2. Run `/complete-work` — since v0.23 it detects sessions this chat is registered on straight from the launcher, asks which to finish, and proceeds with its own merge confirmation.
+
+  If the inventory shows a **diverged** remote for that session, say so *before* the operator chooses Finish: `/complete-work`'s plain push will be rejected, and pushing the rewritten history needs `--force-with-lease` — which you run only on the operator's explicit yes naming the branch. Never force silently.
 - **Archive** (typical for ABANDONED, an ORPHAN_SHELL that still holds files, or a MERGEABLE the operator gives up on) — take it out of the active lifecycle without destroying anything. When the inventory shows `chat open?`, confirm with the operator that the chat is really done before offering Archive — a live chat's uncommitted work would ride into the archive unseen. Three steps, in this order, each its own decision:
   1. **Clear uncommitted work.** `--archive` refuses when any of the session's worktrees has uncommitted or untracked changes — an edited `session.md` counts — and names them, because edits buried uncommitted in an archive are invisible to every later merge or PR. Offer the operator: commit them to the session branch first (`git -C {worktree} add -A`, then `git -C {worktree} commit -m "…"` — per dirty worktree), discard them explicitly (`git -C {worktree} restore …` / `git -C {worktree} clean …`), or, on an explicit yes, re-run with `--allow-uncommitted` to archive them mid-edit. Do this before the backup: the backup tags committed tips only, so committing first brings those edits under the backup, while anything archived with `--allow-uncommitted` is NOT in it.
   2. **Offer a backup.** Archiving keeps everything on this machine; a backup adds an off-machine copy of the session's commits, and it is what makes a later deletion safe. It covers the committed tips as they stand after step 1. Plain `--backup` creates `drain/{session}/…` tags locally and pushes nothing — for a repo whose only remote is one the operator does not own, that local tag IS the backup. Pushing is a separate, explicitly allowed step:
      ```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 is fine — the archive still keeps everything locally.
-  3. **Archive after an explicit yes naming the session:** `node .claude/scripts/migrate-sessions.mjs --archive --session {name}`. 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, or when it holds a submodule checkout (its link cannot be repaired) — surface the 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).
+     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:
   ```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}
   ```
-- **Keep** (typical for ACTIVE, and the only sane answer for UNKNOWN) — leave it; it completes later under the session lifecycle.
+- **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.
 
-Unbacked commits (present on no remote) are safe in an archive — they are only ever at risk when someone deletes one. Say so when you archive such a session, and offer the backup.
+Unbacked commits (present on no remote) are safe in an archive — they are only ever at risk when someone deletes one. That is why the backup decision is a gate rather than a suggestion: the archive itself refuses until the backup step ran or the decline is recorded, and its result names what rode along.
 
 ## 3. Switch — never write the launcher's tracked `workspace.json` directly
 

package/template/_claude/skills/workspace-update/SKILL.md

@@ -34,9 +34,9 @@ ANY remote — even one you cannot push to — routes the update through a workt
 
 - **A remote exists (the normal case)** — create a task worktree up front and treat it as the workspace root for Steps 2–6:
   ```bash
-  node .claude/scripts/task-worktree.mjs --root . --create --repo . --branch chore/template-update-{version}
+  node {scripts}/task-worktree.mjs --root . --create --repo . --branch chore/template-update-{version}
   ```
-  The payload is untracked, so it does not appear inside the worktree — keep referencing it at the launcher's absolute path (`{launcher}/.workspace-update`). Everything the update needs travels with the payload, including any `.template-baseline.reconstructed.json` the CLI staged for a pre-baseline workspace. Step 7 commits, pushes, and opens the PR/MR from the worktree.
+  `{scripts}` is `.claude/scripts` when the workspace has the script, `{payload}/.claude/scripts` when it doesn't — pre-0.18 workspaces predate the task scripts entirely, and the payload always carries them (the same rule Step 2 already uses for the classifier). The payload is untracked, so it does not appear inside the worktree — keep referencing it at the launcher's absolute path (`{launcher}/.workspace-update`). Everything the update needs travels with the payload, including any `.template-baseline.reconstructed.json` the CLI staged for a pre-baseline workspace. Step 7 commits, pushes, and opens the PR/MR from the worktree.
 - **No remote** — apply in place. The Step 7 commit lands on the launcher's default branch: the one sanctioned launcher commit, because a repo with no remote has nowhere else for a template update to go. The payload path is `.workspace-update/`.
 
 In the commands below, `{payload}` is `.workspace-update` in the no-remote flow and `{launcher}/.workspace-update` in the worktree flow.
@@ -59,8 +59,9 @@ It runs from the payload precisely so workspaces that don't have it installed ye
 - `localOnly` — installed file differs from the payload, but the payload equals the baseline: these are local edits to files the template didn't touch. Informational only — never asked about, never applied
 - `deletedLocally` — the baseline records the file and the payload still ships it, but it is missing from the workspace (deleted locally, or declined at install time). Step 3 asks once whether to restore the list
 - `activated` — the payload ships `rules/{name}.md.skip` while the workspace keeps `{name}.md` active: the rule was deliberately activated. Nothing to install — the active rule stays.
-- `removed` — installed file with no counterpart in the payload. The config files above never appear here (the template dropping one hands it to the workspace). Gitignored paths, `.claude/worktrees/`, and files listed in `workspace.json` → `workspace.localFiles` (an array of `.claude/`-relative paths or globs the workspace owns) are excluded automatically, so only real template removals are listed.
+- `removed` — installed file with no counterpart in the payload. The config files above never appear here (the template dropping one hands it to the workspace). Gitignored paths, `.claude/worktrees/`, and files listed in `workspace.json` → `workspace.localFiles` (an array of `.claude/`-relative paths or globs the workspace owns) are excluded automatically. An entry is a plain path, `{ file, referencedBy }` — a hook a workspace-only `settings.json` entry still registers (the paths say where) — or `{ file, userOwned: true }` — no baseline record, so the template never shipped it and it is the workspace's own.
 - `staleTests` — `*.test.mjs` files under `.claude/` the payload doesn't carry. The package never ships tests, so these came from a dev checkout and no update refreshes them (Step 3 offers removal).
+- `implicitDefaults` — `workspace.json` keys whose absence carried a default in the version being upgraded from. Today: `canonicalBudgetBytes`, an implicit 40960-byte budget between v0.15.0-beta.1 and v0.19.0-beta.0 (before v0.15 there was no budget at all; since v0.19 absent means off). An upgrade from inside that window into a workspace.json that never set the key reports `{ key, value, reason }` — Step 3's workspace.json step writes the value explicitly so trimming doesn't silently stop.
 
 Content is compared with line endings normalized (CRLF ≡ LF; binary files byte-exact), so a Windows autocrlf checkout does not read as locally modified.
 
@@ -73,7 +74,7 @@ Report with version info from the manifest:
 "Template update: v{fromVersion} → v{templateVersion}. {N} new files, {U} template-updated, {M} locally modified, {C} config files to merge, {L} local-only edits, {D} deleted locally, {A} activated rules, {R} removed files, {K} unchanged."
 ```
 
-If `new`, `updated`, `differs`, `config` (an entry with empty `added`/`workspaceOnly`/`changed` lists and no array elements to merge counts as empty), `deletedLocally`, `activated`, and `removed` are all empty, report: "Workspace is up to date (template v{templateVersion}). No changes needed." (`localOnly` files are informational and `staleTests` may still be worth offering.)
+If `new`, `updated`, `differs`, `config` (an entry with empty `added`/`workspaceOnly`/`changed` lists and no array elements to merge counts as empty), `deletedLocally`, `activated`, `removed`, and `implicitDefaults` are all empty, report: "Workspace is up to date (template v{templateVersion}). No changes needed." (`localOnly` files are informational and `staleTests` may still be worth offering.)
 
 ### Step 2b: Historical .gitignore safety check
 
@@ -101,19 +102,19 @@ Batch the safe cases, ask on the rest:
 - **Config files (`config`):** `.mcp.json` and `.claude/settings.json` are never copied wholesale — a batch copy wipes the workspace's own MCP servers and settings. Merge each entry key by key (values from `{payload}/{path}` and the workspace's copy): add every `added` key, keep every `workspaceOnly` key untouched, and for each `changed` key ask — "Template changed `{key}` in `{path}`. Take the template's, keep yours, or inspect?" Array-valued keys merge as a union, no ask: keep the workspace's elements in place and append each `arrays` entry's `added` elements (`workspaceOnly` elements are already in place, listed for visibility). `notInstalled` — ask once: "Install {path} from the template? [Y/n]" (never install a config silently); `unparseable` means broken JSON on one side — show the file and ask, never merge blind.
 - **Local-only edits (`localOnly`):** nothing to decide — these are your local edits to files the template hasn't changed since the last update. List them in the summary (so the edits are visible) and move on; do not ask about them.
 - **Deleted locally (`deletedLocally`):** "These {N} files exist in the template and its baseline but not in your workspace — deleted locally (or never installed). Restore from the template? [Y/n]" — one confirmation for the whole list. Restoring installs the payload's version of each.
-- **Removed in template (`removed`):** "Template removed {file}. Delete locally? [y/N]" — conservative default.
+- **Removed in template (`removed`):** a plain path — "Template removed {file}. Delete locally? [y/N]" (conservative default). An entry `{ file, referencedBy }` is a hook still registered in `.claude/settings.json`: ask once — "Template removed {file}, which your settings.json still references via {refs}. Remove the file and those settings entries together? [Y/n]" — never delete the file and leave a settings entry pointing at nothing. An entry `{ file, userOwned: true }` was never shipped by the template (no baseline record): do not offer deletion — suggest claiming it in `workspace.json` → `workspace.localFiles` instead, showing the exact entry (`"localFiles": ["skills/my-skill/**"]`, or `["rules/my-rule.md"]` for a single file) so future updates skip it.
 - **Activated rules (`activated`):** keep the active file, install nothing — report: "Rule {name} is active here and optional in the template; your activation is preserved."
 - **Stale tests (`staleTests`):** "These {N} test files under .claude/ came from a dev checkout — the package never ships them, so updates can't refresh them (tests live in the template repo). Remove them? [Y/n]" — one confirmation for the whole list.
 - **Hook migration (.sh to .mjs):** Detect old `.sh` hooks in `.claude/hooks/` that have `.mjs` replacements in the payload. Offer: "Hook {name}.sh has a .mjs replacement in the update. Replace and update settings.json commands? [Y/n]" — this is a one-time migration for workspaces upgrading from pre-0.2.0
 
 Also handle these non-component files from the payload:
 
-- **workspace.json keys:** Compare the `workspace` object of the payload's `workspace.json.tmpl` with the installed `workspace.json`, key by key. For each key the template ships that the workspace lacks, show its template default and ask before adding. Never remove an existing key just because the template no longer ships it. `canonicalBudgetBytes` is opt-in since v0.19 — leave an existing value alone and mention it can be removed to turn the budget off.
+- **workspace.json keys:** First apply any `implicitDefaults` from Step 2 — write the reported key and value into the workspace.json being updated and tell the operator: "kept your previous canonical trimming (40 KB) explicitly; remove the key to turn it off." Then compare the `workspace` object of the payload's `workspace.json.tmpl` with the installed `workspace.json`, key by key. For each key the template ships that the workspace lacks, show its template default and ask before adding. Never remove an existing key just because the template no longer ships it. `canonicalBudgetBytes` is opt-in since v0.19 — leave an existing value alone and mention it can be removed to turn the budget off.
 - **CLAUDE.md:** If `{payload}/CLAUDE.md.tmpl` exists, merge — never regenerate from scratch:
   ```bash
   node {payload}/.claude/scripts/classify-update.mjs --root . --payload {payload} --merge-claude-md
   ```
-  The command prints the merged CLAUDE.md: template-owned lines take the template's new versions (skill-list entries match by their `/name`), while lines the template doesn't have — the workspace's own skill entries, custom bullets, whole sections — are kept in place. Two consequences to watch in the diff: an edit made directly to a template-owned skill line is replaced by the template's new wording, and a template prose line that was reworded locally survives alongside the new template line (it may appear twice). The merge keeps the current file's line endings. Show the user the diff against the current CLAUDE.md before writing the merged result. (The two JSON configs are the `config` list's, not this block's.)
+  The command prints JSON `{ claudeMd, missingIncludes }`. `claudeMd` is the merged CLAUDE.md: template-owned lines take the template's new versions (skill-list entries match by their `/name`), while lines the template doesn't have — the workspace's own skill entries, custom bullets, whole sections — are kept in place. `missingIncludes` lists the `@{file}` include lines the merged file carries whose targets don't exist here (machine-local `local-only-*` targets are exempt — expected absent, never reported). Two consequences to watch in the diff: an edit made directly to a template-owned skill line is replaced by the template's new wording, and a template prose line that was reworded locally survives alongside the new template line (it may appear twice). The merge keeps the current file's line endings. Show the user the diff against the current CLAUDE.md before writing the merged result, and act on each `missingIncludes` entry — ask "The merged CLAUDE.md includes `{file}`, which doesn't exist here. Create the stub, or leave the include out?" — never write a dangling include silently. (The two JSON configs are the `config` list's, not this block's.)
 - **.gitignore:** Merge new entries from the payload's `_gitignore` into the existing `.gitignore` — do not remove user-added lines. An ignore pattern does not untrack already-committed files: if the workspace still tracks the per-machine catalogs the template now ignores (`git ls-files -- 'workspace-context/team-member/*/index.md'`), untrack them (`git rm -r --cached 'workspace-context/team-member/*/index.md'`), or every machine's regenerations keep dirtying pulls.
 
 ### Step 4: Update version and write the baseline
@@ -176,7 +177,7 @@ node {payload}/.claude/scripts/maintenance-audit.mjs --root . --changed workspac
 
 Run it from the payload for the same reason as the classifier in Step 2: the workspace's own copy may predate this update. It reuses the sections of `/maintenance` audit that a script can decide (cross-references, frontmatter, structure, git state, catalog integrity, budgets, freshness) and marks findings on changed files `(from this update)`.
 
-Present its report as the verification result. Git-state warnings are expected here — the update's commit hasn't landed yet (Step 7). Delete the temp changed list afterwards.
+Present its report as the verification result. Git-state warnings are expected here — the update's commit hasn't landed yet (Step 7) — and the launcher's replaced `workspace-update` skill copy is reported as info while it matches the payload's. Missing `@local-only-*` imports are info too (machine-local files never appear inside the worktree). Delete the temp changed list afterwards.
 
 - Findings labeled `(from this update)` — caused by this update; fix before committing (usually a new skill missing from CLAUDE.md's list, or a stale catalog).
 - Other findings — pre-existing; mention briefly.
@@ -197,12 +198,24 @@ Where the commit lands was decided in Step 1 — the launcher's default branch i
   git add -A
   git commit -m "chore: update workspace from template v{fromVersion} to v{templateVersion}"
   ```
-- **Remote exists:** from the task worktree created in Step 1, commit the applied update, push the branch, and open the PR/MR through `node .claude/scripts/task-pr.mjs` — it drives GitHub today and GitLab once gh:185 lands; if it reports the forge unsupported, open the MR with the forge's own CLI (for GitLab, `glab mr create`) from the worktree and say so in the report. After the PR/MR merges, restore the launcher's skill copy before pulling — `--upgrade` replaced `.claude/skills/workspace-update/` in the launcher (a tracked modification) and the merged PR delivers the same content, so a dirty launcher blocks the pull. If `.claude/skills/workspace-update/SKILL.md.local-backup` sits there (a customised skill the CLI backed up), move it somewhere safe first (e.g. `workspace-scratchpad/`), then:
-  ```bash
-  git -C {launcher} checkout -- .claude/skills/workspace-update
-  git -C {launcher} clean -f -- .claude/skills/workspace-update
-  ```
-  Then pull the launcher and delete the payload (Step 6).
+- **Remote exists:** from the task worktree created in Step 1, commit the applied update, push the branch, and open the PR/MR through `node {scripts}/task-pr.mjs` (`{scripts}` resolves as in Step 1 — the payload's copy whenever the workspace's own is missing). The workspace repo is addressed as `.`, so pass its PR body as `--body-file ".={path}"` (a repo with commits to merge but no body file is an error). If task-pr reports the forge unsupported, open the MR with the forge's own CLI (for GitLab, `glab mr create`) from the worktree and say so in the report. After the PR/MR merges, at the launcher and in this order:
+  1. Restore the bootstrapped skill — `--upgrade` replaced `.claude/skills/workspace-update/` in the launcher (a tracked modification) and the merged PR delivers the same content, so a dirty launcher blocks the pull. If `SKILL.md.local-backup` sits there (a customised skill the CLI backed up), move it somewhere safe first (e.g. `workspace-scratchpad/`), then:
+     ```bash
+     git -C {launcher} checkout -- .claude/skills/workspace-update
+     git -C {launcher} clean -f -- .claude/skills/workspace-update
+     ```
+  2. `git -C {launcher} pull --ff-only`
+  3. Rebuild the catalogs — the pull can delete the gitignored per-user `workspace-context/team-member/{user}/index.md` (tracked before this update, untracked by it) that `CLAUDE.local.md` imports:
+     ```bash
+     node {launcher}/.claude/scripts/build-workspace-context.mjs --write --root {launcher}
+     ```
+  4. Remove the update worktree and its local branch:
+     ```bash
+     node {launcher}/.claude/scripts/task-worktree.mjs --root {launcher} --remove --repo . --branch chore/template-update-{version} --delete-branch
+     ```
+  5. Delete the payload (Step 6).
+
+  Newly added skills appear only after this merge — start a new chat or `/reload` to pick them up.
 
 Report: "Workspace updated to v{templateVersion}. Restart Claude Code if rules or hooks changed."
 
@@ -212,7 +225,7 @@ After the update is applied, if the sessions directory (`workspace.workSessionsD
 
 ## Notes
 
-- The CLI (`npx @ulysses-ai/create-workspace --upgrade`) stages the payload, installs the current copy of this skill into `.claude/skills/workspace-update/` (so an outdated installed flow never processes a new payload; a locally customised SKILL.md is backed up as `SKILL.md.local-backup` first), and stages a reconstructed baseline inside the payload as `.template-baseline.reconstructed.json` when the workspace has none — the launcher itself gets no new untracked files, and Step 7 restores the launcher's skill copy before the post-merge pull
+- The CLI (`npx @ulysses-ai/create-workspace --upgrade`) stages the payload, installs the current copy of this skill into `.claude/skills/workspace-update/` (so an outdated installed flow never processes a new payload; a locally customised SKILL.md is backed up as `SKILL.md.local-backup` first), and stages a reconstructed baseline inside the payload as `.template-baseline.reconstructed.json` when the workspace has none — the launcher itself gets no new untracked files, and Step 7 restores the launcher's skill copy before the post-merge pull, rebuilds the per-user catalogs the pull may delete, and removes the update worktree with its branch
 - Never overwrites without asking — `new` and `updated` files are batched behind one confirmation; `differs` files are asked per file; `config` files (`.mcp.json`, `.claude/settings.json`) are merged key by key (array-valued keys union-merged) and never copied wholesale; `localOnly` files are never asked about (local edits to files the template didn't touch)
 - Preserves local modifications, custom content, the workspace's own MCP servers and settings, existing `workspace.json` keys, and deliberately activated rules
 - The template baseline (`.claude/.template-baseline.json`) is what separates `updated`, `differs`, and `localOnly`: entries hold the payload hash of the last-shipped content (unapplied updates keep the older entry), so a deliberately kept local edit stays visible across updates while an untouched file never prompts