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

package/README.md

@@ -28,14 +28,16 @@ See [CHANGELOG.md](./CHANGELOG.md) for release-by-release fixes and [Legacy Rele
 ## Latest Release Highlights
 
 <!-- release-highlights:start -->
-Latest release: **v1.8.1**
-
-- **doctor:** Extract state checks.
-- **doctor:** Extract history and workspace checks.
-- **issue:** Unregistered-milestone false positive: flat-phase ID extractor derives bare M### from descriptive slug, missing suffixed DB row (M###-abcdef) (#1282).
-- **issue:** [Bug] reconcile triggers mass re-projection of all historical PLAN.md files, resetting completed task checkboxes to unchecked (#1279).
-- **issue:** [Bug]: `migrateHierarchyToDb` imports a `[sketch]` slice's stub PLAN tasks as real DB rows, flipping planning→executing.
-- **issue:** [Bug]: `sketchFlagHandler` clears `is_sketch` on mere PLAN-file existence, including a stub or leftover PLAN.
+Latest release: **v1.9.0**
+
+- **gsd:** Add task rework briefs.
+- **web:** Delete unused chart.tsx and recharts.
+- **deps:** Move ajv to devDependencies.
+- **daemon:** Dedupe @anthropic-ai/sdk to ^0.91.1.
+- **deps:** Override hono to >=4.12.25.
+- **gsd:** Batch plan-v2 task queries and skip unchanged graph writes.
+- **gsd:** Open the worker DB once per parallel-monitor tick.
+- **gsd:** Batch parallel-eligibility task queries.
 
 <!-- release-highlights:end -->
 

package/dist/cli.js

@@ -10,6 +10,7 @@ import chalk from 'chalk';
 import { checkForGsdBrowserUpdates, checkForUpdates } from './update-check.js';
 import { shouldBypassManagedResourceMismatchGate } from './cli-policy.js';
 import { shouldRedirectAutoToHeadless } from './cli-auto-routing.js';
+import { resolvePrintModeExitCode } from './print-mode-exit.js';
 import { printHelp, printSubcommandHelp } from './help-text.js';
 import { applySecurityOverrides } from './security-overrides.js';
 import { validateConfiguredModel } from './startup-model-validation.js';
@@ -691,7 +692,10 @@ if (isPrintMode) {
         mode: mode,
         messages: cliFlags.messages,
     });
-    process.exit(0);
+    // Honor any exit code a slash command or extension handler set during the
+    // turn (e.g. a machine-readable verdict for headless orchestrators); default
+    // to 0 when none was set.
+    process.exit(resolvePrintModeExitCode(process.exitCode));
 }
 // ---------------------------------------------------------------------------
 // Worktree flag (-w) — create/resume a worktree for the interactive session

package/dist/headless-events.d.ts

@@ -38,7 +38,8 @@ export declare function mapStatusToExitCode(status: string): number;
  *   "Auto-mode paused..."
  *   "Step-mode paused..."
  * plus bootstrap-time manual-resolution failures that return before auto-mode
