gsd-pi 2.73.1 → 2.74.0-dev.0306a2e

package/dist/resources/extensions/gsd/auto-verification.js

@@ -10,18 +10,129 @@
  * checks the result and handles control flow.
  */
 import { mkdirSync, writeFileSync } from "node:fs";
-import { resolveSlicePath } from "./paths.js";
+import { resolveSlicePath, resolveMilestoneFile } from "./paths.js";
 import { parseUnitId } from "./unit-id.js";
-import { isDbAvailable, getTask, getSliceTasks } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSliceTasks, getMilestoneSlices } from "./gsd-db.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { extractVerdict } from "./verdict-parser.js";
+import { isClosedStatus } from "./status-guards.js";
+import { loadFile } from "./files.js";
+import { parseRoadmap } from "./parsers-legacy.js";
+import { isMilestoneComplete } from "./state.js";
 import { runVerificationGate, formatFailureContext, captureRuntimeErrors, runDependencyAudit, } from "./verification-gate.js";
 import { writeVerificationJSON } from "./verification-evidence.js";
 import { logWarning } from "./workflow-logger.js";
 import { runPostExecutionChecks } from "./post-execution-checks.js";
 import { join } from "node:path";
+import { resolveUokFlags } from "./uok/flags.js";
+import { UokGateRunner } from "./uok/gate-runner.js";
 function isInfraVerificationFailure(stderr) {
     return /\b(ENOENT|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN|spawn\s+\S+\s+ENOENT|command not found)\b/i.test(stderr);
 }
