@opengsd/gsd-pi 1.8.1 → 1.9.0-dev.97ef11e3

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -7,7 +7,9 @@ import { canonicalToolName } from "../engine-hook-contract.js";
 import { loadJsonFileOrNull } from "../json-persistence.js";
 import { getIsolationMode } from "../preferences.js";
 import { compileSubagentPermissionContract } from "../unit-context-manifest.js";
+import { allowedPlanningDispatchAgentsList, isReadOnlyPlanningDispatchAgent, } from "../planning-subagent-registry.js";
 import { logWarning } from "../workflow-logger.js";
+import { acquireSyncLock, releaseSyncLock } from "../sync-lock.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { worktreesDirs } from "../worktree-placement.js";
 import { bashReferencesProjectRootOutsideWorktree } from "../worktree-shell-guard.js";
@@ -318,12 +320,65 @@ export function refreshWriteGateStateFromDisk(basePath) {
     }
     return currentWriteGateSnapshot(basePath);
 }
+const WRITE_GATE_LOCK_NAME = "write-gate.lock";
+/**
+ * Test-only seam: fires once inside the held cross-process lock (after acquire,
+ * before the read-merge-write body) with the resolved lock root. Lets a
+ * regression test observe that a concurrent process is genuinely locked out of
+ * the critical section. Production leaves it null. Follows the repo's
+ * `_setGhAvailableForTest` naming convention.
+ */
+let interleaveHookForTest = null;
+export function _setWriteGateInterleaveHookForTest(fn) {
+    interleaveHookForTest = fn;
+}
+/**
+ * Serialize the read-merge-write critical section across the two processes
+ * that share the snapshot file (extension host + workflow MCP child). Atomic
+ * rename prevents torn files but not lost updates: without this lock the host
+ * can read the snapshot, the child can arm a gate and persist, then the host's
+ * later persist overwrites `pendingGateId`/`activeQueuePhase` (last-writer-wins
+ * fields) and silently drops the armed HARD-BLOCK gate.
+ *
+ * Fail-OPEN by contract: if a live peer holds the lock we proceed WITHOUT it —
+ * exactly the racy-but-functional behavior that shipped before this lock — and
+ * log once. The lock shrinks the race window to ~zero; it must never block,
+ * throw, or refuse a gate mutation. The lock is skipped entirely when snapshot
+ * persistence is off (no disk file, no cross-process seam).
+ */
+function withWriteGateLock(basePath, fn) {
+    if (!shouldPersistWriteGateSnapshot())
+        return fn();
+    const lockRoot = resolveWriteGateSnapshotRoot(basePath);
+    // Materialize `.gsd/` (including a dangling external-state symlink target)
+    // before locking. acquireSyncLock's own mkdir does NOT follow a symlink to
+    // create its target, so without this the O_EXCL open lands on a missing
+    // parent and the lock silently fails open — leaving the seam unserialized
+    // for exactly the external-state projects that need it. This is the same
+    // directory the persist path ensures anyway.
+    try {
+        ensureWriteGateSnapshotDirectory(basePath);
+    }
+    catch { /* best-effort; acquire fails-open below */ }
+    const { acquired } = acquireSyncLock(lockRoot, 0, WRITE_GATE_LOCK_NAME);
+    if (!acquired) {
+        logWarning("intercept", "write-gate: proceeding without cross-process lock (held by live peer)", { lockRoot });
+        return fn();
+    }
+    try {
+        interleaveHookForTest?.(lockRoot);
+        return fn();
+    }
+    finally {
+        releaseSyncLock(lockRoot, WRITE_GATE_LOCK_NAME);
+    }
+}
 /**
  * Read-modify-write primitive for gate mutations. Reconciles the disk
  * snapshot into memory (union merge), applies the mutation on top, then
- * persists. The whole sequence is synchronous, so the reconcile read
- * doubles as the pre-persist merge of concurrent writes — there is no
- * version field; the read-merge-write is simply unconditional.
+ * persists — all under the cross-process lock (withWriteGateLock). The whole
+ * sequence is synchronous, so the reconcile read doubles as the pre-persist
+ * merge of concurrent writes; there is no version field.
  *
  * The mutate callback sees the already-reconciled state, so policy checks
  * (e.g. host setPending's verified-on-disk-wins guard) can live inside it
@@ -335,23 +390,25 @@ export function refreshWriteGateStateFromDisk(basePath) {
  */
 function mutateWriteGateState(basePath, mutate, opts) {
     const state = getWriteGateState(basePath);
-    if (shouldPersistWriteGateSnapshot() && (opts?.reconcile ?? true)) {
-        const disk = readDiskSnapshot(basePath);
-        if (disk) {
-            mergeSnapshotIntoState(state, disk);
-        }
-        else {
-            // Missing OR unparseable on disk: treat as a full reset. Keeping
-            // stale in-memory state across a corrupt snapshot would persist it
-            // back on this very mutation and defeat the documented
-            // "delete the file to clear the HARD BLOCK gate" escape hatch.
-            replaceStateFromSnapshot(state, EMPTY_SNAPSHOT);
+    return withWriteGateLock(basePath, () => {
+        if (shouldPersistWriteGateSnapshot() && (opts?.reconcile ?? true)) {
+            const disk = readDiskSnapshot(basePath);
+            if (disk) {
+                mergeSnapshotIntoState(state, disk);
+            }
+            else {
+                // Missing OR unparseable on disk: treat as a full reset. Keeping
+                // stale in-memory state across a corrupt snapshot would persist it
+                // back on this very mutation and defeat the documented
+                // "delete the file to clear the HARD BLOCK gate" escape hatch.
+                replaceStateFromSnapshot(state, EMPTY_SNAPSHOT);
+            }
         }
-    }
-    if (mutate(state) === false)
-        return false;
-    persistWriteGateSnapshot(basePath, opts?.writer ?? defaultWriteGateWriter());
-    return true;
+        if (mutate(state) === false)
+            return false;
+        persistWriteGateSnapshot(basePath, opts?.writer ?? defaultWriteGateWriter());
+        return true;
+    });
 }
 export function isDepthVerified(basePath = process.cwd()) {
     return getWriteGateState(basePath).verifiedDepthMilestones.size > 0;
@@ -550,13 +607,15 @@ export const childWriteGateAdapter = {
 };
 function childMutate(basePath, mutate) {
     const state = getWriteGateState(basePath);
-    if (shouldPersistWriteGateSnapshot()) {
-        // Always-fresh: disk is the only truth for the child; discard any
-        // cross-turn in-memory residue before mutating.
-        replaceStateFromSnapshot(state, readDiskSnapshot(basePath) ?? EMPTY_SNAPSHOT);
-    }
-    mutate(state);
-    persistWriteGateSnapshot(basePath, "child");
+    withWriteGateLock(basePath, () => {
+        if (shouldPersistWriteGateSnapshot()) {
+            // Always-fresh: disk is the only truth for the child; discard any
+            // cross-turn in-memory residue before mutating.
+            replaceStateFromSnapshot(state, readDiskSnapshot(basePath) ?? EMPTY_SNAPSHOT);
+        }
+        mutate(state);
+        persistWriteGateSnapshot(basePath, "child");
+    });
 }
 /**
  * Which adapter the module-level convenience exports (markDepthVerified,
@@ -923,29 +982,8 @@ export function shouldBlockQueueExecutionInSnapshot(snapshot, toolName, input, q
 // guards.
 const PLANNING_WRITE_TOOLS = new Set(["write", "edit", "multi_edit", "notebook_edit"]);
 const PLANNING_SUBAGENT_TOOLS = new Set(["subagent", "task"]);
-/**
- * Canonical registry for agents that planning-dispatch may consider. Unit
- * manifests still declare per-unit subsets via ToolsPolicy.allowedSubagents.
- */
-const PLANNING_DISPATCH_AGENT_REGISTRY = {
-    mnemo: { readOnlySpecialist: true },
-    scout: { readOnlySpecialist: true },
-    planner: { readOnlySpecialist: true },
-    reviewer: { readOnlySpecialist: true },
-    security: { readOnlySpecialist: true },
-    tester: { readOnlySpecialist: true },
-};
-export const ALLOWED_PLANNING_DISPATCH_AGENTS = new Set(Object.entries(PLANNING_DISPATCH_AGENT_REGISTRY)
-    .filter(([, metadata]) => metadata.readOnlySpecialist)
-    .map(([agentId]) => agentId));
+export { ALLOWED_PLANNING_DISPATCH_AGENTS } from "../planning-subagent-registry.js";
 let warnedMissingControlledDispatchAgentClasses = false;
-function isReadOnlySpecialist(agentId) {
-    const metadata = PLANNING_DISPATCH_AGENT_REGISTRY[agentId];
-    return metadata?.readOnlySpecialist === true;
-}
-function allowedPlanningDispatchAgentsList() {
-    return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
-}
 function allowsControlledSubagentDispatch(policy) {
     return ((policy.mode === "planning-dispatch" || policy.mode === "verification" || policy.mode === "workflow-only") &&
         Array.isArray(policy.allowedSubagents));
@@ -1093,13 +1131,13 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
             if (requested.length === 0) {
                 return { block: false };
             }
-            const globallyDisallowed = requested.find(a => !isReadOnlySpecialist(a));
+            const globallyDisallowed = requested.find(a => !isReadOnlyPlanningDispatchAgent(a));
             if (globallyDisallowed) {
                 return planningBlock(unitType, policy.mode, `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from ${policy.mode} units`);
             }
             const disallowedByPolicy = requested.find(a => !allowed.has(a));
             if (disallowedByPolicy) {
-                return planningBlock(unitType, policy.mode, `subagent dispatch of "${disallowedByPolicy}" not permitted by ToolsPolicy.allowedSubagents; permitted agents for this unit: ${allowedSubagents.join(", ")}`);
+                return planningBlock(unitType, policy.mode, `subagent dispatch of "${disallowedByPolicy}" not permitted by unit allowlist (ToolsPolicy.allowedSubagents/planning_subagents); permitted agents for this unit: ${allowedSubagents.join(", ")}`);
             }
             return { block: false };
         }

package/dist/resources/extensions/gsd/command-feedback.js

@@ -57,19 +57,23 @@ export function notifyDiscussNeedsInteractiveMenu(ctx, reason) {
         hints: DISCUSS_HINTS,
     });
 }
