@opengsd/gsd-pi 1.8.1 → 1.9.0-dev.5c1a3ff2

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/compat/compat-marker.js

@@ -6,7 +6,7 @@
 // (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 { dirname, join, isAbsolute, normalize } 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). */
@@ -170,10 +170,27 @@ 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;
     }

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));
+}

package/dist/resources/extensions/gsd/db/command-queue.js

@@ -12,7 +12,7 @@
 //   - broadcast queries: WHERE target_worker IS NULL
 // Workers should poll for both forms (their own ID + broadcasts) on each
 // claim cycle.
-import { _getAdapter, isDbAvailable, transaction, } from "../gsd-db.js";
+import { _getAdapter, immediateTransaction, isDbAvailable, transaction, } from "../gsd-db.js";
 /**
  * Enqueue a command. Returns the new row id. Broadcast commands
  * (targetWorker=null) will be claimed by exactly one worker — the IPC
@@ -47,7 +47,12 @@ export function claimNextCommand(workerId) {
         return null;
     const now = new Date().toISOString();
     const db = _getAdapter();
-    return transaction(() => {
+    // BEGIN IMMEDIATE: this is a read-then-write claim. Under WAL, a deferred
+    // transaction that reads first and then upgrades to a writer can fail with
+    // SQLITE_BUSY_SNAPSHOT (not retried by busy_timeout) when two workers race;
+    // taking the write lock up front serializes claimants so the loser waits
+    // and then sees the row already claimed (changes !== 1 → null).
+    return immediateTransaction(() => {
         // Find the oldest unclaimed command targeted at this worker OR
         // broadcast. The partial index covers both via NULL-in-B-tree.
         const row = db.prepare(`SELECT id, target_worker, command, args_json, enqueued_at,

package/dist/resources/extensions/gsd/db/engine.js

@@ -18,7 +18,7 @@ import { createBaseSchemaObjects } from "../db-base-schema.js";
 import { createCoordinationTablesV24 } from "../db-coordination-schema.js";
 import { createDbConnectionCache } from "../db-connection-cache.js";
 import { backupDatabaseBeforeMigration, isMigrationBackupError } from "../db-migration-backup.js";
-import { applyMigrationV2Artifacts, applyMigrationV3Memories, applyMigrationV4DecisionMadeBy, applyMigrationV5HierarchyTables, applyMigrationV6SliceSummaries, applyMigrationV7Dependencies, applyMigrationV8PlanningFields, applyMigrationV9Ordering, applyMigrationV10ReplanTrigger, applyMigrationV11TaskPlanning, applyMigrationV12QualityGates, applyMigrationV13HotPathIndexes, applyMigrationV14SliceDependencies, applyMigrationV15AuditTables, applyMigrationV16EscalationSource, applyMigrationV17TaskEscalation, applyMigrationV18MemorySources, applyMigrationV19MemoryFts, applyMigrationV20MemoryRelations, applyMigrationV21StructuredMemories, applyMigrationV22QualityGateRepair, applyMigrationV23MilestoneQueue, applyMigrationV26MilestoneCommitAttributions, applyMigrationV27ArtifactHash, applyMigrationV28MemoryLastHitAt, applyMigrationV29RepositoryTargets, } from "../db-migration-steps.js";
+import { applyMigrationV2Artifacts, applyMigrationV3Memories, applyMigrationV4DecisionMadeBy, applyMigrationV5HierarchyTables, applyMigrationV6SliceSummaries, applyMigrationV7Dependencies, applyMigrationV8PlanningFields, applyMigrationV9Ordering, applyMigrationV10ReplanTrigger, applyMigrationV11TaskPlanning, applyMigrationV12QualityGates, applyMigrationV13HotPathIndexes, applyMigrationV14SliceDependencies, applyMigrationV15AuditTables, applyMigrationV16EscalationSource, applyMigrationV17TaskEscalation, applyMigrationV18MemorySources, applyMigrationV19MemoryFts, applyMigrationV20MemoryRelations, applyMigrationV21StructuredMemories, applyMigrationV22QualityGateRepair, applyMigrationV23MilestoneQueue, applyMigrationV26MilestoneCommitAttributions, applyMigrationV27ArtifactHash, applyMigrationV28MemoryLastHitAt, applyMigrationV29RepositoryTargets, applyMigrationV30ReworkBriefs, } from "../db-migration-steps.js";
 import { isMemoriesFtsAvailableSchema, rebuildMemoriesFtsSchemaOnce, tryCreateMemoriesFtsSchema, } from "../db-memory-fts-schema.js";
 import { createDbOpenState } from "../db-open-state.js";
 import { createRuntimeKvTableV25 } from "../db-runtime-kv-schema.js";
@@ -55,7 +55,7 @@ const providerLoader = createSqliteProviderLoader({
     nodeVersion: process.versions.node,
     writeStderr: (message) => process.stderr.write(message),
 });
-export const SCHEMA_VERSION = 29;
+export const SCHEMA_VERSION = 30;
 function initSchema(db, fileBacked, dbPath) {
     const conservativeFilePragmas = fileBacked && _isLikelyWslDrvFsPathForTest(dbPath);
     if (fileBacked)
@@ -80,19 +80,41 @@ function initSchema(db, fileBacked, dbPath) {
         });
         const existing = db.prepare("SELECT count(*) as cnt FROM schema_version").get();
         if (existing && existing["cnt"] === 0) {
-            createCoordinationTablesV24(db);
-            createRuntimeKvTableV25(db);
-            // Fresh install — all tables are created above with the full current schema,
-            // so it is safe to create all migration-specific indexes here.  For existing
-            // databases these indexes are created inside the individual migration guards
-            // in migrateSchema() after the corresponding columns have been added.
-            db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_escalation_pending ON tasks(milestone_id, slice_id, escalation_pending)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_to ON memory_relations(to_id)");
-            recordSchemaVersion(db, SCHEMA_VERSION);
+            // An empty schema_version table usually means a fresh install, but it can
+            // also be a legacy/truncated DB that already holds user data. Stamping
+            // that DB SCHEMA_VERSION without running migrations would mis-mark it as
+            // fully migrated and break at first query. Probe before stamping.
+            const hasData = ["milestones", "decisions", "memories"].some((t) => {
+                try {
+                    const r = db.prepare(`SELECT count(*) as cnt FROM ${t}`).get();
+                    return (r?.["cnt"] ?? 0) > 0;
+                }
+                catch { /* table absent on a truly fresh DB — treat as no data */
+                    return false;
+                }
+            });
+            if (hasData) {
+                // Legacy DB with data but no version row: record the baseline so
+                // migrateSchema runs the full chain instead of stamping the current version.
+                recordSchemaVersion(db, 1);
+            }
+            else {
+                createCoordinationTablesV24(db);
+                createRuntimeKvTableV25(db);
+                // Fresh install — all tables are created above with the full current schema,
+                // so it is safe to create all migration-specific indexes here.  For existing
+                // databases these indexes are created inside the individual migration guards
+                // in migrateSchema() after the corresponding columns have been added.
+                db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_escalation_pending ON tasks(milestone_id, slice_id, escalation_pending)");
+                db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
+                db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
+                db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
+                db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id)");
+                db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_to ON memory_relations(to_id)");
+                db.exec("CREATE INDEX IF NOT EXISTS idx_rework_briefs_task ON rework_briefs(milestone_id, slice_id, task_id)");
+                db.exec("CREATE INDEX IF NOT EXISTS idx_rework_findings_status ON rework_brief_findings(brief_id, severity, status)");
+                recordSchemaVersion(db, SCHEMA_VERSION);
+            }
         }
         db.exec("COMMIT");
     }