+/**
+ * Post-unit guard for `validate-milestone` units (#4094).
+ *
+ * When validate-milestone writes verdict=needs-remediation, the agent is
+ * expected to also call gsd_reassess_roadmap in the same turn to add
+ * remediation slices. If they don't, the state machine re-derives
+ * `phase: validating-milestone` indefinitely (all slices still complete +
+ * verdict still needs-remediation), wasting ~3 dispatches before the stuck
+ * detector fires.
+ *
+ * This guard fires immediately on the first occurrence: if VALIDATION.md
+ * verdict is needs-remediation and no incomplete slices exist for the
+ * milestone, pause the auto-loop with a clear blocker.
+ */
+async function runValidateMilestonePostCheck(vctx, pauseAuto) {
+    const { s, ctx, pi } = vctx;
+    const prefs = loadEffectiveGSDPreferences()?.preferences;
+    const uokFlags = resolveUokFlags(prefs);
+    const persistMilestoneValidationGate = async (outcome, failureClass, rationale, findings = "", milestoneId) => {
+        if (!uokFlags.gates || !s.currentUnit)
+            return;
+        const gateRunner = new UokGateRunner();
+        gateRunner.register({
+            id: "milestone-validation-post-check",
+            type: "verification",
+            execute: async () => ({
+                outcome,
+                failureClass,
+                rationale,
+                findings,
+            }),
+        });
+        await gateRunner.run("milestone-validation-post-check", {
+            basePath: s.basePath,
+            traceId: `validation-post-check:${s.currentUnit.id}`,
+            turnId: s.currentUnit.id,
+            milestoneId,
+            unitType: s.currentUnit.type,
+            unitId: s.currentUnit.id,
+        });
+    };
+    if (!s.currentUnit)
+        return "continue";
+    const { milestone: mid } = parseUnitId(s.currentUnit.id);
+    if (!mid)
+        return "continue";
+    const validationFile = resolveMilestoneFile(s.basePath, mid, "VALIDATION");
+    if (!validationFile)
+        return "continue";
+    const validationContent = await loadFile(validationFile);
+    if (!validationContent)
+        return "continue";
+    const verdict = extractVerdict(validationContent);
+    if (verdict !== "needs-remediation") {
+        await persistMilestoneValidationGate("pass", "none", `milestone validation verdict is ${verdict}; no remediation loop risk`, "", mid);
+        return "continue";
+    }
+    const incompleteSliceCount = await countIncompleteSlices(s.basePath, mid);
+    // If any non-closed slices exist, the agent successfully queued remediation
+    // work — proceed normally. The state machine will execute those slices and
+    // re-validate per the #3596/#3670 fix.
+    if (incompleteSliceCount > 0) {
+        await persistMilestoneValidationGate("pass", "none", `remediation slices present (${incompleteSliceCount}); validation can continue`, "", mid);
+        return "continue";
+    }
+    ctx.ui.notify(`Milestone ${mid} validation returned verdict=needs-remediation but no remediation slices were added. Pausing for human review.`, "error");
+    process.stderr.write(`validate-milestone: pausing — verdict=needs-remediation with no incomplete slices for ${mid}. ` +
+        `The agent must call gsd_reassess_roadmap to add remediation slices before re-validation.\n`);
+    await persistMilestoneValidationGate("manual-attention", "manual-attention", "needs-remediation verdict without queued remediation slices", `No incomplete slices found for ${mid} while verdict=needs-remediation`, mid);
+    await pauseAuto(ctx, pi);
+    return "pause";
+}
+/**
+ * Count slices for a milestone that are not in a closed status.
+ * DB-backed projects are authoritative (#4094 peer review); falls back to
+ * roadmap parsing only when the DB is unavailable.
+ */
+async function countIncompleteSlices(basePath, milestoneId) {
+    if (isDbAvailable()) {
+        const slices = getMilestoneSlices(milestoneId);
+        if (slices.length === 0) {
+            // No DB rows — treat as "unknown", do not pause.
+            return 1;
+        }
+        return slices.filter((slice) => !isClosedStatus(slice.status)).length;
+    }
+    // Filesystem fallback: parse the roadmap markdown.
+    try {
+        const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+        if (!roadmapFile)
+            return 1;
+        const roadmapContent = await loadFile(roadmapFile);
+        if (!roadmapContent)
+            return 1;
+        const roadmap = parseRoadmap(roadmapContent);
+        if (roadmap.slices.length === 0)
+            return 1;
+        return isMilestoneComplete(roadmap) ? 0 : 1;
+    }
+    catch {
+        // Parsing failures should not cause false-positive pauses.
+        return 1;
+    }
+}
 /**
  * Run the verification gate for the current execute-task unit.
  * Returns:
@@ -31,12 +142,19 @@ function isInfraVerificationFailure(stderr) {
  */
 export async function runPostUnitVerification(vctx, pauseAuto) {
     const { s, ctx, pi } = vctx;
-    if (!s.currentUnit || s.currentUnit.type !== "execute-task") {
+    if (!s.currentUnit) {
+        return "continue";
+    }
+    if (s.currentUnit.type === "validate-milestone") {
+        return await runValidateMilestonePostCheck(vctx, pauseAuto);
+    }
+    if (s.currentUnit.type !== "execute-task") {
         return "continue";
     }
     try {
         const effectivePrefs = loadEffectiveGSDPreferences();
         const prefs = effectivePrefs?.preferences;
+        const uokFlags = resolveUokFlags(prefs);
         // Read task plan verify field
         const { milestone: mid, slice: sid, task: tid } = parseUnitId(s.currentUnit.id);
         let taskPlanVerify;
@@ -68,6 +186,35 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
                 process.stderr.write(`  [${w.severity}] ${w.name}: ${w.title}\n`);
             }
         }
+        if (uokFlags.gates) {
+            const gateRunner = new UokGateRunner();
+            gateRunner.register({
+                id: "verification-gate",
+                type: "verification",
+                execute: async () => ({
+                    outcome: result.passed ? "pass" : "fail",
+                    failureClass: result.runtimeErrors?.some((e) => e.blocking)
+                        ? "execution"
+                        : "verification",
+                    rationale: result.passed
+                        ? "verification checks passed"
+                        : "verification checks failed",
+                    findings: result.passed
+                        ? ""
+                        : formatFailureContext(result),
+                }),
+            });
+            await gateRunner.run("verification-gate", {
+                basePath: s.basePath,
+                traceId: `verification:${s.currentUnit.id}`,
+                turnId: s.currentUnit.id,
+                milestoneId: mid ?? undefined,
+                sliceId: sid ?? undefined,
+                taskId: tid ?? undefined,
+                unitType: s.currentUnit.type,
+                unitId: s.currentUnit.id,
+            });
+        }
         // Auto-fix retry preferences
         const autoFixEnabled = prefs?.verification_auto_fix !== false;
         const maxRetries = typeof prefs?.verification_max_retries === "number"
@@ -168,6 +315,42 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
                                     : "⚠";
                             process.stderr.write(`gsd-post-exec:   ${checkEmoji} [${check.category}] ${check.target}: ${check.message}\n`);
                         }
