@gr8ful/spf 0.11.1 → 0.12.0

package/assets/defaults/spf.config.yaml

@@ -246,6 +246,7 @@ agents:
       - ls
       - bash
       - write
+      - webfetch                   # check current docs for a stack/tool the repo uses, rather than guessing from training data
 
   # No tester agent: running the suite is a known command, so it is a kind="code"
   # phase over core/quality.ts. See SKILL.md hard rule 8.
@@ -265,6 +266,7 @@ agents:
       - ls
       - bash
       - write
+      - webfetch                   # look up a possible tech stack/tool/3rd-party API's current docs before decomposing around it
 
   - name: reviewer
     model: openai/gpt-5.6-terra

package/assets/prompts/refiner/system.md

@@ -11,6 +11,7 @@ Decompose a product spec into a feature/story-or-bug tree of vertical slices the
 - You inherit the operator's shell environment — their PATH, toolchains and credentials are already live. Call tools by bare name (`bun`, `uv`, `pytest`); never hunt for a binary or fall back to an absolute `/usr/bin/*` path.
 - Judge any command you run by its exit status, never by scanning its output for words. `error` or `not found` inside passing output is text, not a failure.
 - Write your working notes to `<context_handoff_dir>/refine_plan.md` before emitting your Report JSON.
+- `webfetch` fetches a URL's current content — use it to check a specific library/API/tool's actual current docs when a slice depends on one you're not certain about, rather than decomposing around stale training-data assumptions. It fetches a page you name; it cannot search the web for one.
 
 ## Grounding: tie every slice to real code
 

package/assets/prompts/scout/system.md

@@ -12,6 +12,7 @@ Find and report where things live. Change nothing.
 - Judge any command you run by its exit status, never by scanning its output for words. `error` or `not found` inside passing output is text, not a failure.
 - Write your findings to `<context_handoff_dir>/scout_findings.md` for agents that follow.
 - If you find nothing, say so plainly — an empty finding is a valid finding.
+- `webfetch` fetches a URL's current content when the repo touches a library, API, or tool you're not certain about — use it to check, don't rely on stale training-data knowledge of a fast-moving stack. Not for general research: fetch a specific doc/reference page, not a search query.
 
 ## Subagents
 

package/assets/skill/references/config.md

@@ -564,11 +564,17 @@ session** — a joined run starts that agent fresh instead of resuming.
 | `grep` | search file contents |
 | `glob` (alias: `find`) | find files by pattern |
 | `ls` | recognized name, **no built-in on either backend** — harmless to list, never mounts |
+| `webfetch` | fetch a URL over HTTP(S), return its content as plain text — e.g. a library/API's current docs |
 
 These names are canonical across backends — a roster entry never says
 which; each backend module (`agent_flue.ts`, `agent_cc.ts`) maps them to
 its own tool vocabulary (Flue's lowercase functions, Claude Code's
-capitalized `Read`/`Bash`/...).
+capitalized `Read`/`Bash`/...). `webfetch` maps to Claude Code's own native
+`WebFetch` on that backend; Flue has no such built-in, so on `flue` it's a
+custom tool that runs `curl`/`wget` through the agent's own `Sandbox.exec()`
+— which means a remote sandbox's `egress` policy (see `sandbox` below)
+governs it exactly like any other `bash`-issued network call, with no
+separate rule to configure.
 
 **Resolution order:** an agent's own `tools` wins → else `defaults.tools` →
 else unset (all tools usable). An empty list is a tool-less agent, and it

package/dist/chains/index.js

@@ -80,7 +80,13 @@ export const CHAINS = [
         // {{previous_envelope}}. This makes `scout` a required agent for this
         // chain: a roster that pruned it fails agents.validate() by name at
         // `spf watch` startup, same as any other missing required agent.
-        steps.scout({ description: "Map the subsystems this spec touches — change nothing" }),
+        // retries: 2 (3 attempts total) — `gates.artifactsExist` failing here has
+        // historically been transient (a declared artifact briefly missing,
+        // since fixed at the source by giving `claim()` real per-issue
+        // exclusivity — see `core/watch.ts`'s `issueLockPath`), so a same-session
+        // correction retry or two is worth it before this blocks the whole spec
+        // and pages a human.
+        steps.scout({ description: "Map the subsystems this spec touches — change nothing", retries: 2 }),
         steps.refine(),
         steps.publishIssues(),
     ]),

