@opengsd/gsd-core 1.12.0 → 1.13.0

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

@@ -34,6 +34,9 @@ const phaseId = require("./phase-id.cjs");
 const worktreeSafety = require("./worktree-safety.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
 const secrets_cjs_1 = require("./secrets.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-scan.cjs is an export= CommonJS module
 const scanPhasePlans = require("./plan-scan.cjs");
@@ -83,7 +86,7 @@ const { resolveModelInternal, resolveGranularityInternal, assertValidGranularity
 const { findPhaseInternal, listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocator;
 const { getRoadmapPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, } = roadmapParser;
 const { pathExistsInternal, generateSlugInternal, toPosixPath } = coreUtils;
-const { normalizePhaseName, matchPhaseDirs, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, isForeignPrefixedPhaseQuery, isSentinelPhaseId, extractPhaseToken, scopeToPhase } = phaseId;
+const { comparePhaseNum, normalizePhaseName, matchPhaseDirs, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, isForeignPrefixedPhaseQuery, isSentinelPhaseId, extractPhaseToken, scopeToPhase } = phaseId;
 const { pruneOrphanedWorktrees } = worktreeSafety;
 const { planningPaths, planningDir, planningRoot, listAvailableWorkstreams, peekActiveWorkstream, diagnoseUnresolvedActiveWorkstream, describeUnresolvedWorkstreamReason, findContextMdIn, } = planningWorkspace;
 const { determinePhaseStatus } = commandsMod;
@@ -771,7 +774,6 @@ function cmdInitExecutePhase(cwd, phase, raw, options = {}) {
         ? reqMatch[1].replace(/[\[\]]/g, '').split(',').map((s) => s.trim()).filter(Boolean).join(', ')
         : null;
     const phase_req_ids = reqExtracted && reqExtracted !== 'TBD' ? reqExtracted : null;
-    const wf = (config.workflow ?? {});
     // #3188: these paths are null when the file is absent, matching the contract
     // the conditional sibling fields (context_path, patterns_path, ...) already
     // honour and that ultraplan-phase.md / execute-phase.md gate on. Hoisted so
@@ -782,7 +784,7 @@ function cmdInitExecutePhase(cwd, phase, raw, options = {}) {
     const result = {
         executor_model: resolveModelInternal(cwd, 'gsd-executor'),
         verifier_model: resolveModelInternal(cwd, 'gsd-verifier'),
-        tdd_mode: options['tdd'] || Boolean(wf['tdd_mode']) || false,
+        tdd_mode: options['tdd'] || Boolean(config.tdd_mode) || false,
         commit_docs: config.commit_docs,
         sub_repos: config.sub_repos,
         parallelization: config.parallelization,
@@ -924,7 +926,6 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
     const granularityOverride = options['granularity'];
     assertValidGranularityOverride(granularityOverride, error);
     const granularity = resolveGranularityInternal(cwd, 'planning', granularityOverride || undefined);
-    const wf = (config.workflow ?? {});
     // #3188: see cmdInitExecutePhase — null when absent, parity with the
     // conditional sibling fields in this same result object.
     const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
@@ -934,11 +935,11 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
         researcher_model: resolveModelInternal(cwd, 'gsd-phase-researcher'),
         planner_model: resolveModelInternal(cwd, 'gsd-planner'),
         checker_model: resolveModelInternal(cwd, 'gsd-plan-checker'),
-        tdd_mode: options['tdd'] || Boolean(wf['tdd_mode']) || false,
+        tdd_mode: options['tdd'] || Boolean(config.tdd_mode) || false,
         granularity,
-        research_enabled: wf['research'],
+        research_enabled: config.research,
         plan_checker_enabled: config.plan_checker,
-        nyquist_validation_enabled: wf['nyquist_validation'],
+        nyquist_validation_enabled: config.nyquist_validation,
         commit_docs: config.commit_docs,
         text_mode: config.text_mode,
         auto_advance: !!(config.auto_advance),
@@ -960,6 +961,11 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
             : 'Pending',
         has_research: phaseInfo?.['has_research'] || false,
         has_context: phaseInfo?.['has_context'] || false,
+        // #4014 (epic #3473 B4-unreadable): additive scope signal adjacent to
+        // has_context — SCOPE.COMPLETE by default (no phase directory to read is
+        // a genuine, not-unreadable answer), overwritten below to whatever
+        // findContextMdIn(phaseDirFull) reports once a directory is known.
+        context_scope: SCOPE.COMPLETE,
         has_reviews: phaseInfo?.['has_reviews'] || false,
         has_plans: (phaseInfo?.['plans']?.length || 0) > 0,
         plan_count: phaseInfo?.['plans']?.length || 0,
@@ -974,6 +980,13 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
     };
     if (phaseInfo?.['directory']) {
         const phaseDirFull = node_path_1.default.join(cwd, phaseInfo['directory']);
+        // #4014 (epic #3473 B4-unreadable): findContextMdIn's directory-string
+        // form never throws, so this can record the real scope BEFORE the
+        // pre-existing `fs.readdirSync(phaseDirFull)` immediately below
+        // (unchanged) throws on the same unreadable directory and is caught
+        // exactly as before — additive only, the failure control-flow for
+        // context_path/research_path/etc. is untouched.
+        result['context_scope'] = findContextMdIn(phaseDirFull).scope;
         try {
             const files = node_fs_1.default.readdirSync(phaseDirFull);
             const phaseDirName = node_path_1.default.basename(phaseDirFull);
@@ -1100,6 +1113,34 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
     result['prior_verify_commands'] = priorVerifyCommands;
     output(withProjectRoot(cwd, result), raw);
 }
+// #4040: shared partial-init discriminator for the init.progress / init.resume /
+// init.new-project payloads. A bootstrap interrupted before the core quartet
+// (PROJECT.md / REQUIREMENTS.md / ROADMAP.md / STATE.md) all landed is a
+// DISTINCT routing state from "new project" and from "between milestones";
+// pre-#4040 the payloads could not express it, so progress.md mis-routed it to
+// Route F and resume-project.md offered STATE.md reconstruction.
+//
+// Negative-space guard: `milestone.complete` archives ROADMAP.md (and
+// REQUIREMENTS.md) but always leaves MILESTONES.md behind — so MILESTONES.md
+// present proves missing core files are archival (between-milestones), never an
+// unfinished bootstrap. REQUIREMENTS.md is written by new-project BEFORE
+// ROADMAP/STATE, so its absence also proves init never finished.
+function buildInitCompletenessFields(cwd) {
+    const dir = planningDir(cwd);
+    const planningExists = node_fs_1.default.existsSync(dir);
+    const requirementsExists = node_fs_1.default.existsSync(node_path_1.default.join(dir, 'REQUIREMENTS.md'));
+    const milestonesExists = node_fs_1.default.existsSync(node_path_1.default.join(dir, 'MILESTONES.md'));
+    const coreComplete = node_fs_1.default.existsSync(node_path_1.default.join(dir, 'PROJECT.md')) &&
+        requirementsExists &&
+        node_fs_1.default.existsSync(node_path_1.default.join(dir, 'ROADMAP.md')) &&
+        node_fs_1.default.existsSync(node_path_1.default.join(dir, 'STATE.md'));
+    return {
+        planning_exists: planningExists,
+        requirements_exists: requirementsExists,
+        milestones_exists: milestonesExists,
+        init_incomplete: planningExists && !coreComplete && !milestonesExists,
+    };
+}
 function cmdInitNewProject(cwd, raw, options = {}) {
     const config = loadConfig(cwd);
     const homedir = node_os_1.default.homedir();
@@ -1119,6 +1160,11 @@ function cmdInitNewProject(cwd, raw, options = {}) {
         synthesizer_model: resolveModelInternal(cwd, 'gsd-research-synthesizer'),
         roadmapper_model: resolveModelInternal(cwd, 'gsd-roadmapper'),
         commit_docs: config.commit_docs,
+        // #4040: partial-init discriminator (see buildInitCompletenessFields).
+        // Spread BEFORE this literal's own planning_exists so the existing
+        // root-scoped (`pathExistsInternal(cwd, '.planning')`) semantics for that
+        // one key stay byte-identical for existing consumers.
+        ...buildInitCompletenessFields(cwd),
         project_exists: pathExistsInternal(cwd, toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'PROJECT.md')))),
         has_codebase_map: hasCodebaseMap,
         planning_exists: pathExistsInternal(cwd, '.planning'),
@@ -1158,13 +1204,12 @@ function cmdInitNewMilestone(cwd, raw, options = {}) {
     // owns — routed through it instead of a local readdirSync + hand-rolled
     // window filter (which also never excluded sentinels, unlike the owner).
     const phaseDirCount = listMilestonePhaseDirs(phasesDir, { cwd }).value.length;
-    const wf = (config.workflow ?? {});
     const result = {
         researcher_model: resolveModelInternal(cwd, 'gsd-project-researcher'),
         synthesizer_model: resolveModelInternal(cwd, 'gsd-research-synthesizer'),
         roadmapper_model: resolveModelInternal(cwd, 'gsd-roadmapper'),
         commit_docs: config.commit_docs,
-        research_enabled: wf['research'],
+        research_enabled: config.research,
         // #3216 review Finding 2: `?? null` so an unresolved milestone still emits
         // the key with an explicit `null` rather than letting JSON.stringify drop
         // it — an omitted key reaches the prompt layer's `{current_milestone}`
@@ -1246,6 +1291,10 @@ function cmdInitQuick(cwd, description, raw, options = {}) {
         executor_model: resolveModelInternal(cwd, 'gsd-executor'),
         checker_model: resolveModelInternal(cwd, 'gsd-plan-checker'),
         verifier_model: resolveModelInternal(cwd, 'gsd-verifier'),
+        // #3936: Step 4.75 dispatches gsd-phase-researcher; resolve its own tier
+        // (parity with cmdInitPlanPhase) so the research spawn stops pinning
+        // planner_model.
+        researcher_model: resolveModelInternal(cwd, 'gsd-phase-researcher'),
         // #2072: the quick review step spawns gsd-code-reviewer; resolve its own model
         // so model_overrides / models.verification apply (was reusing executor_model).
         reviewer_model: resolveModelInternal(cwd, 'gsd-code-reviewer'),
@@ -1281,6 +1330,45 @@ function cmdInitQuick(cwd, description, raw, options = {}) {
     result['section_manifest'] = buildSectionManifestField(cwd, null, sectionManifestOptions, 'quick');
     output(withProjectRoot(cwd, result), raw);
 }
+/**
+ * `init.quick-batch` (#3676, Phase 4 of epic #3344, ADR-1239 "Quick-batch
+ * binding"). Unlike `cmdInitQuick`, this init bundle does NOT allocate a
+ * quick id / slug / task directory itself — batch-level id allocation and
+ * `BATCH.json` creation is the job of the `quick-batch create` CLI verb
+ * (`src/quick-batch-command-router.cts`, wrapping `createBatch` in
+ * `src/quick-batch.cts`). This bundle supplies the per-role model profiles,
+ * `commit_docs`, the roadmap/planning existence checks `quick-batch.md`'s
+ * ROADMAP.md gate needs (same check `cmdInitQuick` runs), the `.planning/quick`
+ * directory path, and the `section_manifest` field gating the optional
+ * `--research`/`--validate` step fragments — the same `flag:--research`/
+ * `flag:--validate` atoms `quick`'s own section manifest already uses
+ * (`WHEN_VOCABULARY` is workflow-agnostic; no new atom is needed). `--discuss`/
+ * `--full` are rejected by `quick-batch-dispatch.cts`'s `parseQuickBatchArgs`
+ * before this init bundle is ever reached, so no `discuss`/`full` flag key is
+ * accepted here (unlike `cmdInitQuick`, which still supports both).
+ */
+function cmdInitQuickBatch(cwd, raw, options = {}) {
+    const config = loadConfig(cwd);
+    const result = {
+        planner_model: resolveModelInternal(cwd, 'gsd-planner'),
+        executor_model: resolveModelInternal(cwd, 'gsd-executor'),
+        checker_model: resolveModelInternal(cwd, 'gsd-plan-checker'),
+        verifier_model: resolveModelInternal(cwd, 'gsd-verifier'),
+        researcher_model: resolveModelInternal(cwd, 'gsd-phase-researcher'),
+        reviewer_model: resolveModelInternal(cwd, 'gsd-code-reviewer'),
+        commit_docs: config.commit_docs,
+        // #2376: absolute — see comment on phase_dir in cmdInitExecutePhase; a
+        // per-item task_dir is re-derived by the workflow itself (quick_id +
+        // generate-slug over that item's description), never allocated here.
+        quick_dir: toPosixPath(node_path_1.default.join(planningDir(cwd), 'quick')),
+        quick_batches_dir: toPosixPath(node_path_1.default.join(planningDir(cwd), 'quick-batches')),
+        roadmap_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
+        planning_exists: node_fs_1.default.existsSync(planningRoot(cwd)),
+    };
+    // #2992 (Phase 6.1): additive, optional field — degrades to null, never throws.
+    result['section_manifest'] = buildSectionManifestField(cwd, null, options, 'quick-batch');
+    output(withProjectRoot(cwd, result), raw);
+}
 function cmdInitIngestDocs(cwd, raw) {
     const config = loadConfig(cwd);
     const result = {
@@ -1305,12 +1393,11 @@ function cmdInitIngestDocs(cwd, raw) {
 }
 function cmdInitOnboard(cwd, raw, options = {}) {
     const config = loadConfig(cwd);
-    const workflowConfig = (config.workflow ?? {});
     const result = {
         ...buildOnboardProjection(cwd, {
             commitDocs: !!config.commit_docs,
             fast: options['fast'] === true,
-            textMode: options['text'] === true || !!config.text_mode || !!workflowConfig['text_mode'],
+            textMode: options['text'] === true || !!config.text_mode,
         }),
         ...getInitGitState(cwd),
     };
@@ -1323,6 +1410,11 @@ function cmdInitResume(cwd, raw) {
     if (agentIdRaw !== null)
         interruptedAgentId = agentIdRaw.trim();
     const result = {
+        // #4040: partial-init discriminator (see buildInitCompletenessFields).
+        // Spread FIRST so this literal's own root-scoped planning_exists
+        // (planningRoot) keeps its existing semantics; init_incomplete itself
+        // keys off the artifact dir (planningDir) where the core docs live.
+        ...buildInitCompletenessFields(cwd),
         state_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
         roadmap_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
         project_exists: pathExistsInternal(cwd, toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'PROJECT.md')))),
@@ -1720,6 +1812,9 @@ function cmdInitPhaseOp(cwd, phase, raw) {
         padded_phase: phaseNumber ? normalizePhaseName(phaseNumber) : null,
         has_research: phaseInfo?.['has_research'] || false,
         has_context: phaseInfo?.['has_context'] || false,
+        // #4014 (epic #3473 B4-unreadable): see the parallel field in
+        // cmdInitPlanPhase — additive scope signal adjacent to has_context.
+        context_scope: SCOPE.COMPLETE,
         has_plans: (phaseInfo?.['plans']?.length || 0) > 0,
         has_verification: phaseInfo?.['has_verification'] || false,
         has_reviews: phaseInfo?.['has_reviews'] || false,
@@ -1734,6 +1829,9 @@ function cmdInitPhaseOp(cwd, phase, raw) {
     };
     if (phaseInfo?.['directory']) {
         const phaseDirFull = node_path_1.default.join(cwd, phaseInfo['directory']);
+        // #4014 (epic #3473 B4-unreadable): see the parallel site in
+        // cmdInitPlanPhase — additive only, failure control-flow below unchanged.
+        result['context_scope'] = findContextMdIn(phaseDirFull).scope;
         try {
             const files = node_fs_1.default.readdirSync(phaseDirFull);
             const phaseDirName = node_path_1.default.basename(phaseDirFull);
@@ -2062,6 +2160,9 @@ function cmdInitManager(cwd, raw) {
         let hasResearch = false;
         let lastActivity = null;
         let isActive = false;
+        // #4014 (epic #3473 B4-unreadable): default COMPLETE — no directory at
+        // all (dirMatch not found) is a genuine, not-unreadable answer.
+        let contextScope = SCOPE.COMPLETE;
         let completion = buildPhaseCompletionProjection(cwd, phaseNum, null, planCount, summaryCount, _slashRuntime);
         try {
             // #3185 (ADR-3180 Decision 2) moved this lookup off the
@@ -2072,6 +2173,17 @@ function cmdInitManager(cwd, raw) {
             if (dirMatch) {
                 const fullDir = node_path_1.default.join(phasesDir, dirMatch);
                 const phaseDirRel = toPosixPath(node_path_1.default.relative(cwd, fullDir));
+                // #4014 (epic #3473 B4-unreadable): this whole block used to swallow
+                // ANY readdirSync failure below into the bare `catch { /* empty */ }`
+                // at the bottom — an unreadable phase directory reported the exact
+                // same `has_context: false` / `disk_status: 'no_directory'` as a
+                // directory that never existed. findContextMdIn's directory-string
+                // form never throws, so it can record the real scope (COMPLETE vs
+                // UNREADABLE) here, BEFORE the pre-existing `fs.readdirSync(fullDir)`
+                // immediately below (unchanged) throws on the exact same unreadable
+                // directory and is caught exactly as before — this line is additive
+                // only, the failure control-flow is untouched.
+                contextScope = findContextMdIn(fullDir).scope;
                 const phaseFiles = node_fs_1.default.readdirSync(fullDir);
                 planCount = listPhasePlanFiles(fullDir).length;
                 summaryCount = listPhaseSummaryFiles(fullDir).length;
@@ -2146,6 +2258,7 @@ function cmdInitManager(cwd, raw) {
             ...completion,
             last_activity: lastActivity,
             is_active: isActive,
+            context_scope: contextScope,
         });
     }
     const MAX_NAME_WIDTH = 20;
@@ -2522,7 +2635,7 @@ function cmdInitTransition(cwd, raw, options = {}) {
  *   location has one source instead of two kept in sync by hand.
  * - `debugger_model` — `resolveModelInternal`, which IS what `query
  *   resolve-model --pick model` returns (`cmdResolveModel`, src/commands.cts).
- * - `tdd_mode` — the `Boolean(wf['tdd_mode'])` idiom `cmdInitExecutePhase` and
+ * - `tdd_mode` — the `Boolean(config.tdd_mode)` idiom `cmdInitExecutePhase` and
  *   `cmdInitPlanPhase` already use. `/gsd:debug` has no `--tdd` flag, so the
  *   sibling handlers' `options['tdd'] ||` disjunct is deliberately omitted
  *   rather than carried as a phantom.
@@ -2540,7 +2653,6 @@ function cmdInitTransition(cwd, raw, options = {}) {
  */
 function cmdInitDebug(cwd, raw, options = {}) {
     const config = loadConfig(cwd);
-    const wf = (config.workflow ?? {});
     const result = {
         commit_docs: config.commit_docs,
         // #2376: absolute — debug.md builds `debug_file_path` as
@@ -2548,7 +2660,7 @@ function cmdInitDebug(cwd, raw, options = {}) {
         // own cwd may differ from the orchestrator's.
         debug_dir: toPosixPath(planningPaths(cwd).debug),
         debugger_model: resolveModelInternal(cwd, 'gsd-debugger'),
-        tdd_mode: Boolean(wf['tdd_mode']),
+        tdd_mode: Boolean(config.tdd_mode),
         diagnose: options['diagnose'] === true,
     };
     // Additive, optional field — degrades to null while `debug` has no key in
@@ -2709,7 +2821,7 @@ function cmdInitProgress(cwd, raw, options = {}) {
             }
         }
     }
-    phases.sort((a, b) => parseInt(a['number'], 10) - parseInt(b['number'], 10));
+    phases.sort((a, b) => comparePhaseNum(a['number'], b['number']));
     // #3581: the frontier is ROADMAP ORDER, not artifact presence. The disk loop
     // above could claim nextPhase from a stray out-of-order artifact directory
     // (a phase-9 UAT evidence dir while roadmap phase 8 was pending and
@@ -2771,6 +2883,10 @@ function cmdInitProgress(cwd, raw, options = {}) {
         project_exists: pathExistsInternal(cwd, toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'PROJECT.md')))),
         roadmap_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
         state_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
+        // #4040: partial-init discriminator (see buildInitCompletenessFields) —
+        // also adds planning_exists / requirements_exists / milestones_exists so
+        // progress.md's init_context routing never has to fall back to Glob.
+        ...buildInitCompletenessFields(cwd),
         // #2376: absolute — see comment on phase_dir in cmdInitExecutePhase.
         state_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
         roadmap_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
@@ -3419,6 +3535,7 @@ module.exports = {
     cmdInitNewProject,
     cmdInitNewMilestone,
     cmdInitQuick,
+    cmdInitQuickBatch,
     cmdInitIngestDocs,
     cmdInitOnboard,
     cmdInitResume,

package/gsd-core/bin/lib/install-engine.cjs

@@ -55,6 +55,148 @@ const { processAttribution } = runtimeArtifactConversion;
 // resolveRuntimeArtifactLayout: accessed via module ref (not destructured) so
 // test stubs that monkeypatch the module's exports are seen at call time.
 const { getDirName } = runtimeNamePolicy;
+function withInstallerPackageSource(configDir, fn) {
+    // Reuse the existing compatibility-marker contract through the existing fs
+    // seam. The marker exists only in this synchronous call tree: no disk state,
+    // layout export, stage argument, or caller-settable authority flag is added.
+    const markerPath = node_path_1.default.resolve(configDir, '.gsd-source');
+    const packageCommandsRoot = runtimeArtifactLayout.findInstallSourceRoot();
+    const markerBytes = Buffer.from(packageCommandsRoot + '\n');
+    const base = installFs();
+    const overlay = {
+        ...base,
+        existsSync: (candidate) => node_path_1.default.resolve(candidate) === markerPath || base.existsSync(candidate),
+        lstatSync: (candidate) => node_path_1.default.resolve(candidate) === markerPath
+            ? { isFile: () => true, isDirectory: () => false, isSymbolicLink: () => false }
+            : base.lstatSync(candidate),
+        readFileSync: ((candidate, encoding) => {
+            if (node_path_1.default.resolve(candidate) !== markerPath) {
+                return encoding ? base.readFileSync(candidate, encoding) : base.readFileSync(candidate);
+            }
+            return encoding ? markerBytes.toString(encoding) : Buffer.from(markerBytes);
+        }),
+    };
+    return withInstallFs(overlay, fn);
+}
+function isRuntimeSurfaceSourceUnavailable(message) {
+    return message.startsWith('Runtime Surface source is unavailable or incomplete for ') &&
+        message.endsWith('install or upgrade gsd-core before materializing this surface.');
+}
+function assertCorpusTreeHasNoSymlinks(root) {
+    if (!installFs().existsSync(root))
+        return;
+    const stat = installFs().lstatSync(root);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`Runtime Surface corpus path is a symlink: ${root}`);
+    }
+    if (!stat.isDirectory())
+        return;
+    for (const name of installFs().readdirSync(root)) {
+        assertCorpusTreeHasNoSymlinks(node_path_1.default.join(root, name));
+    }
+}
+function previousOwnedCorpusFiles(configDir, prefix) {
+    try {
+        const files = installerMigrations.readInstallManifest(configDir).files;
+        return Object.keys(files)
+            .filter((entry) => entry.startsWith(prefix))
+            .map((entry) => entry.slice(prefix.length))
+            .filter((entry) => entry !== '' && !node_path_1.default.posix.isAbsolute(entry) && !entry.split('/').some((part) => part === '' || part === '.' || part === '..'));
+    }
+    catch {
+        // An absent or unreadable prior manifest provides no ownership evidence.
+        // Preserve existing entries rather than guessing that they are stale.
+        return [];
+    }
+}
+function pruneEmptyCorpusParents(start, stop) {
+    let current = node_path_1.default.dirname(start);
+    while (current !== stop && current.startsWith(stop + node_path_1.default.sep)) {
+        if (installFs().readdirSync(current).length > 0)
+            return;
+        installFs().rmdirSync(current);
+        current = node_path_1.default.dirname(current);
+    }
+}
+function syncRuntimeSurfaceCorpus(source, destination, configDir, manifestPrefix) {
+    if (hasExistingSymlinkBetween(node_path_1.default.resolve(configDir), destination, { allowOptInFollow: isSymlinkedDestOptIn() })) {
+        throw new Error(`syncRuntimeSurfaceCorpus: destination "${destination}" contains a symlink the install root "${configDir}" does not trust — refusing to write.`);
+    }
+    assertCorpusTreeHasNoSymlinks(destination);
+    // Remove only paths the previous manifest proves GSD owned and which the
+    // executing package no longer ships. Unknown neighbouring files survive.
+    for (const relative of previousOwnedCorpusFiles(configDir, manifestPrefix)) {
+        const sourceEntry = node_path_1.default.join(source, ...relative.split('/'));
+        let sourceIsFile = false;
+        try {
+            sourceIsFile = installFs().lstatSync(sourceEntry).isFile();
+        }
+        catch {
+            sourceIsFile = false;
+        }
+        if (sourceIsFile)
+            continue;
+        const target = node_path_1.default.join(destination, ...relative.split('/'));
+        if (!installFs().existsSync(target))
+            continue;
+        const targetStat = installFs().lstatSync(target);
+        if (!targetStat.isFile()) {
+            throw new Error(`Runtime Surface corpus ownership conflict at ${target}`);
+        }
+        installFs().rmSync(target, { force: true });
+        pruneEmptyCorpusParents(target, destination);
+    }
+    installFs().mkdirSync(node_path_1.default.dirname(destination), { recursive: true });
+    installFs().cpSync(source, destination, { recursive: true });
+}
+/**
+ * Provision the raw, installation-owned input needed to re-materialize a
+ * global Runtime Surface after the executing package tree disappears.
+ *
+ * The corpus deliberately lives below the already-installed `gsd-core/`
+ * tree and is accepted only after its manifest ownership and hashes verify.
+ * The compatibility marker does not replace that installed-corpus authority.
+ */
+function provisionRuntimeSurfaceCorpus(layout, configDir, scope) {
+    const required = new Set();
+    if ((0, install_scope_cjs_1.isGlobalScope)(scope)) {
+        for (const kind of layout.kinds) {
+            if (kind.kind === 'commands' || kind.kind === 'skills')
+                required.add('commands');
+            if (kind.kind === 'agents' || kind.kind === 'kimi-agents')
+                required.add('agents');
+        }
+    }
+    if (required.size === 0)
+        return;
+    const corpusRoot = node_path_1.default.join(configDir, 'gsd-core');
+    if (required.has('commands')) {
+        const source = runtimeArtifactLayout.findInstallSourceRoot();
+        const destination = node_path_1.default.join(corpusRoot, 'commands', 'gsd');
+        syncRuntimeSurfaceCorpus(source, destination, configDir, 'gsd-core/commands/gsd/');
+    }
+    if (required.has('agents')) {
+        const source = node_path_1.default.join(executingPackageRoot(), 'agents');
+        const destination = node_path_1.default.join(corpusRoot, 'agents');
+        syncRuntimeSurfaceCorpus(source, destination, configDir, 'gsd-core/agents/');
+    }
+    const markerFile = _hostBehaviors(layout.runtime).sourceMarkerFile;
+    if (typeof markerFile === 'string' && markerFile !== '' && required.has('commands')) {
+        try {
+            const markerPath = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, markerFile);
+            if (hasExistingSymlinkBetween(node_path_1.default.resolve(configDir), markerPath, { allowOptInFollow: isSymlinkedDestOptIn() })) {
+                throw new Error(`compatibility marker "${markerPath}" contains an untrusted symlink`);
+            }
+            installFs().writeFileSync(markerPath, node_path_1.default.join(corpusRoot, 'commands', 'gsd') + '\n', 'utf8');
+        }
+        catch {
+            // The existing installer marker writer owns the user-facing warning and
+            // keeps marker failure non-fatal. The installed corpus remains usable
+            // without the compatibility marker.
+        }
+    }
+}
+function executingPackageRoot() { return node_path_1.default.dirname(node_path_1.default.dirname(runtimeArtifactLayout.findInstallSourceRoot())); }
 // ---------------------------------------------------------------------------
 // USER_OWNED_ARTIFACTS
 // ---------------------------------------------------------------------------
@@ -977,6 +1119,7 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
  */
 function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined, capabilityRegistry, deps = {}) {
     return withInstallFs(deps.fs, () => {
+        const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, configDir, scope, capabilityRegistry);
         // A removed descriptor kind is no longer visited by the layout loop, so it
         // cannot prune its own previous output. Clean manifest-proven retired files
         // before materializing the current layout (#2644).
@@ -986,6 +1129,7 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         // generic layout-driven loop below, mirroring the bespoke install path that
         // previously lived inline in bin/install.js.
         const behaviors = _hostBehaviors(runtime);
+        const projectDir = scope === 'global' ? process.cwd() : configDir;
         if (behaviors.combinedFamilyInstall) {
             // #2329: combined-family runtimes (OpenCode/Kilo) bypass
             // _runLegacyInstallMigrations below entirely (early return), so their
@@ -994,17 +1138,24 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
             // #2874 design row 2: this early return must ALSO return an executed
             // plan — installOpencodeFamilyArtifacts reports what it wrote, so a
             // whole runtime family returning undefined is no longer a hole.
-            return installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution, behaviors, capabilityRegistry);
+            // An injected filesystem supplies its own hermetic corpus fixture. The
+            // real installer is the authority that refreshes package bytes into the
+            // durable installed corpus; attempting that cross-filesystem copy through
+            // an in-memory destination adapter would read from the wrong filesystem.
+            if (!deps.fs)
+                provisionRuntimeSurfaceCorpus(layout, configDir, scope);
+            return installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution, behaviors, capabilityRegistry, deps.packageRoot, projectDir);
         }
         // Legacy cleanup before layout-driven writes
         _runLegacyInstallMigrations(runtime, configDir, scope);
-        const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, configDir, scope, capabilityRegistry);
+        if (!deps.fs)
+            provisionRuntimeSurfaceCorpus(layout, configDir, scope);
         // #3712: a global `home` override escapes the sandboxed configDir. Refuse to
         // execute when a test run would land that escape in the developer's real home.
         testHomeGuard.assertTestHomeSandboxed('installRuntimeArtifacts', runtime, layout?.kinds, {
             os: deps.os, env: deps.env,
         });
-        const planResult = runtimeArtifactInstallPlan.createRuntimeArtifactInstallPlan({
+        const createPlan = () => runtimeArtifactInstallPlan.createRuntimeArtifactInstallPlan({
             // `Layout` is structurally identical across the layout/install-plan .cjs
             // modules but nominally distinct to tsc (untyped .cjs boundary) — bridge it.
             layout: layout,
@@ -1012,7 +1163,16 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
             homedir: () => node_os_1.default.homedir(),
             platform: process.platform,
             resolveAttribution,
+            projectDir,
         });
+        let planResult = createPlan();
+        if (scope === 'global' &&
+            !planResult.ok &&
+            planResult.kind === 'stage_failed' &&
+            planResult.cleanupDirs.length === 0 &&
+            isRuntimeSurfaceSourceUnavailable(planResult.message)) {
+            planResult = withInstallerPackageSource(configDir, createPlan);
+        }
         const cleanupDirs = planResult.ok ? planResult.plan.cleanupDirs : planResult.cleanupDirs;
         // #2874 row 1/4/5: per-kind executed-plan entries, appended only as the
         // loop below actually finishes writing each kind — a kind that throws
@@ -1176,8 +1336,10 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         // is safe even when configDir has no .gsd-source marker (artifactLayout: []).
         let nativePluginInstalled = false;
         if (behaviors.nativePlugin) {
-            const commandsGsdDir = runtimeArtifactLayout.findInstallSourceRoot(configDir);
-            const src = node_path_1.default.dirname(node_path_1.default.dirname(commandsGsdDir));
+            // Native plugin sources live only in the executing package, never in the
+            // durable Runtime Surface corpus. Do not derive this package root from a
+            // config-scoped provider that may now correctly resolve installed input.
+            const src = deps.packageRoot ?? executingPackageRoot();
             _installNativePluginIfDeclared(runtime, configDir, behaviors, src);
             nativePluginInstalled = true;
         }
@@ -1388,12 +1550,13 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
  * @param capabilityRegistry - #2362: optional composed capability registry, threaded
  *   straight through to resolveRuntimeArtifactLayout (unused by the agents kind today,
  *   but kept for signature parity with the skills/commands siblings on this call tree)
+ * @param projectDir - project/config discovery root, distinct from the artifact destination
  * @returns `{ sourceDir, destDir }` describing what was written, or `null` when the
  *   runtime's layout declares no `agents` kind.
  */
-function installAgentsKindStandalone(runtime, targetDir, scope, resolvedProfile, pathPrefix, resolveAttribution = () => undefined, capabilityRegistry) {
+function installAgentsKindStandalone(runtime, targetDir, scope, resolvedProfile, pathPrefix, resolveAttribution = () => undefined, capabilityRegistry, projectDir) {
     const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, targetDir, scope, capabilityRegistry);
-    const agentsKindEntry = layout.kinds.find((k) => k.kind === 'agents');
+    const agentsKindEntry = layout.kinds.find((kind) => kind.kind === 'agents');
     if (!agentsKindEntry)
         return null;
     // #3712: this writer selects `agentsKindEntry.home` over targetDir below and then
@@ -1408,8 +1571,16 @@ function installAgentsKindStandalone(runtime, targetDir, scope, resolvedProfile,
     // for the generic layout-driven loop (runtime-artifact-install-plan.cts) —
     // targetDir IS the install root the inline agent loop called `targetDir`.
     const attribution = resolveAttribution ? resolveAttribution(runtime) : undefined;
-    const agentCtx = { runtime, pathPrefix, attribution, targetDir };
-    const stagedDir = agentsKindEntry.stage(resolvedProfile, agentCtx);
+    const agentCtx = { runtime, pathPrefix, attribution, targetDir, projectDir: projectDir ?? targetDir };
+    let stagedDir;
+    try {
+        stagedDir = agentsKindEntry.stage(resolvedProfile, agentCtx);
+    }
+    catch (err) {
+        if (scope !== 'global' || !isRuntimeSurfaceSourceUnavailable(err.message))
+            throw err;
+        stagedDir = withInstallerPackageSource(targetDir, () => agentsKindEntry.stage(resolvedProfile, agentCtx));
+    }
     const stagedAgentFiles = installFs().existsSync(stagedDir)
         ? installFs().readdirSync(stagedDir).filter((f) => f.endsWith('.md'))
         : [];
@@ -1670,12 +1841,13 @@ function _migrateLegacyOpencodeCommandDir(runtime, configDir, behaviors) {
  *   installOpencodeFamilySkills so an installed third-party capability skill
  *   materializes for this combined-family (OpenCode/Kilo) install path too.
  *   Absent -> no third-party skills staged (fail closed).
+ * @param projectDir - project/config discovery root, distinct from configDir for global installs
  * @returns #2874 design row 2: an executed-plan value, same top-level shape
  *   (`runtime`/`scope`/`kinds`/`cleanup`/`postSteps`) as the generic
  *   `installRuntimeArtifacts` branch — this was the one early return a
  *   `void`-shaped hole survived unnoticed in.
  */
-function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined, behaviors = {}, capabilityRegistry) {
+function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined, behaviors = {}, capabilityRegistry, packageRoot, projectDir) {
     // #2870: `scope` keeps its exported required `string` signature (no
     // signature change). It is always the `installRuntimeArtifacts`-forwarded
     // 'global' | 'local' literal produced by bin/install.js's scope-resolution
@@ -1688,7 +1860,7 @@ function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfi
     // into stageSkillsForProfile/stageSkillsForRuntimeAsSkills. The repo/package
     // root (needed below for the native plugin source) is two levels up.
     const commandsGsdDir = runtimeArtifactLayout.findInstallSourceRoot(configDir);
-    const src = node_path_1.default.dirname(node_path_1.default.dirname(commandsGsdDir));
+    const src = packageRoot ?? executingPackageRoot();
     const rawCommandsDir = installProfiles.stageSkillsForProfile(commandsGsdDir, resolvedProfile);
     const pathPrefix = runtimeArtifactConversion._computePathPrefix({
         isGlobal,
@@ -1711,7 +1883,7 @@ function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfi
     // generic layout-driven loop uses (see installAgentsKindStandalone's own
     // doc). A `null` result means this runtime's layout declares no `agents`
     // kind — nothing written, nothing reported (no #1879-F15 inert claim).
-    const agentsResult = installAgentsKindStandalone(runtime, configDir, scope, resolvedProfile, pathPrefix, resolveAttribution, capabilityRegistry);
+    const agentsResult = installAgentsKindStandalone(runtime, configDir, scope, resolvedProfile, pathPrefix, resolveAttribution, capabilityRegistry, projectDir);
     _installNativePluginIfDeclared(runtime, configDir, behaviors, src);
     // #2874 design row 2: report what this combined-family install wrote,
     // mirroring the generic branch's top-level shape. `cleanup` is `[]` — this