-/** Hub picker for /gsd queue (reorder vs add) is unavailable. */
+/**
+ * Hub picker for /gsd queue (reorder vs add) is unavailable.
+ *
+ * Unlike the other picker-guidance notices, /gsd queue does NOT dead-end here:
+ * the caller falls through to the add-work flow, which runs headlessly. So this
+ * notice must avoid the "did not start:" picker-failure phrasing — the headless
+ * host classifies that as a blocked dead-end (see stop-notice.ts / #1294) and
+ * would exit 10 before the add-work run starts.
+ */
 export function notifyQueueHubNeedsInteractiveMenu(ctx, reason) {
-    notifyPickerCommandNeedsInteractiveMenu(ctx, {
-        command: "/gsd queue",
-        reason,
-        alternatives: [
-            "Add-work flow can run headless — continuing with queue discussion.",
-        ],
-        hints: [
-            "/gsd queue — run from the GSD TUI to reorder pending milestones",
-            "/gsd status — see milestone order and phase",
-        ],
-    });
+    ctx.ui.notify([
+        `/gsd queue reorder menu needs an interactive session (${reason}).`,
+        "Continuing headless with the add-work flow.",
+        "",
+        "  • /gsd queue — run from the GSD TUI to reorder pending milestones",
+        "  • /gsd status — see milestone order and phase",
+    ].join("\n"), "warning");
 }
 /** /gsd, /gsd new-milestone, /gsd new-project wizard menus. */
 export function notifySmartEntryNeedsInteractiveMenu(ctx, reason) {

package/dist/resources/extensions/gsd/commands-verdict.js

@@ -8,6 +8,7 @@ import { executeValidateMilestone } from "./tools/workflow-tool-executors.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { getLatestAssessmentByScope } from "./gsd-db.js";
 import { checkpointWorkflowDatabase } from "./db-workspace.js";
+import { formatVerdictRecordedNotice, formatVerdictRejectedNotice } from "./stop-notice.js";
 import { VALIDATION_VERDICTS, extractVerdict, isValidMilestoneVerdict, } from "./verdict-parser.js";
 const USAGE = 'Usage: /gsd verdict <pass|needs-attention|needs-remediation> [--milestone Mxxx] [--rationale "..."]';
 function tokenize(raw) {
@@ -123,35 +124,35 @@ async function loadExistingValidation(basePath, milestoneId) {
 }
 export async function handleVerdict(rawArgs, ctx, basePath) {
     if (!rawArgs.trim()) {
-        ctx.ui.notify(USAGE, "warning");
+        ctx.ui.notify(formatVerdictRejectedNotice(USAGE), "warning");
         return;
     }
     const parsed = parseArgs(rawArgs);
     if ("error" in parsed) {
-        ctx.ui.notify(`${parsed.error}\n${USAGE}`, "warning");
+        ctx.ui.notify(formatVerdictRejectedNotice(`${parsed.error}\n${USAGE}`), "warning");
         return;
     }
     if (!parsed.verdict) {
-        ctx.ui.notify(USAGE, "warning");
+        ctx.ui.notify(formatVerdictRejectedNotice(USAGE), "warning");
         return;
     }
     let milestoneId = parsed.milestoneId;
     if (!milestoneId) {
         const state = await deriveState(basePath);
         if (!state.activeMilestone) {
-            ctx.ui.notify("No active milestone — pass --milestone Mxxx to target a specific milestone.", "warning");
+            ctx.ui.notify(formatVerdictRejectedNotice("No active milestone — pass --milestone Mxxx to target a specific milestone."), "warning");
             return;
         }
         milestoneId = state.activeMilestone.id;
     }
     const existingValidation = await loadExistingValidation(basePath, milestoneId);
     if (!existingValidation) {
-        ctx.ui.notify(`No milestone validation found for ${milestoneId}. Run /gsd auto to validate first, then retry /gsd verdict.`, "warning");
+        ctx.ui.notify(formatVerdictRejectedNotice(`No milestone validation found for ${milestoneId}. Run /gsd auto to validate first, then retry /gsd verdict.`), "warning");
         return;
     }
     const current = parseValidationFile(existingValidation.content);
     if (parsed.verdict !== "pass" && !parsed.rationale) {
-        ctx.ui.notify(`--rationale is required when overriding to ${parsed.verdict}.`, "warning");
+        ctx.ui.notify(formatVerdictRejectedNotice(`--rationale is required when overriding to ${parsed.verdict}.`), "warning");
         return;
     }
     const verdictRationale = parsed.rationale ?? "Manually overridden via /gsd verdict";
@@ -169,17 +170,17 @@ export async function handleVerdict(rawArgs, ctx, basePath) {
     }, basePath, parsed.verdict === "pass" ? { skipBrowserEvidenceGate: true } : undefined);
     if (result.isError) {
         const msg = result.content[0]?.type === "text" ? result.content[0].text : "Unknown error";
-        ctx.ui.notify(msg, "error");
+        ctx.ui.notify(formatVerdictRejectedNotice(msg), "error");
         return;
     }
     checkpointWorkflowDatabase();
     const prevVerdict = current.verdict ?? "unknown";
     const effectiveVerdict = extractEffectiveVerdict(result.details, parsed.verdict);
     if (effectiveVerdict !== parsed.verdict) {
-        ctx.ui.notify(`Milestone ${milestoneId} verdict requested: ${parsed.verdict}, effective: ${effectiveVerdict} (${existingValidation.source})`, "warning");
+        ctx.ui.notify(formatVerdictRecordedNotice(`Milestone ${milestoneId} verdict requested: ${parsed.verdict}, effective: ${effectiveVerdict} (${existingValidation.source})`), "warning");
     }
     else {
-        ctx.ui.notify(`Milestone ${milestoneId} verdict: ${prevVerdict} -> ${effectiveVerdict} (${existingValidation.source})`, "success");
+        ctx.ui.notify(formatVerdictRecordedNotice(`Milestone ${milestoneId} verdict: ${prevVerdict} -> ${effectiveVerdict} (${existingValidation.source})`), "success");
     }
     if (effectiveVerdict === "needs-remediation") {
         ctx.ui.notify("Follow up with /gsd dispatch reassess to add remediation slices, then re-run /gsd auto.", "info");

package/dist/resources/extensions/gsd/compat/compat-marker.js

@@ -5,8 +5,8 @@
 // distinguish gsd-pi's own writes (expected) from external edits made by gsd-core
 // (drift to import). gsd-core is oblivious to this file and ignores it.
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join, isAbsolute, normalize, relative, resolve } from "node:path";
 /** Current marker schema version. Bump on breaking format changes + migrate. */
 export const COMPAT_MARKER_SCHEMA = 2;
 /** Marker returned when no marker exists yet (fresh project, first gsd-pi run). */
@@ -32,6 +32,35 @@ export function normalizeForHash(content) {
 export function computeProjectionSha(content) {
     return createHash("sha256").update(normalizeForHash(content)).digest("hex").slice(0, 16);
 }
+function normalizeRealPath(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+function rootRelativeKey(rootPath, absPath) {
+    const root = normalizeRealPath(rootPath);
+    const abs = normalizeRealPath(absPath);
+    const rel = relative(root, abs);
+    if (!rel || rel === ".." || rel.startsWith(`..${sepForRelative(rel)}`) || isAbsolute(rel)) {
+        return null;
+    }
+    return rel.replace(/\\/g, "/");
+}
+function sepForRelative(rel) {
+    return rel.includes("\\") ? "\\" : "/";
+}
+export function deriveCompatProjectionKey(absPath, roots) {
+    for (const root of roots) {
+        const key = rootRelativeKey(root, absPath);
+        if (key)
+            return key;
+    }
+    const fallbackRoot = roots[roots.length - 1] ?? dirname(absPath);
+    return relative(fallbackRoot, absPath).replace(/\\/g, "/");
+}
 /**
  * Read & validate the marker. A missing marker → EMPTY_MARKER (treat every
  * projection as external on next reconcile). A malformed marker is quarantined
@@ -39,7 +68,9 @@ export function computeProjectionSha(content) {
  * EMPTY_MARKER. A schema-mismatch returns EMPTY_MARKER (forward-compat: refuse
  * to act on a future format we don't understand).
  */
-export function readCompatMarker(basePath) {
+export function readCompatMarker(basePath, options = {}) {
+    const healInvalidKeys = options.healInvalidKeys ?? true;
+    const quarantineInvalid = options.quarantineInvalid ?? true;
     const path = compatMarkerPath(basePath);
     if (!existsSync(path))
         return emptyMarker();
@@ -55,11 +86,16 @@ export function readCompatMarker(basePath) {
         parsed = JSON.parse(raw);
     }
     catch {
-        quarantine(basePath, raw);
+        if (quarantineInvalid)
+            quarantine(basePath, raw);
         return emptyMarker();
     }
+    if (healInvalidKeys && healMarkerProjectionKeys(basePath, parsed) && isValidMarker(parsed)) {
+        writeCompatMarker(basePath, parsed);
+    }
     if (!isValidMarker(parsed)) {
-        quarantine(basePath, raw);
+        if (quarantineInvalid)
+            quarantine(basePath, raw);
         return emptyMarker();
     }
     // Promote older markers by defaulting absent fields. Schema 1 → 2 only adds
@@ -170,15 +206,71 @@ function isValidProjectionEntry(x) {
         return false;
     return true;
 }
+/**
+ * Projection-map keys are repo-relative paths under .gsd/ or .planning/.
+ * The marker is repo-controlled content, so a key must never escape its
+ * root: reject absolute paths, drive letters, backslashes, and any
+ * normalized form that starts with "..". Mirrors the write-side guard in
+ * db-writer.ts.
+ */
+function isSafeProjectionKey(key) {
+    if (key.length === 0 || key.includes("\\") || key.includes("\0"))
+        return false;
+    if (isAbsolute(key) || /^[A-Za-z]:/.test(key))
+        return false;
+    const norm = normalize(key);
+    return norm !== ".." && !norm.startsWith("../") && !isAbsolute(norm);
+}
 function isValidProjectionMap(x) {
     if (typeof x !== "object" || x === null)
         return false;
-    for (const v of Object.values(x)) {
+    for (const [k, v] of Object.entries(x)) {
+        if (!isSafeProjectionKey(k))
+            return false;
         if (!isValidProjectionEntry(v))
             return false;
     }
     return true;
 }
+function healMarkerProjectionKeys(basePath, marker) {
+    if (typeof marker !== "object" || marker === null)
+        return false;
+    const m = marker;
+    let changed = false;
+    if (typeof m.projections === "object" && m.projections !== null) {
+        changed = healProjectionMapKeys(basePath, ".gsd", m.projections) || changed;
+    }
+    const planning = m.planning;
+    if (typeof planning === "object" && planning !== null) {
+        const p = planning;
+        if (typeof p.projections === "object" && p.projections !== null) {
+            changed = healProjectionMapKeys(basePath, ".planning", p.projections) || changed;
+        }
+        if (typeof p.passthrough === "object" && p.passthrough !== null) {
+            changed = healProjectionMapKeys(basePath, ".planning", p.passthrough) || changed;
+        }
+    }
+    return changed;
+}
+function healProjectionMapKeys(basePath, rootName, map) {
+    let changed = false;
+    const root = join(basePath, rootName);
+    for (const key of Object.keys(map)) {
+        if (isSafeProjectionKey(key))
+            continue;
+        if (key.includes("\0") || isAbsolute(key) || /^[A-Za-z]:/.test(key))
+            continue;
+        const healedKey = rootRelativeKey(root, resolve(root, key));
+        if (!healedKey || !isSafeProjectionKey(healedKey))
+            continue;
+        if (!map[healedKey]) {
+            map[healedKey] = map[key];
+        }
+        delete map[key];
+        changed = true;
+    }
+    return changed;
+}
 function isValidPlanningMarker(x) {
     if (typeof x !== "object" || x === null)
         return false;

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

@@ -24,36 +24,35 @@ export const CACHE_MAX = 50;
  * By scoping tools to this allowlist during discuss dispatches, the grammar
  * sent to the provider stays well under provider limits.
  *
- * Included tools and why:
+ * Included tools and why (canonical names only — aliases are no longer
+ * advertised to models by default, see plan 035):
  *   - gsd_summary_save: writes CONTEXT.md artifacts (all discuss prompts)
- *   - gsd_save_summary: alias for above
  *   - gsd_decision_save: records decisions (discuss.md output phase)
- *   - gsd_save_decision: alias for above
  *   - gsd_plan_milestone: writes roadmap (discuss.md single/multi milestone)
- *   - gsd_milestone_plan: alias for above
  *   - gsd_milestone_generate_id: generates milestone IDs (discuss.md multi-milestone)
- *   - gsd_generate_milestone_id: alias for above
  *   - gsd_requirement_save: creates requirements during discuss
- *   - gsd_save_requirement: alias for above
  *   - gsd_requirement_update: updates requirements during discuss
- *   - gsd_update_requirement: alias for above
  */
 export const DISCUSS_TOOLS_ALLOWLIST = [
     // Context / summary writing
     "gsd_summary_save",
-    "gsd_save_summary",
     // Decision recording
     "gsd_decision_save",
-    "gsd_save_decision",
     // Milestone planning (needed for discuss.md output phase)
     "gsd_plan_milestone",
-    "gsd_milestone_plan",
     // Milestone ID generation (multi-milestone flow)
     "gsd_milestone_generate_id",
-    "gsd_generate_milestone_id",
     // Requirement updates
     "gsd_requirement_save",
-    "gsd_save_requirement",
     "gsd_requirement_update",
-    "gsd_update_requirement",
 ];
+// ─── Context Injection ────────────────────────────────────────────────────────
+/**
+ * Leading marker stamped on every buildContextMessage() output
+ * (bootstrap/system-context.ts). Single source of truth for the producer and
+ * the consumer: the provider payload policy (filterSupersededContextInjections
+ * in context-masker.ts) matches this prefix to find and dedupe injected
+ * memory/guided/forensics messages after convertToLlm strips their customType.
+ * Both sides import it from here — do not inline the literal in either module.
+ */
+export const GSD_CONTEXT_MESSAGE_SENTINEL = "[GSD Context Injection]";

package/dist/resources/extensions/gsd/context-masker.js

@@ -1,22 +1,4 @@
-/**
- * Observation masking for GSD auto-mode sessions.
- *
- * Replaces tool result content older than N turns with a placeholder.
- * Reduces context bloat between compactions with zero LLM overhead.
- * Preserves message ordering, roles, and all assistant/user messages.
- *
- * Operates on provider payloads after convertToLlm:
- *
- * pi-ai Message[] payloads:
- *   - toolResult messages: { role: "toolResult", content: TextContent[] }
- *   - bash results are already converted to: { role: "user", content: [{type:"text",text:"..."}] }
- *     and start with "Ran `" from bashExecutionToText.
- *
- * OpenAI/Codex Responses payloads:
- *   - conversation items live in `input`, not `messages`
- *   - tool results are { type: "function_call_output", output: string | content[] }
- *   - bash results are user items with input_text content starting with "Ran `"
- */
+import { GSD_CONTEXT_MESSAGE_SENTINEL } from "./constants.js";
 const MASK_PLACEHOLDER = "[result masked — within summarized history]";
 const MASK_CONTENT_BLOCK = [{ type: "text", text: MASK_PLACEHOLDER }];
 const RESPONSES_MASK_CONTENT_BLOCK = [{ type: "input_text", text: MASK_PLACEHOLDER }];
@@ -52,6 +34,26 @@ function findTurnBoundary(messages, keepRecentTurns) {
     }
     return 0;
 }
+function countRealUserTurns(messages) {
+    let count = 0;
+    for (const m of messages) {
+        if (m.role === "user" && !isBashResultUserMessage(m))
+            count++;
+    }
+    return count;
+}
+/**
+ * Quantizes how many recent turns stay unmasked so the boundary only moves
+ * forward once per full block of `keepRecentTurns` new turns, instead of
+ * every turn. Keeps the masked prefix byte-stable within a block, which is
+ * what lets the LLM provider's prompt cache survive across turns.
+ */
+function quantizedKeepTurns(totalTurns, keepRecentTurns) {
+    if (keepRecentTurns <= 0 || totalTurns < 2 * keepRecentTurns)
+        return totalTurns;
+    const maskedTurns = Math.floor((totalTurns - keepRecentTurns) / keepRecentTurns) * keepRecentTurns;
+    return totalTurns - maskedTurns;
+}
 /**
  * Detect user messages that originated from bashExecution.
  * After convertToLlm, these are {role: "user", content: [{type:"text", text:"Ran `cmd`\n..."}]}.
@@ -73,7 +75,8 @@ function isMaskableMessage(m) {
 }
 export function createObservationMask(keepRecentTurns = 8) {
     return (messages) => {
-        const boundary = findTurnBoundary(messages, keepRecentTurns);
+        const totalTurns = countRealUserTurns(messages);
+        const boundary = findTurnBoundary(messages, quantizedKeepTurns(totalTurns, keepRecentTurns));
         if (boundary === 0)
             return messages;
         return messages.map((m, i) => {
@@ -104,6 +107,14 @@ function findResponsesTurnBoundary(items, keepRecentTurns) {
     }
     return 0;
 }
+function countResponsesRealUserTurns(items) {
+    let count = 0;
+    for (const item of items) {
+        if (item.role === "user" && !isResponsesBashResultUserItem(item))
+            count++;
+    }
+    return count;
+}
 /**
  * Observation masking for OpenAI/Codex Responses API payloads.
  *
@@ -113,7 +124,8 @@ function findResponsesTurnBoundary(items, keepRecentTurns) {
  */
 export function createResponsesInputObservationMask(keepRecentTurns = 8) {
     return (items) => {
-        const boundary = findResponsesTurnBoundary(items, keepRecentTurns);
+        const totalTurns = countResponsesRealUserTurns(items);
+        const boundary = findResponsesTurnBoundary(items, quantizedKeepTurns(totalTurns, keepRecentTurns));
         if (boundary === 0)
             return items;
         return items.map((item, i) => {
@@ -190,3 +202,67 @@ export function truncateResponsesInputResultItems(items, maxChars = 800) {
         return item;
     });
 }
+// GSD injects at most one context message per turn (memory/guided/forensics —
+// see buildContextMessage in bootstrap/system-context.ts), marked with
+// GSD_CONTEXT_MESSAGE_SENTINEL. convertToLlm strips the distinguishing
+// customType before the payload reaches this hook, so detection is by content
+// prefix instead. Pre-sentinel session history lacks the sentinel, so we also
+// match the stable *bracketed* GSD block labels those injections begin with,
+// letting resumed sessions dedupe older memory/guided blocks.
+//
+// Only GSD-specific bracketed markers belong here — never generic prose. A
+// message is dropped from the payload when it matches, so a natural-language
+// prefix (e.g. the forensics prompt "Debug GSD itself.") could silently delete
+// a real user message that happens to start the same way. Legacy forensics
+// injections without memory are therefore left un-deduped by design; those
+// with memory still match via the "[GSD Context Metadata]" wrapper.
+const LEGACY_GSD_CONTEXT_INJECTION_PREFIXES = [
+    "[GSD Context Metadata]",
+    "[MEMORY — Critical and prompt-relevant memories from the GSD memory store]",
+    "[GSD Guided Execute Context]",
+];
+function isGsdContextInjectionText(text) {
+    if (typeof text !== "string")
+        return false;
+    if (text.startsWith(GSD_CONTEXT_MESSAGE_SENTINEL))
+        return true;
+    return LEGACY_GSD_CONTEXT_INJECTION_PREFIXES.some((prefix) => text.startsWith(prefix));
+}
+function isGsdContextInjectionMessage(m) {
+    if (m.role !== "user")
+        return false;
+    return isGsdContextInjectionText(firstTextFromContent(m.content));
+}
+/**
+ * Removes every GSD context-injection user message except the latest one.
+ * Each turn re-injects a near-identical memory/guided/forensics block; left
+ * in place they duplicate verbatim across an N-turn session. Removal (not
+ * masking) — an empty placeholder still costs tokens and shifts message
+ * positions, breaking cache byte-stability. Pure function: stored history is
+ * never mutated, only the outgoing payload array.
+ */
+export function filterSupersededContextInjections(messages) {
+    let lastIndex = -1;
+    for (let i = 0; i < messages.length; i++) {
+        if (isGsdContextInjectionMessage(messages[i]))
+            lastIndex = i;
+    }
+    if (lastIndex === -1)
+        return messages;
+    return messages.filter((m, i) => i === lastIndex || !isGsdContextInjectionMessage(m));
+}
+function isResponsesGsdContextInjectionItem(item) {
+    if (item.role !== "user")
+        return false;
+    return isGsdContextInjectionText(firstTextFromContent(item.content));
+}
+export function filterSupersededResponsesContextInjections(items) {
+    let lastIndex = -1;
+    for (let i = 0; i < items.length; i++) {
+        if (isResponsesGsdContextInjectionItem(items[i]))
+            lastIndex = i;
+    }
+    if (lastIndex === -1)
+        return items;
+    return items.filter((item, i) => i === lastIndex || !isResponsesGsdContextInjectionItem(item));
+}