@brainervirus/workit-core 8.35.2 → 8.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.35.2",
+  "version": "8.37.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/skills/workit-implement/SKILL.md

@@ -23,7 +23,7 @@ description: Build a requested change in small verified steps - follow local pat
    (`workit check test`, plus `lint` and `typecheck` when the repo has them),
    not after every edit. Heavy work runs under one machine-wide lease: an ad-hoc
    suite is `workit check --heavy -- <cmd>`, never a hand-made flock; a busy
-   lease waits and names its holder (`workit lock status`).
+   lease waits and names its holder (`workit lock status`). A tool warning is a finding: fix it in this PR in the right layer, or record the false positive with evidence; pre-existing ones get their own PR.
 5. Prove the feature on its real surface with the project's `verify-<app>`
    skill; none yet? Write one (workit-verify-app). Tests show branch behavior,
    not that the feature works. The report carries what you observed: a UI

package/skills/workit-ship/SKILL.md

@@ -49,7 +49,7 @@ the same check. Fix round and recheck both failed: a decider (workit-fanout).
 5. **CI.** Local gates mirror CI: push and continue; `workit ci wait` once on
    the final head, in the background where the host allows. Red: read `logTail`, classify. Flake or infra: one
    `workit ci rerun --failed --reason flake|infra` per head. Real: reproduce
-   with `workit check`, fix the root cause, batch every fix in one push.
+   with `workit check`, fix the root cause, batch every fix in one push. A tool warning is a finding: fix it in this PR in the right layer, or record the false positive with evidence; pre-existing ones get their own PR.
 6. **Verified.** The lane in `workit pr status` decides: none, no verdict; self, your `--self` verdict; focused or full (or `verification: self|independent`), one non-author verifier per PR after the last push, never per push (workit-review), on Claude Code with the `model` and `effort` of `workit models show --role verifier`. A docs-only push (or test-only under a unit verdict) keeps the verdict (`carried`); `reverify: focused` re-checks only the new diff, reusing green CI; one verdict at a stack's top covers its unchanged lower PRs. Land only when
    granted: `workit stack land` or `workit pr merge`; `--unverified --reason` if user-asked.
 7. **Observe it landed:** `workit verify-delivery pr` or `merge`. After a failed

package/src/fanout-brief.ts