- * can emit a formal pause/stop notification.
+ * can emit a formal pause/stop notification, plus interactive menus that could
+ * not render headlessly (a dead-end that returns without dispatching). (#1294)
  *
  * Does NOT match progress notifications that happen to contain words like
  * "complete" or "stopped" (e.g., "Override resolved — rewrite-docs completed",

package/dist/headless-events.js

@@ -10,7 +10,7 @@
  * lives in the Stop Notice module — the same module the emitters format with,
  * so wording stays in lockstep with detection.
  */
-import { isBlockedNoticeMessage, isManualResolutionNotice, isPauseNotice, isTerminalNotice, } from './resources/extensions/gsd/stop-notice.js';
+import { isBlockedNoticeMessage, isInteractiveMenuUnavailableNotice, isManualResolutionNotice, isPauseNotice, isTerminalNotice, } from './resources/extensions/gsd/stop-notice.js';
 import { canonicalToolName } from './resources/extensions/gsd/engine-hook-contract.js';
 // ---------------------------------------------------------------------------
 // Exit Code Constants
@@ -63,7 +63,8 @@ export function mapStatusToExitCode(status) {
  *   "Auto-mode paused..."
  *   "Step-mode paused..."
  * plus bootstrap-time manual-resolution failures that return before auto-mode
- * can emit a formal pause/stop notification.
+ * can emit a formal pause/stop notification, plus interactive menus that could
+ * not render headlessly (a dead-end that returns without dispatching). (#1294)
  *
  * Does NOT match progress notifications that happen to contain words like
  * "complete" or "stopped" (e.g., "Override resolved — rewrite-docs completed",
@@ -107,7 +108,14 @@ export function isTerminalNotification(event) {
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
         return false;
     const message = String(event.message ?? '').toLowerCase();
-    return isTerminalNotice(message) || isPauseNotice(message) || isManualResolutionNotice(message);
+    // A menu that could not render headlessly is a terminal dead-end: the
+    // extension already returned without dispatching, so nothing else will fire.
+    // Resolve the run (as blocked, via isBlockedNotification) instead of idling
+    // forever waiting for a completion signal. (#1294)
+    return (isTerminalNotice(message) ||
+        isPauseNotice(message) ||
+        isManualResolutionNotice(message) ||
+        isInteractiveMenuUnavailableNotice(message));
 }
 export function isBlockedNotification(event) {
     if (isBlockingCommandBlock(event))

package/dist/headless-milestone-readiness.d.ts

@@ -0,0 +1,29 @@
+export interface MilestoneExecutionSnapshot {
+    milestones: Record<string, {
+        status: string;
+        sliceCount: number;
+        dependsOn: string[];
+    }>;
+}
+/**
+ * Capture the milestone execution state before a `new-milestone --auto` run.
+ * Missing DBs are treated as an empty pre-run snapshot; unreadable DBs return
+ * null so callers can conservatively skip the DB fallback.
+ */
+export declare function captureMilestoneExecutionSnapshot(basePath: string): MilestoneExecutionSnapshot | null;
+export declare function findExecutableMilestoneInDb(basePath: string, options?: {
+    changedSince?: MilestoneExecutionSnapshot;
+}): string | null;
+/**
+ * Return true when the workflow DB for `basePath` holds an executable milestone —
+ * an active (non-terminal) milestone with at least one slice — meaning auto-mode
+ * has real work to pick up.
+ * When `changedSince` is supplied, the executable milestone must also be newly
+ * created or materially changed since that snapshot.
+ *
+ * Never throws: returns false when the DB is missing or cannot be opened/queried,
+ * so the caller can fall back to the notify-text signal.
+ */
+export declare function isMilestoneExecutableInDb(basePath: string, options?: {
+    changedSince?: MilestoneExecutionSnapshot;
+}): boolean;

package/dist/headless-milestone-readiness.js

@@ -0,0 +1,161 @@
+// Project/App Name: gsd-pi + DB-authoritative milestone readiness for `--auto` chaining
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+//
+// The `new-milestone --auto` chain decision historically hinged on regex-matching
+// a specific notify string ("Milestone <id> ready."), which is only emitted on one
+// of several planning success paths. Any run that finishes planning through a
+// different branch — or takes an early-return handoff path — completes successfully
+// yet never chains into execution (issue #1295).
+//
+// This module makes the decision authoritative by querying the workflow DB directly:
+// a milestone is executable when the derived active (non-terminal) milestone has at
+// least one slice. For `new-milestone --auto`, callers can pass a pre-run snapshot
+// so the fallback only trusts readiness produced by the current planning command.
+// The notify-text signal remains a fast path; this is the deciding fallback.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { closeWorkflowDatabase, openExistingWorkflowDatabase, } from './resources/extensions/gsd/db-workspace.js';
+import { getAllMilestones, getMilestoneSlices, getSlicesByMilestoneIds, } from './resources/extensions/gsd/gsd-db.js';
+import { classifyMilestoneReadiness } from './resources/extensions/gsd/milestone-readiness.js';
+import { buildMilestoneFileName, resolveFile, resolveMilestonePath, } from './resources/extensions/gsd/paths.js';
+import { isClosedStatus } from './resources/extensions/gsd/status-guards.js';
+function milestoneArtifactExistsInResolvedDir(milestoneDir, milestoneId, suffix) {
+    if (!milestoneDir)
+        return false;
+    const flatPath = join(milestoneDir, buildMilestoneFileName(milestoneId, suffix));
+    return existsSync(flatPath) || resolveFile(milestoneDir, milestoneId, suffix) !== null;
+}
+/**
+ * Mirror `buildRegistryAndFindActive` active-milestone selection: defer queued-shell
+ * milestones (queued, no context, zero slices) so a later planned milestone is
+ * treated as active instead of an older orphan shell (#1295).
+ */
+function findDerivedActiveMilestone(basePath) {
+    const milestones = getAllMilestones();
+    const completeMilestoneIds = new Set();
+    const parkedMilestoneIds = new Set();
+    for (const m of milestones) {
+        if (m.status === 'parked') {
+            parkedMilestoneIds.add(m.id);
+            continue;
+        }
+        if (isClosedStatus(m.status)) {
+            completeMilestoneIds.add(m.id);
+        }
+    }
+    const activeMilestoneIds = milestones
+        .filter((m) => !parkedMilestoneIds.has(m.id))
+        .map((m) => m.id);
+    const slicesByMilestone = getSlicesByMilestoneIds(activeMilestoneIds);
+    let firstDeferredQueuedShell = null;
+    let activeMilestoneFound = false;
+    for (const m of milestones) {
+        if (parkedMilestoneIds.has(m.id))
+            continue;
+        if (completeMilestoneIds.has(m.id))
+            continue;
+        const slices = slicesByMilestone.get(m.id) ?? [];
+        const milestoneDir = resolveMilestonePath(basePath, m.id);
+        const hasContext = milestoneArtifactExistsInResolvedDir(milestoneDir, m.id, 'CONTEXT');
+        const hasDraftContext = !hasContext && milestoneArtifactExistsInResolvedDir(milestoneDir, m.id, 'CONTEXT-DRAFT');
+        const readiness = classifyMilestoneReadiness({
+            status: m.status,
+            hasContext,
+            hasDraftContext,
+            sliceCount: slices.length,
+        });
+        if (!activeMilestoneFound) {
+            const depsUnmet = m.depends_on.some((dep) => !completeMilestoneIds.has(dep));
+            if (depsUnmet)
+                continue;
+            if (readiness.kind === 'queued-shell') {
+                if (!firstDeferredQueuedShell)
+                    firstDeferredQueuedShell = m;
+                continue;
+            }
+            activeMilestoneFound = true;
+            return m;
+        }
+    }
+    return firstDeferredQueuedShell;
+}
+function buildMilestoneExecutionSnapshot() {
+    const milestones = getAllMilestones();
+    const slicesByMilestone = getSlicesByMilestoneIds(milestones.map((m) => m.id));
+    const snapshot = { milestones: {} };
+    for (const milestone of milestones) {
+        snapshot.milestones[milestone.id] = {
+            status: milestone.status,
+            sliceCount: (slicesByMilestone.get(milestone.id) ?? []).length,
+            dependsOn: milestone.depends_on,
+        };
+    }
+    return snapshot;
+}
+function milestoneSnapshotEntryChanged(before, after) {
+    if (!after)
+        return false;
+    if (!before)
+        return true;
+    return (before.status !== after.status ||
+        before.sliceCount !== after.sliceCount ||
+        before.dependsOn.join('\0') !== after.dependsOn.join('\0'));
+}
+/**
+ * Capture the milestone execution state before a `new-milestone --auto` run.
+ * Missing DBs are treated as an empty pre-run snapshot; unreadable DBs return
+ * null so callers can conservatively skip the DB fallback.
+ */
+export function captureMilestoneExecutionSnapshot(basePath) {
+    const opened = openExistingWorkflowDatabase(basePath);
+    if (!opened.ok) {
+        return opened.reason === 'missing-database' || opened.reason === 'missing-gsd-dir'
+            ? { milestones: {} }
+            : null;
+    }
+    try {
+        return buildMilestoneExecutionSnapshot();
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeWorkflowDatabase();
+    }
+}
+export function findExecutableMilestoneInDb(basePath, options = {}) {
+    const opened = openExistingWorkflowDatabase(basePath);
+    if (!opened.ok)
+        return null;
+    try {
+        const active = findDerivedActiveMilestone(basePath);
+        if (active == null || getMilestoneSlices(active.id).length === 0)
+            return null;
+        if (options.changedSince) {
+            const after = buildMilestoneExecutionSnapshot();
+            if (!milestoneSnapshotEntryChanged(options.changedSince.milestones[active.id], after.milestones[active.id])) {
+                return null;
+            }
+        }
+        return active.id;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeWorkflowDatabase();
+    }
+}
+/**
+ * Return true when the workflow DB for `basePath` holds an executable milestone —
+ * an active (non-terminal) milestone with at least one slice — meaning auto-mode
+ * has real work to pick up.
+ * When `changedSince` is supplied, the executable milestone must also be newly
+ * created or materially changed since that snapshot.
+ *
+ * Never throws: returns false when the DB is missing or cannot be opened/queried,
+ * so the caller can fall back to the notify-text signal.
+ */
+export function isMilestoneExecutableInDb(basePath, options = {}) {
+    return findExecutableMilestoneInDb(basePath, options) != null;
+}

package/dist/headless.js

@@ -22,13 +22,15 @@ import { isTerminalNotification, isBlockedNotification, isMilestoneReadyNotifica
 import { VALID_OUTPUT_FORMATS } from './headless-types.js';
 import { handleExtensionUIRequest, formatProgress, formatThinkingLine, formatTextStart, formatTextEnd, formatThinkingStart, formatThinkingEnd, startSupervisedStdinReader, } from './headless-ui.js';
 import { loadContext, bootstrapGsdProject, } from './headless-context.js';
+import { captureMilestoneExecutionSnapshot, isMilestoneExecutableInDb, } from './headless-milestone-readiness.js';
 const HEADLESS_CHAIN_AUTO_FLAG = '--headless-chain-auto';
 export function buildHeadlessSlashCommand(options) {
     const commandArgs = [...options.commandArgs];
     if (options.command === 'new-milestone' && options.auto && !commandArgs.includes(HEADLESS_CHAIN_AUTO_FLAG)) {
         commandArgs.push(HEADLESS_CHAIN_AUTO_FLAG);
     }
-    return `/gsd ${options.command}${commandArgs.length > 0 ? ' ' + commandArgs.join(' ') : ''}`;
+    const serializedArgs = commandArgs.map(arg => /\s/.test(arg) ? JSON.stringify(arg) : arg);
+    return `/gsd ${options.command}${serializedArgs.length > 0 ? ' ' + serializedArgs.join(' ') : ''}`;
 }
 /**
  * Commands classified as multi-turn in headless mode: they involve multiple
@@ -159,6 +161,13 @@ export function parseHeadlessArgs(argv) {
             else if (arg === '--bare') {
                 options.bare = true;
             }
+            else {
+                // Unrecognized flag: pass it through to the slash command verbatim
+                // instead of silently dropping it. This lets subcommand flags such as
+                // `verdict pass --rationale "..."` reach the assembled slash command
+                // (#1297). Known headless flags above still win regardless of position.
+                options.commandArgs.push(arg);
+            }
         }
         else if (options.command === 'auto') {
             options.command = arg;
@@ -852,6 +861,9 @@ async function runHeadlessOnce(options, restartCount) {
             }
         });
     }
+    const preRunMilestoneSnapshot = isNewMilestone && options.auto
+        ? captureMilestoneExecutionSnapshot(process.cwd())
+        : null;
     // Send the command
     const command = buildHeadlessSlashCommand(options);
     if (!options.json) {
@@ -868,8 +880,20 @@ async function runHeadlessOnce(options, restartCount) {
     if (exitCode === EXIT_SUCCESS || exitCode === EXIT_BLOCKED) {
         await completionPromise;
     }
-    // Auto-mode chaining: if --auto and milestone creation succeeded, send /gsd auto
-    if (isNewMilestone && options.auto && milestoneReady && !blocked && exitCode === EXIT_SUCCESS) {
+    // Auto-mode chaining: if --auto and milestone creation succeeded, send /gsd auto.
+    //
+    // The chain decision is DB-authoritative. `milestoneReady` (regex on a notify
+    // string) is only a fast path — it fires on just one of several planning
+    // success branches, so "planning succeeded" frequently does not imply the
+    // "ready" text was emitted. When the fast path misses, fall back to querying
+    // the milestone readiness changed by this command and chain if it is executable
+    // (issue #1295).
+    const dbMilestoneReady = preRunMilestoneSnapshot
+        ? isMilestoneExecutableInDb(process.cwd(), { changedSince: preRunMilestoneSnapshot })
+        : false;
+    const shouldChainAuto = isNewMilestone && options.auto && !blocked && exitCode === EXIT_SUCCESS &&
+        (milestoneReady || dbMilestoneReady);
+    if (shouldChainAuto) {
         if (!options.json) {
             process.stderr.write('[headless] Milestone ready — chaining into auto-mode...\n');
         }

package/dist/print-mode-exit.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve the process exit code the CLI should use after `runPrintMode`
+ * completes.
+ *
+ * Print mode previously always exited 0, discarding any `process.exitCode` a
+ * slash command or extension handler set during the turn (e.g. a machine
+ * readable verdict for a headless orchestrator). Honor a code that was set;
+ * default to 0 when none was.
+ *
+ * Regression: #1293
+ */
+export declare function resolvePrintModeExitCode(exitCode: NodeJS.Process['exitCode']): string | number;

package/dist/print-mode-exit.js

@@ -0,0 +1,14 @@
+/**
+ * Resolve the process exit code the CLI should use after `runPrintMode`
+ * completes.
+ *
+ * Print mode previously always exited 0, discarding any `process.exitCode` a
+ * slash command or extension handler set during the turn (e.g. a machine
+ * readable verdict for a headless orchestrator). Honor a code that was set;
+ * default to 0 when none was.
+ *
+ * Regression: #1293
+ */
+export function resolvePrintModeExitCode(exitCode) {
+    return exitCode ?? 0;
+}

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-f38cd5787a6340c5
+5f0f1c788a126951

package/dist/resources/GSD-WORKFLOW.md

@@ -121,7 +121,7 @@ The boundary map is a **planning artifact** — not runnable code. It:
 - Enables deterministic verification that slices actually connect
 - Gets updated during slice planning if new interfaces emerge
 
-### `S##-PLAN.md` (slice-level)
+### `<NN>-<MM>-PLAN.md` (slice-level, with embedded task planning)
 
 ```markdown
 # S01: Slice Title
@@ -136,53 +136,22 @@ The boundary map is a **planning artifact** — not runnable code. It:
 ## Tasks
 
 - [ ] **T01: Task Title**
-  Description of what this task does.
-  
+  Why this task matters, what to change, and what "done" means.
+  - Files: `src/path/to/file.ts`
+  - Verify: `npm test`
+  - Must-haves:
+    - Observable behavior that must be true when this task is done
+    - Files or wiring that must exist with real implementation
+
 - [ ] **T02: Another Task**
-  Description.
+  Why / Do / Done-when detail for the next task.
 
 ## Files Likely Touched
 - path/to/file.ts
 - path/to/another.ts
 ```
 
-### `T##-PLAN.md` (task-level)
-
-```markdown
-# T01: Task Title
-
-**Slice:** S01
-**Milestone:** M001
-
-## Goal
-What this task accomplishes in one sentence.
-
-## Must-Haves
-
-### Truths
-Observable behaviors that must be true when this task is done:
-- "User can sign up with email and password"
-- "Login returns a JWT token"
-
-### Artifacts
-Files that must exist with real implementation (not stubs):
-- `src/lib/auth.ts` — JWT helpers (min 30 lines, exports: generateToken, verifyToken)
-- `src/app/api/auth/login/route.ts` — Login endpoint (exports: POST)
-
-### Key Links
-Critical wiring between artifacts:
-- `login/route.ts` → `auth.ts` via import of `generateToken`
-- `middleware.ts` → `auth.ts` via import of `verifyToken`
-
-## Steps
-1. First thing to do
-2. Second thing to do
-3. Third thing to do
-
-## Context
-- Relevant prior decisions or patterns to follow
-- Key files to read before starting
-```
+Task plan content lives inside the slice plan. There is no standalone task-level PLAN file in the flat-phase layout; layout-aware task PLAN paths resolve to the owning `<NN>-<MM>-PLAN.md`.
 
 **Must-haves are what make verification mechanically checkable.** Truths are checked by running commands or reading output. Artifacts are checked by confirming files exist with real content. Key links are checked by confirming imports/references actually connect the pieces.
 
@@ -322,7 +291,7 @@ The **Don't Hand-Roll** and **Common Pitfalls** sections prevent the most expens
 ### Phase 3: Plan
 
 **Purpose:** Decompose work into context-window-sized tasks with must-haves.
-**Produces:** `S##-PLAN.md` + individual `T01-PLAN.md` files.
+**Produces:** `<NN>-<MM>-PLAN.md` with task planning embedded in the slice plan.
 
 **For a milestone (roadmap):**
 1. Read `CONTEXT.md`, `M###-RESEARCH.md`, and `.gsd/DECISIONS.md` if they exist.
@@ -339,7 +308,7 @@ The **Don't Hand-Roll** and **Common Pitfalls** sections prevent the most expens
 5. Decompose into 1-7 tasks, each fitting one context window.
 6. Each task needs: title, description, steps (3-10), must-haves (observable verification criteria).
 7. Must-haves should reference boundary map contracts — e.g. "exports `generateToken()` as specified in boundary map S01→S02".
-8. Write `S##-PLAN.md` and individual `T##-PLAN.md` files.
+8. Write `<NN>-<MM>-PLAN.md` with the slice contract and embedded task planning. Do not write standalone task plan files.
 
 ### Phase 4: Execute
 
@@ -347,7 +316,7 @@ The **Don't Hand-Roll** and **Common Pitfalls** sections prevent the most expens
 **Produces:** Code changes + `[DONE:n]` markers.
 
 **How to do it manually:**
-1. Read the task's `T##-PLAN.md`.
+1. Read the active slice's `<NN>-<MM>-PLAN.md` and use the selected task entry as the task plan.
 2. Read relevant summaries from prior tasks (for context on what's already built).
 3. Execute each step. Mark progress with `[DONE:n]` in responses.
 4. If you made an architectural, pattern, or library decision, append it to `.gsd/DECISIONS.md`.
@@ -398,7 +367,7 @@ When verification finds gaps, include a **Gaps** section with what's missing, im
 ### Phase 6: Summarize
 
 **Purpose:** Record what happened for downstream tasks.
-**Produces:** `T##-SUMMARY.md`, and when slice completes, `S##-SUMMARY.md`.
+**Produces:** `S##-T##-SUMMARY.md` in flat-phase projects, and when slice completes, `S##-SUMMARY.md`. Legacy flat `T##-SUMMARY.md` task summaries are still readable.
 
 **Task summary format:**
 ```markdown
@@ -459,7 +428,7 @@ key_decisions: []
 **Purpose:** Mark work done and move to the next thing.
 
 **After a task completes:**
-1. Mark the task done in `S##-PLAN.md` (checkbox).
+1. Mark the task done in `<NN>-<MM>-PLAN.md` (checkbox).
 2. Check if there's a next task in the slice → execute it.
 3. If slice is complete → write slice summary, mark slice done in `ROADMAP.md`.
 
@@ -524,8 +493,8 @@ It is NOT the source of truth. It's a convenience dashboard.
 
 **Sources of truth:**
 - `ROADMAP.md` → which slices exist and which are done
-- `S##-PLAN.md` → which tasks exist within a slice
-- `T##-SUMMARY.md` → what happened during a task
+- `<NN>-<MM>-PLAN.md` → which tasks exist within a slice and what each task must do
+- `S##-T##-SUMMARY.md` → what happened during a task in flat-phase projects (legacy `T##-SUMMARY.md` is still readable)
 - `S##-SUMMARY.md` and `M###-SUMMARY.md` → compressed slice and milestone outcomes
 
 **Update `STATE.md`** after every significant action:
@@ -642,7 +611,7 @@ This methodology doc is generic. Project-specific guidance belongs in the milest
 1. Read `.gsd/STATE.md` — what's the next action?
 2. Check for `continue.md` in the active slice — is there interrupted work?
 3. If resuming: read `continue.md`, delete it, pick up from "Next Action".
-4. If starting fresh: read the active slice's `S##-PLAN.md`, find the next incomplete task.
+4. If starting fresh: read the active slice's `<NN>-<MM>-PLAN.md`, find the next incomplete task.
 5. If in a planning or research phase, read `.gsd/DECISIONS.md` — respect existing decisions.
 6. Read relevant summaries from prior tasks/slices for context.
 7. Do the work.

package/dist/resources/extensions/browser-tools/capture.js

@@ -4,55 +4,12 @@
  * Functions for capturing compact page state, screenshots, and summaries.
  * Used by tool implementations for post-action feedback.
  */
-// sharp is an optional native dependency. Load it lazily so that the extension
-// can still be loaded on platforms where sharp is unavailable (e.g. bunx on
-// Raspberry Pi). constrainScreenshot falls back to returning the raw buffer
-// when sharp is not installed, which means screenshots won't be resized but
-// the tool remains functional.
-let _sharp;
-async function getSharp() {
-    if (_sharp !== undefined)
-        return _sharp;
-    try {
-        _sharp = (await import("sharp")).default;
-    }
-    catch {
-        _sharp = null;
-    }
-    return _sharp;
-}
-/**
- * Test-only seam: override the cached sharp module. Pass `null` to simulate
- * an environment where the sharp native dep is unavailable; pass `undefined`
- * to clear the cache and let the next getSharp() call re-import. See
- * tests/capture-sharp-optional.test.cjs.
- */
-export function __setSharpForTesting(value) {
-    _sharp = value;
-}
+import { constrainScreenshot } from "./screenshot-constraints.js";
+export { constrainScreenshot, __setSharpForTesting } from "./screenshot-constraints.js";
 import { formatCompactStateSummary } from "./utils.js";
-// Anthropic vision: 1568px is the recommended optimal width. Height is capped
-// generously at 8000px so tall full-page screenshots remain readable rather
-// than being squished into a square constraint.
-//
 // Override via environment variables:
-//   SCREENSHOT_MAX_WIDTH=0   → uncap width (use raw resolution)
-//   SCREENSHOT_MAX_HEIGHT=0  → uncap height
 //   SCREENSHOT_FORMAT=png    → lossless PNG for all viewport/fullpage screenshots
 //   SCREENSHOT_QUALITY=100   → max JPEG quality (1-100, default 80)
-const MAX_SCREENSHOT_WIDTH = parseScreenshotDimension(process.env.SCREENSHOT_MAX_WIDTH, 1568);
-const MAX_SCREENSHOT_HEIGHT = parseScreenshotDimension(process.env.SCREENSHOT_MAX_HEIGHT, 8000);
-/** Parse a dimension env var: positive int = that value, 0 = Infinity (uncapped), absent/invalid = default. */
-function parseScreenshotDimension(value, fallback) {
-    if (value === undefined || value === "")
-        return fallback;
-    const n = parseInt(value, 10);
-    if (isNaN(n) || n < 0)
-        return fallback;
-    if (n === 0)
-        return Infinity;
-    return n;
-}
 /** Return the user-configured screenshot format override, or null for default behavior. */
 export function getScreenshotFormatOverride() {
     const fmt = process.env.SCREENSHOT_FORMAT?.toLowerCase();
@@ -160,38 +117,6 @@ export async function postActionSummary(p, target) {
         return "[summary unavailable]";
     }
 }
-// ---------------------------------------------------------------------------
-// Screenshot helpers
-// ---------------------------------------------------------------------------
-/**
- * Constrain screenshot dimensions for the Anthropic vision API.
- * Width is capped at 1568px (optimal) and height at 8000px, each
- * independently, using `fit: "inside"` so aspect ratio is preserved.
- * Small images are never upscaled.
- *
- * `page` parameter is retained for ToolDeps signature stability (D008)
- * but is no longer used — all processing is server-side via sharp.
- */
-export async function constrainScreenshot(_page, buffer, mimeType, quality) {
-    const sharp = await getSharp();
-    if (!sharp)
-        return buffer;
-    const meta = await sharp(buffer).metadata();
-    const width = meta.width;
-    const height = meta.height;
-    if (width === undefined || height === undefined)
-        return buffer;
-    if (width <= MAX_SCREENSHOT_WIDTH && height <= MAX_SCREENSHOT_HEIGHT)
-        return buffer;
-    const resizer = sharp(buffer).resize(MAX_SCREENSHOT_WIDTH, MAX_SCREENSHOT_HEIGHT, {
-        fit: "inside",
-        withoutEnlargement: true,
-    });
-    if (mimeType === "image/png") {
-        return Buffer.from(await resizer.png().toBuffer());
-    }
-    return Buffer.from(await resizer.jpeg({ quality }).toBuffer());
-}
 /** Capture a JPEG screenshot for error debugging. Returns base64 or null. */
 export async function captureErrorScreenshot(p) {
     if (!p)