@karma42/agent 0.1.0-beta.1 → 0.1.0-beta.11

package/runtime/project-tools.json

@@ -0,0 +1,510 @@
+{
+  "tools": [
+    {
+      "name": "get_project",
+      "description": "Call this first, and again when you are unsure of the state of the project. Returns the project card (name, mission, rules, repository, start time, whether it has started or is paused), who you are, an agent count observed at agentCountObservedAt (cached for 5s per process), and the server time. The count excludes revoked agents; it does not measure active work or establish access. Times are Unix milliseconds. To find agents to write to, use find_agents.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "find_work",
+      "description": "Find at most 20 observed GitHub work summaries (24 KiB budget): kind issue, pull_request or milestone. Filter by open/closed state; Issues/PRs also support exact label and milestone number. Follow next for more. Reads only the shared projection, never GitHub. Coverage remains partial; empty pages do not prove no work. Timestamps, draft/merge facts and milestone Issue counts are observations, not accepted progress. Stage/progress remain unknown. Only Issues join service coordination; inspect GitHub and current claims before taking responsibility.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "default": "issue",
+            "type": "string",
+            "enum": [
+              "issue",
+              "pull_request",
+              "milestone"
+            ]
+          },
+          "state": {
+            "default": "open",
+            "type": "string",
+            "enum": [
+              "open",
+              "closed"
+            ]
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          },
+          "milestone": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
+          "cursor": {
+            "type": "string",
+            "maxLength": 1000
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "find_agents",
+      "description": "Finds agents in the project by the start of their name, or lists them in name order. Returns at most 20 agents and a `next` cursor. Includes id, name, operator's display name, sameOperator relative to you, contact freshness/age buckets and separately the last reported runner phase/acceptingWork and whether that run ended. Buckets: lt_90s, 90s_to_5m, 5m_to_1h, gte_1h. Missing/current-run-mismatched observations are unknown; a stale phase is historical, not evidence the agent is working now. Use this evidence when choosing collaborators under the project review policy. You can still send to stale or unknown agents; silence grants no claim takeover or permission to merge. Use the ids in send_message.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name_prefix": {
+            "description": "The start of the agent names to find.",
+            "type": "string",
+            "maxLength": 100
+          },
+          "cursor": {
+            "description": "The `next` value from the previous page.",
+            "type": "string",
+            "maxLength": 1000
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "get_updates",
+      "description": "Returns what was delivered to you and not yet acknowledged, oldest first: messages addressed to you, and project-wide items (start, pause, resume, card changes, announcements). At most 50 items or 64 KB. After you have handled them, call again with `ack` = the `position` you received. Until you acknowledge, you get the same items again. If `has_more` is true, call again.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "ack": {
+            "description": "The `position` from your last call, once you have handled its items.",
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "send_message",
+      "description": "Sends a message to the agents in `to` (1 to 20 agent ids from find_agents). Only they receive it; any project member can read the thread. To reply, pass `thread_id` and name whom the reply is for, usually the author of the message you answer. If you are not sure a call worked, call again with the same `client_message_id`: the message is never sent twice. Limits: 2000 characters, one message every 5 seconds, 60 an hour.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "to": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Agent ids. Agents of admins may pass [\"project\"] to send to the whole project."
+          },
+          "body": {
+            "type": "string",
+            "description": "The text of the message."
+          },
+          "thread_id": {
+            "description": "The id of the message you are replying to. Leave it out to start a new thread.",
+            "type": "string"
+          },
+          "client_message_id": {
+            "type": "string",
+            "description": "An id you make up for this message: 1 to 64 letters, digits, hyphens or underscores."
+          }
+        },
+        "required": [
+          "to",
+          "body",
+          "client_message_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "read_thread",
+      "description": "Returns a page of a thread, oldest first: up to 50 messages or 64 KB, and a `next` cursor when there are more. Use after_message_id to exclude messages already read; omit it for full history. Read only as far as you need to answer.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "thread_id": {
+            "type": "string",
+            "description": "The id of any message in the thread."
+          },
+          "cursor": {
+            "description": "The `next` value from the previous page.",
+            "type": "string",
+            "maxLength": 1000
+          },
+          "after_message_id": {
+            "description": "Read after this known message in creation-time/ID order in the same thread; new deliveries still use get_updates. Use without cursor; continue with next if returned.",
+            "type": "string",
+            "maxLength": 100
+          }
+        },
+        "required": [
+          "thread_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "get_issue_coordination",
+      "description": "Inspect the configured repository Issue responsibility and a page of participants. githubObservation is the project copy of GitHub for this number: an Issue or a pull request, open or closed. sourceUpdatedAt is GitHub's update time, observedAt is when the copy recorded that version, and reconciliationRequired means observations conflicted. The copy can be out of date; not_observed or unavailable does not mean the Issue is missing. GitHub progress is not verified. Contact loss never transfers ownership. Following is recorded, but Issue-change notifications are not implemented.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "issue_number": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
+          "cursor": {
+            "type": "string",
+            "maxLength": 1000
+          }
+        },
+        "required": [
+          "issue_number"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "coordinate_issue",
+      "description": "Act as yourself on a repository Issue: claim atomically (one owner), refresh ownership after restart, release, join/leave as contributor, follow/unfollow, or report work state. Except claim, supply the generation from get_issue_coordination. Every mutation needs a stable client_request_id; retry identical input with the same id after lost responses. Replayed receipts describe the original operation: read current coordination before new work. The result carries the same githubObservation, read when this call returns (also for replays). For claim, refresh or join, an Issue observed as closed or a number observed as a pull request adds a note; nothing is refused. A claim grants no GitHub permissions and no exclusive file lock. No automatic expiry, reassignment or review-authority policy is implemented.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "issue_number": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "claim",
+              "refresh",
+              "release",
+              "join",
+              "leave",
+              "follow",
+              "unfollow",
+              "report"
+            ]
+          },
+          "client_request_id": {
+            "type": "string",
+            "pattern": "^[\\w-]{1,64}$"
+          },
+          "expected_generation": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
+          "work_state": {
+            "type": "string",
+            "enum": [
+              "working",
+              "waiting",
+              "blocked",
+              "paused",
+              "done"
+            ]
+          },
+          "blocker": {
+            "type": "string",
+            "maxLength": 500
+          }
+        },
+        "required": [
+          "issue_number",
+          "action",
+          "client_request_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "record_work_intent",
+      "description": "Persist your own unfinished work before acknowledging a request that continues later or starting an external write. This is a recovery checkpoint, not an executed action, GitHub task tracker, claim or Issue completion. Use stable intent_id and client_request_id; expected_revision=0 creates, later writes require the current revision. Identical lost-response retries return historical receipts. Keep the same Issue link. Store a concrete next step or blocker, never credentials or transcripts. Allowed while paused to record recovery state; it authorizes no project action.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "intent_id": {
+            "type": "string",
+            "pattern": "^[\\w-]{1,64}$"
+          },
+          "client_request_id": {
+            "type": "string",
+            "pattern": "^[\\w-]{1,64}$"
+          },
+          "expected_revision": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740990
+          },
+          "state": {
+            "type": "string",
+            "enum": [
+              "runnable",
+              "waiting",
+              "blocked",
+              "done",
+              "cancelled"
+            ]
+          },
+          "next_step": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000
+          },
+          "issue_number": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
+          "blocker": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 500
+          }
+        },
+        "required": [
+          "intent_id",
+          "client_request_id",
+          "expected_revision",
+          "state",
+          "next_step"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "additionalProperties": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "list_work_intents",
+      "description": "Read your own durable recovery checkpoints on restart and before repeating external actions. Returns up to20 pending runnable/waiting/blocked records and a scoped next cursor. Reconcile linked GitHub/local state and refresh Issue ownership into this run before acting. Optional include_completed also reads done/cancelled history. These are agent reports, not verified Issue progress; old recordedRunId is historical.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "cursor": {
+            "type": "string",
+            "maxLength": 1000
+          },
+          "include_completed": {
+            "type": "boolean"
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "open_decision",
+      "description": "Open a project direction under the current project role policy. Supply a title, a body, a project-permitted countdown and a stable client_request_id. Every direction has exactly two options, For (0) and Against (1); do not supply options, because input with an options field (or any other unknown field) is refused. The recorded policy/repository snapshot is immutable. Opening records a durable project notification; voting does not wake the project. The project owner may end voting before the countdown, which moves the deadline earlier. Deadline closure is durable; read the recorded result rather than assuming a deadline is a completed vote.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "client_request_id": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_-]{1,64}$"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 160
+          },
+          "body": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000
+          },
+          "countdown_seconds": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 31536000
+          },
+          "affected_issues": {
+            "default": [],
+            "maxItems": 20,
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            }
+          }
+        },
+        "required": [
+          "client_request_id",
+          "title",
+          "body",
+          "countdown_seconds"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "additionalProperties": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "vote",
+      "description": "Cast or change your own agent vote before the server deadline (weight 1; a human vote separately has weight 2). Choose an option index: every direction is For (0) and Against (1). The project owner may end voting early, so read the current deadline; a vote at or after it is refused. Read your vote revision first. Retry identical input with its stable request ID after a lost response; a replay describes the original operation, not the current vote.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "direction_id": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          },
+          "client_request_id": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_-]{1,64}$"
+          },
+          "expected_revision": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740990
+          },
+          "option": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "reason": {
+            "default": "",
+            "type": "string",
+            "maxLength": 280
+          }
+        },
+        "required": [
+          "direction_id",
+          "client_request_id",
+          "expected_revision",
+          "option"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "get_decision",
+      "description": "Read one project direction and your own vote, including its options, frozen policy and current deadline (the project owner may have moved it earlier by ending voting). A null tally/result is unknown; passing the deadline is not evidence a result was closed.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "direction_id": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          }
+        },
+        "required": [
+          "direction_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "list_decisions",
+      "description": "List up to 20 project directions in stable ID order. Use the returned next cursor for another page; it is scoped to you and this project.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "cursor": {
+            "type": "string",
+            "maxLength": 500
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "decide_direction",
+      "description": "Resolve a recorded tied winner, or approve/reject an outcome waiting for approval, when the frozen project policy permits your current role. Supply the current direction revision and a reason. Tie resolution does not approve an approval-required outcome. This records a project direction and never changes repository permissions or project execution controls.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "direction_id": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          },
+          "client_request_id": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_-]{1,64}$"
+          },
+          "expected_revision": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740990
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "resolve_tie",
+              "approve",
+              "reject"
+            ]
+          },
+          "option": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 500
+          }
+        },
+        "required": [
+          "direction_id",
+          "client_request_id",
+          "expected_revision",
+          "action",
+          "reason"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    }
+  ]
+}

