@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/installer-migrations/009-pi-retire-reserved-hooks-dir.cjs

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * Installer migration: retire pi's legacy `<piConfigDir>/hooks/` directory
+ * after GSD's shared hook bundle moved to `<piConfigDir>/gsd-hooks/` (#3023).
+ *
+ * What old artifact is being retired?
+ *   `hooks/` (and its `hooks/lib/` subdirectory) at the pi config root. pi
+ *   reserves that exact name as its own deprecated extension directory and
+ *   warns on every startup whenever it exists — pi's
+ *   `checkDeprecatedExtensionDirs()` fires on mere PATH EXISTENCE, not on the
+ *   directory having contents (unlike the sibling `tools/` check, which does
+ *   `readdir` first). GSD used to install its shared hook bundle at exactly
+ *   that reserved path, so every pi install carried the warning permanently.
+ *   The fix moved the install target to `gsd-hooks/`
+ *   (`hostBehaviors.sharedHooksDirName`), but an EXISTING install that
+ *   upgrades still has the old `hooks/` tree sitting on disk — nothing
+ *   removes it on its own, so the warning would persist forever without this
+ *   migration.
+ *
+ * How do we prove it is GSD-owned?
+ *   Per file, by manifest membership — the same `classifyArtifact()` check
+ *   every other migration in this directory uses. Pre-#3023 pi installs
+ *   record the shared hook bundle under `hooks/…` keys in
+ *   `gsd-file-manifest.json`; the new install target writes `gsd-hooks/…`
+ *   keys instead, which this migration structurally never sees because it
+ *   only ever walks the `hooks/` subtree.
+ *
+ * What happens if the user modified it?
+ *   `backup-and-remove` instead of `remove-managed`, so a locally patched
+ *   hook script is recoverable from the backup rather than silently
+ *   destroyed — mirrors migration 006.
+ *
+ * What happens to files the manifest never recorded?
+ *   Nothing. An unmanifested file under `hooks/` (classification `unknown`)
+ *   is left exactly where it is, and — because its presence keeps the
+ *   directory non-empty — it also keeps the directory itself from being
+ *   retired. That is a deliberate consequence of directory removal being
+ *   gated on emptiness, not a special case.
+ *
+ * What happens to the directory itself?
+ *   `hooks/lib/` and then `hooks/` each get a `remove-empty-dir` action (see
+ *   `evaluateRemoveEmptyDir` in `../installer-migrations.cts`). That action
+ *   only ever calls `fs.rmdirSync` — never a recursive removal — and
+ *   re-checks emptiness immediately before doing so, so a directory that
+ *   still holds anything (an unmanifested file, or a file-level action that
+ *   failed to apply) is left in place rather than assumed empty. Actions are
+ *   emitted deepest-first (`hooks/lib` before `hooks`) so the parent has a
+ *   chance to become empty in the same pass.
+ *
+ * What happens if it is missing?
+ *   No actions. A fresh post-#3023 pi install never creates `hooks/` at all,
+ *   and an already-migrated install has nothing left to retire — both plan
+ *   empty, so the migration is idempotent.
+ *
+ * What runtime and scope does it affect?
+ *   pi only, global and local. No other runtime's install is affected:
+ *   `hostBehaviors.sharedHooksDirName` defaults to `'hooks'` for every other
+ *   runtime, and none of them reserve that name the way pi does, so a
+ *   claude/kimi/opencode/etc. `hooks/` directory is a live, in-use install
+ *   surface that must never be touched here. The runtime check is the FIRST
+ *   thing `plan()` does, ahead of even checking whether the directory exists,
+ *   as defense in depth beyond the `runtimes: ['pi']` record-level filter the
+ *   framework itself already enforces.
+ *
+ * Is the action safe in non-interactive install?
+ *   Yes. Every emitted action type (`remove-managed`, `backup-and-remove`,
+ *   `remove-empty-dir`) is non-interactive and journaled; none requires a
+ *   user choice, and unknown files never produce an action.
+ *
+ * See docs/installer-migrations.md#shipped-migrations, the pi row of
+ * docs/installer-migrations.md#runtime-configuration-contract-registry, and
+ * the 2026-08-07 amendment to docs/adr/0008-installer-migration-module.md.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/** pi's reserved (and, pre-#3023, GSD-populated) legacy hook directory name. */
+const HOOKS_DIR = 'hooks';
+const FILE_REASON = "pi's startup check warns whenever hooks/ exists (checkDeprecatedExtensionDirs), and GSD's shared " +
+    'hook bundle now installs at gsd-hooks/ instead (#3023), so the legacy files are superseded';
+const FILE_OWNERSHIP_EVIDENCE = 'pre-#3023 pi installs record the shared hook bundle under hooks/… keys in gsd-file-manifest.json; ' +
+    'the new install target is gsd-hooks/…, which this migration never touches because it only walks the ' +
+    'hooks/ subtree';
+const DIR_REASON = "pi's checkDeprecatedExtensionDirs() warns on hooks/'s mere existence, not its contents (#3023); the " +
+    'reserved container is retired once every GSD-owned entry inside it is gone';
+const DIR_OWNERSHIP_EVIDENCE = 'hooks/ and hooks/lib/ are GSD-installed container directories under the pi config root (the pre-#3023 ' +
+    'default of hostBehaviors.sharedHooksDirName); removal is gated on emptiness by the shared ' +
+    'remove-empty-dir action, so a directory that still holds an unmanifested user file — or any file-level ' +
+    'action that failed to apply — is left in place rather than assumed empty';
+/**
+ * Recursively collect files and directories under `relDir`, never following a
+ * symlink (whether it names a file or a directory) and never emitting a path
+ * that resolves outside `baseResolved`. Mirrors the traversal guard in
+ * migration 003 (`walkLegacyFiles`).
+ */
+function walkPiHooksTree(root, relDir, baseResolved, files, dirs) {
+    const dir = node_path_1.default.join(root, relDir);
+    const entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        // Never follow a symlink into or through: it must not be traversed,
+        // hashed, or removed, regardless of what it points at.
+        if (entry.isSymbolicLink())
+            continue;
+        const relPath = node_path_1.default.posix.join(relDir, entry.name);
+        const resolved = node_path_1.default.resolve(root, relPath);
+        if (resolved !== baseResolved && !resolved.startsWith(baseResolved + node_path_1.default.sep))
+            continue;
+        if (entry.isDirectory()) {
+            dirs.push(relPath);
+            walkPiHooksTree(root, relPath, baseResolved, files, dirs);
+        }
+        else if (entry.isFile()) {
+            files.push(relPath);
+        }
+    }
+}
+const migration = {
+    id: '2026-08-07-pi-retire-reserved-hooks-dir',
+    title: "Retire pi's reserved hooks/ directory",
+    description: 'Remove manifest-managed files under <piConfigDir>/hooks/ and, once empty, the directory itself ' +
+        '(and its hooks/lib/ subdirectory), now that the shared hook bundle installs at gsd-hooks/ instead. pi ' +
+        'reserves hooks/ as its own deprecated extension directory and warns on every startup while it exists (#3023).',
+    introducedIn: '1.9.2',
+    runtimes: ['pi'],
+    scopes: ['global', 'local'],
+    destructive: true,
+    plan: (ctx) => {
+        // Defense in depth ahead of the framework's own runtimes filter: a
+        // claude/kimi/opencode/etc. hooks/ directory is a live install surface,
+        // never a retirement target.
+        if (ctx.runtime !== 'pi')
+            return [];
+        const hooksRoot = node_path_1.default.join(ctx.configDir, HOOKS_DIR);
+        let rootLstat;
+        try {
+            rootLstat = node_fs_1.default.lstatSync(hooksRoot);
+        }
+        catch {
+            return []; // absent -> nothing to retire, idempotent
+        }
+        // Never follow a symlinked hooks/ root: walking through it could plan
+        // actions against paths outside the pi config directory entirely.
+        if (rootLstat.isSymbolicLink())
+            return [];
+        if (!rootLstat.isDirectory())
+            return [];
+        const baseResolved = node_path_1.default.resolve(ctx.configDir);
+        const files = [];
+        const dirs = [];
+        try {
+            walkPiHooksTree(ctx.configDir, HOOKS_DIR, baseResolved, files, dirs);
+        }
+        catch {
+            // Unreadable directory: nothing safe to plan.
+            return [];
+        }
+        const actions = [];
+        for (const relPath of files) {
+            const { classification } = ctx.classifyArtifact(relPath);
+            if (classification === 'managed-pristine') {
+                actions.push({ type: 'remove-managed', relPath, reason: FILE_REASON, ownershipEvidence: FILE_OWNERSHIP_EVIDENCE });
+            }
+            else if (classification === 'managed-modified') {
+                actions.push({ type: 'backup-and-remove', relPath, reason: FILE_REASON, ownershipEvidence: FILE_OWNERSHIP_EVIDENCE });
+            }
+            // 'unknown' (user-added, not manifest-recorded): no action, preserved.
+            // 'missing' / 'managed-missing': impossible here — relPath was just
+            // discovered by walking the live filesystem, so it currently exists.
+        }
+        // Deepest directories first, so a child has already been evaluated (and
+        // possibly removed) before its parent's own emptiness is re-checked by
+        // the executor. `hooks/` itself is appended last, unconditionally: the
+        // executor's own emptiness re-check is what actually decides whether it
+        // goes, not this ordering — this ordering only gives it the chance to.
+        const orderedDirs = [...dirs].sort((a, b) => b.split('/').length - a.split('/').length);
+        orderedDirs.push(HOOKS_DIR);
+        for (const relPath of orderedDirs) {
+            actions.push({
+                type: 'remove-empty-dir',
+                relPath,
+                reason: DIR_REASON,
+                ownershipEvidence: DIR_OWNERSHIP_EVIDENCE,
+                // Declared, not derived: classifyArtifact() hashes file contents via
+                // sha256File(), which throws EISDIR against a directory path. These
+                // relPaths name directories, so classification is stated directly
+                // (never 'unknown', so the planner's unknown-classification block
+                // never fires for them) rather than routed through the file
+                // classifier.
+                classification: 'managed-pristine',
+                originalHash: null,
+                currentHash: null,
+            });
+        }
+        return actions;
+    },
+};
+module.exports = migration;

