gsd-pi 2.80.0 → 2.81.0-dev.72a81bdf3

package/dist/resources/extensions/gsd/state-reconciliation/drift/stale-render.js

@@ -0,0 +1,124 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 stale-render drift handler. Relocated from
+// markdown-renderer.ts as part of issue #5702. detectStaleRenders stays in
+// markdown-renderer.ts (it's a useful diagnostic primitive on its own); only
+// the detect+repair composition moves here. The previous repairStaleRenders
+// had zero callers in production code — wiring it through
+// reconcileBeforeDispatch closes that gap.
+import { detectStaleRenders, renderPlanCheckboxes, renderRoadmapCheckboxes, renderSliceSummary, renderTaskSummary, } from "../../markdown-renderer.js";
+import { logWarning } from "../../workflow-logger.js";
+// ─── Core (basePath-only — usable by both drift API and legacy wrapper) ──────
+function detectStaleRenderDriftFromBasePath(basePath) {
+    const entries = detectStaleRenders(basePath);
+    if (entries.length === 0)
+        return [];
+    // detectStaleRenders may emit multiple entries for the same path (one per
+    // mismatched checkbox). Dedupe by path; the repair re-renders the whole
+    // file in a single call. Prefer a reason the repair dispatcher can handle.
+    const seen = new Map();
+    for (const entry of entries) {
+        const currentReason = seen.get(entry.path);
+        if (currentReason === undefined ||
+            (!isRepairableStaleRenderReason(currentReason) && isRepairableStaleRenderReason(entry.reason))) {
+            seen.set(entry.path, entry.reason);
+        }
+    }
+    return Array.from(seen.entries()).map(([renderPath, reason]) => ({
+        kind: "stale-render",
+        renderPath,
+        reason,
+    }));
+}
+function isRepairableStaleRenderReason(reason) {
+    return (reason.includes("in roadmap") ||
+        reason.includes("in plan") ||
+        (reason.includes("SUMMARY.md missing") && /^T\d+/.test(reason)) ||
+        (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) ||
+        reason.includes("UAT.md missing"));
+}
+async function repairStaleRenderFromBasePath(record, basePath) {
+    const normPath = record.renderPath.replace(/\\/g, "/");
+    const reason = record.reason;
+    if (reason.includes("in roadmap")) {
+        const milestoneMatch = normPath.match(/milestones\/([^/]+)\//);
+        if (!milestoneMatch) {
+            throw new Error(`stale-render drift: roadmap path missing milestone segment: ${record.renderPath}`);
+        }
+        await renderRoadmapCheckboxes(basePath, milestoneMatch[1]);
+        return;
+    }
+    if (reason.includes("in plan")) {
+        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        if (!pathMatch) {
+            throw new Error(`stale-render drift: plan path missing milestone/slice segments: ${record.renderPath}`);
+        }
+        await renderPlanCheckboxes(basePath, pathMatch[1], pathMatch[2]);
+        return;
+    }
+    if (reason.includes("SUMMARY.md missing") && /^T\d+/.test(reason)) {
+        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//);
+        const taskMatch = reason.match(/^(T\d+)/);
+        if (!pathMatch || !taskMatch) {
+            throw new Error(`stale-render drift: task summary path/reason malformed: ${record.renderPath} reason=${reason}`);
+        }
+        await renderTaskSummary(basePath, pathMatch[1], pathMatch[2], taskMatch[1]);
+        return;
+    }
+    if (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) {
+        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        if (!pathMatch) {
+            throw new Error(`stale-render drift: slice summary path missing milestone/slice segments: ${record.renderPath}`);
+        }
+        await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
+        return;
+    }
+    if (reason.includes("UAT.md missing")) {
+        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        if (!pathMatch) {
+            throw new Error(`stale-render drift: UAT path missing milestone/slice segments: ${record.renderPath}`);
+        }
+        // renderSliceSummary handles both SUMMARY and UAT.
+        await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
+        return;
+    }
+    throw new Error(`stale-render drift: detector emitted unknown reason "${reason}" for ${record.renderPath}`);
+}
+// ─── Drift Handler API ───────────────────────────────────────────────────────
+export function detectStaleRenderDrift(_state, ctx) {
+    return detectStaleRenderDriftFromBasePath(ctx.basePath);
+}
+export async function repairStaleRender(record, ctx) {
+    await repairStaleRenderFromBasePath(record, ctx.basePath);
+}
+export const staleRenderHandler = {
+    kind: "stale-render",
+    detect: detectStaleRenderDrift,
+    repair: repairStaleRender,
+};
+// ─── Legacy entry point ──────────────────────────────────────────────────────
+/**
+ * Legacy bulk entry preserved for existing tests
+ * (tests/markdown-renderer.test.ts, tests/integration/integration-proof.test.ts).
+ * New code prefers the drift handler via `reconcileBeforeDispatch`. Matches the
+ * pre-ADR-017 behavior: silent per-entry error handling, returns the count of
+ * successful repairs.
+ */
+export async function repairStaleRenders(basePath) {
+    const drifts = detectStaleRenderDriftFromBasePath(basePath);
+    if (drifts.length === 0)
+        return 0;
+    let repaired = 0;
+    for (const drift of drifts) {
+        try {
+            await repairStaleRenderFromBasePath(drift, basePath);
+            repaired++;
+        }
+        catch (err) {
+            logWarning("renderer", `repair failed for ${drift.renderPath}: ${err.message}`);
+        }
+    }
+    if (repaired > 0) {
+        process.stderr.write(`markdown-renderer: repaired ${repaired} stale render(s)\n`);
+    }
+    return repaired;
+}

package/dist/resources/extensions/gsd/state-reconciliation/drift/stale-worker.js

@@ -0,0 +1,32 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 stale-worker drift handler. Detects session-lock
+// artifacts whose owning PID is no longer alive (typical after SIGKILL or
+// laptop sleep where the heartbeat wasn't released cleanly), and clears them
+// before the next dispatch attempts to acquire the lock.
+import { effectiveLockFile, isSessionLockProcessAlive, readSessionLockData, removeStaleSessionLock, } from "../../session-lock.js";
+export function detectStaleWorkerDrift(_state, ctx) {
+    const data = readSessionLockData(ctx.basePath);
+    if (!data)
+        return [];
+    if (typeof data.pid !== "number")
+        return [];
+    if (isSessionLockProcessAlive(data))
+        return [];
+    return [
+        {
+            kind: "stale-worker",
+            lockPath: effectiveLockFile(),
+            pid: data.pid,
+        },
+    ];
+}
+export function repairStaleWorker(_record, ctx) {
+    // removeStaleSessionLock is idempotent: it re-reads lock state and is a
+    // no-op when the lock is held by an alive process. Safe under cap=2 retry.
+    removeStaleSessionLock(ctx.basePath);
+}
+export const staleWorkerHandler = {
+    kind: "stale-worker",
+    detect: detectStaleWorkerDrift,
+    repair: repairStaleWorker,
+};

package/dist/resources/extensions/gsd/state-reconciliation/errors.js

@@ -0,0 +1,41 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 typed reconciliation failure for Recovery Classification.
+/**
+ * Thrown by reconcileBeforeDispatch when:
+ *   - one or more repair functions throw within a pass (`failures` populated), or
+ *   - drift persists after the cap=2 lifecycle (`persistentDrift` populated).
+ *
+ * Recovery Classification recognizes this error via instanceof and maps it to
+ * failureKind "reconciliation-drift" with action "escalate".
+ */
+export class ReconciliationFailedError extends Error {
+    failures;
+    detectionFailures;
+    persistentDrift;
+    pass;
+    constructor(opts) {
+        super(formatMessage(opts));
+        this.name = "ReconciliationFailedError";
+        this.failures = opts.failures ?? [];
+        this.detectionFailures = opts.detectionFailures ?? [];
+        this.persistentDrift = opts.persistentDrift ?? [];
+        this.pass = opts.pass;
+    }
+}
+function formatMessage(opts) {
+    if (opts.detectionFailures && opts.detectionFailures.length > 0) {
+        const kinds = opts.detectionFailures.map((f) => f.handlerKind).join(", ");
+        const passSuffix = opts.pass !== undefined ? ` in pass ${opts.pass}` : "";
+        return `Reconciliation detect failed${passSuffix} for handlers: ${kinds}`;
+    }
+    if (opts.failures && opts.failures.length > 0) {
+        const kinds = opts.failures.map((f) => f.drift.kind).join(", ");
+        const passSuffix = opts.pass !== undefined ? ` in pass ${opts.pass}` : "";
+        return `Reconciliation repair failed${passSuffix} for drift kinds: ${kinds}`;
+    }
+    if (opts.persistentDrift && opts.persistentDrift.length > 0) {
+        const kinds = opts.persistentDrift.map((d) => d.kind).join(", ");
+        return `Reconciliation drift persisted after cap=2 passes: ${kinds}`;
+    }
+    return "Reconciliation failed";
+}

package/dist/resources/extensions/gsd/state-reconciliation/index.js

@@ -0,0 +1,99 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 drift-driven State Reconciliation Module entry point.
+// reconcileBeforeDispatch runs before every Dispatch decision and worker spawn.
+import { deriveState as defaultDeriveState, invalidateStateCache as defaultInvalidate, } from "../state.js";
+import { ReconciliationFailedError, } from "./errors.js";
+import { DRIFT_REGISTRY } from "./registry.js";
+export { ReconciliationFailedError } from "./errors.js";
+export { DRIFT_REGISTRY } from "./registry.js";
+const MAX_PASSES = 2;
+const defaultDeps = {
+    invalidateStateCache: defaultInvalidate,
+    deriveState: defaultDeriveState,
+};
+/**
+ * Drift-driven pre-dispatch reconciliation per ADR-017.
+ *
+ * Lifecycle: derive → detect drift → apply repairs → re-derive. Capped at
+ * MAX_PASSES (=2) cycles. The loop runs only when the prior pass fully
+ * succeeded but re-derive surfaces NEW drift (cascading repairs — e.g.
+ * fixing milestone registration uncovers a downstream completion-timestamp
+ * drift).
+ *
+ * Returns ok=true with `repaired` and terminal `blockers` populated.
+ * Throws ReconciliationFailedError when:
+ *   - any repair function throws within a pass, or
+ *   - drift persists after the cap.
+ */
+export async function reconcileBeforeDispatch(basePath, deps = defaultDeps) {
+    const registry = deps.registry ?? DRIFT_REGISTRY;
+    const repaired = [];
+    for (let pass = 0; pass < MAX_PASSES; pass++) {
+        deps.invalidateStateCache();
+        const stateSnapshot = await deps.deriveState(basePath, deps.deriveStateOptions);
+        const ctx = { basePath, state: stateSnapshot };
+        const drift = await detectAllDrift(stateSnapshot, ctx, registry, pass);
+        if (drift.length === 0) {
+            return {
+                ok: true,
+                stateSnapshot,
+                repaired,
+                blockers: stateSnapshot.blockers ?? [],
+            };
+        }
+        const failures = [];
+        for (const record of drift) {
+            const handler = registry.find((h) => h.kind === record.kind);
+            if (!handler) {
+                failures.push({
+                    drift: record,
+                    cause: new Error(`No drift handler registered for kind "${record.kind}"`),
+                });
+                continue;
+            }
+            try {
+                await handler.repair(record, ctx);
+                repaired.push(record);
+            }
+            catch (cause) {
+                failures.push({ drift: record, cause });
+            }
+        }
+        if (failures.length > 0) {
+            throw new ReconciliationFailedError({ failures, pass });
+        }
+        // Pass fully succeeded; loop runs again to detect cascading drift.
+    }
+    // After MAX_PASSES, one more derive+detect to verify nothing persists.
+    deps.invalidateStateCache();
+    const finalState = await deps.deriveState(basePath, deps.deriveStateOptions);
+    const finalCtx = { basePath, state: finalState };
+    const persistent = await detectAllDrift(finalState, finalCtx, registry);
+    if (persistent.length > 0) {
+        throw new ReconciliationFailedError({ persistentDrift: persistent });
+    }
+    return {
+        ok: true,
+        stateSnapshot: finalState,
+        repaired,
+        blockers: finalState.blockers ?? [],
+    };
+}
+async function detectAllDrift(state, ctx, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+registry, pass) {
+    const collected = [];
+    for (const handler of registry) {
+        try {
+            const detected = await handler.detect(state, ctx);
+            collected.push(...detected);
+        }
+        catch (cause) {
+            throw new ReconciliationFailedError({
+                failures: [{ drift: { kind: handler.kind }, cause }],
+                pass,
+            });
+        }
+    }
+    return collected;
+}

package/dist/resources/extensions/gsd/state-reconciliation/registry.js

@@ -0,0 +1,24 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 drift handler registry. Single source of truth for
+// the catalog. Tests can override per-call via ReconciliationDeps.registry.
+import { completionTimestampHandler } from "./drift/completion.js";
+import { mergeStateHandler } from "./drift/merge-state.js";
+import { unregisteredMilestoneHandler } from "./drift/project-md.js";
+import { roadmapDivergenceHandler } from "./drift/roadmap.js";
+import { sketchFlagHandler } from "./drift/sketch-flag.js";
+import { staleRenderHandler } from "./drift/stale-render.js";
+import { staleWorkerHandler } from "./drift/stale-worker.js";
+// Each handler is parameterized over its specific DriftRecord variant for
+// internal type safety. The registry stores them under DriftHandler<any> so
+// handlers with disjoint repair parameter types coexist; the lifecycle matches
+// by kind before invoking repair, so this is sound at runtime.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const DRIFT_REGISTRY = [
+    sketchFlagHandler,
+    mergeStateHandler,
+    staleRenderHandler,
+    staleWorkerHandler,
+    unregisteredMilestoneHandler,
+    roadmapDivergenceHandler,
+    completionTimestampHandler,
+];