+                        if (uokFlags.gates) {
+                            const strictMode = prefs?.enhanced_verification_strict === true;
+                            const warnEscalated = postExecResult.status === "warn" && strictMode;
+                            const blockingFailure = postExecResult.status === "fail" || warnEscalated;
+                            const findings = postExecResult.checks
+                                .filter((check) => !check.passed)
+                                .map((check) => `[${check.category}] ${check.target}: ${check.message}`)
+                                .join("\n");
+                            const gateRunner = new UokGateRunner();
+                            gateRunner.register({
+                                id: "post-execution-checks",
+                                type: "artifact",
+                                execute: async () => ({
+                                    outcome: blockingFailure ? "fail" : "pass",
+                                    failureClass: postExecResult.status === "fail"
+                                        ? "artifact"
+                                        : warnEscalated
+                                            ? "policy"
+                                            : "none",
+                                    rationale: blockingFailure
+                                        ? `post-execution checks ${postExecResult.status}${warnEscalated ? " (strict)" : ""}`
+                                        : "post-execution checks passed",
+                                    findings,
+                                }),
+                            });
+                            await gateRunner.run("post-execution-checks", {
+                                basePath: s.basePath,
+                                traceId: `verification:${s.currentUnit.id}`,
+                                turnId: s.currentUnit.id,
+                                milestoneId: mid,
+                                sliceId: sid,
+                                taskId: tid,
+                                unitType: s.currentUnit.type,
+                                unitId: s.currentUnit.id,
+                            });
+                        }
                         // Check for blocking failures
                         if (postExecResult.status === "fail") {
                             postExecBlockingFailure = true;

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

@@ -36,7 +36,7 @@ import { captureAvailableSkills, resetSkillTelemetry, } from "./skill-telemetry.
 import { getRtkSessionSavings } from "../shared/rtk-session-stats.js";
 import { deactivateGSD } from "../shared/gsd-phase-state.js";
 import { initMetrics, resetMetrics, getLedger, getProjectTotals, formatCost, formatTokenCount, } from "./metrics.js";
-import { logWarning } from "./workflow-logger.js";
+import { setLogBasePath, logWarning } from "./workflow-logger.js";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -55,15 +55,18 @@ import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent } from "./journal.js";
 import { updateProgressWidget as _updateProgressWidget, updateSliceProgressCache, clearSliceProgressCache, hideFooter, } from "./auto-dashboard.js";
 import { registerSigtermHandler as _registerSigtermHandler, deregisterSigtermHandler as _deregisterSigtermHandler, } from "./auto-supervisor.js";
-import { isDbAvailable } from "./gsd-db.js";
+import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { countPendingCaptures } from "./captures.js";
 import { clearCmuxSidebar, logCmuxEvent, syncCmuxSidebar } from "../cmux/index.js";
 // ── Extracted modules ──────────────────────────────────────────────────────
 import { startUnitSupervision } from "./auto-timers.js";
 import { runPostUnitVerification } from "./auto-verification.js";
-import { postUnitPreVerification, postUnitPostVerification, } from "./auto-post-unit.js";
+import { autoCommitUnit, postUnitPreVerification, postUnitPostVerification, } from "./auto-post-unit.js";
 import { bootstrapAutoSession, openProjectDbIfPresent } from "./auto-start.js";