package/dist/cli/commands/watch.js

@@ -5,7 +5,7 @@
  * actual state machine; this file is just the wiring: config, the GitHub
  * provider, the chain-dispatch callback, the lockfile, and the CLI loop.
  */
-import { existsSync, mkdirSync, readFileSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, symlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import * as v from "valibot";
@@ -23,7 +23,7 @@ import { withRunScope } from "../../core/sandbox.js";
 import { excludeSpfDataFromGit } from "../../core/worktree_data.js";
 import { ReviewOutput } from "../../core/data_types.js";
 import { SfDb } from "../../ui/server/db.js";
-import { parseCli } from "../../core/utils.js";
+import { acquirePidLock, parseCli, releasePidLock } from "../../core/utils.js";
 import { isInteractive } from "../ask.js";
 /** Kept well under Slack's own 2900-char slice on `detail` (see `slack_channel.ts`) — a reviewer can emit a lot of findings, but the PR body/notification only needs enough to tell a human whether to look closer. */
 const MAX_REVIEW_DIGEST_CHARS = 1200;
@@ -149,34 +149,14 @@ function resolveCodeHostProvider(cfg) {
     console.error(`watch.code_host ${JSON.stringify(cfg.watch.code_host)} is not supported`);
     return null;
 }
-function isPidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/** Stale-steal, like the reference implementation's daemon lock: a dead pid never blocks a restart. */
+/** Stale-steal, like the reference implementation's daemon lock: a dead pid never blocks a restart. Atomic — see `utils.acquirePidLock`. */
 function acquireLock(lockPath) {
-    if (existsSync(lockPath)) {
-        const pid = Number.parseInt(readFileSync(lockPath, "utf-8").trim(), 10);
-        if (Number.isInteger(pid) && isPidAlive(pid)) {
-            throw new Error(`another \`spf watch\` is already running (pid ${pid}) — lock at ${lockPath}`);
-        }
-    }
-    mkdirSync(path.dirname(lockPath), { recursive: true });
-    writeFileSync(lockPath, String(process.pid));
-}
-function releaseLock(lockPath) {
-    try {
-        unlinkSync(lockPath);
-    }
-    catch {
-        // already gone — fine
+    const result = acquirePidLock(lockPath);
+    if (!result.ok) {
+        throw new Error(`another \`spf watch\` is already running (pid ${result.holderPid}) — lock at ${lockPath}`);
     }
 }
+const releaseLock = releasePidLock;
 /**
  * `spf watch init` — idempotently seed the `<prefix>:*` labels the state
  * machine needs, with sensible colors/descriptions. Doesn't touch git or
@@ -743,8 +723,18 @@ export async function watchCommand(argv) {
             if (stopping)
                 break;
         }
-        while (state.inflight.size > 0) {
-            deps.log(`[spf] watch     draining ${state.inflight.size} in-flight issue(s)...`); // deps.log already routes to the dashboard when one is mounted, console.log otherwise
+        // BOTH lanes, not just `inflight` — `state.refining`'s specs are exactly
+        // as in-flight (a fire-and-forget `runSpec(...).finally(...)`, same
+        // shape as `runIssue`'s), and a graceful stop that only waits on
+        // `inflight` would print "stopping after the current tick" and then
+        // exit while a refine chain is still writing into its worktree — the
+        // next `spf watch` start-up would find `claimSpecs`'s per-issue lock
+        // still held by this (still-alive, still-running) process's own pid and
+        // correctly back off, but ONLY because that lock exists; before it did,
+        // this exact gap is what let a resumed spec race a still-running prior
+        // attempt for the same issue.
+        while (state.inflight.size > 0 || state.refining.size > 0) {
+            deps.log(`[spf] watch     draining ${state.inflight.size} in-flight issue(s), ${state.refining.size} refining spec(s)...`); // deps.log already routes to the dashboard when one is mounted, console.log otherwise
             await interruptibleSleep(1000);
             if (stopping && sigints >= 2)
                 break; // stop() itself already exits on the 2nd signal; this is belt-and-suspenders

package/dist/core/agent_cc.js

@@ -213,6 +213,15 @@ const TOOL_NAME_MAP = {
     bash: "Bash",
     grep: "Grep",
     glob: "Glob",
+    // CC's own built-in — fetches a URL and returns its content as markdown,
+    // already runs headlessly under --dangerously-skip-permissions like every
+    // other tool here. No sandbox/egress layer of SPF's own to route through:
+    // CC's own process makes the request directly, same as a bash `curl` an
+    // agent with `bash` could already issue — see agent_flue.ts's
+    // `createWebFetchTool` for the equivalent on the flue backend, where no
+    // native fetch tool exists and one has to route through the Sandbox
+    // instead.
+    webfetch: "WebFetch",
 };
 const TOOL_ALIASES = { find: "glob" };
 const DROPPED_TOOLS = new Set(["ls"]);

package/dist/core/agent_flue.d.ts

@@ -22,7 +22,8 @@
  * `run()`'s signature deliberately mirrors the old agent_pi.ts `run()` so
  * agents.ts's `send()` closure changes only its imports and field names.
  */
-import { type ConversationStreamChunk } from "@flue/runtime";
+import * as v from "valibot";
+import { type ConversationStreamChunk, type Sandbox } from "@flue/runtime";
 import type { AgentRequest, AgentResult } from "./data_types.ts";
 /**
  * Folds Flue's `tool-input` + `tool-output`/`tool-output-error` chunk pair
@@ -37,6 +38,45 @@ export declare class ToolCallTracker {
     observe(chunk: ConversationStreamChunk): Record<string, any> | null;
     private finish;
 }
+/**
+ * Strip `<script>`/`<style>` blocks and tags, decode the handful of entities
+ * a real docs page actually uses, and collapse whitespace. NOT a real
+ * HTML-to-markdown renderer — Claude Code's native `WebFetch` (the
+ * claude_code backend) does that; Flue has nothing equivalent built in, and
+ * a full renderer is more than this needs. A JSON/plain-text response
+ * passes through essentially unchanged, since none of these patterns match
+ * it — same "minimal, not a full parser" trade `jira_provider.ts`'s
+ * `adfToText` makes for ADF.
+ */
+export declare function stripHtml(text: string): string;
+/**
+ * The flue backend's stand-in for Claude Code's native `WebFetch` tool —
+ * `@flue/runtime` ships no such built-in (its only tool factories are
+ * read/write/edit/bash/grep/glob), so this is a custom `defineTool()`.
+ *
+ * Runs the actual request THROUGH `env.exec()` rather than calling Node's
+ * own `fetch()` directly — deliberately: `exec()` is the one universal
+ * primitive every `Sandbox` implements (`local`, and the remote
+ * `opensandbox`/`cloudflare` backends via `core/sandbox.ts`), so a command
+ * run through it executes INSIDE whichever sandbox the agent is actually
+ * using. A remote sandbox's own `egress` policy (`sandbox_opensandbox.ts`'s
+ * `networkPolicy`) then governs this exactly as it already governs every
+ * `bash` call — no separate egress rule needed for this tool. Calling
+ * `fetch()` here instead would silently bypass that policy by making the
+ * request from SPF's own orchestrator process rather than the sandbox.
+ *
+ * `curl`, with a `wget` fallback in the SAME command for portability across
+ * whatever base image a remote sandbox happens to ship — both are close to
+ * universal, but neither is guaranteed; a sandbox image with neither
+ * surfaces that plainly as a failed tool call (exit code + stderr handed
+ * back to the model), not a hang. Only `http`/`https` are accepted — this is
+ * also what stops a `file://` URL from turning "fetch a page" into "read an
+ * arbitrary local file" on the `local` sandbox, where `exec()` runs with the
+ * operator's own full filesystem access.
+ */
+export declare function createWebFetchTool(env: Sandbox): import("@flue/runtime").ToolDefinition<v.ObjectSchema<{
+    readonly url: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, "url is required">]>;
+}, undefined>, undefined, false, false>;
 /** Used by agents.validate() so a typo'd tool name fails before anything spawns. */
 export declare function isKnownToolName(name: string): boolean;
 /**

package/dist/core/agent_flue.js

@@ -22,7 +22,8 @@
  * `run()`'s signature deliberately mirrors the old agent_pi.ts `run()` so
  * agents.ts's `send()` closure changes only its imports and field names.
  */
-import { AgentRunError, createBashTool, createEditTool, createGlobTool, createGrepTool, createReadTool, createWriteTool, init, observe, useDataWriter, useModel, useSandbox, useTool, } from "@flue/runtime";
+import * as v from "valibot";
+import { AgentRunError, createBashTool, createEditTool, createGlobTool, createGrepTool, createReadTool, createWriteTool, defineTool, init, observe, useDataWriter, useModel, useSandbox, useTool, } from "@flue/runtime";
 import { local, sqlite, start } from "@flue/runtime/node";
 import { UsageBreakdown, makeAgentResult } from "./data_types.js";
 import { registerOllamaModel } from "./ollama_provider.js";
@@ -127,6 +128,102 @@ export class ToolCallTracker {
         return record;
     }
 }