package/dist/resources/extensions/gsd/state-reconciliation/spawn-gate.js

@@ -0,0 +1,43 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 #5707 caller-closure helper. Parent processes that
+// spawn auto-loop workers must reconcile before spawn — otherwise each
+// worker independently detects+repairs the same drift, racing on shared
+// state. This helper centralises the reconcile+catch flow so the two
+// production spawn sites (commands/handlers/parallel.ts and auto/phases.ts
+// startSliceParallel) share one contract.
+import { reconcileBeforeDispatch, ReconciliationFailedError, } from "./index.js";
+/**
+ * Run reconciliation before spawning workers. Returns ok=true when the run
+ * completed without throwing (blockers ride along but don't fail the gate —
+ * spawn callers can choose how to handle them). On
+ * ReconciliationFailedError, returns ok=false with the error message so the
+ * caller can surface it to the user without re-throwing.
+ *
+ * Other unexpected errors propagate; they are not part of the drift
+ * taxonomy.
+ */
+export async function reconcileBeforeSpawn(basePath, deps = {}) {
+    const reconcileFn = deps.reconcile ?? reconcileBeforeDispatch;
+    try {
+        const result = await reconcileFn(basePath, deps);
+        if (result.blockers.length > 0) {
+            return {
+                ok: false,
+                reason: `Reconciliation blocker: ${result.blockers[0]}`,
+            };
+        }
+        const repairedKinds = result.repaired.map((d) => d.kind);
+        return {
+            ok: true,
+            reason: repairedKinds.length > 0
+                ? `repaired before spawn: ${repairedKinds.join(", ")}`
+                : undefined,
+        };
+    }
+    catch (err) {
+        if (err instanceof ReconciliationFailedError) {
+            return { ok: false, reason: err.message };
+        }
+        throw err;
+    }
+}