+import { initHealthWidget } from "./health-widget.js";
 import { autoLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto-loop.js";
+import { runAutoLoopWithUok } from "./uok/kernel.js";
+import { resolveUokFlags } from "./uok/flags.js";
 import { WorktreeResolver, } from "./worktree-resolver.js";
 import { reorderForCaching } from "./prompt-ordering.js";
 // ─── Session State ─────────────────────────────────────────────────────────
@@ -359,10 +362,22 @@ function clearUnitTimeout() {
 }
 /** Build snapshot metric opts. */
 function buildSnapshotOpts(_unitType, _unitId) {
+    const prefs = loadEffectiveGSDPreferences()?.preferences;
+    const uokFlags = resolveUokFlags(prefs);
     return {
         ...(s.autoStartTime > 0 ? { autoSessionKey: String(s.autoStartTime) } : {}),
         promptCharCount: s.lastPromptCharCount,
         baselineCharCount: s.lastBaselineCharCount,
+        traceId: s.currentTraceId ?? undefined,
+        turnId: s.currentTurnId ?? undefined,
+        ...(uokFlags.gitops
+            ? {
+                gitAction: uokFlags.gitopsTurnAction,
+                gitPush: uokFlags.gitopsTurnPush,
+                gitStatus: s.lastGitActionStatus ?? undefined,
+                gitError: s.lastGitActionFailure ?? undefined,
+            }
+            : {}),
         ...(s.currentUnitRouting ?? {}),
     };
 }
@@ -397,6 +412,8 @@ function handleLostSessionLock(ctx, lockStatus) {
     ctx?.ui.setStatus("gsd-auto", undefined);
     ctx?.ui.setWidget("gsd-progress", undefined);
     ctx?.ui.setFooter(undefined);
+    if (ctx)
+        initHealthWidget(ctx);
 }
 /**
  * Lightweight cleanup after autoLoop exits via step-wizard break.
@@ -431,6 +448,7 @@ function cleanupAfterLoopExit(ctx) {
         ctx.ui.setStatus("gsd-auto", undefined);
         ctx.ui.setWidget("gsd-progress", undefined);
         ctx.ui.setFooter(undefined);
+        initHealthWidget(ctx);
     }
     // Restore CWD out of worktree back to original project root
     if (s.originalBasePath) {
@@ -501,17 +519,30 @@ export async function stopAuto(ctx, pi, reason) {
                     ? { notify: ctx.ui.notify.bind(ctx.ui) }
                     : { notify: () => { } };
                 const resolver = buildResolver();
-                // Check if the milestone is complete — SUMMARY file is the authoritative signal.
+                // Check if the milestone is complete. DB status is the authoritative
+                // signal — only a successful gsd_complete_milestone call flips it to
+                // "complete" (tools/complete-milestone.ts). SUMMARY file presence is
+                // NOT sufficient: a blocker placeholder stub or a partial write can
+                // leave a file behind without the milestone actually being done,
+                // which previously caused stopAuto to merge a failed milestone and
+                // emit a misleading metadata-only merge warning (#4175).
+                // DB-unavailable projects fall back to SUMMARY-file presence.
                 let milestoneComplete = false;
                 try {
-                    const summaryPath = resolveMilestoneFile(s.originalBasePath || s.basePath, s.currentMilestoneId, "SUMMARY");
-                    if (!summaryPath) {
-                        // Also check in the worktree path (SUMMARY may not be synced yet)
-                        const wtSummaryPath = resolveMilestoneFile(s.basePath, s.currentMilestoneId, "SUMMARY");
-                        milestoneComplete = wtSummaryPath !== null;
+                    if (isDbAvailable()) {
+                        const dbRow = getMilestone(s.currentMilestoneId);
+                        milestoneComplete = dbRow?.status === "complete";
                     }
                     else {
-                        milestoneComplete = true;
+                        const summaryPath = resolveMilestoneFile(s.originalBasePath || s.basePath, s.currentMilestoneId, "SUMMARY");
+                        if (!summaryPath) {
+                            // Also check in the worktree path (SUMMARY may not be synced yet)
+                            const wtSummaryPath = resolveMilestoneFile(s.basePath, s.currentMilestoneId, "SUMMARY");
+                            milestoneComplete = wtSummaryPath !== null;
+                        }
+                        else {
+                            milestoneComplete = true;
+                        }
                     }
                 }
                 catch (err) {
@@ -676,6 +707,8 @@ export async function stopAuto(ctx, pi, reason) {
         ctx?.ui.setStatus("gsd-auto", undefined);
         ctx?.ui.setWidget("gsd-progress", undefined);
         ctx?.ui.setFooter(undefined);
+        if (ctx)
+            initHealthWidget(ctx);
         restoreProjectRootEnv();
         restoreMilestoneLockEnv();
         // Reset all session state in one call
@@ -762,6 +795,8 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
     ctx?.ui.setStatus("gsd-auto", "paused");
     ctx?.ui.setWidget("gsd-progress", undefined);
     ctx?.ui.setFooter(undefined);
+    if (ctx)
+        initHealthWidget(ctx);
     const resumeCmd = s.stepMode ? "/gsd next" : "/gsd auto";
     ctx?.ui.notify(`${s.stepMode ? "Step" : "Auto"}-mode paused (Escape). Type to interact, or ${resumeCmd} to resume.`, "info");
 }
@@ -863,6 +898,7 @@ function buildLoopDeps() {
         getMainBranch,
         // Unit closeout + runtime records
         closeoutUnit,
+        autoCommitUnit,
         recordOutcome,
         writeLock,
         captureAvailableSkills,
@@ -1060,6 +1096,11 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         s.stepMode = requestedStepMode;
         s.cmdCtx = ctx;
         s.basePath = base;
+        // Ensure the workflow-logger audit log is pinned to the project root
+        // even when auto-mode is entered via a path that bypasses the
+        // bootstrap/dynamic-tools ensureDbOpen() → setLogBasePath() chain
+        // (e.g. /clear resume, hot-reload).
+        setLogBasePath(base);
         s.unitDispatchCount.clear();
         s.unitLifetimeDispatches.clear();
         if (!getLedger())
@@ -1138,7 +1179,13 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
         logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
         captureProjectRootEnv(s.originalBasePath || s.basePath);
-        await autoLoop(ctx, pi, s, buildLoopDeps());
+        await runAutoLoopWithUok({
+            ctx,
+            pi,
+            s,
+            deps: buildLoopDeps(),
+            runLegacyLoop: autoLoop,
+        });
         cleanupAfterLoopExit(ctx);
         return;
     }
@@ -1162,7 +1209,13 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     }
     logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
     // Dispatch the first unit
-    await autoLoop(ctx, pi, s, buildLoopDeps());
+    await runAutoLoopWithUok({
+        ctx,
+        pi,
+        s,
+        deps: buildLoopDeps(),
+        runLegacyLoop: autoLoop,
+    });
     cleanupAfterLoopExit(ctx);
 }
 // ─── Agent End Handler ────────────────────────────────────────────────────────

package/dist/resources/extensions/gsd/bootstrap/register-extension.js

@@ -1,7 +1,7 @@
 // GSD2 — Extension registration: wires all GSD tools, commands, and hooks into pi
-import { registerGSDCommand } from "../commands.js";
 import { registerExitCommand } from "../exit-command.js";
 import { registerWorktreeCommand } from "../worktree-command.js";
+import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
@@ -9,6 +9,7 @@ import { registerQueryTools } from "./query-tools.js";
 import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
+import { logWarning } from "../workflow-logger.js";
 export { writeCrashLog } from "./crash-log.js";
 export function handleRecoverableExtensionProcessError(err) {
     if (err.code === "EPIPE") {
@@ -52,20 +53,41 @@ function installEpipeGuard() {
     }
 }
 export function registerGsdExtension(pi) {
-    registerGSDCommand(pi);
+    // Note: registerGSDCommand is called by index.ts before this function,
+    // so we intentionally skip it here to avoid double-registration.
     registerWorktreeCommand(pi);
     registerExitCommand(pi);
     installEpipeGuard();
+    // Ecosystem handlers captured by the GSDExtensionAPI wrapper for the
+    // GSD-owned `before_agent_start` dispatch step (#3338).
+    const ecosystemHandlers = [];
     pi.registerCommand("kill", {
         description: "Exit GSD immediately (no cleanup)",
         handler: async (_args, _ctx) => {
             process.exit(0);
         },
     });
-    registerDynamicTools(pi);
-    registerDbTools(pi);
-    registerJournalTools(pi);
-    registerQueryTools(pi);
-    registerShortcuts(pi);
-    registerHooks(pi);
+    // Wrap non-critical registrations individually so one failure
+    // doesn't prevent the others from loading.
+    const nonCriticalRegistrations = [
+        ["dynamic-tools", () => registerDynamicTools(pi)],
+        ["db-tools", () => registerDbTools(pi)],
+        ["journal-tools", () => registerJournalTools(pi)],
+        ["query-tools", () => registerQueryTools(pi)],
+        ["shortcuts", () => registerShortcuts(pi)],
+        ["hooks", () => registerHooks(pi, ecosystemHandlers)],
+        ["ecosystem", () => {
+                void loadEcosystemExtensions(pi, ecosystemHandlers).catch((err) => {
+                    logWarning("ecosystem", `loader failed: ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }],
+    ];
+    for (const [name, register] of nonCriticalRegistrations) {
+        try {
+            register();
+        }
+        catch (err) {
+            logWarning("bootstrap", `Failed to register ${name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
 }

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -1,5 +1,7 @@
 import { join } from "node:path";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
+import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
+import { getEcosystemReadyPromise } from "../ecosystem/loader.js";
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
 import { buildBeforeAgentStartResult } from "./system-context.js";
 import { handleAgentEnd } from "./agent-end-recovery.js";
@@ -29,7 +31,7 @@ async function syncServiceTierStatus(ctx) {
     const { getEffectiveServiceTier, formatServiceTierFooterStatus } = await import("../service-tier.js");
     ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus(getEffectiveServiceTier(), ctx.model?.id));
 }
-export function registerHooks(pi) {
+export function registerHooks(pi, ecosystemHandlers) {
     pi.on("session_start", async (_event, ctx) => {
         initNotificationStore(process.cwd());
         installNotifyInterceptor(ctx);
@@ -85,7 +87,44 @@ export function registerHooks(pi) {
         loadToolApiKeys();
     });
     pi.on("before_agent_start", async (event, ctx) => {
-        return buildBeforeAgentStartResult(event, ctx);
+        // Wait for ecosystem loader to finish (no-op after first turn).
+        await getEcosystemReadyPromise();
+        // GSD's own context injection (existing behavior — unchanged).
+        const gsdResult = await buildBeforeAgentStartResult(event, ctx);
+        // Refresh the snapshot used by ecosystem getPhase()/getActiveUnit().
+        // deriveState has its own ~100ms cache so this is cheap on repeat calls.
+        try {
+            const state = await deriveState(process.cwd());
+            updateSnapshot(state);
+        }
+        catch {
+            updateSnapshot(null);
+        }
+        // Chain ecosystem handlers using pi's runner.ts chaining protocol:
+        // each handler sees the systemPrompt mutated by prior handlers.
+        let currentSystemPrompt = gsdResult?.systemPrompt ?? event.systemPrompt;
+        // `any` because pi's BeforeAgentStartEventResult.message uses an internal
+        // CustomMessage type that's not re-exported (see ecosystem/gsd-extension-api.ts).
+        let lastMessage = gsdResult?.message;
+        for (const handler of ecosystemHandlers) {
+            try {
+                const r = await handler({ ...event, systemPrompt: currentSystemPrompt }, ctx);
+                if (r?.systemPrompt !== undefined)
+                    currentSystemPrompt = r.systemPrompt;
+                if (r?.message)
+                    lastMessage = r.message;
+            }
+            catch (err) {
+                safetyLogWarning("ecosystem", `before_agent_start handler failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Compose result. Return undefined if nothing changed (preserves runner contract).
+        if (currentSystemPrompt === event.systemPrompt && !lastMessage)
+            return undefined;
+        return {
+            systemPrompt: currentSystemPrompt !== event.systemPrompt ? currentSystemPrompt : undefined,
+            message: lastMessage,
+        };
     });
     pi.on("agent_end", async (event, ctx) => {
         resetToolCallLoopGuard();

package/dist/resources/extensions/gsd/commands/catalog.js

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { loadRegistry } from "../workflow-templates.js";
 import { resolveProjectRoot } from "../worktree.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-export const GSD_COMMAND_DESCRIPTION = "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications";
+export const GSD_COMMAND_DESCRIPTION = "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests";
 export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "help", desc: "Categorized command reference with descriptions" },
     { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
@@ -62,6 +62,12 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" },
     { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
     { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache (.gsd/CODEBASE.md)" },
+    { cmd: "ship", desc: "Create PR from milestone artifacts and open for review" },
+    { cmd: "do", desc: "Route freeform text to the right GSD command" },
+    { cmd: "session-report", desc: "Session cost, tokens, and work summary" },
+    { cmd: "backlog", desc: "Manage backlog items (add, promote, remove, list)" },
+    { cmd: "pr-branch", desc: "Create clean PR branch filtering .gsd/ commits" },
+    { cmd: "add-tests", desc: "Generate tests for completed slices" },
 ];
 const NESTED_COMPLETIONS = {
     auto: [
@@ -231,6 +237,25 @@ const NESTED_COMPLETIONS = {
         { cmd: "stats", desc: "Show file count, description coverage, and generation time" },
         { cmd: "help", desc: "Show usage and available subcommands" },
     ],
+    ship: [
+        { cmd: "--dry-run", desc: "Preview PR without creating" },
+        { cmd: "--draft", desc: "Open as draft PR" },
+        { cmd: "--base", desc: "Override target branch (default: main)" },
+        { cmd: "--force", desc: "Ship even with pending tasks" },
+    ],
+    "session-report": [
+        { cmd: "--json", desc: "Machine-readable JSON output" },
+        { cmd: "--save", desc: "Save report to .gsd/reports/" },
+    ],
+    backlog: [
+        { cmd: "add", desc: "Add item to backlog" },
+        { cmd: "promote", desc: "Promote backlog item to active slice" },
+        { cmd: "remove", desc: "Remove backlog item" },
+    ],
+    "pr-branch": [
+        { cmd: "--dry-run", desc: "Preview what would be filtered" },
+        { cmd: "--name", desc: "Custom branch name" },
+    ],
 };
 function filterOptions(partial, options, prefix = "") {
     const normalizedPrefix = prefix ? `${prefix} ` : "";

package/dist/resources/extensions/gsd/commands/handlers/ops.js

@@ -8,6 +8,9 @@ import { handleExport } from "../../export.js";
 import { handleHistory } from "../../history.js";
 import { handleUndo } from "../../undo.js";
 import { handleRemote } from "../../../remote-questions/mod.js";
+import { handleShip } from "../../commands-ship.js";
+import { handleSessionReport } from "../../commands-session-report.js";
+import { handlePrBranch } from "../../commands-pr-branch.js";
 import { projectRoot } from "../context.js";
 export async function handleOpsCommand(trimmed, ctx, pi) {
     if (trimmed === "init") {
@@ -213,5 +216,27 @@ Examples:
         await handleCodebase(trimmed.replace(/^codebase\s*/, "").trim(), ctx, pi);
         return true;
     }
+    if (trimmed === "ship" || trimmed.startsWith("ship ")) {
+        await handleShip(trimmed.replace(/^ship\s*/, "").trim(), ctx, pi);
+        return true;
+    }
+    if (trimmed === "session-report" || trimmed.startsWith("session-report ")) {
+        await handleSessionReport(trimmed.replace(/^session-report\s*/, "").trim(), ctx);
+        return true;
+    }
+    if (trimmed === "pr-branch" || trimmed.startsWith("pr-branch ")) {
+        await handlePrBranch(trimmed.replace(/^pr-branch\s*/, "").trim(), ctx);
+        return true;
+    }
+    if (trimmed === "add-tests" || trimmed.startsWith("add-tests ")) {
+        const { handleAddTests } = await import("../../commands-add-tests.js");
+        await handleAddTests(trimmed.replace(/^add-tests\s*/, "").trim(), ctx, pi);
+        return true;
+    }
+    if (trimmed === "extract-learnings" || trimmed.startsWith("extract-learnings ")) {
+        const { handleExtractLearnings } = await import("../../commands-extract-learnings.js");
+        await handleExtractLearnings(trimmed.replace(/^extract-learnings\s*/, "").trim(), ctx, pi);
+        return true;
+    }
     return false;
 }