+// ── webfetch: Flue's stand-in for Claude Code's native WebFetch ─────────────
+const WEBFETCH_MAX_BYTES = 200_000; // a bounded chunk of a page, not the whole thing — matches RESULT_SNIPPET_CHARS's spirit
+const WEBFETCH_TIMEOUT_MS = 20_000;
+const WebFetchParams = v.object({ url: v.pipe(v.string(), v.nonEmpty("url is required")) });
+/** POSIX-safe single-quoting for a shell argument: closes and reopens the quote around any embedded `'`. */
+function shQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Strip `<script>`/`<style>` blocks and tags, decode the handful of entities
+ * a real docs page actually uses, and collapse whitespace. NOT a real
+ * HTML-to-markdown renderer — Claude Code's native `WebFetch` (the
+ * claude_code backend) does that; Flue has nothing equivalent built in, and
+ * a full renderer is more than this needs. A JSON/plain-text response
+ * passes through essentially unchanged, since none of these patterns match
+ * it — same "minimal, not a full parser" trade `jira_provider.ts`'s
+ * `adfToText` makes for ADF.
+ */
+export function stripHtml(text) {
+    const cleaned = text
+        .replace(/<script[\s\S]*?<\/script>/gi, "")
+        .replace(/<style[\s\S]*?<\/style>/gi, "")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/[ \t]+/g, " ");
+    // Line-by-line trim BEFORE collapsing blank runs: a tag->" " substitution
+    // (above) routinely leaves a stray leading/trailing space on the line that
+    // used to hold a block-level tag's boundary — collapsing blank lines first
+    // would miss those, since they're not yet blank.
+    return cleaned
+        .split("\n")
+        .map((line) => line.trim())
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+/**
+ * The flue backend's stand-in for Claude Code's native `WebFetch` tool —
+ * `@flue/runtime` ships no such built-in (its only tool factories are
+ * read/write/edit/bash/grep/glob), so this is a custom `defineTool()`.
+ *
+ * Runs the actual request THROUGH `env.exec()` rather than calling Node's
+ * own `fetch()` directly — deliberately: `exec()` is the one universal
+ * primitive every `Sandbox` implements (`local`, and the remote
+ * `opensandbox`/`cloudflare` backends via `core/sandbox.ts`), so a command
+ * run through it executes INSIDE whichever sandbox the agent is actually
+ * using. A remote sandbox's own `egress` policy (`sandbox_opensandbox.ts`'s
+ * `networkPolicy`) then governs this exactly as it already governs every
+ * `bash` call — no separate egress rule needed for this tool. Calling
+ * `fetch()` here instead would silently bypass that policy by making the
+ * request from SPF's own orchestrator process rather than the sandbox.
+ *
+ * `curl`, with a `wget` fallback in the SAME command for portability across
+ * whatever base image a remote sandbox happens to ship — both are close to
+ * universal, but neither is guaranteed; a sandbox image with neither
+ * surfaces that plainly as a failed tool call (exit code + stderr handed
+ * back to the model), not a hang. Only `http`/`https` are accepted — this is
+ * also what stops a `file://` URL from turning "fetch a page" into "read an
+ * arbitrary local file" on the `local` sandbox, where `exec()` runs with the
+ * operator's own full filesystem access.
+ */
+export function createWebFetchTool(env) {
+    return defineTool({
+        name: "webfetch",
+        description: "Fetch a URL over HTTP(S) and return its content as plain text (HTML tags stripped). " +
+            "Use it to check current documentation for a library, API, or tool before relying on prior " +
+            "knowledge that may be stale or version-specific. GET only, no custom headers/auth, response " +
+            "truncated to a safe size.",
+        input: WebFetchParams,
+        run: async ({ data }) => {
+            let parsed;
+            try {
+                parsed = new URL(data.url);
+            }
+            catch {
+                return `webfetch: ${JSON.stringify(data.url)} is not a valid URL`;
+            }
+            if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+                return `webfetch: unsupported scheme ${JSON.stringify(parsed.protocol)} — only http/https are allowed`;
+            }
+            const url = shQuote(parsed.toString());
+            const command = `(curl -sS -L --max-time 20 --max-redirs 5 -A "spf-webfetch/1.0" ${url} ` +
+                `|| wget -qO- --timeout=20 ${url}) | head -c ${WEBFETCH_MAX_BYTES}`;
+            const result = await env.exec(command, { timeoutMs: WEBFETCH_TIMEOUT_MS });
+            if (result.exitCode !== 0 || !result.stdout.trim()) {
+                return `webfetch: fetching ${parsed.toString()} failed (exit ${result.exitCode}): ${(result.stderr || "no output").trim().slice(0, 2000)}`;
+            }
+            return stripHtml(result.stdout);
+        },
+    });
+}
 // ── tool-name resolution ─────────────────────────────────────────────────────
 const BUILTIN_TOOLS = {
     read: createReadTool,
@@ -135,6 +232,7 @@ const BUILTIN_TOOLS = {
     bash: createBashTool,
     grep: createGrepTool,
     glob: createGlobTool,
+    webfetch: createWebFetchTool,
 };
 // pi's vocabulary -> Flue's. "ls" has no Flue built-in (bash/glob cover it);
 // it is a KNOWN name that resolves to nothing, not an unknown one.

package/dist/core/utils.d.ts

@@ -31,6 +31,30 @@ export declare function newId(length?: number): string;
  * on the first attempt so callers see it immediately).
  */
 export declare function fetchRetryTransient(input: string, init?: RequestInit): Promise<Response>;