package/dist/resources/extensions/gsd/state-reconciliation/types.js

@@ -0,0 +1,3 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 types for drift-driven state reconciliation.
+export {};

package/dist/resources/extensions/gsd/state-reconciliation.js

@@ -0,0 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 State Reconciliation Module — public entry point.
+// Re-exports the drift-driven implementation from the state-reconciliation/
+// folder so existing import paths (./state-reconciliation.js) keep working.
+export { reconcileBeforeDispatch, ReconciliationFailedError, DRIFT_REGISTRY, } from "./state-reconciliation/index.js";
+export { reconcileBeforeSpawn } from "./state-reconciliation/spawn-gate.js";

package/dist/resources/extensions/gsd/state.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Runtime state derivation from GSD workflow database and legacy files.
 // GSD Extension — State Derivation
 // DB-authoritative runtime derivation with explicit legacy filesystem fallback.
 // Pure TypeScript, zero Pi dependencies.
@@ -15,6 +17,7 @@ import { logWarning } from './workflow-logger.js';
 import { extractVerdict } from './verdict-parser.js';
 import { detectPendingEscalation } from './escalation.js';
 import { isTerminalMilestoneSummaryContent } from './milestone-summary-classifier.js';
+import { incrementLegacyTelemetry } from './legacy-telemetry.js';
 import { isDbAvailable, wasDbOpenAttempted, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, getRequirementCounts, getLatestAssessmentByScope, getPendingGateCountForTurn, } from './gsd-db.js';
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive
@@ -239,6 +242,7 @@ export async function deriveState(basePath, opts) {
         }
         result = await _deriveStateImpl(basePath, opts);
         _telemetry.markdownDeriveCount++;