package/gsd-core/bin/lib/installer-migrations.cjs

@@ -16,32 +16,133 @@ const node_crypto_1 = __importDefault(require("node:crypto"));
 const installer_migration_authoring_cjs_1 = require("./installer-migration-authoring.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const clock_cjs_1 = require("./clock.cjs");
+const install_scope_cjs_1 = require("./install-scope.cjs");
+// #2874 (ADR-58 cleanup phase): this file is the ~1200-line migration
+// plan/apply/rollback/lock/journal engine — almost none of it is on the
+// installRuntimeArtifacts call tree. Only `readInstallManifest` and
+// `classifyArtifact` are reached (via install-engine.cts's
+// _migrateLegacyOpencodeCommandDir and retired-artifact-cleanup.cts's
+// pruneRetiredRuntimeArtifacts), so only those two entry points — plus their
+// shared `readJsonIfPresent` helper and `classifyArtifact`'s `sha256File`
+// hashing helper — are routed through the injectable seam. Everything else
+// in this file (locking, journal, apply/rollback, migration discovery)
+// keeps using real `fs` directly: it is not reachable from
+// installRuntimeArtifacts, so routing it would grow this seam past what
+// AC2 actually requires. See install-fs-adapter.cts's module doc.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installFsAdapter = require("./install-fs-adapter.cjs");
+const { installFs } = installFsAdapter;
 const MANIFEST_NAME = 'gsd-file-manifest.json';
 const INSTALL_STATE_NAME = 'gsd-install-state.json';
 const INSTALL_MIGRATION_LOCK_NAME = 'gsd-install-migration.lock';
 const DEFAULT_MIGRATIONS_DIR = node_path_1.default.join(__dirname, 'installer-migrations');
 const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
 const STRICT_JSON = Symbol('strict-json');
+// #2874: routed through installFs()'s openSync/readSync/closeSync trio
+// instead of importing `node:fs` directly, so classifyArtifact — reachable
+// from installRuntimeArtifacts — can be exercised against an injected
+// adapter. This function was briefly converted to a single
+// `installFs().readFileSync` call (buffering the whole file); that broke
+// tests/installer-migrations.test.cjs's "classifies large files without
+// loading the whole file through readFileSync", which monkeypatches real
+// fs.readFileSync to throw for the file under test and asserts hashing still
+// succeeds — an explicit, pre-existing contract that large files must be
+// streamed, not buffered. Restored to the original raw-fd streaming shape,
+// now going through the adapter instead of `node:fs` directly. This is the
+// ONLY call site of sha256File in this file (confirmed by inspection) — no
+// other caller is affected.
 function sha256File(filePath) {
     const hash = node_crypto_1.default.createHash('sha256');
     const buffer = Buffer.allocUnsafe(1024 * 1024);
-    const fd = node_fs_1.default.openSync(filePath, 'r');
+    const fd = installFs().openSync(filePath, 'r');
     try {
         while (true) {
-            const bytesRead = node_fs_1.default.readSync(fd, buffer, 0, buffer.length, null);
+            const bytesRead = installFs().readSync(fd, buffer, 0, buffer.length, null);
             if (bytesRead === 0)
                 break;
             hash.update(buffer.subarray(0, bytesRead));
         }
     }
     finally {
-        node_fs_1.default.closeSync(fd);
+        installFs().closeSync(fd);
     }
     return hash.digest('hex');
 }
 function sha256Text(value) {
     return node_crypto_1.default.createHash('sha256').update(value).digest('hex');
 }
+/**
+ * Evaluate and, if safe, perform a `remove-empty-dir` action against `fullPath`.
+ *
+ * This is deliberately WEAKER than a recursive directory-removal primitive
+ * (which 003's docblock records as an intentional absence in the ADR-0008
+ * design): it only ever calls `fs.rmdirSync` — never `fs.rmSync`, never
+ * `{ recursive: true }`, never `{ force: true }` — so a non-empty directory
+ * fails the underlying syscall rather than being swept. The emptiness check
+ * immediately above the call is what turns that failure mode into a
+ * deliberate, non-error "left in place" outcome instead of surfacing ENOTEMPTY.
+ *
+ * Guards, in order:
+ *   - lstat (not stat): a symlinked directory is refused outright, never
+ *     followed. A missing target is reported distinctly so callers can tell
+ *     "nothing was ever there" from "something was there and is left alone".
+ *   - must actually be a directory (not a file masquerading under the relPath).
+ *   - containment: the REALPATH of the target must resolve strictly inside the
+ *     REALPATH of configDir — never equal to it (removing the config root
+ *     itself is never in scope) and never escaping it (e.g. via an ancestor
+ *     symlink the lstat check alone would not catch).
+ *   - emptiness, re-checked here rather than trusted from planning time: a
+ *     directory that still holds any entry (managed-but-undeleted, unknown,
+ *     or created between plan and apply) is left in place. This is reported
+ *     as 'skipped-not-empty', a successful no-op, not a failure.
+ *
+ * Any unexpected error along the way (EACCES, EBUSY, a race that removes the
+ * target between the lstat and the rmdir, etc.) degrades to 'left-in-place'.
+ * This action must never throw out of the executor, matching every sibling
+ * action type's failure posture.
+ */
+function evaluateRemoveEmptyDir(configDir, fullPath) {
+    let stat;
+    try {
+        stat = node_fs_1.default.lstatSync(fullPath);
+    }
+    catch {
+        return 'missing';
+    }
+    if (stat.isSymbolicLink())
+        return 'left-in-place';
+    if (!stat.isDirectory())
+        return 'left-in-place';
+    let resolvedRoot;
+    let resolvedTarget;
+    try {
+        resolvedRoot = node_fs_1.default.realpathSync(configDir);
+        resolvedTarget = node_fs_1.default.realpathSync(fullPath);
+    }
+    catch {
+        return 'left-in-place';
+    }
+    if (resolvedTarget === resolvedRoot || !resolvedTarget.startsWith(resolvedRoot + node_path_1.default.sep)) {
+        // Refuses both "target IS configDir" and "target escaped configDir".
+        return 'left-in-place';
+    }
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(fullPath);
+    }
+    catch {
+        return 'left-in-place';
+    }
+    if (entries.length > 0)
+        return 'skipped-not-empty';
+    try {
+        node_fs_1.default.rmdirSync(fullPath);
+        return 'removed';
+    }
+    catch {
+        return 'left-in-place';
+    }
+}
 /**
  * Copy a managed path for the rollback snapshot or the user-facing backup,
  * WITHOUT dereferencing a symlink.
@@ -60,24 +161,36 @@ function sha256Text(value) {
  * surfaces as an apply failure and triggers the normal rollback path, which is
  * the correct outcome — refusing to proceed beats silently copying referent
  * bytes.
+ *
+ * #2875 (epic #2866 Phase 6): all five fs calls routed through `installFs()`
+ * so this primitive can be reused on the routed install path (by
+ * user-artifact-staging.cts) without punching a hole through the seam Phase 5
+ * built. Every EXISTING caller of this function is on the migration
+ * plan/apply/rollback tree, which never wraps a call in `withInstallFs` — the
+ * ambient adapter there resolves to real `node:fs` by default, so this
+ * routing is behavior-preserving for them (test-matrix D2).
  */
 function copyPreservingSymlink(srcPath, destPath) {
-    if (node_fs_1.default.lstatSync(srcPath).isSymbolicLink()) {
+    if (installFs().lstatSync(srcPath).isSymbolicLink()) {
         // symlinkSync fails with EEXIST on an occupied path, so clear it first.
         // Scoped to this branch on purpose: the regular-file path below keeps
         // copyFileSync's overwrite-in-place, so a mid-restore failure cannot leave
         // the destination destroyed.
-        node_fs_1.default.rmSync(destPath, { force: true });
-        node_fs_1.default.symlinkSync(node_fs_1.default.readlinkSync(srcPath), destPath);
+        installFs().rmSync(destPath, { force: true });
+        installFs().symlinkSync(installFs().readlinkSync(srcPath), destPath);
         return;
     }
-    node_fs_1.default.copyFileSync(srcPath, destPath);
+    installFs().copyFileSync(srcPath, destPath);
 }
+// Shared by readInstallManifest (on the installRuntimeArtifacts call tree —
+// routed) and readInstallState/readJson (not on that call tree — the
+// ambient default resolves to real fs for those, unchanged). Routing once
+// here is safe for all three callers.
 function readJsonIfPresent(filePath, fallback) {
-    if (!node_fs_1.default.existsSync(filePath))
+    if (!installFs().existsSync(filePath))
         return fallback;
     try {
-        return JSON.parse(node_fs_1.default.readFileSync(filePath, 'utf8'));
+        return JSON.parse(installFs().readFileSync(filePath, 'utf8'));
     }
     catch (error) {
         if (fallback === STRICT_JSON) {
@@ -86,17 +199,81 @@ function readJsonIfPresent(filePath, fallback) {
         return fallback;
     }
 }
+/** Lowest manifest schema version that records `runtime`/`scope` (#2872). */
+const MANIFEST_SCHEMA_VERSION = 2;
+/**
+ * Longest `runtime` string this reader will report. Real runtime ids are
+ * registry keys (`claude`, `antigravity`, `kimi-code` — 11 chars at the
+ * longest), so this loses nothing legitimate; it exists because the manifest
+ * is attacker-influenceable (a project-local one lives inside a repository a
+ * user may merely have cloned) and the value reaches a consumer that renders
+ * it. Same 64-char convention as `truncatePostureValue`
+ * (`agent-install-check.cts`), deliberately, so the subsystem caps reported
+ * values one way.
+ */
+const MAX_REPORTED_RUNTIME_LENGTH = 64;
+/**
+ * A manifest's `runtime` is reported as a FACT about the file — it is
+ * deliberately NOT validated against the capability registry, because an
+ * unregistered id is exactly the kind of mismatch the Installed Surface
+ * Resolver exists to surface (#2872 design row B8). It is, however, LENGTH
+ * bounded: "report the fact" never required "report unbounded bytes".
+ */
+function normalizeReportedRuntime(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    if (raw.trim() === '')
+        return null;
+    return raw.length > MAX_REPORTED_RUNTIME_LENGTH
+        ? `${raw.slice(0, MAX_REPORTED_RUNTIME_LENGTH)}…`
+        : raw;
+}
+/**
+ * Normalize a raw `manifestVersion`. Only a finite integer >= 1 is a version
+ * claim; everything else (absent, `"2"`, `0`, `-1`, `2.5`, `NaN`, `Infinity`)
+ * reads as `1` — a pre-#2872 manifest. Liberal in what it accepts, but the
+ * normalization is a stated value rather than a silent guess: a caller can
+ * always tell v1 (`1`) from "no manifest at all" (`null`).
+ */
+function normalizeManifestVersion(raw) {
+    if (typeof raw !== 'number')
+        return 1;
+    if (!Number.isInteger(raw))
+        return 1;
+    if (raw < 1)
+        return 1;
+    return raw;
+}
 function readInstallManifest(configDir) {
     const manifest = readJsonIfPresent(node_path_1.default.join(configDir, MANIFEST_NAME), null);
-    if (!manifest || typeof manifest !== 'object') {
-        return { version: null, timestamp: null, mode: null, files: {} };
+    // `typeof [] === 'object'` in JS, so a bare `typeof !== 'object'` guard lets
+    // a top-level JSON array (valid JSON, but not the manifest's documented
+    // object shape) fall through to the field reads below — `m.manifestVersion`
+    // reads `undefined` off an array, which `normalizeManifestVersion` then
+    // reports as `1` (a v1 manifest), misclassifying "not an object" as
+    // "installed". `Array.isArray` closes that gap explicitly rather than
+    // relying on the object-shape checks below to catch it incidentally.
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+        return {
+            version: null,
+            timestamp: null,
+            mode: null,
+            files: {},
+            manifestVersion: null,
+            runtime: null,
+            scope: null,
+        };
     }
     const m = manifest;
+    const rawRuntime = m.runtime;
     return {
         version: typeof m.version === 'string' ? m.version : null,
         timestamp: typeof m.timestamp === 'string' ? m.timestamp : null,
         mode: typeof m.mode === 'string' ? m.mode : null,
         files: m.files && typeof m.files === 'object' ? m.files : {},
+        manifestVersion: normalizeManifestVersion(m.manifestVersion),
+        runtime: normalizeReportedRuntime(rawRuntime),
+        scope: (0, install_scope_cjs_1.isInstallScopeId)(m.scope) ? m.scope : null,
     };
 }
 function readInstallState(configDir) {
@@ -163,7 +340,7 @@ function classifyArtifact(configDir, relPath, manifest) {
     const normalized = normalizeRelPath(relPath);
     const originalHash = manifest.files[normalized] || null;
     const fullPath = node_path_1.default.join(configDir, normalized);
-    if (!node_fs_1.default.existsSync(fullPath)) {
+    if (!installFs().existsSync(fullPath)) {
         return { classification: originalHash ? 'managed-missing' : 'missing', originalHash, currentHash: null };
     }
     const currentHash = sha256File(fullPath);
@@ -643,7 +820,8 @@ function applyInstallerMigrationPlan({ configDir, plan, now = () => new Date().t
                 action.type !== 'backup-and-remove' &&
                 action.type !== 'rewrite-json' &&
                 action.type !== 'record-baseline' &&
-                action.type !== 'baseline-preserve-user') {
+                action.type !== 'baseline-preserve-user' &&
+                action.type !== 'remove-empty-dir') {
                 throw new Error(`unsupported migration action type: ${action.type}`);
             }
             const { normalized, fullPath } = ensureInsideConfig(configDir, action.relPath);
@@ -655,6 +833,18 @@ function applyInstallerMigrationPlan({ configDir, plan, now = () => new Date().t
                 journal.actions.push(journalAction(action, action.type === 'record-baseline' ? 'recorded' : 'preserved'));
                 continue;
             }
+            if (action.type === 'remove-empty-dir') {
+                // Directory actions never enter the file-copy/rollback machinery below:
+                // there is nothing to snapshot-and-restore for a directory node itself
+                // (its former CONTENTS were already snapshotted by their own file-level
+                // actions before this one runs), and rollback of a removed empty
+                // directory is simply re-creating it, which the rollback path below
+                // does not model. Non-recursive by construction (evaluateRemoveEmptyDir
+                // only ever calls fs.rmdirSync), so there is nothing destructive to undo
+                // beyond an mkdir the next install/migration run will happily redo.
+                journal.actions.push(journalAction(action, evaluateRemoveEmptyDir(configDir, fullPath)));
+                continue;
+            }
             const rollbackPath = node_path_1.default.join(rollbackRoot, normalized);
             node_fs_1.default.mkdirSync(node_path_1.default.dirname(rollbackPath), { recursive: true });
             copyPreservingSymlink(fullPath, rollbackPath);
@@ -852,7 +1042,10 @@ module.exports = {
     acquireInstallMigrationLock,
     applyInstallerMigrationPlan,
     classifyArtifact,
+    copyPreservingSymlink,
     discoverInstallerMigrations,
+    evaluateRemoveEmptyDir,
+    MANIFEST_SCHEMA_VERSION,
     migrationChecksum,
     planInstallerMigrations,
     readInstallManifest,

package/gsd-core/bin/lib/io.cjs

@@ -118,6 +118,22 @@ function writeAllSync(fd, data) {
         }
     }
 }
+/**
+ * The wire form of a JSON result: the exact bytes `output()` emits for it.
+ *
+ * Exported because a caller that has to reason about the size of its own
+ * response — graphify's `--budget` accounting (#2738) — must measure the string
+ * this function produces rather than a second, privately-maintained
+ * serialization that can drift from it. One definition, so estimator and
+ * emitter cannot disagree about indentation or shape.
+ *
+ * The `@file:` redirection in `output()` is a transport detail, not a payload
+ * change: the caller still consumes these bytes, so these are the right ones to
+ * measure.
+ */
+function serializeForOutput(result) {
+    return JSON.stringify(result, null, 2);
+}
 function output(result, raw, rawValue) {
     let data;
     if (raw && rawValue !== undefined) {
@@ -125,7 +141,7 @@ function output(result, raw, rawValue) {
         data = String(rawValue);
     }
     else {
-        const json = JSON.stringify(result, null, 2);
+        const json = serializeForOutput(result);
         // Large payloads exceed Claude Code's Bash tool buffer (~50KB).
         // Write to tmpfile and output the path prefixed with @file: so callers can detect it.
         if (json.length > 50000) {
@@ -168,12 +184,23 @@ const ERROR_REASON = Object.freeze({
     // workflow / phase
     PHASE_NOT_FOUND: 'phase_not_found',
     PHASE_VERIFICATION_INCOMPLETE: 'phase_verification_incomplete',
+    PHASE_PLAN_COVERAGE_INCOMPLETE: 'phase_plan_coverage_incomplete',
     SUMMARY_NO_PLANNING: 'summary_no_planning',
+    // #3579: workstream-mode fail-safe guards (init.progress, phase.complete) —
+    // distinguishes "no marker/pointer anywhere" from "a marker exists but
+    // didn't resolve" so a JSON-error-mode caller can branch on `reason`
+    // instead of regexing the human message.
+    WORKSTREAM_MODE_NONE_ACTIVE: 'workstream_mode_none_active',
+    WORKSTREAM_MODE_MARKER_UNRESOLVED: 'workstream_mode_marker_unresolved',
     // graphify
     GRAPHIFY_NO_GRAPH: 'graphify_no_graph',
     GRAPHIFY_INVALID_QUERY: 'graphify_invalid_query',
     // hooks
     HOOKS_OPT_OUT: 'hooks_opt_out',
+    // commit-docs-guard (#3588)
+    COMMIT_DOCS_GUARD_NOT_A_REPO: 'commit_docs_guard_not_a_repo',
+    COMMIT_DOCS_GUARD_FOREIGN_HOOK: 'commit_docs_guard_foreign_hook',
+    COMMIT_DOCS_GUARD_HOOKS_PATH_SET: 'commit_docs_guard_hooks_path_set',
     // security-scan
     SECURITY_SCAN_FAILED: 'security_scan_failed',
     // generic
@@ -198,10 +225,17 @@ function getJsonErrorMode() { return _jsonErrorMode; }
  * process is in JSON-error mode, stderr receives `{ ok: false, reason,
  * message }` so callers can parse it; otherwise stderr keeps the plain
  * text form for human operators.
+ *
+ * `extra` (optional) lets a caller attach additional structured fields
+ * (e.g. `{ verification_stale_check_indeterminate: true }`) onto the
+ * JSON-error-mode payload, spread alongside `ok`/`reason`/`message`, so a
+ * test can assert on the value directly instead of regexing `message`'s
+ * human-readable text. Ignored entirely in plain-text mode — the human
+ * message is the only thing an operator sees there.
  */
-function error(message, reason = ERROR_REASON.UNKNOWN) {
+function error(message, reason = ERROR_REASON.UNKNOWN, extra) {
     if (_jsonErrorMode) {
-        const payload = JSON.stringify({ ok: false, reason, message }) + '\n';
+        const payload = JSON.stringify({ ok: false, reason, message, ...(extra || {}) }) + '\n';
         writeAllSync(2, payload);
     }
     else {
@@ -214,6 +248,7 @@ module.exports = {
     ensureGsdTempDir,
     reapStaleTempFiles,
     output,
+    serializeForOutput,
     ERROR_REASON,
     setJsonErrorMode,
     getJsonErrorMode,

package/gsd-core/bin/lib/markdown-sectionizer.cjs

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripFencedCode = stripFencedCode;
 exports.stripInlineCode = stripInlineCode;
 exports.scanInlineCodeSpans = scanInlineCodeSpans;
+exports.scanFencedBlocks = scanFencedBlocks;
 exports.extractFencedBlock = extractFencedBlock;
 exports.tokenizeHeadings = tokenizeHeadings;
 exports.collectSections = collectSections;
@@ -25,6 +26,7 @@ exports.stripTaggedBlocks = stripTaggedBlocks;
 exports.replaceSection = replaceSection;
 exports.withSection = withSection;
 exports.deleteSection = deleteSection;
+const pattern_cjs_1 = require("./pattern.cjs");
 // ─── stripFencedCode ──────────────────────────────────────────────────────────
 /**
  * CommonMark-correct fenced-code-block stripper.
@@ -206,6 +208,11 @@ function stripInlineCodeLine(line) {
  * Tracked duplication (same status as `tokenizeHeadings`'s copy, see its
  * comment above): this is a second independent copy of the fence state
  * machine, pending a T-tier consolidation.
+ *
+ * Exported so `context-predicates.cts` can consume this seam directly for its
+ * line-preserving fenced-line skip detection, instead of carrying a third
+ * independent copy of the fence state machine (see that module's doc
+ * comment).
  */
 function scanFencedBlocks(lines) {
     const delimRe = /^( {0,3})(`{3,}|~{3,})(.*)$/;
@@ -786,7 +793,7 @@ function extractTaggedBlocks(content, tagName, allowAttributes = false) {
  * open>` marks the ACTIVE milestone and must be preserved, not stripped (#557).
  */
 function taggedBlockPattern(tagName, flags, allowAttributes) {
-    const esc = tagName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const esc = (0, pattern_cjs_1.escapeRegex)(tagName);
     const open = allowAttributes ? `<${esc}(?:\\s[^>]{0,1000})?>` : `<${esc}>`;
     const boundary = allowAttributes ? `<${esc}[\\s>]` : `<${esc}>`;
     return new RegExp(`${open}((?:(?!${boundary})[\\s\\S])*?)</${esc}>`, flags);