+/** `process.kill(pid, 0)` sends no signal — it throws iff `pid` isn't running (or isn't ours to signal), the standard Node liveness probe. */
+export declare function isPidAlive(pid: number): boolean;
+export type PidLockResult = {
+    ok: true;
+} | {
+    ok: false;
+    holderPid: number;
+};
+/**
+ * Atomic PID lockfile at `lockPath`: `{ flag: "wx" }` makes "does anyone
+ * hold this" and "claim it" ONE filesystem operation, closing the race a
+ * separate `existsSync` check followed by a later `writeFileSync` leaves
+ * open — two callers can both pass that existence check before either
+ * writes, and both walk away believing they hold the lock. A dead pid never
+ * blocks a caller: on `EEXIST`, `isPidAlive` decides whether this is a live
+ * holder (returns `ok: false`) or a stale lock from a process that never
+ * cleaned up (crash, SIGKILL, a restart that didn't wait for it to exit) —
+ * stolen via unlink-then-retry. Another caller can win that same steal
+ * race; if so, ITS write is what the retry's `wx` finds, and this caller
+ * correctly backs off against a live pid on the next pass instead of
+ * clobbering a real holder.
+ */
+export declare function acquirePidLock(lockPath: string): PidLockResult;
+export declare function releasePidLock(lockPath: string): void;
 /** Matches Python's `datetime.now(timezone.utc).isoformat(timespec="milliseconds")`. */
 export declare function nowIso(): string;
 export declare function ensureDir(dirPath: string): string;