@@ -64,6 +64,15 @@ export type BriefOutcome = {
 
 export const DEFAULT_TIMEBOX = "30 minutes";
 
+/** The TIMEBOX line's tool-call budget when the slice names none (hooks/budget-signal.ts). */
+export const DEFAULT_TOOL_CALLS = 120;
+
+/** The slice's TIMEBOX text plus a tool-call budget unless it already names one. */
+const timeboxText = (timebox: string | null): string => {
+  const text = timebox ?? DEFAULT_TIMEBOX;
+  return /\b\d+\s+tool calls\b/u.test(text) ? text : `${text}, ${DEFAULT_TOOL_CALLS} tool calls`;
+};
+
 const REPORT = [
   "REPORT: branch, head SHA, files changed, each VERIFY command with its exit code,",
   "  each ACCEPTANCE line met / not met, rulings you made (`workit ledger ruling`),",
@@ -151,7 +160,12 @@ function workerSession(lead: string, slice: string, attempt: number | null): str
 export function renderBrief(
   cwd: string,
   plan: FanoutFile,
-  input: { slice: string; mode: BriefMode | null; attempt: number | null; actor: LedgerActor },
+  input: {
+    slice: string;
+    mode: BriefMode | null;
+    attempt: number | null;
+    actor: LedgerActor;
+  },
 ): FanoutResult<BriefOutcome> {
   const found = findSlice(plan, input.slice);
   if (!found.ok) return found;
@@ -250,7 +264,7 @@ export function renderBrief(
           `  verifier: model ${verifier.model}${verifier.effort ? `  effort ${verifier.effort}` : ""}  (${verifier.source})`,
         ]
       : []),
-    `TIMEBOX: ${slice.timebox ?? DEFAULT_TIMEBOX}; past it without a new commit you will be replaced`,
+    `TIMEBOX: ${timeboxText(slice.timebox)}; past it without a new commit you will be replaced`,
     scratchLine,
     `FORBIDDEN: ${slice.forbidden.join("; ")}`,
     ...fanIn,

package/src/fanout-status.ts

@@ -92,10 +92,15 @@ export type StatusOptions = {
   host?: string | null;
 };
 
-/** A TIMEBOX such as `45 minutes`, `2h` or `1h30m`, in ms; null without a unit or otherwise. */
+/**
+ * A TIMEBOX such as `45 minutes`, `2h` or `1h30m`, in ms; null without a unit
+ * or otherwise. A tool-call budget beside it (`45 minutes, 80 tool calls`) is
+ * not time: only the rest is parsed, so `80 tool calls` alone is null.
+ */
 export function timeboxMs(text: string | null): number | null {
-  if (!text || /^\s*\d+(?:\.\d+)?\s*$/u.test(text)) return null;
-  const ms = parseDuration(text);
+  const time = text?.replace(/[\s,;]*\b\d+\s+tool calls\b[\s,;]*/gu, " ").trim();
+  if (!time || /^\d+(?:\.\d+)?$/u.test(time)) return null;
+  const ms = parseDuration(time);
   return ms && ms > 0 ? ms : null;
 }
 

package/src/hooks/budget-signal.ts

@@ -0,0 +1,284 @@
+// The worker tool-call budget (retro P9, ruling mvrhg6lc). A brief's TIMEBOX
+// names `N tool calls`; the spawn that carries it records N for the next
+// subagent of that type (`<store>/budget/spawns-<lead>.jsonl`), SubagentStart
+// binds it to the agent (`<store>/budget/<agent>.json`: limit and the last
+// multiple told), and every pre-tool hook of that agent appends one byte to
+// `<store>/budget/<agent>.calls`. At N calls (and 2N, 3N…) one line rides the
+// standing-order channel; the call is never denied. An agent without a
+// budget file is never counted.
+// fs, path and crypto only: the Codex launcher imports this before the
+// runtime, and the Claude Code launcher (bin/workit-hook.mjs) keeps a copy of
+// spawnBudget, noteSpawnBudget and tickBudget that
+// test/workit-core/hooks/budget-signal.test.ts holds equal.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { gitStoreDir } from "./standing-signal";
+import type { HookInput } from "./protocol";
+
+const hash = (text: string): string => createHash("sha256").update(text).digest("hex").slice(0, 32);
+
+const budgetDir = (store: string): string => path.join(store, "budget");
+
+/** The same key as the standing seen file: one per host session or subagent. */
+const agentBase = (store: string, session: string, agentId: string | null): string =>
+  path.join(budgetDir(store), hash(`${session}\0${agentId ?? ""}`));
+
+const spawnsFile = (store: string, session: string): string =>
+  path.join(budgetDir(store), `spawns-${hash(session)}.jsonl`);
+
+/** `N tool calls` on a brief's TIMEBOX line, else null. */
+export const spawnBudget = (prompt: string): number | null => {
+  const found = /^TIMEBOX:[^\n]*?\b(\d+)\s+tool calls\b/mu.exec(prompt);
+  const n = found ? Number(found[1]) : NaN;
+  return Number.isInteger(n) && n > 0 ? n : null;
+};
+
+/**
+ * A lead's spawn that will run: queue its budget, or an explicit none, for
+ * the next subagent of `type`. Every spawn of a type queues one entry, so the
+ * FIFO stays aligned with the SubagentStart order. Call it only once the
+ * spawn is allowed: a denied spawn must leave no entry.
+ */
+export const noteSpawnBudget = (
+  cwd: string,
+  session: string,
+  type: string | null,
+  prompt: string,
+): void => {
+  try {
+    const store = session ? gitStoreDir(cwd) : null;
+    if (!store) return;
+    fs.mkdirSync(budgetDir(store), { recursive: true });
+    fs.appendFileSync(
+      spawnsFile(store, session),
+      `${JSON.stringify({ type: type ?? "", n: spawnBudget(prompt) })}\n`,
+    );
+  } catch {
+    // Without the note the worker runs unbudgeted.
+  }
+};
+
+type Budget = { limit: number; told: number };
+
+/** Small files written whole; a torn read fails open as "no budget". */
+const readBudget = (file: string): Budget | null => {
+  try {
+    const { limit, told } = JSON.parse(fs.readFileSync(file, "utf8")) as Partial<Budget>;
+    return typeof limit === "number" && limit > 0 ? { limit, told: Number(told) || 0 } : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * SubagentStart: take the head entry queued for this agent's type and bind
+ * its budget to the agent. Returns the limit, or null when the entry says
+ * none or nothing was queued.
+ */
+export const claimSpawnBudget = (
+  cwd: string,
+  session: string,
+  agentId: string,
+  agentType: string | null,
+): number | null => {
+  try {
+    const store = session ? gitStoreDir(cwd) : null;
+    if (!store) return null;
+    const file = spawnsFile(store, session);
+    const entries = fs
+      .readFileSync(file, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => JSON.parse(line) as { type?: unknown; n?: unknown });
+    const at = entries.findIndex((entry) => entry.type === (agentType ?? ""));
+    if (at < 0) return null;
+    const [{ n }] = entries.splice(at, 1);
+    fs.writeFileSync(file, entries.map((entry) => `${JSON.stringify(entry)}\n`).join(""));
+    if (typeof n !== "number" || n <= 0) return null;
+    startBudget(store, session, agentId, n);
+    return n;
+  } catch {
+    return null;
+  }
+};
+
+/** Starts a budget; first ages out files of agents that never stopped, older than 7 days. */
+const startBudget = (store: string, session: string, agentId: string | null, n: number): void => {
+  const dir = budgetDir(store);
+  fs.mkdirSync(dir, { recursive: true });
+  const cutoff = Date.now() - 6048e5;
+  for (const name of fs.readdirSync(dir))
+    try {
+      if (fs.statSync(path.join(dir, name)).mtimeMs < cutoff) fs.rmSync(path.join(dir, name));
+    } catch {
+      // Another hook removed it first.
+    }
+  const base = agentBase(store, session, agentId);
+  fs.writeFileSync(`${base}.json`, JSON.stringify({ limit: n, told: 0 }));
+  fs.rmSync(`${base}.calls`, { force: true });
+};
+
+/**
+ * A host that launches the worker itself (Pi) binds the budget its prompt
+ * names straight to the worker's session. Returns the limit, else null.
+ */
+export const bindBudget = (
+  cwd: string,
+  session: string,
+  agentId: string | null,
+  prompt: string,
+): number | null => {
+  try {
+    const n = spawnBudget(prompt);
+    const store = n && session ? gitStoreDir(cwd) : null;
+    if (!n || !store) return null;
+    startBudget(store, session, agentId, n);
+    return n;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Count one tool call of a budgeted agent. True when the count reached the
+ * next untold multiple of the budget, so the runtime must load to tell it.
+ */
+export const tickBudget = (cwd: string, session: string, agentId: string | null): boolean => {
+  try {
+    const store = session ? gitStoreDir(cwd) : null;
+    if (!store) return false;
+    const base = agentBase(store, session, agentId);
+    const budget = readBudget(`${base}.json`);
+    if (!budget) return false;
+    fs.appendFileSync(`${base}.calls`, ".");
+    return fs.statSync(`${base}.calls`).size >= budget.limit * (budget.told + 1);
+  } catch {
+    return false;
+  }
+};
+
+const lineFor = (calls: number): string =>
+  `Tool-call budget reached (${calls}): commit your work, write your report, stop.`;
+
+/** The agent's base path, its budget, and how many multiples of it its calls reached. */
+const reachedOf = (cwd: string, session: string, agentId: string | null) => {
+  const store = session ? gitStoreDir(cwd) : null;
+  const base = store && agentBase(store, session, agentId);
+  const budget = base && readBudget(`${base}.json`);
+  if (!budget) return null;
+  return { base, budget, reached: Math.floor(fs.statSync(`${base}.calls`).size / budget.limit) };
+};
+
+/** SubagentStop: the agent's budget and counter go. */
+export const dropBudget = (cwd: string, session: string, agentId: string | null): void => {
+  const store = session ? gitStoreDir(cwd) : null;
+  if (store)
+    for (const ext of [".json", ".calls"])
+      fs.rmSync(agentBase(store, session, agentId) + ext, { force: true });
+};
+
+/** The one line for a budget reached and not yet told (marked told), else null. */
+export const budgetLine = (cwd: string, session: string, agentId: string | null): string | null => {
+  try {
+    const at = reachedOf(cwd, session, agentId);
+    if (!at || at.reached <= at.budget.told) return null;
+    fs.writeFileSync(`${at.base}.json`, JSON.stringify({ ...at.budget, told: at.reached }));
+    return lineFor(at.budget.limit * at.reached);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * For a host that rebuilds its context on every model call (OpenCode): the
+ * line while the budget stands reached, else null. Never marks it told.
+ */
+export const budgetStanding = (
+  cwd: string,
+  session: string,
+  agentId: string | null,
+): string | null => {
+  try {
+    const at = reachedOf(cwd, session, agentId);
+    return at && at.reached > 0 ? lineFor(at.budget.limit * at.reached) : null;
+  } catch {
+    return null;
+  }
+};
+
+/** Codex tools Workit may deny; any other PreToolUse is never denied there. */
+const CODEX_GATED = new Set(["bash", "unifiedexec", "shell", "applypatch", "edit", "write"]);
+
+/**
+ * One native Codex PreToolUse payload: a lead's spawn (a tool input naming an
+ * agent type, or carrying a brief) queues its budget or an explicit none, and
+ * a budgeted subagent's call is counted. A spawn is a tool Workit never denies
+ * on Codex, so queueing here cannot outlive a denied call. True when the
+ * count reached the budget, so the runtime tells it.
+ */
+export const observeHookBudget = (payload: string): boolean => {
+  try {
+    const value = JSON.parse(payload) as Record<string, unknown>;
+    if (value.hook_event_name !== "PreToolUse" || typeof value.session_id !== "string")
+      return false;
+    const cwd = typeof value.cwd === "string" ? value.cwd : ".";
+    const agentId =
+      typeof value.agent_id === "string" && value.agent_id.trim() ? value.agent_id : null;
+    if (agentId) return tickBudget(cwd, value.session_id, agentId);
+    const tool = typeof value.tool_name === "string" ? value.tool_name : "";
+    const spawn = value.tool_input;
+    if (
+      CODEX_GATED.has(tool.toLowerCase().replace(/[_-]/g, "")) ||
+      !spawn ||
+      typeof spawn !== "object"
+    )
+      return false;
+    const fields = spawn as Record<string, unknown>;
+    const prompt = Object.values(fields).find(
+      (field): field is string => typeof field === "string" && field.includes("TIMEBOX:"),
+    );
+    const type = [fields.agent_type, fields.subagent_type].find(
+      (field): field is string => typeof field === "string",
+    );
+    if (prompt !== undefined || type !== undefined)
+      noteSpawnBudget(cwd, value.session_id, type ?? null, prompt ?? "");
+    return false;
+  } catch {
+    return false;
+  }
+};
+
+/** What handleHook does with a budget, for the hosts whose entry passes it (HookDeps.budget). */
+export type BudgetHooks = {
+  /** A pre-tool answer that lets the call run: the line once reached. */
+  line: (input: HookInput) => string | null;
+  /** SubagentStart: bind the queued budget. */
+  start: (input: HookInput, agentId: string, agentType: string) => void;
+  /** A lead's spawn the gate let through (Claude Code: untyped is general-purpose). */
+  spawn: (input: HookInput, spawn: Record<string, unknown>) => void;
+  /** SubagentStop: drop the agent's files. */
+  stop: (input: HookInput, agentId: string) => void;
+};
+
+export const budgetHooks: BudgetHooks = {
+  line: (input) => budgetLine(input.cwd, input.session.id ?? "", input.session.agentId),
+  start: (input, agentId, agentType) =>
+    void claimSpawnBudget(input.cwd, input.session.id ?? "", agentId, agentType),
+  spawn: (input, spawn) => {
+    if (!input.session.agentId)
+      noteSpawnBudget(
+        input.cwd,
+        input.session.id ?? "",
+        String(spawn.subagent_type || "general-purpose"),
+        String(spawn.prompt ?? ""),
+      );
+  },
+  stop: (input, agentId) => {
+    try {
+      dropBudget(input.cwd, input.session.id ?? "", agentId);
+    } catch {
+      // Aged out by the next startBudget.
+    }
+  },
+};

package/src/hooks/handle.ts

@@ -30,6 +30,7 @@ import {
 } from "./skill-nudge";
 import { spawnDecision } from "./spawn-gate";
 import { seedStanding, standingDelta } from "./standing";
+import type { BudgetHooks } from "./budget-signal";
 import { modelSwitchedOnDisk, trackJudge } from "./session-marker";
 import { invariantBootstrap } from "../core/methods";
 import { stopDecision } from "./stop";
@@ -39,7 +40,16 @@ import { confineImplementer, confineImplementerShell } from "./worktree-confine"
 import { agentSteering, workitRole } from "./steering";
 import type { HookDecision, HookEventKind, HookInput, HostAdapter, RenderedHook } from "./protocol";
 
-export type HookDeps = { descriptor: HostDescriptor; addendum: string | null };
+/**
+ * `budget`: the worker tool-call budget (budget-signal.ts budgetHooks), given
+ * only by the hosts that count calls in their launcher (Claude Code, Codex),
+ * so other hook bundles do not carry it.
+ */
+export type HookDeps = {
+  descriptor: HostDescriptor;
+  addendum: string | null;
+  budget?: BudgetHooks;
+};
 
 const usable = (value: Support) => value === "native" || value === "partial";
 const NONE: HookDecision = { kind: "none" };
@@ -125,9 +135,11 @@ const subagentStartText = (
 const PRE_TOOL = new Set<HookEventKind>(["shell.pre", "write.pre", "tool.pre"]);
 
 /**
- * A running worker's standing-order delta rides any pre-tool answer that lets
- * the call run. In-process hosts deliver it on their own channel (OpenCode's
- * system context, Pi's tool result), so it is never spent here for them.
+ * A running worker's standing-order delta, and its tool-call budget line once
+ * the launcher counted it reached (budget-signal.ts), ride any pre-tool answer
+ * that lets the call run. In-process hosts deliver them on their own channel
+ * (OpenCode's system context, Pi's tool result), so they are never spent here
+ * for them.
  */
 export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
   const decision = decide(input, deps);
@@ -138,7 +150,8 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
     decision.kind === "ask"
   )
     return decision;
-  const delta = standingDelta(input);
+  const delta =
+    [standingDelta(input), deps.budget?.line(input) ?? null].filter(Boolean).join("\n") || null;
   if (!delta) return decision;
   return decision.kind === "rewrite" || decision.kind === "update-input"
     ? { ...decision, text: [decision.text, delta].filter(Boolean).join("\n") }
@@ -285,7 +298,11 @@ function decide(input: HookInput, deps: HookDeps): HookDecision {
     case "subagent.start":
       if (workitRole(descriptor, event.agentType) === "judge")
         trackJudge(input, event.agentId, true);
-      seedStanding({ ...input, session: { ...input.session, agentId: event.agentId } });
+      seedStanding({
+        ...input,
+        session: { ...input.session, agentId: event.agentId },
+      });
+      deps.budget?.start(input, event.agentId, event.agentType);
       return {
         kind: "context",
         text: subagentStartText(input, descriptor, event),
@@ -299,8 +316,13 @@ function decide(input: HookInput, deps: HookDeps): HookDecision {
     case "tool.pre":
       // Host permission policy owns other tools; a skill load is recorded.
       if (event.skill) recordSkillLoad(input, event.skill, "tool");
-      if (event.agentInput && input.host === "claude_code")
-        return spawnDecision(descriptor, input.cwd, event.agentInput);
+      if (event.agentInput && input.host === "claude_code") {
+        const spawn = spawnDecision(descriptor, input.cwd, event.agentInput);
+        // A spawn the gate lets through queues its tool-call budget, or
+        // none; the launcher does so for one its fast path allows.
+        if (spawn.kind !== "deny") deps.budget?.spawn(input, event.agentInput);
+        return spawn;
+      }
       return NONE;
     case "stop":
       return usable(descriptor.events.stop.support) ? stopDecision(input, descriptor) : NONE;
@@ -308,6 +330,7 @@ function decide(input: HookInput, deps: HookDeps): HookDecision {
     // arrive with the CLI-observed evidence model.
     case "subagent.stop":
       trackJudge(input, event.agentId, false);
+      if (event.agentId) deps.budget?.stop(input, event.agentId);
       return NONE;
     case "prompt.submit":
       return NONE;
@@ -335,7 +358,7 @@ export const failureDecision = (
 
 /** Parse, handle, and render one native payload. `error` is set on any failure. */
 export const dispatchHook = (
-  adapter: HostAdapter,
+  adapter: HostAdapter & { budget?: BudgetHooks },
   raw: unknown,
   env: NodeJS.ProcessEnv = process.env,
 ): RenderedHook & { error: string | null } => {
@@ -353,6 +376,7 @@ export const dispatchHook = (
     const decision = handleHook(parsed.input, {
       descriptor,
       addendum: adapter.addendum?.(parsed.input) ?? null,
+      budget: adapter.budget,
     });
     return { ...adapter.render(decision, parsed.native), error: null };
   } catch (error) {

package/src/hooks/hosts/claude-code.ts

@@ -44,11 +44,12 @@ export const CLAUDE_CODE_DESCRIPTOR: HostDescriptor = {
     // SubagentStart output is additionalContext only: it cannot block or bind.
     "subagent.start": { support: "native", native: "SubagentStart" },
     "prompt.submit": { support: "native", native: "UserPromptSubmit" },
-    // Claude Code has SubagentStop and PreCompact, but the plugin registers
-    // neither: events list what workit registers (docs/agents/hosts.md, Host
-    // parity). A subagent's stop is never blocked; compaction restore runs on
-    // SessionStart source=compact.
-    "subagent.stop": { support: "none", native: null },
+    // SubagentStop is never blocked: the launcher answers it itself, dropping
+    // the stopped agent's tool-call budget files (hooks/budget-signal.ts).
+    // Claude Code has PreCompact, but the plugin does not register it: events
+    // list what workit registers (docs/agents/hosts.md, Host parity);
+    // compaction restore runs on SessionStart source=compact.
+    "subagent.stop": { support: "native", native: "SubagentStop" },
     "compact.pre": { support: "none", native: null },
     // `{"decision":"block","reason"}` continues the turn; the input carries
     // `stop_hook_active` and `last_assistant_message` (claude 2.1.295).