@indigoai-us/hq-cloud 6.14.11 → 6.14.13

package/src/bin/sync-runner.ts

@@ -62,7 +62,9 @@ import * as fs from "fs";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "url";
 import {
+  CognitoRefreshError,
   getValidAccessToken,
+  invalidateCachedTokensByFingerprint,
   loadCachedTokens,
   VaultClient,
   VaultAuthError,
@@ -532,6 +534,16 @@ export type { PullScope };
  */
 const MEMBERSHIPS_RETRY_BACKOFFS_MS: readonly number[] = [50, 100];
 
+const REAUTH_MESSAGE =
+  "Your HQ session needs a quick refresh. Sign in again to keep sync moving.";
+
+/**
+ * Internal-only result used between a watch pass and its owning loop. The
+ * outer process still exits 0 (auth-required is a handled UX state), while
+ * the loop stops instead of retrying a known-unusable session forever.
+ */
+export const AUTH_REQUIRED_PASS_EXIT = 18;
+
 /**
  * Call `listMyMemberships()` with up to 3 attempts and a small linear
  * backoff between them. The single network call that drives every cloud
@@ -589,6 +601,8 @@ export interface RunnerDeps {
   stderr?: { write: (chunk: string) => boolean | void };
   /** Resolve a valid access token. Defaults to `getValidAccessToken` non-interactive. */
   getAccessToken?: () => Promise<string>;
+  /** Invalidate only the rejected token generation. Injectable for tests. */
+  clearSession?: (tokenFingerprint?: string) => void;
   /**
    * Read the caller's identity claims (sub/email/name) off the cached Cognito
    * idToken. Defaults to decoding `loadCachedTokens().idToken`. Returns `null`
@@ -621,6 +635,8 @@ export interface RunnerDeps {
   ) => Promise<void>;
   /** Internal: set when runRunner is invoked under the per-root operation lock. */
   operationLockAlreadyHeld?: boolean;
+  /** Internal watch-loop result override; one-shot callers keep exit 0. */
+  authRequiredExitCode?: number;
   /** Share function (push phase). Defaults to `cli/share.share`. */
   share?: (options: ShareOptions) => Promise<ShareResult>;
   /**
@@ -1109,14 +1125,27 @@ export async function runRunner(
   const getAccessToken =
     deps.getAccessToken ??
     (() => getValidAccessToken(DEFAULT_COGNITO, { interactive: false }));
+  const clearSession =
+    deps.clearSession ?? invalidateCachedTokensByFingerprint;
   try {
     await getAccessToken();
   } catch (err) {
+    if (
+      (err instanceof CognitoRefreshError && !err.requiresReauth) ||
+      isTransientNetworkError(err)
+    ) {
+      emit({
+        type: "error",
+        path: "(auth)",
+        message: err instanceof Error ? err.message : String(err),
+      });
+      return TRANSIENT_NETWORK_EXIT;
+    }
     emit({
       type: "auth-error",
-      message: err instanceof Error ? err.message : String(err),
+      message: REAUTH_MESSAGE,
     });
-    return 0;
+    return deps.authRequiredExitCode ?? 0;
   }
 
   // ---- vault client -----------------------------------------------------
@@ -1257,11 +1286,12 @@ export async function runRunner(
     memberships = resolution.memberships;
   } catch (err) {
     if (err instanceof VaultAuthError) {
+      clearSession(err.tokenFingerprint);
       emit({
         type: "auth-error",
-        message: err.message,
+        message: REAUTH_MESSAGE,
       });
-      return 0;
+      return deps.authRequiredExitCode ?? 0;
     }
     // Surface the failure as an error event for observability either way.
     emit({
@@ -1279,15 +1309,31 @@ export async function runRunner(
     return isTransientNetworkError(err) ? TRANSIENT_NETWORK_EXIT : 1;
   }
 
-  const targetPlan = await buildFanoutPlan({
-    memberships,
-    companies: parsed.companies,
-    personal: parsed.personal,
-    skipPersonal: parsed.skipPersonal,
-    client,
-    claims,
-    resolveSkipPersonal,
-  });
+  let targetPlan: Awaited<ReturnType<typeof buildFanoutPlan>>;
+  try {
+    targetPlan = await buildFanoutPlan({
+      memberships,
+      companies: parsed.companies,
+      personal: parsed.personal,
+      skipPersonal: parsed.skipPersonal,
+      client,
+      claims,
+      resolveSkipPersonal,
+    });
+  } catch (err) {
+    if (err instanceof VaultAuthError) {
+      clearSession(err.tokenFingerprint);
+      emit({ type: "auth-error", message: REAUTH_MESSAGE });
+      return deps.authRequiredExitCode ?? 0;
+    }
+    emit({
+      type: "error",
+      message: err instanceof Error ? err.message : String(err),
+      path: "(discovery)",
+    });
+    emitRunnerTerminalTelemetry({ status: "failed" });
+    return isTransientNetworkError(err) ? TRANSIENT_NETWORK_EXIT : 1;
+  }
   if (targetPlan.status === "setup-needed") {
     emit({ type: "setup-needed" });
     return 0;
@@ -1306,24 +1352,34 @@ export async function runRunner(
   // ---- fanout -----------------------------------------------------------
   const syncFn = deps.sync ?? defaultSync;
   const shareFn = deps.share ?? defaultShare;
-  const fanout = await executeCompanyFanout({
-    plan,
-    direction: parsed.direction,
-    hqRoot: parsed.hqRoot,
-    onConflict: parsed.onConflict,
-    client,
-    vaultConfig,
-    ...(uploadAuthor ? { uploadAuthor } : {}),
-    ...(deps.operationLockAlreadyHeld ? { operationLockAlreadyHeld: true } : {}),
-    syncFn,
-    shareFn,
-    resolveDeletePolicy,
-    emit,
-    scopePaths: parsed.scopePaths,
-    telemetryClient: client,
-    telemetryClaims: claims,
-    telemetrySessionId,
-  });
+  let fanout: Awaited<ReturnType<typeof executeCompanyFanout>>;
+  try {
+    fanout = await executeCompanyFanout({
+      plan,
+      direction: parsed.direction,
+      hqRoot: parsed.hqRoot,
+      onConflict: parsed.onConflict,
+      client,
+      vaultConfig,
+      ...(uploadAuthor ? { uploadAuthor } : {}),
+      ...(deps.operationLockAlreadyHeld ? { operationLockAlreadyHeld: true } : {}),
+      syncFn,
+      shareFn,
+      resolveDeletePolicy,
+      emit,
+      scopePaths: parsed.scopePaths,
+      telemetryClient: client,
+      telemetryClaims: claims,
+      telemetrySessionId,
+    });
+  } catch (err) {
+    if (err instanceof VaultAuthError) {
+      clearSession(err.tokenFingerprint);
+      emit({ type: "auth-error", message: REAUTH_MESSAGE });
+      return deps.authRequiredExitCode ?? 0;
+    }
+    throw err;
+  }
   const { errors, allConflicts, meaningfulOutcomeCount } = fanout;
   const rollup = rollupAllComplete(plan, fanout.stateByCompany);
 
@@ -1787,7 +1843,11 @@ export async function runRunnerWithLoop(
   const parsed = parseArgs(argv);
   const runtime = {
     runPassWithOperationLockAlreadyHeld: (passArgv: string[]) =>
-      runRunner(passArgv, { operationLockAlreadyHeld: true }),
+      runRunner(passArgv, {
+        operationLockAlreadyHeld: true,
+        authRequiredExitCode: AUTH_REQUIRED_PASS_EXIT,
+      }),
+    authRequiredPassExit: AUTH_REQUIRED_PASS_EXIT,
     defaultGetIdTokenClaims,
     defaultGetAccessToken: () =>
       getValidAccessToken(DEFAULT_COGNITO, { interactive: false }),

package/src/cli/reindex.test.ts

@@ -4,8 +4,8 @@
  *
  * The logic is implemented natively in TypeScript in ./reindex.ts; these tests
  * exercise reindex() directly against a temp HQ tree, asserting the observable
- * filesystem outcomes (skill wrappers, personal-overlay mirroring) rather than
- * re-deriving the implementation internals.
+ * filesystem outcomes (skill wrappers, retired personal-overlay mirror cleanup)
+ * rather than re-deriving the implementation internals.
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
@@ -112,26 +112,29 @@ describe("reindex", () => {
     );
   });
 
-  it("mirrors the personal overlay into core/<type>/", () => {
+  it("does NOT mirror the personal overlay into core/<type>/ (read directly now)", () => {
     fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
     fs.writeFileSync(path.join(root, "personal/policies/myrule.md"), "rule\n");
 
     const { status } = reindex({ repoRoot: root });
     expect(status).toBe(0);
 
-    const link = path.join(root, "core/policies/myrule.md");
-    expect(fs.lstatSync(link).isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(link)).toBe("../../personal/policies/myrule.md");
+    // personal is the sole read source — reindex must NOT create a mirror
+    // symlink in core/policies. The HQ tooling reads personal/policies directly,
+    // so a mirror would only double-surface every entry.
+    expect(fs.existsSync(path.join(root, "core/policies/myrule.md"))).toBe(false);
   });
 
-  it("collapses per-file overlay-skip spam into ONE summary line (HQ-SYNC-2)", () => {
-    // A REAL core file sits where an overlay symlink would go — the legitimate
-    // no-op that used to spam one stderr line per entry and flood the Sentry
-    // breadcrumb ring, evicting the real per-company sync error.
-    fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
-    fs.writeFileSync(path.join(root, "personal/policies/collide.md"), "rule\n");
-    fs.mkdirSync(path.join(root, "core/policies"), { recursive: true });
-    fs.writeFileSync(path.join(root, "core/policies/collide.md"), "REAL core file\n");
+  it("collapses per-file wrapper-skip spam into ONE summary line (HQ-SYNC-2)", () => {
+    // A REAL file sits where a managed skill-wrapper symlink would go — the
+    // legitimate no-op that used to spam one stderr line per entry and flood the
+    // Sentry breadcrumb ring, evicting the real per-company sync error.
+    writeSkill("core/skills/demo");
+    reindex({ repoRoot: root });
+    // Replace the managed per-file symlink with a real (non-symlink) file.
+    const slot = path.join(root, ".claude/skills/core:demo/SKILL.md");
+    fs.rmSync(slot);
+    fs.writeFileSync(slot, "REAL file, not a link\n");
 
     const writes: string[] = [];
     const spy = vi
@@ -150,7 +153,7 @@ describe("reindex", () => {
 
     expect(status).toBe(0);
     // The pre-existing real file is left untouched (never overwritten).
-    expect(fs.lstatSync(path.join(root, "core/policies/collide.md")).isSymbolicLink()).toBe(false);
+    expect(fs.lstatSync(slot).isSymbolicLink()).toBe(false);
     // No per-file spam…
     expect(stderr).not.toContain("already exists and is not a symlink; skipping");
     // …just ONE collapsed summary naming the count.
@@ -158,11 +161,12 @@ describe("reindex", () => {
     expect(stderr).toContain("HQ_REINDEX_VERBOSE=1");
   });
 
-  it("keeps per-file overlay-skip detail under HQ_REINDEX_VERBOSE=1", () => {
-    fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
-    fs.writeFileSync(path.join(root, "personal/policies/collide.md"), "rule\n");
-    fs.mkdirSync(path.join(root, "core/policies"), { recursive: true });
-    fs.writeFileSync(path.join(root, "core/policies/collide.md"), "REAL\n");
+  it("keeps per-file wrapper-skip detail under HQ_REINDEX_VERBOSE=1", () => {
+    writeSkill("core/skills/demo");
+    reindex({ repoRoot: root });
+    const slot = path.join(root, ".claude/skills/core:demo/SKILL.md");
+    fs.rmSync(slot);
+    fs.writeFileSync(slot, "REAL\n");
 
     const writes: string[] = [];
     const spy = vi
@@ -180,7 +184,7 @@ describe("reindex", () => {
     }
     const stderr = writes.join("");
     expect(stderr).toContain(
-      "core/policies/collide.md already exists and is not a symlink; skipping",
+      ".claude/skills/core:demo/SKILL.md already exists and is not a symlink; skipping",
     );
   });
 
@@ -203,75 +207,55 @@ describe("reindex", () => {
     ).toBe("../../../core/skills/demo/SKILL.md");
   });
 
-  // ── Cleanup pass C: orphan personal-overlay mirror symlinks ──────────────
-  // The mirror creates core/<type>/<entry> -> ../../personal/<type>/<entry>.
-  // When the personal source is later deleted/renamed, the next reindex must
-  // prune the now-dangling core symlink — the gap that used to leave a retired
-  // personal policy pointer surfacing in core/policies/ until hand-deleted.
+  // ── Migration cleanup: retired personal-overlay mirror symlinks ──────────
+  // reindex no longer CREATES core/<type>/<entry> -> ../../personal/<type>/<entry>
+  // mirror symlinks — personal is read directly. A managed mirror symlink a
+  // PRIOR release left behind must be pruned on the next reindex, WHETHER OR NOT
+  // its personal source still exists, so it can never double-surface alongside
+  // the direct read.
+
+  // Forge a legacy managed mirror symlink exactly as the old reindex would have.
+  function legacyMirror(type: string, entry: string): string {
+    const coreDir = path.join(root, "core", type);
+    fs.mkdirSync(coreDir, { recursive: true });
+    const link = path.join(coreDir, entry);
+    fs.symlinkSync(`../../personal/${type}/${entry}`, link);
+    return link;
+  }
 
-  it("prunes an orphan personal-overlay mirror symlink when the source is deleted", () => {
+  it("prunes a legacy mirror symlink even when its personal source still exists", () => {
     fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
     fs.writeFileSync(path.join(root, "personal/policies/myrule.md"), "rule\n");
-    reindex({ repoRoot: root });
-    const link = path.join(root, "core/policies/myrule.md");
+    const link = legacyMirror("policies", "myrule.md");
     expect(fs.lstatSync(link).isSymbolicLink()).toBe(true);
 
-    // Retire the personal source, then reindex again.
-    fs.rmSync(path.join(root, "personal/policies/myrule.md"));
     expect(reindex({ repoRoot: root }).status).toBe(0);
 
-    // The dangling mirror symlink is gone — no entry at all (lstat throws).
+    // Pruned — personal/policies/myrule.md is read directly now, no mirror.
     expect(fs.existsSync(link)).toBe(false);
     expect(() => fs.lstatSync(link)).toThrow();
+    // The personal source itself is untouched.
+    expect(fs.existsSync(path.join(root, "personal/policies/myrule.md"))).toBe(true);
   });
 
-  it("prunes mirror symlinks when the ENTIRE personal/<type>/ directory is removed", () => {
-    fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
-    fs.writeFileSync(path.join(root, "personal/policies/a.md"), "a\n");
-    fs.writeFileSync(path.join(root, "personal/policies/b.md"), "b\n");
-    reindex({ repoRoot: root });
-    expect(fs.lstatSync(path.join(root, "core/policies/a.md")).isSymbolicLink()).toBe(true);
-    expect(fs.lstatSync(path.join(root, "core/policies/b.md")).isSymbolicLink()).toBe(true);
+  it("prunes a legacy mirror symlink whose personal source was deleted", () => {
+    const link = legacyMirror("policies", "gone.md"); // dangling: no source
+    expect(fs.lstatSync(link).isSymbolicLink()).toBe(true);
 
-    // Nuke the whole personal/policies dir (the creation loop's isDir guard would
-    // skip the type entirely — the prune must still run and clean both links).
-    fs.rmSync(path.join(root, "personal/policies"), { recursive: true, force: true });
     expect(reindex({ repoRoot: root }).status).toBe(0);
-
-    expect(fs.existsSync(path.join(root, "core/policies/a.md"))).toBe(false);
-    expect(fs.existsSync(path.join(root, "core/policies/b.md"))).toBe(false);
-  });
-
-  it("keeps a LIVE personal-overlay mirror symlink (only orphans are pruned)", () => {
-    fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
-    fs.writeFileSync(path.join(root, "personal/policies/keep.md"), "keep\n");
-    fs.writeFileSync(path.join(root, "personal/policies/drop.md"), "drop\n");
-    reindex({ repoRoot: root });
-
-    // Retire only one source; the other stays live.
-    fs.rmSync(path.join(root, "personal/policies/drop.md"));
-    reindex({ repoRoot: root });
-
-    const keep = path.join(root, "core/policies/keep.md");
-    expect(fs.lstatSync(keep).isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(keep)).toBe("../../personal/policies/keep.md");
-    expect(fs.readFileSync(keep, "utf-8")).toBe("keep\n");
-    expect(fs.existsSync(path.join(root, "core/policies/drop.md"))).toBe(false);
+    expect(fs.existsSync(link)).toBe(false);
   });
 
-  it("prunes an orphan personal-overlay mirror DIRECTORY symlink (DEV-1767 shape)", () => {
-    // personal/knowledge/<kb>/ mirrors as a directory symlink; deleting the kb
-    // must prune the dangling directory symlink too (rmSync on a symlink, not
-    // recursive into a resolved dir).
+  it("prunes a legacy mirror DIRECTORY symlink without recursing into the source (DEV-1767 shape)", () => {
     fs.mkdirSync(path.join(root, "personal/knowledge/my-kb"), { recursive: true });
     fs.writeFileSync(path.join(root, "personal/knowledge/my-kb/note.md"), "n\n");
-    reindex({ repoRoot: root });
-    const link = path.join(root, "core/knowledge/my-kb");
+    const link = legacyMirror("knowledge", "my-kb"); // directory-shaped symlink
     expect(fs.lstatSync(link).isSymbolicLink()).toBe(true);
 
-    fs.rmSync(path.join(root, "personal/knowledge/my-kb"), { recursive: true, force: true });
     expect(reindex({ repoRoot: root }).status).toBe(0);
     expect(fs.existsSync(link)).toBe(false);
+    // rmSync on the symlink must NOT recurse into the resolved directory.
+    expect(fs.existsSync(path.join(root, "personal/knowledge/my-kb/note.md"))).toBe(true);
   });
 
   it("leaves a real core file and a foreign symlink in core/<type>/ untouched (cross-check invariant)", () => {
@@ -369,24 +353,21 @@ describe("reindex", () => {
     expect(fs.readlinkSync(agentsLink)).toBe("../../../core/skills/demo/agents");
   });
 
-  it("mirrors a personal/<type> DIRECTORY entry as a directory symlink into core/ and preserves it", () => {
-    // personal/knowledge/<kb>/ is a directory of notes — the exact DEV-1767
-    // reindex artifact shape that rescue/update-hq used to choke on.
+  it("does NOT mirror a personal/<type> DIRECTORY entry into core/ (read directly now)", () => {
+    // personal/knowledge/<kb>/ is a directory of notes. It used to mirror as a
+    // core/ directory symlink (the DEV-1767 shape rescue/update-hq choked on).
+    // The mirror is retired: qmd indexes personal/knowledge directly, so reindex
+    // must leave core/knowledge alone — nothing to choke on anymore.
     fs.mkdirSync(path.join(root, "personal/knowledge/my-kb"), { recursive: true });
     fs.writeFileSync(path.join(root, "personal/knowledge/my-kb/note.md"), "owned by personal\n");
 
     expect(reindex({ repoRoot: root }).status).toBe(0);
 
-    const link = path.join(root, "core/knowledge/my-kb");
-    expect(fs.lstatSync(link).isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(link)).toBe("../../personal/knowledge/my-kb");
-    expect(fs.statSync(link).isDirectory()).toBe(true);
-    expect(fs.readFileSync(path.join(link, "note.md"), "utf-8")).toBe("owned by personal\n");
-
-    // Idempotent re-run: existing directory symlink recognised, left in place.
-    expect(reindex({ repoRoot: root }).status).toBe(0);
-    expect(fs.readlinkSync(link)).toBe("../../personal/knowledge/my-kb");
-    expect(fs.readFileSync(path.join(link, "note.md"), "utf-8")).toBe("owned by personal\n");
+    expect(fs.existsSync(path.join(root, "core/knowledge/my-kb"))).toBe(false);
+    // The personal source is untouched.
+    expect(fs.readFileSync(path.join(root, "personal/knowledge/my-kb/note.md"), "utf-8")).toBe(
+      "owned by personal\n",
+    );
   });
 
   // ── operation lock: reindex uses a SEPARATE scope from sync/rescue ──────
@@ -497,22 +478,6 @@ describe("reindex", () => {
     }
   });
 
-  it("does not abort reindex when a core/<type> mirror mkdir fails", () => {
-    writeSkill("core/skills/demo");
-    fs.mkdirSync(path.join(root, "personal/knowledge/my-kb"), { recursive: true });
-    fs.writeFileSync(path.join(root, "personal/knowledge/my-kb/note.md"), "n\n");
-
-    hoisted.failMkdirContaining = path.join("core", "knowledge");
-    try {
-      expect(reindex({ repoRoot: root }).status).toBe(0);
-    } finally {
-      hoisted.failMkdirContaining = "";
-    }
-
-    // The mirror for the failed type is skipped; skill surfacing still happened.
-    expect(fs.existsSync(path.join(root, ".claude/skills/core:demo"))).toBe(true);
-  });
-
   // ── HQ-CLI-4: symlink creation is privileged on Windows. Without Developer
   //    Mode, fs.symlinkSync throws EPERM. The HQ-B0 work guarded every mkdir
   //    site but left the symlink sites unguarded, so `hq reindex` still aborted
@@ -536,28 +501,6 @@ describe("reindex", () => {
     ).toBe(false);
   });
 
-  it("does not abort reindex when a personal-mirror symlink fails with EPERM, and other work still runs", () => {
-    writeSkill("core/skills/demo");
-    fs.mkdirSync(path.join(root, "personal/knowledge/my-kb"), { recursive: true });
-    fs.writeFileSync(path.join(root, "personal/knowledge/my-kb/note.md"), "n\n");
-
-    // Fail ONLY the core/<type> personal-mirror symlinks; wrapper symlinks
-    // succeed, proving the skip is scoped and the reindex completes.
-    hoisted.failSymlinkContaining = path.join("core", "knowledge");
-    try {
-      expect(reindex({ repoRoot: root }).status).toBe(0);
-    } finally {
-      hoisted.failSymlinkContaining = "";
-    }
-
-    // The personal mirror was skipped (EPERM)...
-    expect(fs.existsSync(path.join(root, "core/knowledge/my-kb"))).toBe(false);
-    // ...but unaffected work still happened: the skill wrapper + its symlink.
-    expect(
-      fs.lstatSync(path.join(root, ".claude/skills/core:demo/SKILL.md")).isSymbolicLink(),
-    ).toBe(true);
-  });
-
   // --- multi-harness session-log capture into workspace/.session-logs/<harness>/
   describe("session-log capture", () => {
     let claudeDir: string; // CLAUDE_CONFIG_DIR

package/src/cli/reindex.ts

@@ -1,9 +1,10 @@
 /**
  * hq reindex — surfaces namespaced skills as Claude Code skill wrappers under
- * .claude/skills/<ns>:<skill>/ (one symlink per source file), mirrors
- * personal/{knowledge,policies,workers,settings}/<entry> into core/<type>/,
- * prunes orphan wrappers + legacy command symlinks, captures this HQ tree's
- * coding-harness session logs (Claude Code / Codex / Grok) into
+ * .claude/skills/<ns>:<skill>/ (one symlink per source file), prunes orphan
+ * wrappers + legacy command symlinks (plus a migration cleanup of retired
+ * personal/{knowledge,policies,workers,settings} mirror symlinks in core/<type>/
+ * — that overlay is now read directly from personal/, not mirrored), captures
+ * this HQ tree's coding-harness session logs (Claude Code / Codex / Grok) into
  * workspace/.session-logs/<harness>/, and regenerates the workers registry.
  *
  * The logic historically lived in a bundled bash script (scripts/reindex.sh)
@@ -689,63 +690,24 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
     }
   }
 
-  // --- Personal type mirroring ----------------------------------------------
-  // Mirror personal/<type>/<entry> into core/<type>/<entry> as symlinks.
-  for (const type of ["knowledge", "policies", "workers", "settings"]) {
-    const personalDir = path.join(root, "personal", type);
-    const coreDir = path.join(root, "core", type);
-
-    if (!isDir(personalDir)) continue;
-    if (!safeMkdir(coreDir, `core/${type} directory`)) continue;
-
-    for (const entry of globEntries(personalDir)) {
-      const entryPath = path.join(personalDir, entry);
-      if (!existsFollow(entryPath)) continue;
-
-      const linkPath = path.join(coreDir, entry);
-      const relativeTarget = `../../personal/${type}/${entry}`;
-
-      const lst = lstatOrNull(linkPath);
-      if (lst && lst.isSymbolicLink()) {
-        const current = readlinkOrNull(linkPath);
-        if (current === relativeTarget) continue;
-        skippedPointsElsewhere++;
-        if (verbose) {
-          warn(
-            `reindex: core/${type}/${entry} already points to '${current}' (expected '${relativeTarget}'); leaving alone`,
-          );
-        }
-        continue;
-      } else if (lst) {
-        skippedNonSymlink++;
-        if (verbose) {
-          warn(`reindex: core/${type}/${entry} already exists and is not a symlink; skipping`);
-        }
-        continue;
-      }
-
-      safeSymlink(relativeTarget, linkPath, `core/${type}/${entry}`);
-    }
-  }
-
-  // --- Cleanup pass C: drop orphan personal-overlay mirror symlinks ----------
-  // The mirror above creates core/<type>/<entry> -> ../../personal/<type>/<entry>
-  // for each LIVE personal entry, but historically never removed that symlink
-  // when its personal source was later deleted or renamed — leaving a dangling
-  // link in core/<type>/ (e.g. a retired personal policy that still surfaced via
-  // the policy-trigger hook until a human hand-deleted it). This pass prunes it.
+  // --- Personal-overlay mirroring: RETIRED + migration cleanup ---------------
+  // personal/{knowledge,policies,workers,settings} is now read DIRECTLY by the
+  // HQ tooling (the inject-policy-on-trigger hook reads personal/policies, the
+  // workers-registry generator walks personal/workers, qmd-reindex-after-sync
+  // registers a personal/knowledge collection, and repo-run-registry reads
+  // personal/settings/orchestrator.yaml). personal is the SOLE read source for
+  // the personal overlay, so reindex no longer SYMLINKS personal/<type>/<entry>
+  // into core/<type>/<entry> — a mirror would now double-surface every entry
+  // (read once directly, once via the link).
   //
-  // Ownership discriminator (policy wrapper-sync-orphan-cleanup-cross-check): a
-  // core/<type>/<entry> is "managed by this mirror" ONLY when it is a symlink
-  // whose target is EXACTLY `../../personal/<type>/<entry>` — i.e. the target
-  // encodes the same <type> and <entry> as the link's own location and name.
-  // That exact cross-check means a real release-shipped core file (not a
-  // symlink), or a human-authored symlink pointing anywhere else, never matches
-  // and is left untouched. A managed link is pruned IFF its target no longer
-  // resolves (existsFollow=false) — which, given the exact-target shape, is
-  // precisely "the personal source was removed". This runs independently of the
-  // creation loop above (note: no `isDir(personalDir)` guard) so that deleting
-  // the ENTIRE personal/<type>/ directory still prunes every mirror it produced.
+  // Migration cleanup: prune any mirror symlink a PRIOR release created —
+  // core/<type>/<entry> whose target is EXACTLY `../../personal/<type>/<entry>`.
+  // That exact-target discriminator (policy wrapper-sync-orphan-cleanup-cross-
+  // check) means a real release-shipped core file (not a symlink) or a human-
+  // authored symlink pointing elsewhere is never touched. Unlike the old
+  // "Cleanup pass C", this prunes the link WHETHER OR NOT its personal source
+  // still exists: the mirror is retired, so every managed link is now stale.
+  // Kept for a few releases so existing trees self-heal on the next reindex.
   for (const type of ["knowledge", "policies", "workers", "settings"]) {
     const coreDir = path.join(root, "core", type);
     for (const entry of globEntries(coreDir)) {
@@ -753,8 +715,7 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
       const lst = lstatOrNull(linkPath);
       if (!lst || !lst.isSymbolicLink()) continue; // real file/dir → not ours
       if (readlinkOrNull(linkPath) !== `../../personal/${type}/${entry}`) continue; // not a managed mirror link
-      if (existsFollow(linkPath)) continue; // live: personal source still present
-      // Managed mirror symlink whose personal source is gone → prune.
+      // Managed mirror symlink from a prior release → prune (mirror is retired).
       try {
         fs.rmSync(linkPath);
       } catch {

package/src/cli/rescue-classify-ordering.test.ts

@@ -143,6 +143,10 @@ describe.skipIf(!gitAvailable)("rescue classify-before-delete + dir-symlink hand
     git(workDir, "init", "-b", "main", "upstream");
     fs.writeFileSync(path.join(upstream, "core/a.md"), "v1\n");
     fs.writeFileSync(path.join(upstream, "core/b.md"), "beta\n");
+    // `.claude/settings.json` is intentionally not supplied by a personal
+    // vault pull. Rescue must lay it down from the release scaffold instead.
+    fs.mkdirSync(path.join(upstream, ".claude"), { recursive: true });
+    fs.writeFileSync(path.join(upstream, ".claude/settings.json"), '{"release":true}\n');
     fs.mkdirSync(path.join(upstream, "core/blocker"), { recursive: true });
     fs.writeFileSync(path.join(upstream, "core/blocker/second.md"), "upstream\n");
     git(upstream, "add", "-A");
@@ -465,6 +469,51 @@ exec ${JSON.stringify(realGit)} "$@"
     }
   });
 
+  it("preserves unreadable machine-local state while overlaying release-owned .claude files", () => {
+    const hqRoot = makeHqRoot();
+    const backupRoot = path.join(workDir, `local-state-backups-${caseSeq}`);
+    const deviceId = path.join(hqRoot, ".local/state/gh/device-id");
+    fs.mkdirSync(path.dirname(deviceId), { recursive: true });
+    fs.writeFileSync(deviceId, "machine-specific\n");
+    // SSM previously ran as root with an empty HOME, so gh could leave this
+    // exact path root-owned and unreadable to the outpost user. A mode-000
+    // fixture exercises the same copy failure without requiring root in CI.
+    fs.chmodSync(deviceId, 0o000);
+
+    try {
+      const r = runRescueCapture(
+        [
+          "--hq-root", hqRoot,
+          "--source", "test/repo",
+          "--ref", "main",
+          "--floor-sha", floorSha,
+          "--backup-dir", backupRoot,
+          "--yes",
+        ],
+        baseEnv,
+      );
+      const out = `${r.stdout}\n${r.stderr}\n${String(r.threw ?? "")}`;
+
+      expect(r.threw, out).toBeUndefined();
+      expect(r.status, out).toBe(0);
+      // The core fixture proves a real rescue apply occurred, while this
+      // release-owned setting proves `.claude` reached the outpost.
+      expect(fs.readFileSync(path.join(hqRoot, "core/a.md"), "utf-8")).toBe("v2\n");
+      expect(fs.readFileSync(path.join(hqRoot, ".claude/settings.json"), "utf-8")).toBe(
+        '{"release":true}\n',
+      );
+      // `.local` survives untouched and is not copied into the safety snapshot.
+      expect(fs.statSync(deviceId).mode & 0o777).toBe(0o000);
+      const snapshots = fs.readdirSync(backupRoot).filter((name) => name.startsWith("pre-update-"));
+      expect(snapshots).toHaveLength(1);
+      expect(lexists(path.join(backupRoot, snapshots[0], ".local"))).toBe(false);
+    } finally {
+      // The fixture is owned by the test process, so restore readability before
+      // the enclosing temp-tree cleanup even when an assertion fails.
+      fs.chmodSync(deviceId, 0o600);
+    }
+  });
+
   it("dry-run never allocates or prunes snapshots", () => {
     const hqRoot = makeHqRoot();
     const backupRoot = path.join(workDir, `dry-backups-${caseSeq}`);