package/dist/core/utils.js

@@ -8,7 +8,7 @@
  */
 import { randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
 /**
  * The engineer's own environment, as their shell would hand it over.
@@ -55,6 +55,61 @@ export async function fetchRetryTransient(input, init) {
         return await fetch(input, init);
     }
 }
+/** `process.kill(pid, 0)` sends no signal — it throws iff `pid` isn't running (or isn't ours to signal), the standard Node liveness probe. */
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Atomic PID lockfile at `lockPath`: `{ flag: "wx" }` makes "does anyone
+ * hold this" and "claim it" ONE filesystem operation, closing the race a
+ * separate `existsSync` check followed by a later `writeFileSync` leaves
+ * open — two callers can both pass that existence check before either
+ * writes, and both walk away believing they hold the lock. A dead pid never
+ * blocks a caller: on `EEXIST`, `isPidAlive` decides whether this is a live
+ * holder (returns `ok: false`) or a stale lock from a process that never
+ * cleaned up (crash, SIGKILL, a restart that didn't wait for it to exit) —
+ * stolen via unlink-then-retry. Another caller can win that same steal
+ * race; if so, ITS write is what the retry's `wx` finds, and this caller
+ * correctly backs off against a live pid on the next pass instead of
+ * clobbering a real holder.
+ */
+export function acquirePidLock(lockPath) {
+    mkdirSync(path.dirname(lockPath), { recursive: true });
+    for (;;) {
+        try {
+            writeFileSync(lockPath, String(process.pid), { flag: "wx" });
+            return { ok: true };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const pid = Number.parseInt(readFileSync(lockPath, "utf-8").trim(), 10);
+            if (Number.isInteger(pid) && isPidAlive(pid))
+                return { ok: false, holderPid: pid };
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                // already gone (another caller's steal beat us to it) — loop back
+                // and let the `wx` above settle who actually gets it
+            }
+        }
+    }
+}
+export function releasePidLock(lockPath) {
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // already gone — fine
+    }
+}
 /** Matches Python's `datetime.now(timezone.utc).isoformat(timespec="milliseconds")`. */
 export function nowIso() {
     const iso = new Date().toISOString(); // e.g. 2024-01-01T12:00:00.123Z

package/dist/core/watch.d.ts

@@ -222,6 +222,23 @@ export declare function createWatchState(): WatchRunState;
 export declare function branchNameFor(issue: Issue): string;
 /** Same idea as `branchNameFor`, for the refine lane's throwaway worktree — a spec never gets a PR, so this branch is only ever fetched-from-and-thrown-away, never pushed. */
 export declare function refineBranchNameFor(issue: Issue): string;
+/**
+ * A local, atomic, PID-checked lock per `adwId` (`issue-<id>`/`spec-<id>`) —
+ * sibling to `worktreesDir`, so it lives at the same per-repo root
+ * (`~/.spf/watch/<repo>/locks/`). `provider.claim()`'s own read-modify-write
+ * (see `IssueProvider.claim`'s doc comment) only verifies the END STATE
+ * looks claimed, not that no one else raced it — the real exclusivity has
+ * to live here, gating `claim()` itself, because a resumed/orphaned spec
+ * dispatches straight into the SAME deterministic worktree and
+ * `context_handoff_dir` a still-running prior attempt already owns (see
+ * `chains/steps.ts`'s `clearStaleRefineOutputFiles` doc comment). A dead
+ * holder (the daemon that owned it got killed, not stopped) never blocks a
+ * fresh claim — `acquirePidLock`'s stale-steal — but a genuinely live
+ * holder (this daemon restarted while the OLD process's chain run, spawned
+ * fire-and-forget from `claimNewWork`/`claimSpecs`, was still in flight)
+ * does, until that run's own `.finally()` releases it.
+ */
+export declare function issueLockPath(deps: WatchDeps, adwId: string): string;
 /**
  * Any issue labeled `working` that THIS process isn't tracking is an
  * orphan — a daemon restart, or another instance's claim this process

package/dist/core/watch.js

@@ -59,7 +59,7 @@ import { attemptAdwId, attemptBranch, attemptWorktreePath, runBestOf } from "./f
 import { PRIORITY_RANK } from "./data_types.js";
 import { redact } from "./otel.js";
 import { parseRefineMarker } from "./refine.js";
-import { newId } from "./utils.js";
+import { acquirePidLock, newId, releasePidLock } from "./utils.js";
 const MAX_ORPHAN_ATTEMPTS = 2;
 /** GitHub's own documented sub-issue nesting cap (see `github_provider.ts`'s `linkChild` doc comment) — `rollUp`'s own recursion bound, so a malformed/cyclic hierarchy can't spin forever. */
 const MAX_ROLLUP_DEPTH = 8;
@@ -95,6 +95,25 @@ function worktreePathFor(deps, issue) {
 function specWorktreePathFor(deps, issue) {
     return path.join(deps.worktreesDir, `spec-${issue.id}`);
 }
+/**
+ * A local, atomic, PID-checked lock per `adwId` (`issue-<id>`/`spec-<id>`) —
+ * sibling to `worktreesDir`, so it lives at the same per-repo root
+ * (`~/.spf/watch/<repo>/locks/`). `provider.claim()`'s own read-modify-write
+ * (see `IssueProvider.claim`'s doc comment) only verifies the END STATE
+ * looks claimed, not that no one else raced it — the real exclusivity has
+ * to live here, gating `claim()` itself, because a resumed/orphaned spec
+ * dispatches straight into the SAME deterministic worktree and
+ * `context_handoff_dir` a still-running prior attempt already owns (see
+ * `chains/steps.ts`'s `clearStaleRefineOutputFiles` doc comment). A dead
+ * holder (the daemon that owned it got killed, not stopped) never blocks a
+ * fresh claim — `acquirePidLock`'s stale-steal — but a genuinely live
+ * holder (this daemon restarted while the OLD process's chain run, spawned
+ * fire-and-forget from `claimNewWork`/`claimSpecs`, was still in flight)
+ * does, until that run's own `.finally()` releases it.
+ */
+export function issueLockPath(deps, adwId) {
+    return path.join(path.dirname(deps.worktreesDir), "locks", `${adwId}.lock`);
+}
 function cleanupWorktree(deps, marker) {
     if (!marker)
         return;
@@ -1182,9 +1201,21 @@ export async function claimNewWork(deps, state) {
             deps.log(`watch: [dry-run] would claim ${issue.id} (${issue.title}) and run chain "${deps.chain}"`);
             continue;
         }
+        // Gate the tracker-side claim itself behind local exclusivity — see
+        // `issueLockPath`'s doc comment. A held lock means a live process (this
+        // machine, this tick or an earlier one) already owns this issue's
+        // worktree, so skip identically to a lost tracker-side claim race
+        // rather than ever writing the tracker label.
+        const lockPath = issueLockPath(deps, `issue-${issue.id}`);
+        const lock = acquirePidLock(lockPath);
+        if (!lock.ok) {
+            deps.log(`watch: ${issue.id} is locked by another live \`spf watch\` process (pid ${lock.holderPid}) — skipping`);
+            continue;
+        }
         const claimed = await deps.provider.claim(issue);
         if (!claimed) {
             deps.log(`watch: ${issue.id} lost the claim race this tick — skipping`);
+            releasePidLock(lockPath);
             continue;
         }
         deps.log(`watch: claimed ${issue.id}: ${issue.title}`);
@@ -1200,6 +1231,7 @@ export async function claimNewWork(deps, state) {
         runIssue(deps, issue).finally(() => {
             state.inflight.delete(issue.id);
             state.inflightParents.delete(issue.id);
+            releasePidLock(lockPath);
         });
     }
 }
@@ -1238,9 +1270,20 @@ export async function claimSpecs(deps, state, from = "spec-ready") {
             deps.log(`watch: [dry-run] would claim spec ${issue.id} (${issue.title}) and run refine chain "${deps.refineChain}"`);
             continue;
         }
+        // See claimNewWork's identical guard and issueLockPath's doc comment —
+        // same local-exclusivity gate, keyed to match runSpec's own adwId
+        // (`spec-<id>`) so it covers the SAME deterministic worktree a resumed
+        // (`continue-refinement`) claim reruns into.
+        const lockPath = issueLockPath(deps, `spec-${issue.id}`);
+        const lock = acquirePidLock(lockPath);
+        if (!lock.ok) {
+            deps.log(`watch: spec ${issue.id} is locked by another live \`spf watch\` process (pid ${lock.holderPid}) — skipping`);
+            continue;
+        }
         const claimed = await deps.provider.claim(issue, { from, to: "refining" });
         if (!claimed) {
             deps.log(`watch: spec ${issue.id} lost the claim race this tick — skipping`);
+            releasePidLock(lockPath);
             continue;
         }
         deps.log(`watch: claimed spec ${issue.id}: ${issue.title}`);
@@ -1251,7 +1294,10 @@ export async function claimSpecs(deps, state, from = "spec-ready") {
             fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.refineChain]],
         });
         state.refining.add(issue.id);
-        runSpec(deps, issue).finally(() => state.refining.delete(issue.id));
+        runSpec(deps, issue).finally(() => {
+            state.refining.delete(issue.id);
+            releasePidLock(lockPath);
+        });
     }
 }
 function tickErrorHandler(deps, stage) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",