@gr8ful/spf 0.11.0 → 0.11.2

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/issues/bitbucket_provider.d.ts

@@ -1,21 +1,3 @@
-/**
- * Bitbucket Cloud REST API v2.0 implementation of `CodeHostProvider` —
- * `spf watch`'s PR seam, not its tracker seam (see `provider.ts`'s module
- * comment): this class never touches issues/labels, so it's paired with an
- * `IssueProvider` (`github_provider.ts` or `jira_provider.ts`) at the CLI
- * layer.
- *
- * Auth is HTTP Basic with an Atlassian account email + API token
- * (`BITBUCKET_EMAIL` / `BITBUCKET_API_TOKEN`) — verified directly against
- * Atlassian's current docs before writing this, not assumed from training
- * data: Bitbucket Cloud app passwords are being fully removed (brownout
- * window closes July 28, 2026), so this project only supports the
- * replacement — API tokens, same auth shape as `jira_provider.ts`.
- *
- * `repo` is `"workspace/repo_slug"` (Bitbucket's own two-part identifier),
- * the same config field GitHub uses for `"owner/name"` — the shape just
- * means something different per `code_host`.
- */
 import type { CodeHostProvider, PrRef, PrStatus } from "./provider.ts";
 export declare class BitbucketProvider implements CodeHostProvider {
     private readonly email;

package/dist/core/issues/bitbucket_provider.js

@@ -1,3 +1,22 @@
+/**
+ * Bitbucket Cloud REST API v2.0 implementation of `CodeHostProvider` —
+ * `spf watch`'s PR seam, not its tracker seam (see `provider.ts`'s module
+ * comment): this class never touches issues/labels, so it's paired with an
+ * `IssueProvider` (`github_provider.ts` or `jira_provider.ts`) at the CLI
+ * layer.
+ *
+ * Auth is HTTP Basic with an Atlassian account email + API token
+ * (`BITBUCKET_EMAIL` / `BITBUCKET_API_TOKEN`) — verified directly against
+ * Atlassian's current docs before writing this, not assumed from training
+ * data: Bitbucket Cloud app passwords are being fully removed (brownout
+ * window closes July 28, 2026), so this project only supports the
+ * replacement — API tokens, same auth shape as `jira_provider.ts`.
+ *
+ * `repo` is `"workspace/repo_slug"` (Bitbucket's own two-part identifier),
+ * the same config field GitHub uses for `"owner/name"` — the shape just
+ * means something different per `code_host`.
+ */
+import { fetchRetryTransient } from "../utils.js";
 const API = "https://api.bitbucket.org/2.0";
 export class BitbucketProvider {
     email;
@@ -15,7 +34,7 @@ export class BitbucketProvider {
         this.repoSlug = repoSlug;
     }
     async bb(path, init) {
-        const response = await fetch(`${API}${path}`, {
+        const response = await fetchRetryTransient(`${API}${path}`, {
             ...init,
             headers: {
                 Authorization: `Basic ${Buffer.from(`${this.email}:${this.apiToken}`).toString("base64")}`,

package/dist/core/issues/jira_provider.js

@@ -1,3 +1,4 @@
+import { fetchRetryTransient } from "../utils.js";
 const STATES = [
     "ready",
     "working",
@@ -65,7 +66,7 @@ export class JiraProvider {
         const debug = Boolean(process.env["SPF_JIRA_DEBUG"]);
         if (debug)
             console.error(`[jira debug] ${init?.method ?? "GET"} ${this.baseUrl}${path} body=${init?.body ?? "(none)"}`);
-        const response = await fetch(`${this.baseUrl}${path}`, {
+        const response = await fetchRetryTransient(`${this.baseUrl}${path}`, {
             ...init,
             headers: {
                 Authorization: this.authHeader(),
@@ -139,7 +140,7 @@ export class JiraProvider {
      * never discovers it from the issue body itself.
      */
     async getIssue(id) {
-        const response = await fetch(`${this.baseUrl}/rest/api/3/issue/${id}?fields=summary,description,labels`, {
+        const response = await fetchRetryTransient(`${this.baseUrl}/rest/api/3/issue/${id}?fields=summary,description,labels`, {
             headers: { Authorization: this.authHeader(), Accept: "application/json" },
         });
         if (response.status === 404)

package/dist/core/utils.d.ts

@@ -19,6 +19,42 @@ import path from "node:path";
  */
 export declare function operatorEnv(): Record<string, string>;
 export declare function newId(length?: number): string;
+/**
+ * `fetch`, but a transport-level blip on the FIRST attempt gets one silent
+ * retry before it's allowed to throw. Node's global `fetch` (undici) pools
+ * keep-alive connections across calls; Atlassian's Cloud APIs (Jira,
+ * Bitbucket) close idle ones from their end, which surfaces here as
+ * `ECONNRESET` the next time a long-lived poller (`spf watch`) reuses one —
+ * a stale-socket race, not a real problem with the request. Only retries
+ * error codes that mean "the transport failed," never an HTTP error status
+ * (a 4xx/5xx response is not a thrown error here, and must keep surfacing
+ * 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.
@@ -31,6 +31,85 @@ export function operatorEnv() {
 export function newId(length = 8) {
     return randomBytes(Math.floor(length / 2)).toString("hex");
 }
+/** Transport-level blips worth one silent retry — see `fetchRetryTransient` below. */
+const TRANSIENT_FETCH_CODES = new Set(["ECONNRESET", "ETIMEDOUT", "EPIPE", "ECONNREFUSED", "EAI_AGAIN"]);
+/**
+ * `fetch`, but a transport-level blip on the FIRST attempt gets one silent
+ * retry before it's allowed to throw. Node's global `fetch` (undici) pools
+ * keep-alive connections across calls; Atlassian's Cloud APIs (Jira,
+ * Bitbucket) close idle ones from their end, which surfaces here as
+ * `ECONNRESET` the next time a long-lived poller (`spf watch`) reuses one —
+ * a stale-socket race, not a real problem with the request. Only retries
+ * error codes that mean "the transport failed," never an HTTP error status
+ * (a 4xx/5xx response is not a thrown error here, and must keep surfacing
+ * on the first attempt so callers see it immediately).
+ */
+export async function fetchRetryTransient(input, init) {
+    try {
+        return await fetch(input, init);
+    }
+    catch (error) {
+        const code = error.cause?.code;
+        if (!code || !TRANSIENT_FETCH_CODES.has(code))
+            throw error;
+        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.0",
+  "version": "0.11.2",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",