@@ -143,9 +165,16 @@ function copyQualityGateRowsToRepairedTable(db) {
     FROM quality_gates
   `);
 }
+let _migrationFaultForTest = false;
+/** Test-only: force migrateSchema to throw after applying its steps but before COMMIT. */
+export function _setMigrationFaultForTest(v) { _migrationFaultForTest = v; }
 function migrateSchema(db, dbPath) {
     const currentVersion = getCurrentSchemaVersion(db);
-    if (currentVersion >= SCHEMA_VERSION)
+    if (currentVersion > SCHEMA_VERSION) {
+        throw new Error(`gsd.db schema is v${currentVersion}, newer than the v${SCHEMA_VERSION} this gsd-pi supports. ` +
+            `Update gsd-pi (npm i -g @opengsd/gsd-pi) before opening this project.`);
+    }
+    if (currentVersion === SCHEMA_VERSION)
         return;
     backupDatabaseBeforeMigration(db, dbPath, currentVersion, {
         existsSync,
@@ -282,6 +311,12 @@ function migrateSchema(db, dbPath) {
             applyMigrationV29RepositoryTargets(db);
             recordSchemaVersion(db, 29);
         }
+        if (currentVersion < 30) {
+            applyMigrationV30ReworkBriefs(db);
+            recordSchemaVersion(db, 30);
+        }
+        if (_migrationFaultForTest)
+            throw new Error("migration fault injected for test");
         db.exec("COMMIT");
     }
     catch (err) {

package/dist/resources/extensions/gsd/db/writers/cascades.js

@@ -172,7 +172,11 @@ export function skipSliceCascade(milestoneId, sliceId) {
             outcome = { ok: false, reason: "slice-not-found" };
             return;
         }
-        if (slice.status === "complete" || slice.status === "done") {
+        // Reject any closed slice except "skipped" (which falls through to the
+        // wasAlreadySkipped no-op). isClosedStatus covers the "closed"/"done"
+        // aliases too — hand-picking literals here nulls a completed slice's
+        // completed_at on re-skip.
+        if (isClosedStatus(slice.status) && slice.status !== "skipped") {
             outcome = { ok: false, reason: "slice-already-complete" };
             return;
         }