@gr8ful/spf 0.1.6 → 0.1.7

package/assets/templates/ts-cc.spf.config.yaml

@@ -41,3 +41,19 @@ quality:
 defaults:
   coding_agent: claude_code
   model: qwen3-coder:30b # swap for whatever `ollama list` shows on your machine
+
+# REQUIRED, not just an example: the packaged default roster pins
+# planner/reviewer/documenter to their own explicit Flue-style
+# provider/model-id strings, which an agent's own model always wins over
+# defaults.model above — switching coding_agent globally does NOT reset
+# those three, so they'd run on Claude Code (redirected at Ollama) with a
+# model id Ollama has never heard of, and fail outright. builder/scout
+# have no model of their own in the packaged roster, so they correctly
+# inherit defaults.model above and need no override here.
+agents:
+  - name: planner
+    model: qwen3-coder:30b
+  - name: reviewer
+    model: qwen3-coder:30b
+  - name: documenter
+    model: qwen3-coder:30b

package/assets/templates/ts-flue-openrouter.spf.config.yaml

@@ -36,3 +36,18 @@ defaults:
   # (kimi-k3, gemini-3.6, gpt-5.6, claude-sonnet-5, ...), not a live catalog
   # entry verified against a real API.
   model: openrouter/moonshotai/kimi-k2.7
+
+# Not required the way the claude_code templates' agents: override is (an
+# agent's own model always wins over defaults.model, but Flue accepts any
+# provider/model-id, so the packaged roster's planner/reviewer/documenter
+# — fireworks/openai models, unrelated to OpenRouter — would still resolve
+# and run fine, just outside OPENROUTER_API_KEY's reach). Overridden here
+# anyway so every agent actually demonstrates the OpenRouter routing this
+# template is about, not just the three without their own packaged model.
+agents:
+  - name: planner
+    model: openrouter/moonshotai/kimi-k2.7
+  - name: reviewer
+    model: openrouter/moonshotai/kimi-k2.7
+  - name: documenter
+    model: openrouter/moonshotai/kimi-k2.7

package/assets/templates/ts.spf.config.yaml

@@ -27,14 +27,29 @@ quality:
 # Optional: run agents on Claude Code instead of the default Flue backend.
 # Needs the `claude` CLI installed and authenticated (`spf doctor` checks) —
 # no separate provider API key required if you're logged in via `claude
-# login`. Remove this whole block to stay on Flue with a `provider/model-id`
-# roster instead.
+# login`. Remove this whole block (and the agents: override below) to stay
+# on Flue with a `provider/model-id` roster instead.
 defaults:
   coding_agent: claude_code
   model: sonnet # claude_code's own alias — NOT provider/model-id
 
-# Optional: retune one agent without touching the rest of the roster.
-# agents:
+# REQUIRED alongside coding_agent: claude_code above, not just an example:
+# the packaged default roster pins planner/reviewer/documenter to their own
+# explicit Flue-style provider/model-id strings, which an agent's own model
+# always wins over defaults.model — switching coding_agent globally does
+# NOT reset those three, so they'd run on Claude Code with a model id it
+# can't resolve at all ("There's an issue with the selected model...").
+# builder/scout have no model of their own in the packaged roster, so they
+# correctly inherit defaults.model above and need no override here.
+agents:
+  - name: planner
+    model: sonnet
+  - name: reviewer
+    model: sonnet
+  - name: documenter
+    model: sonnet
+
+# Optional: retune one agent further without touching the rest of the roster.
 #   - name: builder
 #     thinking: high
 #     writes: [src/, tests/]   # narrow what this agent may change in the repo

package/dist/cli/commands/init.js

@@ -44,6 +44,16 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 #     model: anthropic/claude-sonnet-4-6
 #     coding_agent: claude_code   # run this agent on Claude Code instead of Flue
 #     model: sonnet               # claude_code's own alias, NOT provider/model-id