+        incrementLegacyTelemetry("legacy.markdownFallbackUsed");
     }
     else {
         if (wasDbOpenAttempted()) {

package/dist/resources/extensions/gsd/tool-contract.js

@@ -0,0 +1,50 @@
+// Project/App: GSD-2
+// File Purpose: ADR-015 Tool Contract module for Unit prompt, policy, and tool parity.
+import { resolveManifest, } from "./unit-context-manifest.js";
+import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
+export function compileUnitToolContract(unitType) {
+    const manifest = resolveManifest(unitType);
+    if (!manifest) {
+        return {
+            ok: false,
+            reason: "unknown-unit-type",
+            detail: `No Unit manifest is registered for ${unitType}`,
+        };
+    }
+    const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(unitType);
+    const closeoutTools = requiredWorkflowTools.filter((tool) => /^gsd_(?:task|slice|milestone|complete|validate|save|summary)/.test(tool));
+    if (requiresCloseoutTool(unitType) && closeoutTools.length === 0) {
+        return {
+            ok: false,
+            reason: "missing-closeout-tool",
+            detail: `${unitType} has no closeout workflow tool`,
+        };
+    }
+    return {
+        ok: true,
+        contract: {
+            unitType,
+            contextMode: manifest.contextMode,
+            toolsPolicy: manifest.tools,
+            requiredWorkflowTools,
+            promptObligations: [
+                `context-mode:${manifest.contextMode}`,
+                `tools-policy:${manifest.tools.mode}`,
+            ],
+            validationRules: [
+                "unit-manifest-present",
+                "workflow-tool-surface-present",
+                ...(requiresCloseoutTool(unitType) ? ["closeout-tool-present"] : []),
+            ],
+            closeoutTools,
+            artifacts: {
+                inline: manifest.artifacts.inline,
+                excerpt: manifest.artifacts.excerpt,
+                onDemand: manifest.artifacts.onDemand,
+            },
+        },
+    };
+}
+function requiresCloseoutTool(unitType) {
+    return /^(execute-task|reactive-execute|complete-slice|validate-milestone|complete-milestone|run-uat|gate-evaluate)$/.test(unitType);
+}

package/dist/resources/extensions/gsd/tools/complete-milestone.js

@@ -1,3 +1,4 @@
+// GSD2 complete-milestone tool handler
 /**
  * complete-milestone handler — the core operation behind gsd_complete_milestone.
  *
@@ -16,8 +17,7 @@ import { renderAllProjections, stripIdPrefix } from "../workflow-projections.js"
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
-function renderMilestoneSummaryMarkdown(params) {
-    const now = new Date().toISOString();
+function renderMilestoneSummaryMarkdown(params, completedAt) {
     const displayTitle = stripIdPrefix(params.title, params.milestoneId);
     // Apply defaults for optional enrichment fields (#2771)
     const keyDecisions = params.keyDecisions ?? [];
@@ -36,7 +36,7 @@ function renderMilestoneSummaryMarkdown(params) {
 id: ${params.milestoneId}
 title: "${displayTitle}"
 status: complete
-completed_at: ${now}
+completed_at: ${completedAt}
 key_decisions:
 ${keyDecisionsYaml}
 key_files:
@@ -55,15 +55,15 @@ ${params.narrative}
 
 ## Success Criteria Results
 
-${params.successCriteriaResults ?? "Not provided."}
+${params.successCriteriaResults || "Not provided."}
 
 ## Definition of Done Results
 
-${params.definitionOfDoneResults ?? "Not provided."}
+${params.definitionOfDoneResults || "Not provided."}
 
 ## Requirement Outcomes
 
-${params.requirementOutcomes ?? "Not provided."}
+${params.requirementOutcomes || "Not provided."}
 
 ## Deviations
 
@@ -89,6 +89,7 @@ export async function handleCompleteMilestone(params, basePath) {
     // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
     const completedAt = new Date().toISOString();
     let guardError = null;
+    let alreadyComplete = false;
     transaction(() => {
         // State machine preconditions (inside txn for atomicity)
         const milestone = getMilestone(params.milestoneId);
@@ -97,7 +98,7 @@ export async function handleCompleteMilestone(params, basePath) {
             return;
         }
         if (isClosedStatus(milestone.status)) {
-            guardError = `milestone ${params.milestoneId} is already complete`;
+            alreadyComplete = true;
             return;
         }
         // Verify all slices are complete
@@ -129,7 +130,7 @@ export async function handleCompleteMilestone(params, basePath) {
         return { error: guardError };
     }
     // ── Filesystem operations (outside transaction) ─────────────────────────
-    const summaryMd = renderMilestoneSummaryMarkdown(params);
+    const summaryMd = renderMilestoneSummaryMarkdown(params, completedAt);
     let summaryPath;
     const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
     if (milestoneDir) {
@@ -177,14 +178,16 @@ export async function handleCompleteMilestone(params, basePath) {
         logWarning("tool", `complete-milestone manifest warning: ${mfErr.message}`);
     }
     try {
-        appendEvent(basePath, {
-            cmd: "complete-milestone",
-            params: { milestoneId: params.milestoneId },
-            ts: new Date().toISOString(),
-            actor: "agent",
-            actor_name: params.actorName,
-            trigger_reason: params.triggerReason,
-        });
+        if (!alreadyComplete) {
+            appendEvent(basePath, {
+                cmd: "complete-milestone",
+                params: { milestoneId: params.milestoneId },
+                ts: new Date().toISOString(),
+                actor: "agent",
+                actor_name: params.actorName,
+                trigger_reason: params.triggerReason,
+            });
+        }
     }
     catch (eventErr) {
         logError("tool", `complete-milestone event log FAILED — completion invisible to reconciliation`, { error: eventErr.message });
@@ -193,5 +196,6 @@ export async function handleCompleteMilestone(params, basePath) {
         milestoneId: params.milestoneId,
         summaryPath,
         ...(projectionStale ? { stale: true } : {}),
+        ...(alreadyComplete ? { alreadyComplete: true } : {}),
     };
 }

package/dist/resources/extensions/gsd/tools/complete-task.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Complete-task tool handler for GSD workflow state and summaries.
 /**
  * complete-task handler — the core operation behind gsd_complete_task.
  *
@@ -44,7 +46,7 @@ function taskGateFieldForId(id, params) {
  * Normalize a list parameter that may arrive as a string (newline-delimited
  * bullet list from the LLM) into a string array (#3361).
  */
-function normalizeListParam(value) {
+export function normalizeListParam(value) {
     if (Array.isArray(value))
         return value.map(String);
     if (typeof value === "string" && value.trim()) {

package/dist/resources/extensions/gsd/tools/context-mode-tool-result.js

@@ -0,0 +1,15 @@
+// Project/App: GSD-2
+// File Purpose: Shared Context Mode tool result helpers.
+export function contextModeDisabledResult(operation) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `${operation} is disabled by \`context_mode.enabled: false\` in preferences. ` +
+                    "Remove that override or set it to true to re-enable Context Mode tools.",
+            },
+        ],
+        details: { operation, error: "context_mode_disabled" },
+        isError: true,
+    };
+}

package/dist/resources/extensions/gsd/tools/exec-search-tool.js

@@ -3,7 +3,12 @@
 // Scans .gsd/exec/*.meta.json and returns a ranked summary so agents can
 // re-discover past runs without re-executing. Read-only; no DB writes.
 import { searchExecHistory } from "../exec-history.js";
+import { isContextModeEnabled } from "../preferences-types.js";
+import { contextModeDisabledResult } from "./context-mode-tool-result.js";
 export function executeExecSearch(params, opts) {
+    if (!isContextModeEnabled(opts.preferences)) {
+        return contextModeDisabledResult("gsd_exec_search");
+    }
     const searchOpts = {
         query: typeof params.query === "string" ? params.query : undefined,
         runtime: params.runtime,

package/dist/resources/extensions/gsd/tools/exec-tool.js

@@ -5,6 +5,7 @@
 // for MCP return.
 import { EXEC_DEFAULTS, runExecSandbox, } from "../exec-sandbox.js";
 import { isContextModeEnabled } from "../preferences-types.js";
+import { contextModeDisabledResult } from "./context-mode-tool-result.js";
 export function buildExecOptions(baseDir, cfg, extras) {
     const allowlist = Array.isArray(cfg?.exec_env_allowlist) ? cfg.exec_env_allowlist : EXEC_DEFAULTS.envAllowlist;
     const stdoutCap = clampNumber(cfg?.exec_stdout_cap_bytes, EXEC_DEFAULTS.stdoutCapBytes, 4_096, 16_777_216);
@@ -33,19 +34,6 @@ function clampNumber(value, fallback, min, max) {
 function isEnabled(prefs) {
     return isContextModeEnabled(prefs);
 }
-function disabledResult() {
-    return {
-        content: [
-            {
-                type: "text",
-                text: "gsd_exec is disabled by `context_mode.enabled: false` in preferences. Remove that " +
-                    "override (or set it to true) to re-enable sandboxed tool-output execution.",
-            },
-        ],
-        details: { operation: "gsd_exec", error: "context_mode_disabled" },
-        isError: true,
-    };
-}
 function paramError(message) {
     return {
         content: [{ type: "text", text: `Error: ${message}` }],
@@ -55,7 +43,7 @@ function paramError(message) {
 }
 export async function executeGsdExec(params, deps) {
     if (!isEnabled(deps.preferences))
-        return disabledResult();
+        return contextModeDisabledResult("gsd_exec");
     const runtime = params.runtime;
     if (runtime !== "bash" && runtime !== "node" && runtime !== "python") {
         return paramError(`invalid runtime "${String(runtime)}" — must be bash | node | python`);
@@ -67,7 +55,7 @@ export async function executeGsdExec(params, deps) {
     if (Buffer.byteLength(script, "utf8") > 200_000) {
         return paramError("script exceeds the 200 KB length limit");
     }
-    const opts = buildExecOptions(deps.baseDir, deps.preferences?.context_mode, { now: deps.now, generateId: deps.generateId });
+    const opts = buildExecOptions(deps.baseDir, deps.preferences?.context_mode, { env: deps.env, now: deps.now, generateId: deps.generateId });
     const run = deps.run ?? runExecSandbox;
     try {
         const result = await run({

package/dist/resources/extensions/gsd/tools/memory-tools.js

@@ -256,6 +256,7 @@ function includeSupersededMemories(rankedActive) {
                 scope: row["scope"] ?? "project",
                 tags,
                 structured_fields: structuredFields,
+                last_hit_at: row["last_hit_at"] ?? null,
             };
         });
     }