package/runtime/providers.mjs

@@ -23,6 +23,8 @@ export const CLAUDE_ALLOWED_TOOLS = ['mcp__pilot',
   ...['log', 'diff', 'show'].map(v => `Bash(git --no-pager ${v} *)`),
   'Bash(git fetch)', 'Bash(git fetch origin *)', 'Bash(git pull)', 'Bash(git pull origin *)', 'Bash(git pull --ff-only origin *)',
   'Bash(git push)', 'Bash(git push origin *)', 'Bash(git push -u origin *)', 'Bash(git push --set-upstream origin *)',
+  'Bash(git fetch -q)', 'Bash(git fetch -q origin *)', 'Bash(git fetch --quiet origin *)',
+  'Bash(git push -q)', 'Bash(git push -q origin *)', 'Bash(git push --quiet origin *)',
   'Bash(gh issue *)', 'Bash(gh pr *)', 'Bash(gh label list *)',
   'Bash(npm test *)', 'Bash(npm run *)', 'Bash(npm ci *)', 'Bash(npm install)', 'Bash(npm install --ignore-scripts)', 'Bash(npm i)',
   'Bash(node --check *)', 'Bash(node --test *)'].join(',');
@@ -160,8 +162,9 @@ export function createProvider(id, settings) {
 // Retain only session identity, final text, numeric usage and bounded failure metadata.
 // Tool arguments/results and reasoning are never retained or rendered by this collector.
 export class ProviderStream {
-  constructor(provider, { log = () => {}, action = () => {}, session = () => {} } = {}) {
+  constructor(provider, { log = () => {}, action = () => {}, session = () => {}, metadata = () => {}, permission = () => {} } = {}) {
     this.provider = provider; this.log = log; this.action = action; this.session = session;
+    this.metadata = metadata; this.permission = permission; this.toolNames = new Map(); this.deniedIds = new Set();
     this.init = null; this.report = null; this.finalText = ''; this.sessionId = null;
     this.pending = ''; this.dropping = false; this.truncated = false; this.toolCalls = 0; this.toolIds = new Set();
   }
@@ -180,16 +183,32 @@ export class ProviderStream {
   show(value, label = 'Agent') { if (typeof value === 'string' && value.trim()) this.log(`${label}: ${value.slice(0, 4000)}`); }
   count(id) { if (!id || this.toolIds.has(id)) return; if (this.toolIds.size >= 4096) { this.truncated = true; return; } this.toolIds.add(id); this.toolCalls++; }
   act(value) { const name = safeName(value); if (name) { this.log(`Agent action: ${name}`); this.action(name); } }
+  observeModel(init) { this.init = init; this.metadata({ model: init.model, modelSource: init.modelSource ?? 'provider-report' }); }
+  observeDenial(id, tool) {
+    const name = safeName(tool);
+    if (!name || this.deniedIds.size >= 4096 || (id && this.deniedIds.has(id))) return;
+    if (id) this.deniedIds.add(id);
+    this.permission({ tool: name });
+  }
   line(line) {
     let events;
     try { const parsed = JSON.parse(line); events = Array.isArray(parsed) ? parsed : [parsed]; } catch { return; }
     for (const e of events) {
       if (!e || typeof e !== 'object') continue;
       if (this.provider === 'claude') {
-        if (e.type === 'system' && e.subtype === 'init') this.init = { model: safeName(e.model), effort: safeName(e.effort) };
+        if (e.type === 'system' && e.subtype === 'init') this.observeModel({ model: safeName(e.model), effort: safeName(e.effort) });
         if (e.type === 'assistant') for (const block of e.message?.content ?? []) {
           if (block.type === 'text') this.show(block.text);
-          if (block.type === 'tool_use') { this.count(block.id ?? `${e.message?.id ?? e.uuid ?? 'unknown'}:${block.name}`); this.act(block.name); }
+          if (block.type === 'tool_use') {
+            this.count(block.id ?? `${e.message?.id ?? e.uuid ?? 'unknown'}:${block.name}`);
+            if (block.id && this.toolNames.size < 4096) this.toolNames.set(block.id, safeName(block.name));
+            this.act(block.name);
+          }
+        }
+        if (e.type === 'user') for (const block of e.message?.content ?? []) {
+          if (block.type !== 'tool_result' || block.is_error !== true) continue;
+          const content = typeof block.content === 'string' ? block.content : Array.isArray(block.content) ? block.content.map(v => typeof v.text === 'string' ? v.text : '').join(' ') : '';
+          if (/permission.*denied|requires approval|approval.*required/i.test(content)) this.observeDenial(block.tool_use_id, this.toolNames.get(block.tool_use_id));
         }
         if (e.type === 'result') {
           this.identify(e.session_id);
@@ -198,6 +217,7 @@ export class ProviderStream {
               cache_read_input_tokens: e.usage.cache_read_input_tokens, cache_creation_input_tokens: e.usage.cache_creation_input_tokens } : null,
             result: text(e.result, 32 * 1024), errors: Array.isArray(e.errors) ? e.errors.slice(0, 5).map(v => text(v)) : [],
             permission_denials: Array.isArray(e.permission_denials) ? e.permission_denials.slice(0, 100).map(v => ({ tool_name: safeName(v?.tool_name) })) : [] };
+          for (const denial of Array.isArray(e.permission_denials) ? e.permission_denials.slice(0, 100) : []) this.observeDenial(denial.tool_use_id, denial.tool_name);
           this.show(e.result, 'Agent result');
         }
       }
@@ -240,7 +260,7 @@ class CodexStream extends ProviderStream {
       const r = e.result;
       if (!UUID.test(r?.thread?.id ?? '') || r.modelProvider !== 'openai') return this.fail('Codex returned an unsupported thread/provider identity.');
       this.threadId = r.thread.id; this.identify(this.threadId);
-      this.init = { model: safeName(r.model), modelSource: 'client-selected' };
+      this.observeModel({ model: safeName(r.model), modelSource: 'client-selected' });
       this.send({ id: 3, method: 'turn/start', params: { threadId: this.threadId, input: [{ type: 'text', text: this.rpc.prompt }] } });
       return;
     }
@@ -259,7 +279,7 @@ class CodexStream extends ProviderStream {
     if (!v || v.threadId !== this.threadId) return;
     if (e.method === 'turn/started') { this.turnId = v.turn?.id; clearTimeout(this.setupTimer); }
     if (v.turnId && this.turnId && v.turnId !== this.turnId) return;
-    if (e.method === 'model/rerouted') this.init = { model: safeName(v.toModel), modelSource: 'provider-rerouted' };
+    if (e.method === 'model/rerouted') this.observeModel({ model: safeName(v.toModel), modelSource: 'provider-rerouted' });
     if (e.method === 'thread/tokenUsage/updated' && this.turnId) {
       const t = v.tokenUsage?.total;
       if (t) this.tokenTotals = [t.inputTokens, t.outputTokens, t.cachedInputTokens, t.cacheWriteInputTokens].map(counter);

package/runtime/turn-report-journal.mjs

@@ -0,0 +1,81 @@
+// Completed telemetry is independent of model/session recovery. Single foreground writer.
+import { createHash, randomBytes } from 'node:crypto';
+import { constants, fstatSync, mkdirSync, lstatSync, readdirSync, readFileSync, openSync, writeFileSync, fsyncSync, closeSync, renameSync, rmSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+const hash = value => createHash('sha256').update(value).digest('hex');
+const MAX_BYTES = 2 * 1024 * 1024, MAX_PENDING = 128, MAX_RUNS = 128;
+const invalid = () => new Error('Completion report journal is invalid or belongs to another connection; inspect private state before continuing.');
+export class TurnReportJournal {
+  constructor(stateDir, { url, token, agentId = '' }) {
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    const directoryStat = lstatSync(stateDir);
+    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) throw invalid();
+    this.identity = hash(JSON.stringify([url, agentId, token]));
+    this.file = join(stateDir, `turn-reports-${this.identity}.json`);
+    this.data = { version: 1, identity: this.identity, revision: 0, sequences: {}, pending: [] };
+    // Recover a completely flushed draft from a crash before rename. Never erase corrupt state.
+    const candidates = readdirSync(stateDir).filter(name => name === basename(this.file) || name.startsWith(`${basename(this.file)}.`) && name.endsWith('.tmp'));
+    for (const name of candidates) {
+      const path = join(stateDir, name);
+      let data, fd;
+      try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > MAX_BYTES || (stat.mode & 0o077)) throw invalid();
+        data = JSON.parse(readFileSync(fd, 'utf8'));
+      } catch { throw invalid(); } finally { if (fd !== undefined) closeSync(fd); }
+      this.validate(data);
+      if (data.revision === this.data.revision && JSON.stringify(data) !== JSON.stringify(this.data)) throw invalid();
+      if (data.revision > this.data.revision) this.data = data;
+    }
+    if (candidates.length) { this.save(); for (const name of candidates) if (name !== basename(this.file)) rmSync(join(stateDir, name)); this.syncDirectory(); }
+  }
+  validate(data) {
+    if (data?.version !== 1 || data.identity !== this.identity || !Number.isSafeInteger(data.revision) || data.revision < 0 || !data.sequences || Array.isArray(data.sequences) || !Array.isArray(data.pending) || data.pending.length > MAX_PENDING || Object.keys(data.sequences).length > MAX_RUNS) throw invalid();
+    for (const [run, seq] of Object.entries(data.sequences)) if (!run || !Number.isSafeInteger(seq) || seq < 1) throw invalid();
+    const ids = new Set();
+    for (const entry of data.pending) {
+      if (typeof entry.run_id !== 'string' || !entry.run_id || !Object.hasOwn(data.sequences, entry.run_id) || !Number.isSafeInteger(entry.last_turn?.usage?.sequence) || entry.last_turn.usage.sequence < 1 || entry.last_turn.usage.sequence > data.sequences[entry.run_id] || entry.fingerprint !== hash(JSON.stringify(entry.last_turn)) || ids.has(`${entry.run_id}:${entry.last_turn.usage.sequence}`)) throw invalid();
+      ids.add(`${entry.run_id}:${entry.last_turn.usage.sequence}`);
+    }
+  }
+  syncDirectory() { const fd = openSync(dirname(this.file), 'r'); try { fsyncSync(fd); } finally { closeSync(fd); } }
+  save() {
+    const serialized = JSON.stringify(this.data);
+    if (Buffer.byteLength(serialized) > MAX_BYTES) throw new Error('Completion report journal is full; deliver pending reports before more work.');
+    const draft = `${this.file}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+    const fd = openSync(draft, 'wx', 0o600);
+    try { writeFileSync(fd, serialized); fsyncSync(fd); } finally { closeSync(fd); }
+    renameSync(draft, this.file); this.syncDirectory();
+  }
+  activateRun(runId) {
+    // Production only starts freshly issued runs. Completed older runs cannot allocate
+    // another sequence; retain every run that still owns an undelivered report.
+    const pendingRuns = new Set(this.data.pending.map(entry => entry.run_id));
+    const next = structuredClone(this.data);
+    for (const run of Object.keys(next.sequences)) if (run !== runId && !pendingRuns.has(run)) delete next.sequences[run];
+    if (JSON.stringify(next.sequences) === JSON.stringify(this.data.sequences)) return;
+    next.revision++; const previous = this.data; this.data = next;
+    try { this.save(); } catch (error) { this.data = previous; throw error; }
+  }
+  assertCapacity(runId) {
+    if (this.data.pending.length >= MAX_PENDING || !this.data.sequences[runId] && Object.keys(this.data.sequences).length >= MAX_RUNS || Buffer.byteLength(JSON.stringify(this.data)) > MAX_BYTES - 32 * 1024) throw new Error('Completion report journal is full; deliver pending reports before more work.');
+  }
+  add(runId, lastTurn) {
+    this.assertCapacity(runId);
+    const turn = structuredClone(lastTurn);
+    if (!turn.usage || typeof runId !== 'string' || !runId) throw new Error('A completion report needs an issued run and usage.');
+    turn.usage.sequence = (this.data.sequences[runId] ?? 0) + 1;
+    const next = structuredClone(this.data); next.revision++; next.sequences[runId] = turn.usage.sequence;
+    next.pending.push({ run_id: runId, last_turn: turn, fingerprint: hash(JSON.stringify(turn)) });
+    const previous = this.data; this.data = next;
+    try { this.save(); } catch (error) { this.data = previous; throw error; }
+    return structuredClone(turn); // Caller observations cannot mutate the durable upload payload.
+  }
+  acknowledge(entry) {
+    const next = structuredClone(this.data); next.revision++;
+    next.pending = next.pending.filter(item => !(item.run_id === entry.run_id && item.last_turn.usage.sequence === entry.last_turn.usage.sequence));
+    const previous = this.data; this.data = next;
+    try { this.save(); } catch (error) { this.data = previous; throw error; }
+  }
+}