+#
+# Switching coding_agent globally, in defaults: above, instead of per-agent?
+# The packaged default roster pins planner/reviewer/documenter to their own
+# explicit Flue-style provider/model-id strings, and an agent's own model
+# always wins over defaults.model — so those three keep running on whatever
+# backend you just switched to, with a model id it can't resolve, unless
+# you override their model here too (builder/scout have no model of their
+# own in the packaged roster, so they need no override). See
+# assets/templates/ts.spf.config.yaml (or --template ts) for the full
+# working pattern.
 
 # Uncomment to enable \`spf watch\` — polls an issue tracker labeled
 # <label_prefix>:ready and runs \`chain\` against each in its own worktree.

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, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import * as agents from "../../core/agents.js";
@@ -161,6 +161,27 @@ export async function watchCommand(argv) {
     const git = makeGit(anchor.repo_root);
     const worktreesDir = path.join(homedir(), ".spf", "watch", path.basename(anchor.repo_root), "worktrees");
     mkdirSync(worktreesDir, { recursive: true });
+    /**
+     * Without this, a claimed issue's chain resolves its session/trace data
+     * relative to `cwd` (the worktree, not the main repo — see
+     * ChainContext's doc comment), so it lands in a fresh `.spf/data` that
+     * `cleanupWorktree` deletes along with the rest of the worktree once the
+     * issue finishes: invisible in `spf ui` while running, and gone entirely
+     * afterward. Symlinking `.spf/data` in the worktree to the main repo's
+     * own `dataPaths.data_dir` makes every claimed issue show up in the same
+     * `spf ui` you already have open, and survive worktree cleanup. Multiple
+     * concurrent worktrees writing through the same symlink to one sqlite
+     * file is exactly what tracer.ts's WAL + busy_timeout=5000 already exist
+     * for. Idempotent: a no-op if the worktree already has a `.spf/data`
+     * (e.g. resuming an orphaned worktree).
+     */
+    function linkDataDir(worktreePath) {
+        const target = path.join(worktreePath, ".spf", "data");
+        if (existsSync(target))
+            return;
+        mkdirSync(path.dirname(target), { recursive: true });
+        symlinkSync(dataPaths.data_dir, target, "dir");
+    }
     const runChain = async (opts) => {
         const chainDef = findChain(cfg.watch.chain); // checked above
         const ctx = { prompt: opts.prompt, config_paths: configPaths, adw_id: opts.adwId, cwd: opts.cwd };
@@ -191,6 +212,7 @@ export async function watchCommand(argv) {
         baseBranch: cfg.watch.base_branch,
         concurrency: cfg.watch.concurrency,
         worktreesDir,
+        linkDataDir,
         dryRun: Boolean(flags["dry-run"]),
         runChain,
         log: (message) => console.log(message),

package/dist/core/issues/jira_provider.d.ts

@@ -45,6 +45,15 @@ export declare class JiraProvider implements IssueProvider {
     /** Jira labels are freeform strings, not a seedable registry — report what's used, create nothing. */
     ensureLabels(): Promise<EnsureLabelsResult>;
     private toIssue;
+    /**
+     * POST with the JQL in the JSON body, NOT a GET with `jql` as a query
+     * param: this endpoint's own real-world behavior (confirmed by multiple
+     * independent bug reports against it, not just this project's own
+     * testing) is to silently ignore query-string parameters and return an
+     * empty `issues` array with a 200 OK — no error, nothing to catch. A
+     * `spf watch` that builds this as a GET query string would run cleanly
+     * forever without ever claiming a single issue.
+     */
     private searchByLabel;
     listEligible(): Promise<Issue[]>;
     /**

package/dist/core/issues/jira_provider.js

@@ -36,6 +36,9 @@ export class JiraProvider {
         return `Basic ${Buffer.from(`${this.email}:${this.apiToken}`).toString("base64")}`;
     }
     async jira(path, init) {
+        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}`, {
             ...init,
             headers: {
@@ -51,7 +54,10 @@ export class JiraProvider {
         }
         if (response.status === 204)
             return undefined;
-        return (await response.json());
+        const text = await response.text();
+        if (debug)
+            console.error(`[jira debug] -> ${response.status} ${text.slice(0, 2000)}`);
+        return text ? JSON.parse(text) : undefined;
     }
     label(state) {
         return `${this.labelPrefix}:${state}`;
@@ -68,9 +74,21 @@ export class JiraProvider {
             labels: raw.fields.labels,
         };
     }
+    /**
+     * POST with the JQL in the JSON body, NOT a GET with `jql` as a query
+     * param: this endpoint's own real-world behavior (confirmed by multiple
+     * independent bug reports against it, not just this project's own
+     * testing) is to silently ignore query-string parameters and return an
+     * empty `issues` array with a 200 OK — no error, nothing to catch. A
+     * `spf watch` that builds this as a GET query string would run cleanly
+     * forever without ever claiming a single issue.
+     */
     async searchByLabel(label) {
         const jql = `project = ${JSON.stringify(this.projectKey)} AND labels = ${JSON.stringify(label)}`;
-        const result = await this.jira(`/rest/api/3/search/jql?jql=${encodeURIComponent(jql)}&maxResults=100&fields=summary,description,labels`);
+        const result = await this.jira("/rest/api/3/search/jql", {
+            method: "POST",
+            body: JSON.stringify({ jql, maxResults: 100, fields: ["summary", "description", "labels"] }),
+        });
         return result.issues.map((i) => this.toIssue(i));
     }
     async listEligible() {

package/dist/core/watch.d.ts

@@ -17,6 +17,18 @@ export interface WatchDeps {
     baseBranch: string;
     concurrency: number;
     worktreesDir: string;
+    /**
+     * Symlink (or otherwise wire up) `<worktreePath>/.spf/data` to the MAIN
+     * repo's own persistent data_dir, called once per worktree right after
+     * it's created. Without this, a chain run's session/trace data resolves
+     * relative to `cwd` (the worktree — see ChainContext's doc comment) and
+     * lands in a fresh, throwaway `.spf/data` that `cleanupWorktree` deletes
+     * along with the rest of the worktree once the issue finishes: no trace
+     * in `spf ui`, and no trace anywhere at all after cleanup. Injected (not
+     * called directly) so watch.ts's own tests never touch the real
+     * filesystem for it.
+     */
+    linkDataDir: (worktreePath: string) => void;
     dryRun: boolean;
     runChain: (opts: {
         prompt: string;

package/dist/core/watch.js

@@ -129,8 +129,19 @@ async function runIssue(deps, issue) {
     const worktreePath = worktreePathFor(deps, issue);
     const adwId = `issue-${issue.id}`;
     try {
+        // Both worktreePath and branch are fully deterministic from issue.id —
+        // the only way either could already exist is a previous spf watch
+        // attempt for THIS issue that never reached its own cleanup (killed
+        // mid-run, crashed, machine restart). `git worktree add -b` refuses
+        // outright if the branch already exists ("fatal: a branch named '...'
+        // already exists"), which without this would permanently block the
+        // issue from ever being claimed again — it'd fail this same way on
+        // every single retry. Safe to clear unconditionally: worktreeRemove/
+        // deleteLocalBranch are both no-ops if there's nothing to remove.
+        cleanupWorktree(deps, { worktree: worktreePath, branch });
         deps.git.fetch("origin", deps.baseBranch);
         deps.git.worktreeAdd(worktreePath, branch, `origin/${deps.baseBranch}`);
+        deps.linkDataDir(worktreePath);
         await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, attempt: 0 });
         const prompt = `${issue.title}\n\n${issue.body}`.trim();
         const result = await deps.runChain({ prompt, cwd: worktreePath, adwId });

package/dist/test/watch.test.js

@@ -1,5 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import path from "node:path";
 import { branchNameFor, claimNewWork, createWatchState, finishReviews, reconcileOrphans } from "../core/watch.js";
 /** In-memory fake — exactly the seam `provider.ts` exists for. */
 class FakeProvider {
@@ -91,6 +92,7 @@ function makeDeps(provider, codeHost, overrides = {}) {
         baseBranch: "main",
         concurrency: 2,
         worktreesDir: "/tmp/spf-watch-test-worktrees",
+        linkDataDir: () => { },
         dryRun: false,
         runChain: async () => ({ accepted: true, adwId: "issue-1", detail: "" }),
         log: () => { },
@@ -110,12 +112,45 @@ test("branchNameFor: sanitizes a title into a safe branch name", () => {
     assert.equal(branchNameFor({ id: "7", title: "", body: "", labels: [] }), "spf-watch/7-issue");
     assert.equal(branchNameFor({ id: "PROJ-123", title: "Fix the thing", body: "", labels: [] }), "spf-watch/PROJ-123-fix-the-thing");
 });
+test("claimNewWork: clears a stale worktree/branch from a killed prior attempt before creating a fresh one", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("2", "Retry me");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const calls = [];
+    // Simulates a `spf watch` process killed mid-run for this exact issue: a
+    // real `git.worktreeAdd` would refuse outright with "fatal: a branch
+    // named '...' already exists" until the leftover branch is cleared.
+    let branchExists = true;
+    const deps = makeDeps(provider, codeHost, {
+        git: fakeGit({
+            worktreeRemove: (p) => calls.push(`remove:${p}`),
+            deleteLocalBranch: (n) => {
+                calls.push(`delete-branch:${n}`);
+                branchExists = false;
+            },
+            worktreeAdd: (p, b) => {
+                if (branchExists)
+                    throw new Error(`fatal: a branch named '${b}' already exists`);
+                calls.push(`add:${p}`);
+            },
+        }),
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    const branchIdx = calls.findIndex((c) => c.startsWith("delete-branch:"));
+    const addIdx = calls.findIndex((c) => c.startsWith("add:"));
+    assert.ok(branchIdx !== -1 && addIdx !== -1 && branchIdx < addIdx, `expected the stale branch cleared before worktreeAdd, got: ${calls.join(", ")}`);
+    // The retry then succeeds normally, same as any other claim.
+    assert.deepEqual(provider.transitions.map((t) => t.to), ["review"]);
+});
 test("claimNewWork: claims a ready issue, runs the chain, opens a PR, and moves to review", async () => {
     const provider = new FakeProvider();
     provider.addIssue("1", "Add a /health endpoint");
     const codeHost = new FakeCodeHost();
     const state = createWatchState();
-    const deps = makeDeps(provider, codeHost);
+    const linkedWorktrees = [];
+    const deps = makeDeps(provider, codeHost, { linkDataDir: (worktreePath) => linkedWorktrees.push(worktreePath) });
     await claimNewWork(deps, state);
     await waitUntil(() => state.inflight.size === 0);
     assert.deepEqual(provider.claimCalls, ["1"]);
@@ -123,6 +158,11 @@ test("claimNewWork: claims a ready issue, runs the chain, opens a PR, and moves
     assert.match(codeHost.openedPrs[0].title, /^Add a \/health endpoint \(1\)/);
     assert.deepEqual(provider.transitions.map((t) => t.to), ["review"]);
     assert.equal(provider.entries.get("1").marker?.pr, 1000);
+    // linkDataDir must run before the chain does — otherwise the run's own
+    // session/trace data resolves into the worktree's throwaway .spf/data
+    // instead of the main repo's persistent one (invisible in spf ui, and
+    // deleted along with the worktree on cleanup).
+    assert.deepEqual(linkedWorktrees, [path.join(deps.worktreesDir, "issue-1")]);
 });
 test("claimNewWork: a rejected chain run blocks the issue with the failure detail", async () => {
     const provider = new FakeProvider();

package/package.json

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