@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/workstream-inventory-builder.cjs

@@ -16,30 +16,23 @@ exports.pickRollupWinners = pickRollupWinners;
 exports.isCompletedInventory = isCompletedInventory;
 exports.buildWorkstreamInventory = buildWorkstreamInventory;
 const node_path_1 = __importDefault(require("node:path"));
+const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
 // Internal helpers
 function toPosixPath(p) {
     return p.split('\\').join('/');
 }
-/**
- * #2562: verification verdicts that DISQUALIFY a phase from `complete`, even
- * when its SUMMARY count meets its PLAN count. Deliberately scoped to the two
- * EXPLICIT failing verdicts the verifier emits — `missing`/`unknown` (verifier
- * off / not yet run) and `stale` (mtime-derived, #2348) are intentionally left
- * untouched so verifier-disabled projects do not regress to never-complete.
- *
- * #2645: `'unrecorded'` is NOT a verdict the verifier itself ever emits — it
- * is an internal sentinel `workstream-inventory.cts`'s verification-deletion
- * ledger substitutes for `'missing'` once that workstream has ADOPTED the
- * ledger (a `.verification-ledger.json` file exists for it) but has no
- * remembered entry for this specific phase. Pre-adoption (no ledger file at
- * all) still resolves to plain `'missing'`, which stays OUTSIDE this set —
- * that is what keeps a project untouched by this fix until it actually uses
- * the verifier at least once. Post-adoption, an unrecorded phase fails
- * CLOSED (counted here) rather than open, so a corrupt or evidence-absent
- * ledger entry can no longer be read as "safe to complete" the way a bare
- * `'missing'` sentinel is.
- */
-const FAILING_VERIFICATION_STATUSES = new Set(['gaps_found', 'human_needed', 'unrecorded']);
+// #2562/#2645's FAILING_VERIFICATION_STATUSES set (the verdicts that used to
+// disqualify a phase from `complete` when combined with a local
+// summary-count-meets-plan-count check) was removed by ADR-3180 §7.4
+// (#3186): `complete` is now the single canonical owner's verdict
+// (`PhaseFilesCount.complete`, computed via `isPhaseComplete` by the
+// I/O-capable caller — see the loop below), which already requires
+// `verification.status === 'passed'` unconditionally. Disk-strict (#2957)
+// deliberately DROPS the prior "verifier-disabled projects fall back to
+// summaries-met" tolerance that set existed to preserve — a phase with no
+// `*-VERIFICATION.md` (`missing`) is no longer treated as complete just
+// because its summaries meet its plan count. Disclosed in this phase's
+// changeset.
 /**
  * #2562 / Bug #2445 / #2645 review: pick ONE winning item per key from a
  * PRE-SORTED list — newest `mtimeMs` wins; on an exact tie the incumbent
@@ -127,11 +120,20 @@ function buildWorkstreamInventory(inputs) {
         const counts = countsMap.get(dir);
         const planCount = counts?.planCount ?? 0;
         const summaryCount = counts?.summaryCount ?? 0;
-        // #2562: SUMMARY≥PLAN parity is necessary but not sufficient — a phase whose
-        // verification verdict is an explicit failing one is still in progress.
-        const verificationStatus = counts?.verificationStatus ?? 'missing';
-        const summariesMeetPlans = summaryCount >= planCount && planCount > 0;
-        const status = summariesMeetPlans && !FAILING_VERIFICATION_STATUSES.has(verificationStatus)
+        // ADR-3180 §7.4 (issue #3186): routed through the single canonical owner
+        // (`isPhaseComplete`, src/verification.cts) — via `PhaseFilesCount.complete`,
+        // which the I/O-capable CALLER computes (this module is a PURE, I/O-free
+        // projection — see the module header: "No I/O. No async." — and cannot
+        // call the owner itself). The prior local derivation
+        // (`summaryCount >= planCount && planCount > 0` combined with a
+        // caller-supplied verification status) was this module's OWN completion
+        // verdict computed from raw counts — the exact "post-process a canonical
+        // result locally" bypass §7.4 rules out, and it reproduced the disk-strict
+        // headline case (#3168): a zero-plan phase with a passing verification
+        // read `pending` instead of `complete`. `complete` defaults to `false`
+        // when absent so a caller that has not been updated to pass it never
+        // silently reads as complete.
+        const status = (counts?.complete ?? false)
             ? 'complete'
             : planCount > 0
                 ? 'in_progress'
@@ -243,12 +245,31 @@ function buildWorkstreamInventory(inputs) {
         roadmap_phase_count: effectivePhaseCount,
         total_plans: totalPlans,
         completed_plans: completedPlans,
-        // The `Math.min` cap is unreachable under milestone scoping (the invariant
-        // above throws first) and survives only for the legacy unscoped path, where
-        // the denominator is a roadmap heading count that a caller cannot guarantee
-        // bounds the numerator.
-        progress_percent: effectivePhaseCount > 0
-            ? Math.min(100, Math.round((completedPhases / effectivePhaseCount) * 100))
-            : 0,
+        // `clampPercent`'s 100 ceiling is unreachable under milestone scoping (the
+        // invariant above throws first) and matters only for the legacy unscoped
+        // path, where the denominator is a roadmap heading count that a caller
+        // cannot guarantee bounds the numerator.
+        //
+        // #3217 (ADR-3180 §7.6 rule 4) — WRITTEN REASON this site is NOT migrated
+        // onto the `SCOPE` enum this phase: `buildWorkstreamInventory` is a pure
+        // projection (no I/O — see the module header) fed `BuildWorkstreamInventoryInputs`
+        // by `workstream-inventory.cts`. Its own `milestoneScoped` is a pre-ADR-3180
+        // bespoke boolean, not a `SCOPE` value, and its caller does not currently
+        // thread a real `listMilestonePhaseDirs` scope into these inputs. Doing
+        // this honestly requires ONE of: (a) widening `BuildWorkstreamInventoryInputs`
+        // with a `Scope` field and `WorkstreamInventory.progress_percent`'s type
+        // from `number` to `number | null` — the exact "re-architecting
+        // StateProjection/WorkstreamInventory return types" the design phase
+        // (`.gsd/phase/refactor-3217-completion-ratio-scoping/40-design.md`,
+        // "Known limits") states is OUT of this phase's scope; or (b) silently
+        // reusing `milestoneScoped` as a `Scope` stand-in, which would be exactly
+        // the kind of proxy-for-a-data-flow-property this same phase's guard
+        // section explicitly rejects (a `boolean` cannot distinguish TRUNCATED
+        // from UNSCOPED from UNREADABLE, so a caller could not tell which
+        // non-answer it got). Left un-migrated rather than done dishonestly;
+        // `workstream inventory`'s `progress_percent` can still render a number
+        // derived from an under-scoped set (A8 in the phase's test matrix is
+        // NOT covered here for that reason — see this phase's PR description).
+        progress_percent: (0, phase_lifecycle_cjs_1.clampPercent)(completedPhases, effectivePhaseCount),
     };
 }

package/gsd-core/bin/lib/workstream-inventory.cjs

@@ -27,10 +27,13 @@ const planScan = require("./plan-scan.cjs");
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningPaths, planningRoot, getActiveWorkstream } = planningWorkspace;
 const state_document_cjs_1 = require("./state-document.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
+const frontmatterMod = require("./frontmatter.cjs");
+const { extractFrontmatter, stripFrontmatter } = frontmatterMod;
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
 const verificationMod = require("./verification.cjs");
-const { readVerificationStatus } = verificationMod;
+const { isPhaseComplete } = verificationMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
 const { phaseKeyFromDir, phaseKeyFromProse, parentPhaseKey } = phaseIdMod;
@@ -42,11 +45,28 @@ const workstream_inventory_builder_cjs_1 = require("./workstream-inventory-build
 function workstreamsRoot(cwd) {
     return node_path_1.default.join(planningRoot(cwd), 'workstreams');
 }
-function countRoadmapPhases(roadmapPath, fallbackCount) {
+/**
+ * #3185 (ADR-3180 Decision 1): count the phases the CURRENT milestone
+ * declares, not every `Phase` heading in the file.
+ *
+ * This previously matched `^#{2,4}\s+Phase\s+…` across the whole ROADMAP with
+ * no milestone window and no sentinel filter, so it counted 999.* backlog and
+ * Phase 0 headings and spanned every milestone the document had ever had.
+ * `getMilestonePhaseFilter` already computes exactly this number for the
+ * scoped window (`phaseCount`, sentinel-filtered), and `inspectWorkstream` in
+ * this same file already passes a resolved `currentVersion` to it — this
+ * function was the sibling copy that never got the fix.
+ */
+function countRoadmapPhases(roadmapPath, fallbackCount, cwd, ws, versionOverride) {
     try {
-        const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-        const matches = roadmapContent.match(/^#{2,4}\s+Phase\s+[\w][\w.-]*/gm);
-        return matches ? matches.length : fallbackCount;
+        if (!node_fs_1.default.existsSync(roadmapPath))
+            return fallbackCount;
+        if (!cwd)
+            return fallbackCount;
+        const filter = getMilestonePhaseFilter(cwd, versionOverride ?? null, null, ws ?? null);
+        // A pass-all degrade (phaseCount 0) means the window declared no phases —
+        // fall back rather than reporting a confident zero.
+        return filter.phaseCount > 0 ? filter.phaseCount : fallbackCount;
     }
     catch {
         return fallbackCount;
@@ -312,13 +332,30 @@ function writeVerificationLedger(wsDir, ledger) {
 function readStateProjection(statePath) {
     try {
         const stateContent = node_fs_1.default.readFileSync(statePath, 'utf-8');
+        // #3187: route Status/Current Phase/Last Activity through the single
+        // #1760 fallback-chain owner (state-document.cjs's stateFieldValue)
+        // instead of a frontmatter-blind stateExtractField(stateContent, …) call,
+        // mirroring cmdStateValidate/cmdStateSnapshot — a STATE.md whose fields
+        // live only in frontmatter is no longer projected as absent here.
+        const fm = extractFrontmatter(stateContent, statePath);
+        const body = stripFrontmatter(stateContent);
         return {
-            status: (0, state_document_cjs_1.stateExtractField)(stateContent, 'Status') || 'unknown',
-            current_phase: (0, state_document_cjs_1.stateExtractField)(stateContent, 'Current Phase'),
-            last_activity: (0, state_document_cjs_1.stateExtractField)(stateContent, 'Last Activity'),
+            status: (0, state_document_cjs_1.stateFieldValue)(fm, body, 'status', 'Status').value || 'unknown',
+            current_phase: (0, state_document_cjs_1.stateFieldValue)(fm, body, 'current_phase', 'Current Phase').value,
+            last_activity: (0, state_document_cjs_1.stateFieldValue)(fm, body, 'last_activity', 'Last Activity').value,
         };
     }
     catch {
+        // Read/parse failure (missing file, permission fault, etc.) degrades to
+        // an all-unknown projection — unchanged. Not widened to also carry a
+        // `scope` here: doing so would ripple `StateProjection`
+        // (workstream-inventory-builder.cjs) and every consumer of this
+        // read-only rollup — the design doc's blast-radius table rates
+        // `readStateProjection` "low"/Tier-2, and this call site's migration is
+        // scoped to routing the fallback chain, not to widening the return type.
+        // The existing all-unknown degrade already distinguishes "could not
+        // read" from any real field value; only its scope-vs-absence *reason*
+        // stays uncaptured, same as before this change.
         return {
             status: 'unknown',
             current_phase: null,
@@ -483,7 +520,16 @@ function inspectWorkstream(cwd, name, options = {}) {
     const rawPhaseEntries = [...phaseDirNames].sort().map(dir => {
         const phaseDir = node_path_1.default.join(p.phases, dir);
         const counts = countPhaseFiles(phaseDir);
-        const verificationResult = readVerificationStatus(phaseDir);
+        // ADR-3180 §7.4 (#3186): routed through the single canonical owner
+        // (`isPhaseComplete`, src/verification.cts) instead of calling
+        // `readVerificationStatus` directly and re-deriving "is this phase
+        // complete" locally from its `.status`. `completionResult.value.complete`
+        // is threaded down to the builder below (as `PhaseFilesCount.complete`)
+        // so `buildWorkstreamInventory` — a pure, I/O-free projection that
+        // cannot call the owner itself — consumes the owner's verdict rather
+        // than re-deriving a second one from summary/plan counts.
+        const completionResult = isPhaseComplete(phaseDir);
+        const verificationResult = completionResult.value.verification;
         // #3057 B3: routing is UNCHANGED — `liveVerificationStatus` below is still
         // `.status`, exactly as before, so the ledger/rollup logic that consumes
         // it is unaffected. This only makes an indeterminate staleness check
@@ -502,6 +548,12 @@ function inspectWorkstream(cwd, name, options = {}) {
             summaryCount: counts.summaryCount,
             inMilestone: isDirInCurrentMilestone(dir),
             liveVerificationStatus: verificationResult.status,
+            // ADR-3180 §7.4 (#3186): the owner's verdict, read live off disk — never
+            // ledger-adjusted (see the phaseFilesCounts map below; the ledger only
+            // ever substitutes a 'missing' status with a remembered one, and under
+            // disk-strict neither 'missing' nor 'unrecorded' is ever complete, so
+            // there is nothing for the ledger to override here).
+            complete: completionResult.value.complete,
         };
     });
     // #2645: only the directory Bug #2445's de-dup rollup would actually pick
@@ -573,6 +625,7 @@ function inspectWorkstream(cwd, name, options = {}) {
             summaryCount: entry.summaryCount,
             inMilestone: entry.inMilestone,
             verificationStatus,
+            complete: entry.complete,
         };
     });
     // The denominator is the union of what the roadmap DECLARES for the current
@@ -592,7 +645,7 @@ function inspectWorkstream(cwd, name, options = {}) {
     // declares in its Progress table but never scaffolded — the heading-only
     // count drops them, even when other headings exist. Union the declared rows
     // with the phase directories so neither source can silently shrink it.
-    let fallbackPhaseCount = countRoadmapPhases(p.roadmap, phaseDirNames.length);
+    let fallbackPhaseCount = countRoadmapPhases(p.roadmap, phaseDirNames.length, cwd, name, currentVersion);
     if (!scoped && progressRows.length > 0) {
         const union = new Set(progressRows.map(row => row.key));
         for (const entry of phaseFilesCounts)

package/gsd-core/bin/lib/workstream-name-policy.cjs

@@ -6,6 +6,24 @@
  * byte-for-behaviour from the prior hand-written .cjs; only types are added.
  *
  * Used by active-workstream-store.cjs, planning-workspace.cjs, workstream.cjs.
+ *
+ * #3883 (ADR-3473 §8.3): toWorkstreamSlug delegates to core-utils.cjs's
+ * generateSlugInternal (the canonical slug formula), passing `maxLen: null`
+ * to preserve this site's pre-migration untruncated contract — the 60-char
+ * default collided distinct >60-char workstream names onto the same slug
+ * (verified: `"a".repeat(60)+"alpha"` and `"a".repeat(60)+"beta"` truncated
+ * identically). core-utils.cjs already
+ * requires (transitively, at module-init time) THIS module:
+ * core-utils.cjs -> planning-workspace.cjs -> active-workstream-store.cjs ->
+ * workstream-name-policy.cjs. A top-level require of core-utils.cjs here
+ * would therefore close that cycle and — per this codebase's compiled-.cjs
+ * convention of a single `module.exports = {...}` reassignment at the bottom
+ * of core-utils.cjs — capture a stale, still-empty exports object forever
+ * (verified live: "generateSlugInternal is not a function" whichever module
+ * loads first). The require is deferred (lazy, inside toWorkstreamSlug's
+ * body) instead, mirroring the same cycle-break already used by
+ * core-utils.cts's own getPhaseFileStats/plan-scan.cjs seam and by
+ * phase-id.cts's toDir/getPhaseDirFromPhaseId.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INVALID_ACTIVE_WORKSTREAM_NAME_MESSAGE = void 0;
@@ -68,10 +86,13 @@ function validateWorkstreamName(name) {
  * Lowercases, collapses non-alphanumeric runs to hyphens, strips leading/trailing hyphens.
  */
 function toWorkstreamSlug(name) {
-    return String(name ?? '')
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
+    // #3883 (ADR-3473 §8.3): delegate to the canonical slug formula
+    // (generateSlugInternal, core-utils.cts) rather than re-implementing it —
+    // this call site previously diverged from it (no transliteration, no
+    // 60-char truncation). Lazy require to break the core-utils.cjs cycle
+    // (see the module dependency doc comment above).
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+    return require('./core-utils.cjs').generateSlugInternal(String(name ?? ''), null) ?? '';
 }
 /**
  * Returns true when `name` is a valid active workstream name:

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

@@ -134,8 +134,8 @@ function cmdWorkstreamCreate(cwd, name, options, raw) {
             }
             else {
                 try {
-                    const milestone = getMilestoneInfo(cwd);
-                    existingWsName = generateSlugInternal(milestone.name) || 'default';
+                    const milestone = getMilestoneInfo(cwd).value;
+                    existingWsName = generateSlugInternal(milestone?.name ?? null) || 'default';
                 }
                 catch {
                     existingWsName = 'default';

package/gsd-core/bin/lib/worktree-base-ref.cjs

@@ -94,10 +94,13 @@ function parseJsonc(text) {
 }
 // ─── Message constants (verbatim — downstream docs/tests depend on these) ─────
 function buildMsgDiverged(headSha, forkRef, forkSha) {
-    return `⚠ Worktree base mismatch: HEAD (${shortSha(headSha)}) differs from ${forkRef} (${shortSha(forkSha)}). Running this phase sequentially on the main working tree. To keep parallel worktrees, set worktree.baseRef:"head" in .claude/settings.local.json (or run: gsd-tools worktree set-baseref). See #683.`;
+    return `⚠ Worktree base mismatch: HEAD (${shortSha(headSha)}) differs from ${forkRef} (${shortSha(forkSha)}). Running this phase sequentially on the main working tree. Parallel worktrees return once HEAD is merged/pushed so ${forkRef} matches it. (worktree.baseRef:"head" applies only where GSD itself creates the worktree — the runtime harness does not read it; #48, #3659.)`;
 }
-const MSG_UNKNOWN = `⚠ Cannot determine the worktree fork base (origin/HEAD unresolved). Running this phase sequentially on the main working tree to avoid a base mismatch. To keep parallel worktrees, set worktree.baseRef:"head" in .claude/settings.local.json (or run: gsd-tools worktree set-baseref). See #683.`;
-const MSG_HEAD_UNRESOLVABLE = `⚠ Cannot determine the worktree base (git rev-parse HEAD did not return a definitive answer). Running this phase sequentially on the main working tree to avoid an unverified base mismatch. Note: worktree.baseRef:"head" would silence this check without verifying the base — it skips the comparison rather than resolving it. Retry; if it persists, check for a stalled filesystem mount or a stale git index lock (.git/index.lock). See #683, #3050.`;
+const MSG_UNKNOWN = `⚠ Cannot determine the worktree fork base (origin/HEAD unresolved). Running this phase sequentially on the main working tree to avoid a base mismatch. Parallel worktrees return once origin/HEAD resolves and matches HEAD. See #683, #3659.`;
+function buildMsgBaserefHeadIgnored(headSha, forkRef, forkSha) {
+    return `⚠ Worktree base mismatch: worktree.baseRef:"head" is set, but the runtime harness does not honor it for isolated dispatch — the fork base stays ${forkRef} (${shortSha(forkSha)}) while HEAD is ${shortSha(headSha)} (#48; upstream claude-code#44965). Running this phase sequentially on the main working tree. Parallel worktrees return once HEAD is merged/pushed so ${forkRef} matches it, or on runtimes where GSD itself manages worktree creation. See #3659.`;
+}
+const MSG_HEAD_UNRESOLVABLE = `⚠ Cannot determine the worktree base (git rev-parse HEAD did not return a definitive answer). Running this phase sequentially on the main working tree to avoid an unverified base mismatch. Note: worktree.baseRef:"head" silences this check only where GSD itself creates the worktree (orchestrator-managed runtimes) — in harness mode it never applied (#48, #3659). Retry; if it persists, check for a stalled filesystem mount or a stale git index lock (.git/index.lock). See #683, #3050.`;
 /**
  * Returns true when an execGit result indicates the subprocess was killed by
  * a timeout. A timeout means the command genuinely could not complete — it
@@ -228,7 +231,20 @@ function resolveEffectiveBaseRef(claudeDir, deps, userClaudeDir) {
  * deps.userClaudeDir overrides the user/global config directory resolution
  * (default: getGlobalConfigDir('claude'), which honours CLAUDE_CONFIG_DIR).
  */
-function cmdWorktreeBaseCheck(cwd, _args, deps) {
+function cmdWorktreeBaseCheck(cwd, args, deps) {
+    // --mode threads the dispatch isolation mode through to the evaluation
+    // (#3659): 'harness-worktree' (default) or 'orchestrator-worktree'. Invalid
+    // or missing values after --mode fail closed — a silently defaulted typo
+    // would re-open the hole the flag exists to close.
+    let isolationMode = 'harness-worktree';
+    const modeIdx = args.indexOf('--mode');
+    if (modeIdx !== -1) {
+        const value = args[modeIdx + 1];
+        if (value !== 'harness-worktree' && value !== 'orchestrator-worktree') {
+            throw new Error(`worktree base-check: --mode must be harness-worktree or orchestrator-worktree, got ${JSON.stringify(value ?? null)}`);
+        }
+        isolationMode = value;
+    }
     const claudeDir = node_path_1.default.join(cwd, '.claude');
     const userClaudeDir = Object.prototype.hasOwnProperty.call(deps ?? {}, 'userClaudeDir')
         ? deps.userClaudeDir
@@ -238,8 +254,22 @@ function cmdWorktreeBaseCheck(cwd, _args, deps) {
         cwd,
         effectiveBaseRef,
         execGit: deps?.execGit,
+        isolationMode,
+    });
+    // Default emit goes through fs.writeSync(1, …), NOT process.stdout.write:
+    // the CLI's --pick capture intercepts writeSync, and command substitution
+    // is a pipe — via process.stdout.write a `$(gsd-tools … --pick x)` capture
+    // received the full JSON instead of the picked field, so the workflow
+    // auto-degrade guards never matched (#3659 review). Short-count loop per
+    // io.cjs writeAllSync's rationale (a non-blocking pipe can accept partial
+    // writes).
+    const write = deps?.write ?? ((s) => {
+        const buf = Buffer.from(s, 'utf8');
+        let offset = 0;
+        while (offset < buf.length) {
+            offset += node_fs_1.default.writeSync(1, buf, offset, buf.length - offset);
+        }
     });
-    const write = deps?.write ?? ((s) => process.stdout.write(s));
     write(JSON.stringify(result, null, 2) + '\n');
     return result;
 }
@@ -295,7 +325,20 @@ function cmdWorktreeSetBaseRef(cwd, _args, deps) {
         baseRef: 'head',
         file,
     };
-    const write = deps?.write ?? ((s) => process.stdout.write(s));
+    // Default emit goes through fs.writeSync(1, …), NOT process.stdout.write:
+    // the CLI's --pick capture intercepts writeSync, and command substitution
+    // is a pipe — via process.stdout.write a `$(gsd-tools … --pick x)` capture
+    // received the full JSON instead of the picked field, so the workflow
+    // auto-degrade guards never matched (#3659 review). Short-count loop per
+    // io.cjs writeAllSync's rationale (a non-blocking pipe can accept partial
+    // writes).
+    const write = deps?.write ?? ((s) => {
+        const buf = Buffer.from(s, 'utf8');
+        let offset = 0;
+        while (offset < buf.length) {
+            offset += node_fs_1.default.writeSync(1, buf, offset, buf.length - offset);
+        }
+    });
     write(JSON.stringify(output, null, 2) + '\n');
     return output;
 }
@@ -311,12 +354,19 @@ function evaluateWorktreeBaseDegrade(deps) {
     const execGit = deps?.execGit ?? shell_command_projection_cjs_1.execGit;
     const cwd = deps?.cwd;
     const cwdOpts = cwd ? { cwd } : {};
-    // a. If baseRef is explicitly 'head' the harness forks from HEAD — no mismatch possible.
-    // Claude Code's worktree.baseRef accepts only "fresh" (= origin/HEAD, the default) or "head".
-    // Therefore special-casing "head" here and otherwise comparing HEAD against origin/HEAD is
-    // complete: any non-"head" value (including "fresh" and absent/null) has fresh/origin-HEAD
-    // semantics and must be evaluated against origin/HEAD. (Reference: Claude Code worktrees docs, #683.)
-    if (deps?.effectiveBaseRef === 'head') {
+    // a. baseRef 'head' suppresses ONLY where GSD controls the fork start-point
+    // (#3659). The former unconditional suppress trusted the harness to honor the
+    // setting; #48 verified 5/5 that the Agent-isolation dispatch path never
+    // routes through project settings (upstream claude-code#44965), so in
+    // harness mode the fork base is always origin/HEAD and 'head' must fall
+    // through to the same comparison the fresh path runs. In
+    // orchestrator-worktree mode GSD itself runs `git worktree add <path>
+    // <start-point>` with the orchestrator HEAD — 'head' is honored by
+    // construction there and the suppress is correct. Any non-"head" value
+    // (including "fresh" and absent/null) has fresh/origin-HEAD semantics and is
+    // evaluated against origin/HEAD as before. (Reference: #683, #48, #3659.)
+    const headIgnoredByHarness = deps?.effectiveBaseRef === 'head';
+    if (headIgnoredByHarness && (deps?.isolationMode ?? 'harness-worktree') === 'orchestrator-worktree') {
         return { shouldDegrade: false, reason: 'baseref-head', message: null, headSha: null, forkRef: null, forkSha: null, headAbsenceVerified: null };
     }
     // b. Resolve HEAD sha.
@@ -389,6 +439,10 @@ function evaluateWorktreeBaseDegrade(deps) {
     if (forkSha === headSha) {
         return { shouldDegrade: false, reason: 'head-matches-fork', message: null, headSha, forkRef, forkSha, headAbsenceVerified: null };
     }
+    if (headIgnoredByHarness) {
+        const message = buildMsgBaserefHeadIgnored(headSha, forkRef, forkSha);
+        return { shouldDegrade: true, reason: 'baseref-head-ignored-by-harness', message, headSha, forkRef, forkSha, headAbsenceVerified: null };
+    }
     const message = buildMsgDiverged(headSha, forkRef, forkSha);
     return { shouldDegrade: true, reason: 'head-diverged-from-fork', message, headSha, forkRef, forkSha, headAbsenceVerified: null };
 }