@opengsd/gsd-core 1.10.0 → 1.11.0

package/gsd-core/bin/lib/installed-surface-resolver.cjs

@@ -0,0 +1,381 @@
+"use strict";
+/**
+ * installed-surface-resolver.cts — Installed Surface Resolver Module (#2872,
+ * ADR-2866, Phase 3 — governed by
+ * `.gsd/phase/feat-2872-manifest-scope-runtime/40-design.md`).
+ *
+ * `resolveInstalledSurfaces(runtime?, opts?)` answers a question no existing
+ * module answers: "which surfaces actually exist on THIS machine, across
+ * BOTH install scopes, right now?" `capability-state.cts` answers "which
+ * capabilities are enabled in THIS config dir" — a different question at a
+ * different altitude. This module is a new leaf: it reads two scopes at
+ * once, composing three already-shipped, already-tested pieces
+ * (`resolveScope`, Phase 1; `resolveTriggerSurface`, Phase 2; and
+ * `readInstallManifest`, widened in this same phase) rather than
+ * re-implementing any of their rules.
+ *
+ * ── Probe-not-declared keying ───────────────────────────────────────────────
+ * A scope RECORD is keyed by the PROBED scope (`resolveScope`'s own `id`),
+ * never by what the manifest itself claims. `manifestVersion`/`runtime`/
+ * `scope` recorded inside a v2 manifest are corroboration, not identity: a
+ * manifest copied between config dirs, or a `--config-dir` install, must
+ * still be reported at the scope this machine actually resolves to.
+ *
+ * ── Report, don't correct ───────────────────────────────────────────────────
+ * When a declared `runtime`/`scope` disagrees with the probe, this module
+ * reports the mismatch (`declaredScopeMatchesProbe: false` /
+ * `declaredRuntimeMatchesProbe: false`) and otherwise proceeds exactly as it
+ * would for an undeclared (v1) manifest. It never silently substitutes the
+ * declared value for the probed one, and never throws on a mismatch — see
+ * B-row "Postel's Law" discussion in the design doc.
+ *
+ * ── One trigger call over installed scopes only ─────────────────────────────
+ * `resolveTriggerSurface` is called AT MOST once per runtime, with the
+ * scopes that are actually installed on this machine (per manifest
+ * presence — never per the new corroboration fields, which is what keeps a
+ * v1-only install fully functional with no reinstall required). A
+ * hypothetical "what if both scopes were installed" answer is deliberately
+ * not offered; #2218 is a fact about THIS machine, not a simulation.
+ *
+ * ── Installed-ness is manifest PRESENCE, never the new fields ───────────────
+ * `installed` is `manifestVersion !== null`. A v1 manifest (no
+ * `manifestVersion` key at all, `manifestVersion: 1` after normalization) is
+ * a correct manifest written by an older GSD — never a broken one, never
+ * grounds for `installed: false`, a warning, or a reinstall prompt.
+ *
+ * ── Stems come from the manifest, not the source tree ───────────────────────
+ * `resolveTriggerSurface` needs `stems`. They are derived from the
+ * INSTALLED manifest's own `files` keys (see the private stem-derivation
+ * helpers below), never from a roster read of the source tree — a global
+ * `claude` install ships no `commands/gsd` source, so a roster read would
+ * return `[]` in exactly the configuration #2218 is about. The derivation
+ * consumes `isNamespacedByDir` and `composeCommandFilename`
+ * (`runtime-artifact-layout.cjs`, #2871 Phase 2's exported helpers) rather
+ * than re-deriving either rule as a fourth independent copy.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveInstalledSurfaces = resolveInstalledSurfaces;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const install_scope_cjs_1 = require("./install-scope.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const runtimeArtifactLayoutMod = require("./runtime-artifact-layout.cjs");
+const { resolveRuntimeArtifactLayout, resolveRuntimeArtifactLayoutFromRegistry, resolveTriggerSurface, isNamespacedByDir, composeCommandFilename, } = runtimeArtifactLayoutMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installerMigrationsMod = require("./installer-migrations.cjs");
+const { readInstallManifest, MANIFEST_NAME } = installerMigrationsMod;
+// In .cts (CommonJS output) files, `require` is available as a global.
+const _require = require;
+// ── Internals ───────────────────────────────────────────────────────────
+/**
+ * A trigger stem is a kebab-case token and nothing else. Verified against the
+ * real roster: all 71 `commands/gsd/*.md` stems match this, so it has no false
+ * negatives today.
+ *
+ * This is a SECURITY boundary, not cosmetics. A stem is derived from a manifest
+ * key — attacker-influenceable text, since a project-local
+ * `gsd-file-manifest.json` lives inside a repository a user may merely have
+ * cloned — and Phase 4 (#2873) renders it back to the user as `/gsd-<stem>`.
+ * Without this, `skills/gsd-../../../x` yields the stem `..`, and control
+ * characters, newlines, ANSI escapes and RTL-override codepoints all survive
+ * into that rendered trigger. The `commands` branch happened to be protected by
+ * its `composeCommandFilename` round-trip; the `skills` branch had no
+ * equivalent, so the rule is stated once here and applied to both.
+ */
+const SAFE_STEM = /^[a-z0-9][a-z0-9-]*$/;
+function getDefaultRuntimeRegistry() {
+    return _require('./capability-registry.cjs');
+}
+/** C7: every registered runtime id, sorted for determinism. Reads
+ *  `opts.registry` when provided (so a sweep is assertable without the real
+ *  capability registry), else the real one. */
+function listRegisteredRuntimeIds(opts) {
+    const registry = opts.registry ?? getDefaultRuntimeRegistry();
+    return Object.keys(registry.runtimes).sort();
+}
+/**
+ * D — the stem inverse for one `commands`/`skills` layout kind entry.
+ * Consumes `isNamespacedByDir` (to decide the commands filename shape) and
+ * `composeCommandFilename` (to VERIFY a candidate stem round-trips to the
+ * exact filename seen) rather than re-deriving either rule locally (design
+ * "Rejected" #6). Manifest keys are normalized with an unconditional
+ * `.replace(/\\/g, '/')` (D7) — never gated on `path.sep` — matching this
+ * repo's recorded path-separator-normalization defect class.
+ */
+function deriveStemsForKindEntry(kind, destSubpath, prefix, fileKeys) {
+    const destSubpathNorm = (0, shell_command_projection_cjs_1.posixNormalize)(destSubpath);
+    const boundary = `${destSubpathNorm}/`;
+    const namespacedByDir = isNamespacedByDir(kind, destSubpath, prefix);
+    const stems = new Set();
+    for (const rawKey of fileKeys) {
+        const key = rawKey.replace(/\\/g, '/');
+        if (!key.startsWith(boundary))
+            continue; // D4: key not under this declared subpath
+        const rest = key.slice(boundary.length);
+        if (rest === '')
+            continue;
+        const segments = rest.split('/');
+        if (kind === 'skills') {
+            const dirSegment = segments[0];
+            if (!dirSegment.startsWith(prefix))
+                continue; // D5: subpath matches, prefix does not
+            const stem = dirSegment.slice(prefix.length);
+            if (stem === '')
+                continue; // D7/B7: empty stem never emitted
+            if (!SAFE_STEM.test(stem))
+                continue; // security: reject anything but a kebab-case token
+            stems.add(stem); // D6: several files under one dir -> one stem
+            continue;
+        }
+        // commands: exactly one path segment — the composed filename itself.
+        if (segments.length !== 1)
+            continue;
+        const filename = segments[0];
+        if (!filename.endsWith('.md'))
+            continue;
+        const base = filename.slice(0, -3);
+        const candidateStem = namespacedByDir
+            ? base
+            : (base.startsWith(prefix) ? base.slice(prefix.length) : '');
+        if (candidateStem === '')
+            continue;
+        if (composeCommandFilename(namespacedByDir, prefix, candidateStem) !== filename)
+            continue;
+        if (!SAFE_STEM.test(candidateStem))
+            continue; // security: reject anything but a kebab-case token
+        stems.add(candidateStem);
+    }
+    return [...stems];
+}
+/** D — full stem set for one scope: every `commands`/`skills` layout kind
+ *  entry, unioned. Empty `files` (C13) short-circuits to `[]` without
+ *  resolving a layout at all. */
+function deriveStemsFromManifest(runtime, scopeId, configHome, files, opts) {
+    const fileKeys = Object.keys(files);
+    if (fileKeys.length === 0)
+        return [];
+    const layout = opts.registry !== undefined
+        ? resolveRuntimeArtifactLayoutFromRegistry(opts.registry, runtime, configHome, scopeId)
+        : resolveRuntimeArtifactLayout(runtime, configHome, scopeId);
+    const stems = new Set();
+    for (const kindEntry of layout.kinds) {
+        if (kindEntry.kind !== 'commands' && kindEntry.kind !== 'skills')
+            continue; // excludes agents/kimi-agents (D4)
+        for (const stem of deriveStemsForKindEntry(kindEntry.kind, kindEntry.destSubpath, kindEntry.prefix, fileKeys)) {
+            stems.add(stem);
+        }
+    }
+    return [...stems].sort();
+}
+/**
+ * True when `p` is a symlink. An `lstatSync` throw (ENOENT — nothing at this
+ * path) is NOT evidence of a symlink; it is treated as "not a symlink" here
+ * and left for `readManifest` to classify (it already owns the absent-file
+ * case, per C14 above).
+ */
+function isSymlinkPath(p, lstatSync) {
+    try {
+        return lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The shared "not installed" degraded shape (C14's EACCES path, and this
+ * phase's new symlink-guard path). A FACTORY, not a module-level constant
+ * object: a `const` object spread at each return site would still share the
+ * same `stems` ARRAY reference across every call (`...` shallow-copies the
+ * object but not the array a property points at), which would violate this
+ * module's own "builds fresh arrays/objects on every call" contract (C15) —
+ * a caller mutating one degraded record's `stems` must never be visible on
+ * another's.
+ */
+function notInstalledScopeRecordFields() {
+    return {
+        installed: false,
+        manifestVersion: null,
+        declaredRuntime: null,
+        declaredScope: null,
+        declaredScopeMatchesProbe: null,
+        declaredRuntimeMatchesProbe: null,
+        stems: [],
+    };
+}
+/**
+ * Build one scope's record. `resolvedConfigHome` has already been probed
+ * successfully by the time this is called (a `resolveScope` `TypeError` is
+ * handled by the caller, per C8 — it is never this function's concern).
+ *
+ * Two distinct failure modes are handled with two distinct, narrowly-scoped
+ * try/catches — NOT one catch-all around the whole function:
+ *
+ *  - The manifest READ (`readManifest`) is the only thing that can justify
+ *    `installed: false` (C14, e.g. EACCES). A failure here means "we could
+ *    not even tell whether this scope is installed".
+ *  - The stem DERIVATION (`deriveStemsFromManifest`, which resolves a
+ *    runtime artifact layout) is a separate concern. A `TypeError` thrown
+ *    while deriving stems is a layout-lookup failure, not evidence the
+ *    manifest is absent — the manifest was already read successfully, so
+ *    `installed` and every declared/*MatchesProbe field stay exactly as the
+ *    manifest reported. Conflating the two would report a genuinely
+ *    installed runtime as `installed: false`, hiding a real install from
+ *    #2218 shadow detection precisely when this module exists to surface it.
+ */
+function buildScopeRecord(runtime, scopeId, resolvedConfigHome, opts) {
+    // Hardening requirement 2 (#2873 design doc, "Hardening requirements
+    // claimed from #2873's comment"): `readInstallManifest` -> `readJsonIfPresent`
+    // uses `existsSync` + `readFileSync` and therefore FOLLOWS symlinks, and
+    // this module resolves `local` against `process.cwd()` — a directory that,
+    // as of this phase, becomes reachable from an arbitrary cloned repository
+    // (this is the same phase that makes the local scope's manifest a first
+    // read target, not merely a write target). The in-tree precedent is
+    // `getAgentsDir` (`agent-install-check.cts`), which probes with
+    // `fs.lstatSync(...).isDirectory()`/`.isFile()` and deliberately does not
+    // follow. #2872 left this resolver's read un-guarded only because the path
+    // had zero callers at the time; refusing to follow a symlinked config dir
+    // or manifest here closes that asymmetry rather than carrying it forward.
+    // Degrading to `installed: false` reuses the SAME shape the EACCES catch
+    // below already returns — no new failure shape is introduced.
+    const lstatSync = opts.lstatSync ?? node_fs_1.default.lstatSync;
+    const manifestPath = node_path_1.default.join(resolvedConfigHome, MANIFEST_NAME);
+    if (isSymlinkPath(resolvedConfigHome, lstatSync) || isSymlinkPath(manifestPath, lstatSync)) {
+        return { scope: scopeId, configHome: resolvedConfigHome, ...notInstalledScopeRecordFields() };
+    }
+    let manifest;
+    try {
+        const readManifest = opts.readManifest ?? readInstallManifest;
+        manifest = readManifest(resolvedConfigHome);
+    }
+    catch {
+        // C14: manifest read/probe failure degrades to not-installed, never throws.
+        // Deliberately a BARE catch, unlike the stem-derivation catch below: any
+        // read failure at all (EACCES, ENOENT-after-race, a corrupt filesystem)
+        // legitimately means "cannot tell whether installed" (design row C14), so
+        // there is no error TYPE here that should instead propagate.
+        return { scope: scopeId, configHome: resolvedConfigHome, ...notInstalledScopeRecordFields() };
+    }
+    const installed = manifest.manifestVersion !== null; // C9: presence, never the new fields
+    const declaredRuntime = manifest.runtime;
+    const declaredScope = manifest.scope;
+    const declaredRuntimeMatchesProbe = declaredRuntime === null ? null : declaredRuntime === runtime;
+    const declaredScopeMatchesProbe = declaredScope === null ? null : declaredScope === scopeId;
+    let stems = [];
+    if (installed) {
+        try {
+            stems = deriveStemsFromManifest(runtime, scopeId, resolvedConfigHome, manifest.files, opts);
+        }
+        catch (error) {
+            if (!(error instanceof TypeError))
+                throw error;
+            // A layout-lookup failure means "we could not enumerate this scope's
+            // triggers", NOT "this scope is not installed" — the manifest read
+            // already succeeded above, so `installed` and the declared fields
+            // stay as reported. Conflating the two would hide a real install.
+            // Anything that is not the expected `TypeError` (a genuine bug in
+            // `deriveStemsFromManifest`/`resolveRuntimeArtifactLayout`) is
+            // rethrown rather than silently degrading to `stems: []` — this
+            // matches `resolveInstalledSurfaces`'s own `TypeError` narrowing
+            // below, so the two catches cannot drift apart.
+            stems = [];
+        }
+    }
+    return {
+        scope: scopeId,
+        configHome: resolvedConfigHome,
+        installed,
+        manifestVersion: manifest.manifestVersion,
+        declaredRuntime,
+        declaredScope,
+        declaredScopeMatchesProbe,
+        declaredRuntimeMatchesProbe,
+        stems,
+    };
+}
+/**
+ * Resolve one runtime's full installed surface. A `resolveScope` `TypeError`
+ * (unknown runtime, or `configHome.kind === 'none'`, e.g. vscode) propagates
+ * from here uncaught — `resolveInstalledSurfaces` decides whether that
+ * means "skip" (C7 sweep) or "propagate" (explicit single-runtime ask, C8).
+ */
+function resolveOneRuntime(runtime, opts) {
+    const scopes = install_scope_cjs_1.SCOPE_ORDER.map((scopeId) => {
+        const resolved = (0, install_scope_cjs_1.resolveScope)({
+            id: scopeId,
+            runtime,
+            env: opts.env,
+            home: opts.home,
+            existsSync: opts.existsSync,
+            cwd: opts.cwd,
+        });
+        return buildScopeRecord(runtime, scopeId, resolved.configHome, opts);
+    });
+    // C12: dedupe by resolved configHome BEFORE the trigger call, keeping the
+    // higher-ranked (global, first in SCOPE_ORDER) scope. Both scope RECORDS
+    // above are unaffected — only the scope list handed to resolveTriggerSurface
+    // is deduped.
+    const seenConfigHomes = new Set();
+    const triggerScopeIds = [];
+    for (const record of scopes) {
+        if (!record.installed)
+            continue;
+        if (seenConfigHomes.has(record.configHome))
+            continue;
+        seenConfigHomes.add(record.configHome);
+        triggerScopeIds.push(record.scope);
+    }
+    const stemUnion = new Set();
+    for (const scopeId of triggerScopeIds) {
+        const record = scopes.find((s) => s.scope === scopeId);
+        for (const stem of record?.stems ?? [])
+            stemUnion.add(stem);
+    }
+    const triggers = triggerScopeIds.length > 0
+        ? resolveTriggerSurface(runtime, triggerScopeIds, {
+            stems: [...stemUnion].sort(),
+            registry: opts.registry,
+        })
+        : [];
+    return { runtime, scopes, triggers };
+}
+/**
+ * Read-only. Probes both install scopes for a runtime (or every registered
+ * runtime, sorted by id, when `runtime` is omitted), reads each scope's
+ * manifest, and resolves the trigger surface across the scopes that are
+ * actually installed on this machine. See the module-level comment for the
+ * non-obvious choices (probe-not-declared keying, report-don't-correct, one
+ * trigger call over installed scopes only).
+ *
+ * Pure with respect to caller-visible state: builds fresh arrays/objects on
+ * every call (C15) and performs no writes. Filesystem reads happen only via
+ * `resolveScope`'s injected `existsSync`/`env`/`home`/`cwd` and via
+ * `readManifest` (default: `readInstallManifest`).
+ *
+ * @throws {TypeError} when `runtime` is given explicitly and it is unknown,
+ *   or has no installable config directory (`configHome.kind === 'none'`,
+ *   e.g. vscode) — same contract `resolveScope` throws. In the all-runtimes
+ *   sweep (`runtime` omitted), a runtime that would throw this same
+ *   `TypeError` is skipped instead, so one non-installable runtime cannot
+ *   kill the sweep (C7/C8). Any other error type is never swallowed here.
+ */
+function resolveInstalledSurfaces(runtime, opts = {}) {
+    if (typeof runtime === 'string') {
+        return [resolveOneRuntime(runtime, opts)];
+    }
+    const results = [];
+    for (const runtimeId of listRegisteredRuntimeIds(opts)) {
+        try {
+            results.push(resolveOneRuntime(runtimeId, opts));
+        }
+        catch (error) {
+            if (error instanceof TypeError)
+                continue; // C8: sweep skips, never dies
+            throw error;
+        }
+    }
+    return results;
+}

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

@@ -16,51 +16,61 @@ 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');
 }
-/**
- * Copy a managed path for the rollback snapshot or the user-facing backup,
- * WITHOUT dereferencing a symlink.
- *
- * `fs.copyFileSync` follows symlinks, so a managed path that has been replaced
- * by a link (tampering, or an unexpected user layout) would have had the
- * LINK TARGET's bytes copied into `gsd-migration-journal/…-backups/` — e.g. a
- * `gsd.cjs` symlinked at `~/.ssh/id_rsa` would land that key's contents in the
- * backup tree. Nothing GSD installs is ever a symlink, so the faithful snapshot
- * of a symlinked managed path is the link itself: recreating it preserves
- * rollback fidelity (restore re-creates the same link) while never reading the
- * referent. Deletion was already safe — `fs.rmSync` unlinks the link, never the
- * target.
- *
- * Windows note: `fs.symlinkSync` can throw EPERM for unprivileged users. That
- * surfaces as an apply failure and triggers the normal rollback path, which is
- * the correct outcome — refusing to proceed beats silently copying referent
- * bytes.
- */
 /**
  * Evaluate and, if safe, perform a `remove-empty-dir` action against `fullPath`.
  *
@@ -133,23 +143,54 @@ function evaluateRemoveEmptyDir(configDir, fullPath) {
         return 'left-in-place';
     }
 }
+/**
+ * Copy a managed path for the rollback snapshot or the user-facing backup,
+ * WITHOUT dereferencing a symlink.
+ *
+ * `fs.copyFileSync` follows symlinks, so a managed path that has been replaced
+ * by a link (tampering, or an unexpected user layout) would have had the
+ * LINK TARGET's bytes copied into `gsd-migration-journal/…-backups/` — e.g. a
+ * `gsd.cjs` symlinked at `~/.ssh/id_rsa` would land that key's contents in the
+ * backup tree. Nothing GSD installs is ever a symlink, so the faithful snapshot
+ * of a symlinked managed path is the link itself: recreating it preserves
+ * rollback fidelity (restore re-creates the same link) while never reading the
+ * referent. Deletion was already safe — `fs.rmSync` unlinks the link, never the
+ * target.
+ *
+ * Windows note: `fs.symlinkSync` can throw EPERM for unprivileged users. That
+ * 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) {
@@ -158,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) {
@@ -235,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);
@@ -937,8 +1042,10 @@ module.exports = {
     acquireInstallMigrationLock,
     applyInstallerMigrationPlan,
     classifyArtifact,
+    copyPreservingSymlink,
     discoverInstallerMigrations,
     evaluateRemoveEmptyDir,
+    MANIFEST_SCHEMA_VERSION,
     migrationChecksum,
     planInstallerMigrations,
     readInstallManifest,

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

@@ -186,11 +186,21 @@ const ERROR_REASON = Object.freeze({
     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

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

@@ -26,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.
@@ -792,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);