projectkeeper 0.0.0-stage → 1.0.0

package/src/keeper/scope-tools.ts

@@ -0,0 +1,194 @@
+/**
+ * The Keeper's word on the project scope (Spec §1.1, §3.9, §6.7; CKC-04 AC-13, AC-16, AC-17; CKC-02 AC-25).
+ *
+ * The program offers candidates for third-party material and generated output, counts what the ignore rules leave out
+ * and measures worktrees against the trunk; what a location *is* when the records cannot tell is the Keeper's
+ * judgement, recorded here with a reason, what shows it and a basis, and corrected by the owner in the conversation.
+ * A question only the owner can settle goes into the scope questions Project scope already shows (§3.9).
+ *
+ * These tools write assets only; what is read from a location follows at the next scope pass and intake.
+ */
+import { existsSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { Type } from 'typebox';
+import { defineTool, type ToolDefinition } from '@earendil-works/pi-coding-agent';
+import type { ScopeItem, ScopeJudgement, ScopeQuestion, Source } from '../model/types.ts';
+import type { ScopeRelation } from '../model/vocab.ts';
+import { BASIS, isOneOf } from '../model/vocab.ts';
+import { stableId } from '../model/ids.ts';
+import { anchorLabel, redactCredentials } from '../sources/anchor.ts';
+import { canonicalPath, isWithin, normalizePath, pathKey, samePath } from '../util/paths.ts';
+import { JUDGED_RELATIONS, applyDecisions, keeperQuestionId } from '../scope/decisions.ts';
+import { isDocumentPath, treatmentOf } from '../scope/skip.ts';
+import { ruleUseRefusal } from './rules.ts';
+import type { ToolContext } from './tools.ts';
+
+const text = (v: unknown): string => (typeof v === 'string' ? v : '');
+const arr = <T>(v: unknown): T[] => (Array.isArray(v) ? (v as T[]) : []);
+const redact = (s: string) => redactCredentials(s).text;
+const now = () => new Date().toISOString();
+const ok = (value: unknown) => ({ content: [{ type: 'text' as const, text: JSON.stringify(value, null, 1) }], details: {} });
+const fail = (message: string) => ({ content: [{ type: 'text' as const, text: `ERROR: ${message}` }], details: {}, isError: true });
+
+/** The id discovery gives the item at this location, so a source's marker names the same item Project scope lists. */
+function itemIdAt(scope: readonly ScopeItem[], path: string): string {
+  const listed = scope.find((i) => i.category !== 'Session source' && samePath(i.path, path));
+  if (listed) return listed.id;
+  return stableId('scope', existsSync(join(path, '.git')) ? 'repo' : 'dir', pathKey(path));
+}
+
+/**
+ * Bring the `Used as` of the sources already read under `path` in line with its classification (§1.1): the documents
+ * of third-party material are `Reference only`; when the classification changes, what it set goes with it. What the
+ * owner judged one by one stays, and so does what the Keeper judged one by one.
+ */
+export function syncScopeUsedAs(store: ToolContext['store'], path: string, scopeItemId: string, relation: ScopeRelation, by: 'keeper' | 'owner', trace: { jobId: string | null; summary: string }): { referenceOnly: number; reset: number } {
+  let referenceOnly = 0;
+  let reset = 0;
+  const thirdParty = relation === 'Third-party material';
+  for (const s of store.sources.all()) {
+    if (s.anchor.kind !== 'file' || !isWithin(path, s.anchor.path)) continue;
+    const marker = s.usedAsByScopeItemId ?? null;
+    if (thirdParty) {
+      if (!isDocumentPath(s.anchor.path) || (s.usedAs === 'Reference only' && marker === scopeItemId)) continue;
+      if (s.usedAs !== null && marker === null) continue;   // judged one by one, by the owner or the Keeper: that stands
+      store.sources.put({ ...s, usedAs: 'Reference only', usedAsBy: by, usedAsByScopeItemId: scopeItemId } as Source, { jobId: trace.jobId, basisSourceIds: [s.id], summary: `Used as Reference only: ${trace.summary}` });
+      referenceOnly += 1;
+    } else if (marker === scopeItemId) {
+      store.sources.put({ ...s, usedAs: null, usedAsBy: null, usedAsByScopeItemId: null } as Source, { jobId: trace.jobId, basisSourceIds: [s.id], summary: `Used as no longer set by the scope: ${trace.summary}` });
+      reset += 1;
+    }
+  }
+  return { referenceOnly, reset };
+}
+
+/** After the scope is drawn: every third-party location's documents are Reference only, and a location no longer third-party takes back what it set. */
+export function syncAllScopeUsedAs(store: ToolContext['store'], scope: readonly ScopeItem[]): void {
+  const reading = scope.filter((i) => treatmentOf(i) === 'documents');
+  for (const item of reading) syncScopeUsedAs(store, item.path, item.id, 'Third-party material', item.classification?.by === 'owner' ? 'owner' : 'keeper', { jobId: null, summary: `${item.path}: Third-party material` });
+  const ids = new Set(reading.map((i) => i.id));
+  for (const s of store.sources.all()) {
+    if (!s.usedAsByScopeItemId || ids.has(s.usedAsByScopeItemId)) continue;
+    store.sources.put({ ...s, usedAs: null, usedAsBy: null, usedAsByScopeItemId: null } as Source, { jobId: null, basisSourceIds: [s.id], summary: 'Used as no longer set by the scope: its location is not third-party material any more' });
+  }
+}
+
+export function scopeTools(ctx: ToolContext): ToolDefinition[] {
+  const { store, project } = ctx;
+  const saved = (collection: string, id: string, label: string) => ctx.onSaved?.(collection, id, label);
+  const locations = project.locations.map((l) => canonicalPath(l));
+  const resolve = (raw: string): string | null => {
+    const p = raw.trim().replace(/^[`'"“”]+|[`'"“”]+$/g, '');
+    if (!p) return null;
+    if (isAbsolute(p)) return canonicalPath(p);
+    for (const l of locations) { const full = normalizePath(join(l, p.replace(/[\\/]+$/, ''))); if (existsSync(full)) return full; }
+    return locations[0] ? normalizePath(join(locations[0], p.replace(/[\\/]+$/, ''))) : null;
+  };
+  const inProject = (path: string) => locations.some((l) => isWithin(l, path)) || project.scope.some((i) => i.category !== 'Session source' && isWithin(i.path, path));
+  const current = () => applyDecisions<ScopeItem>(project.scope.map((i) => ({ ...i })), {
+    locations, rules: store.rules.all(), judgements: store.scopeJudgements.all(), questions: project.scopeQuestions,
+    sourceLabel: (id) => { const s = store.sources.get(id); return s ? anchorLabel(s.anchor) : null; },
+    resolveDir: (words) => { const full = resolve(words); try { return full && inProject(full) && statSync(full).isDirectory() ? full : null; } catch { return null; } },
+    newItem: (path, relation) => ({ id: itemIdAt(project.scope, path), path, category: existsSync(join(path, '.git')) ? 'Repository' : 'Directory', relation, reason: '', reasonSourceIds: [], sessionHost: null, readOnly: false, copyOf: null, worktreeOf: null, versionControl: 'unknown', missing: null, addedBy: 'keeper' }),
+  });
+
+  return [
+    defineTool({
+      name: 'pk_classify_scope', label: 'Classify a scope location',
+      description: `Record what a location in the project is, when the records alone cannot tell: ${JUDGED_RELATIONS.join(', ')}. Third-party material is what the project uses but did not write — SDKs, libraries, templates distributed with it; its documents become Reference only (citable, never this project's requirement, plan or work) and its code and history are not organized. Generated is build output, caches, exports: not organized. Main project (or Nested repository for a repository of its own) takes a candidate back as the project's own material; Experiment is for what the project calls an experiment; Excluded leaves a location out. Project scope lists the program's candidates ("candidate, not yet judged by the Keeper") — see pk_scope_items — and you can classify any other directory inside the project. Give the reason in your words, what shows it (sourceIds of material that says it; evidence for what shows it when no source does: a marker file, an upstream remote, file headers), and the basis: Explicit only when the project itself says so (a document, or the project's rule — ruleId), otherwise Inferred. When you cannot tell and it would change the result — for example an unmerged worktree you cannot tie to any work — record your best reading and put the question to the owner with askOwner. In the owner's conversation, ownerCorrection records the owner correcting it; the owner's word then stands over yours.`,
+      parameters: Type.Object({
+        path: Type.String({ description: 'the directory: absolute, or relative to the project root' }),
+        relation: Type.String({ description: JUDGED_RELATIONS.join(' | ') }),
+        reason: Type.String({ description: 'why, in your words; Project scope shows it' }),
+        sourceIds: Type.Optional(Type.Array(Type.String(), { description: 'sources that show it: the directory’s README or LICENSE, a project document naming it' })),
+        evidence: Type.Optional(Type.Array(Type.String(), { description: 'what shows it when no source does: a marker file, an upstream remote, a link target, generated-file headers' })),
+        basis: Type.Optional(Type.String({ description: 'Explicit (the project says so) | Inferred (default: you conclude it)' })),
+        ruleId: Type.Optional(Type.String({ description: 'the project’s rule that settles it' })),
+        askOwner: Type.Optional(Type.Object({ question: Type.String(), whyItMatters: Type.String(), clues: Type.Optional(Type.Array(Type.String())), options: Type.Array(Type.String()) }, { description: 'a question only the owner can settle; name the relations as options when the answer is one of them' })),
+        ownerCorrection: Type.Optional(Type.Object({ quote: Type.String({ description: 'the owner’s words' }) })),
+      }),
+      execute: async (_id, p) => {
+        const path = resolve(text(p.path));
+        if (!path) return fail('path: the directory to classify, absolute or relative to the project root.');
+        if (!inProject(path)) return fail(`${text(p.path)} is not in this project (its locations: ${locations.join(', ')}; or a listed scope item). Classify a location inside the project.`);
+        if (locations.some((l) => samePath(l, path))) return fail(`${path} is one of the project’s own locations, given by the owner; what the project is changes in Project scope, by the owner. Classify a location inside it.`);
+        if (!existsSync(path) && !project.scope.some((i) => samePath(i.path, path))) return fail(`${path} is not on disk.`);
+        if (!isOneOf(JUDGED_RELATIONS, p.relation)) return fail(`relation must be one of ${JUDGED_RELATIONS.join(', ')}. Third-party material and Generated are listed apart from the project's own material.`);
+        const relation = p.relation;
+        const reason = redact(text(p.reason)).trim();
+        if (!reason) return fail('Give the reason in your words (reason); Project scope shows it beside the location.');
+        if (relation === 'Nested repository' && !existsSync(join(path, '.git'))) return fail(`${path} is not a git repository of its own (no .git), so it cannot be a Nested repository; its own material is Main project.`);
+        const correction = p.ownerCorrection;
+        if (correction !== undefined && !ctx.ownerSourceId) return fail('Only the owner’s message in the conversation can correct a classification. Outside it, record your own reading; if the owner should settle it, use askOwner.');
+        const quote = correction ? redact(text(correction.quote)).trim() : '';
+        if (correction && !quote) return fail('ownerCorrection.quote: the owner’s words.');
+        const by = correction ? 'owner' as const : 'keeper' as const;
+        const unknown = arr<string>(p.sourceIds).filter((s) => !store.sources.has(s));
+        if (unknown.length) return fail(`sourceIds names no source in the assets: ${unknown.join(', ')}`);
+        const ruleId = text(p.ruleId).trim() || null;
+        if (ruleId) { const refusal = ruleUseRefusal(store, ruleId, 'Validity'); if (refusal) return fail(refusal); }
+        const sourceIds = [...new Set([...arr<string>(p.sourceIds), ...(ruleId ? store.rules.get(ruleId)!.sourceIds : []), ...(correction ? [ctx.ownerSourceId!] : [])])].filter((s) => store.sources.has(s));
+        const evidence = arr<string>(p.evidence).map((e) => redact(text(e)).trim()).filter(Boolean);
+        const basisGiven = correction || ruleId ? 'Explicit' : (text(p.basis) || 'Inferred');
+        if (!isOneOf(BASIS, basisGiven)) return fail('basis must be Explicit (the project itself says so) or Inferred (you conclude it)');
+        if (basisGiven === 'Explicit' && !correction && !ruleId && arr<string>(p.sourceIds).length === 0) {
+          return fail('Explicit is for what the project itself says: cite the material that says it (sourceIds) or the project’s rule (ruleId). What you conclude from how the location looks is Inferred.');
+        }
+        if (basisGiven === 'Inferred' && sourceIds.length === 0 && evidence.length === 0) {
+          return fail('Say what shows it (the reason comes with its source): sourceIds of material that shows it, or evidence — a marker file, an upstream remote, a link target, file headers — when no source does.');
+        }
+        const id = stableId('scopej', project.id, pathKey(path));
+        const previous = store.scopeJudgements.get(id);
+        if (previous?.by === 'owner' && !correction) {
+          return fail(`The owner corrected this location on ${previous.at.slice(0, 10)}${previous.ownerQuote ? `: “${previous.ownerQuote}”` : ''} (${previous.relation}). The owner’s word stands; if the material says otherwise, write a note to the owner.`);
+        }
+        let question: ScopeJudgement['question'] = null;
+        if (p.askOwner !== undefined) {
+          if (correction) return fail('askOwner is for a question you put to the owner; the owner’s correction already settles it.');
+          const q = p.askOwner;
+          const options = arr<string>(q.options).map((o) => text(o).trim()).filter(Boolean);
+          if (!text(q.question).trim() || !text(q.whyItMatters).trim() || options.length < 2) return fail('askOwner needs the question, whyItMatters (what changes with the answer) and at least two options.');
+          question = { id: keeperQuestionId(path), question: redact(text(q.question)).trim(), whyItMatters: redact(text(q.whyItMatters)).trim(), clues: arr<string>(q.clues).map((c) => redact(text(c)).trim()).filter(Boolean), options };
+        }
+        const at = now();
+        const judgement: ScopeJudgement = {
+          id, projectId: project.id, path, relation, reason, sourceIds, evidence, basis: basisGiven, ruleId, by, ownerQuote: quote || null, question,
+          previous: previous ? { relation: previous.relation, reason: previous.reason, by: previous.by, at: previous.at } : null, jobId: ctx.jobId, at,
+        };
+        const summary = `${path}: ${relation} (${by}, ${basisGiven})`;
+        store.scopeJudgements.put(judgement, { jobId: ctx.jobId, basisSourceIds: sourceIds, summary: `Scope classification — ${summary}` });
+        const synced = syncScopeUsedAs(store, path, itemIdAt(project.scope, path), relation, by, { jobId: ctx.jobId, summary });
+        saved('scopeJudgements', id, `Scope: ${relation} — ${path}`);
+        return ok({
+          path, relation, by, basis: basisGiven, ...(question ? { askedOwner: question.question } : {}),
+          documentsNowReferenceOnly: synced.referenceOnly, usedAsReset: synced.reset,
+          note: 'Project scope shows it once the scope is drawn again, in a few seconds; what is read from the location follows.',
+        });
+      },
+    }),
+    defineTool({
+      name: 'pk_scope_items', label: 'Read the project scope',
+      description: 'The project scope with what the records say about each location: which: candidates — third-party material and generated output the program offered and you have not judged yet, with its evidence; worktrees — each registered worktree measured against the trunk (merged or not, commits the trunk lacks, files skipped as the same or older, files taken); ignored — what the project’s ignore rules leave out, by directory, with the rule and how many documents; rules — locations a project rule covers; judged — what you or the owner classified; all (default). Also the scope questions put to the owner, with their answers.',
+      parameters: Type.Object({ which: Type.Optional(Type.String({ description: 'all | candidates | worktrees | ignored | rules | judged' })) }),
+      execute: async (_id, p) => {
+        const which = text(p.which) || 'all';
+        const view = current();
+        const pick = (i: ScopeItem) => which === 'all' ? true
+          : which === 'candidates' ? i.classification?.by === 'program'
+            : which === 'worktrees' ? i.worktree != null
+              : which === 'ignored' ? i.ignoredBy != null
+                : which === 'rules' ? (i.coveredBy ?? []).length > 0
+                  : which === 'judged' ? i.classification != null && i.classification.by !== 'program' : false;
+        const items = view.items.filter((i) => i.category !== 'Session source' && pick(i)).map((i) => ({
+          id: i.id, path: i.path, category: i.category, relation: i.relation, reason: i.reason, read: treatmentOf(i),
+          ...(i.classification ? { classification: i.classification } : {}),
+          ...(i.worktree ? { worktree: i.worktree } : {}),
+          ...(i.ignoredBy ? { ignoredBy: i.ignoredBy } : {}),
+          ...((i.coveredBy ?? []).length ? { coveredBy: i.coveredBy } : {}),
+        }));
+        const questions: ScopeQuestion[] = [...project.scopeQuestions, ...view.questions.filter((q) => !project.scopeQuestions.some((x) => x.id === q.id))];
+        return ok({ items, questions: questions.map((q) => ({ id: q.id, question: q.question, options: q.options, answer: q.answer?.text ?? null })) });
+      },
+    }),
+  ];
+}

package/src/keeper/sendback-text.ts

@@ -0,0 +1,83 @@
+/**
+ * What `Copy for agent` puts on the clipboard for a send-back (Spec §1.18, §7.10; CKC-24 AC-9; D79): where the problem
+ * is, the evidence — numbers, commits, files and lines, the report's own line word for word — where it should go back
+ * to, and the CLI command that shows the same send-back. The owner pastes it to an execution agent or an orchestrator;
+ * the agent runs the command and sees the same record the owner sees.
+ *
+ * Built only from the record and its resolved evidence: nothing here reads the assets, and nothing the model wrote
+ * becomes a date or a label (§2.11). Credential values never leave in it (§3.1).
+ */
+import type { EvidenceRef, Occurred, SendBack } from '../model/k-types.ts';
+import { materialDate } from '../model/time.ts';
+import { redactCredentials } from '../sources/anchor.ts';
+
+/** The command an execution agent runs to see the same send-back (§7.10): the CLI's `pk get <id>`. */
+export function cliCommandFor(projectId: string, id: string): string {
+  const quote = (v: string) => (/^[A-Za-z0-9._:-]+$/.test(v) ? v : `"${v.replace(/"/g, '\\"')}"`);
+  return `pk get ${quote(id)} --project ${quote(projectId)}`;
+}
+
+const BASIS_WORDS: Record<Occurred['basis'], string> = {
+  Commit: 'committed',
+  Session: 'said',
+  'Written in text': 'dated in the text',
+  'File time': 'file time',
+  'First observed': 'first seen',
+};
+
+/** When a piece of evidence happened, as the text says it: "committed 2026-09-12", "undated · first seen 2026-09-26". */
+export function occurredText(o: Occurred | null | undefined): string | null {
+  if (!o) return null;
+  const main = o.undated ? `undated · first seen ${materialDate(o.at)}` : `${BASIS_WORDS[o.basis] ?? o.basis} ${materialDate(o.at)}`;
+  return o.other ? `${main} · ${BASIS_WORDS[o.other.basis] ?? o.other.basis} ${materialDate(o.other.at)}` : main;
+}
+
+const KIND_WORDS: Record<EvidenceRef['kind'], string> = { commit: 'Commit', file: 'File', source: 'Source', ledger: 'Ledger', object: 'Record' };
+
+/** One piece of evidence: what it is (and in which repository, outside the first), when it happened, the original line. */
+function evidenceLine(e: EvidenceRef): string {
+  const named = e.kind === 'object' ? `${e.label} (${e.id})` : e.label;
+  const what = e.repo && !named.includes(e.repo) ? `${named} in ${e.repo}` : named;
+  const when = occurredText(e.occurred);
+  const head = `- ${KIND_WORDS[e.kind]} ${what}${when ? ` (${when})` : ''}`;
+  if (!e.line) return head;
+  const lines = e.line.split(/\r?\n/);
+  // One line stays on the entry; a cited stretch of several lines keeps its lines, each quoted.
+  return lines.length === 1 ? `${head}: “${e.line}”` : `${head}:\n${lines.map((l) => `  > ${l}`).join('\n')}`;
+}
+
+const FROM_WORDS: Record<SendBack['from']['kind'], string> = {
+  breakpoint: 'a breakpoint in the process',
+  verdict: 'a QC, review or walkthrough verdict',
+  'owner-judgement': 'one of the things the owner judges',
+  'code-anomaly': 'a code territory anomaly',
+};
+
+export interface CopyForAgentOptions {
+  /** The object it hangs on, by name and the project's number (or the Keeper's), when the caller knows them. */
+  readonly target?: { readonly label: string; readonly number?: string | null } | null;
+}
+
+/**
+ * The text `Copy for agent` puts on the clipboard. `resolvedEvidence` is the send-back's evidence as it resolves now
+ * (normally its own `evidence`).
+ */
+export function copyForAgentText(projectId: string, sendBack: SendBack, resolvedEvidence: readonly EvidenceRef[] = sendBack.evidence, options: CopyForAgentOptions = {}): string {
+  const target = options.target;
+  const on = target ? `${target.number ? `${target.number} ` : ''}${target.label} (${sendBack.targetId})` : sendBack.targetId;
+  const back = sendBack.to === 'Work'
+    ? `Send it back to Work — reopen the work or open new work: ${sendBack.suggestion}`
+    : `Send it back to Plan — change the plan or the document: ${sendBack.suggestion}`;
+  const since = occurredText(sendBack.occurred);
+  const lines = [
+    `Send-back ${sendBack.id} · ${sendBack.stage} · to ${sendBack.to} (project ${projectId})`,
+    `Where the problem is: ${sendBack.what}`,
+    `On: ${on}`,
+    `Found as: ${FROM_WORDS[sendBack.from.kind]} (${sendBack.from.id})${since ? ` · happened: ${since}` : ''}`,
+    'Evidence:',
+    ...(resolvedEvidence.length ? resolvedEvidence.map(evidenceLine) : ['- none recorded']),
+    back,
+    `See the same send-back: ${cliCommandFor(projectId, sendBack.id)}`,
+  ];
+  return redactCredentials(lines.join('\n')).text;
+}

package/src/keeper/step-timing.ts

@@ -0,0 +1,207 @@
+/**
+ * Where one job's time went (Spec §3.10, D81; CKC-23 AC-10, CKC-03 AC-19): model generation, tool execution, queueing,
+ * parsing and retries, and what cannot be told apart.
+ *
+ * pi's session events carry no times, so the runtime stamps them as they arrive. An assistant message carries the moment
+ * its request was sent (`timestamp`); its end is when `message_end` arrives, so generation includes building the request,
+ * the network, the provider's queue, time to first token and streaming — pi does not separate them. Parallel tool calls
+ * of one turn count once, as the span from the first start to the last end.
+ *
+ * Parsing and retrying, counted the way the test-B-1 baseline counted them (E106), so the two runs compare:
+ *   - a request that ended in an error or was aborted, and the wait before pi sent it again (`auto_retry_start`);
+ *   - the turn right after a turn whose tool calls were all refused (bad or incomplete arguments, an unknown tool),
+ *     when it sends a tool call again: it re-sends them. The refused turn itself stays generation, and so does a next
+ *     turn that only answers (QC AX-1: a final answer after a refusal was counted as a re-send).
+ */
+import { createHash } from 'node:crypto';
+import type { StepTiming } from '../model/k-types.ts';
+
+/** A tool result that says the call never ran: its arguments failed validation or did not arrive complete (pi's
+ *  "was not executed" — cut off at the output limit, or not complete JSON), or no tool has that name. A pk_* write
+ *  tool's own refusal of a call that leaves out what a new item needs says "Invalid arguments" (`incompleteCall`). */
+const REFUSED = /validation failed|invalid (tool )?arguments|must have required property|unknown tool|tool .{0,80} not found|no tool named|was not executed/i;
+/** pi's refusal of a call whose arguments did not arrive whole (cut off at the output limit, or not complete JSON). */
+const CUT_OFF = /was not executed/i;
+
+/** The call behind this tool result never ran. */
+export function isRefusal(isError: boolean, resultText: string): boolean {
+  return isError && REFUSED.test(resultText);
+}
+
+/**
+ * How a pk_* write tool refuses a call that would create an item but leaves out what a new item needs (a work item's
+ * title and progress, a round document's markdown …). Those fields used to be required by the tools' schemas, so pi
+ * refused such a call before it ran; they are optional now, because an update gives only what it changes, and the tool
+ * refuses the incomplete create itself, before it writes anything. It throws, so pi records the result as an error,
+ * and its words begin "Invalid arguments", so the timer and the refusal guard read it as the refusal of a call that
+ * never ran — as they read pi's own refusal of the same call before. `message` says what is missing and how to update.
+ */
+export function incompleteCall(message: string): Error {
+  return new Error(`Invalid arguments: ${message}`);
+}
+
+/** The message sends at least one tool call. */
+function sendsToolCall(message: { readonly stopReason?: string; readonly content?: readonly { readonly type: string }[] }): boolean {
+  return message.stopReason === 'toolUse' || (message.content ?? []).some((c) => c.type === 'toolCall');
+}
+
+export class StepTimer {
+  private generationMs = 0;
+  private toolMs = 0;
+  private parseRetryMs = 0;
+  private openTools = 0;
+  private toolSpanStart = 0;
+  private turnCalls = 0;
+  private turnRefused = 0;
+  private reissuePending = false;
+
+  /** An assistant message ended at `at`; its `timestamp` is when its request was sent. */
+  assistantEnded(message: { readonly timestamp?: number | string; readonly stopReason?: string; readonly content?: readonly { readonly type: string }[] }, at: number): void {
+    const sent = typeof message.timestamp === 'number' ? message.timestamp : typeof message.timestamp === 'string' ? Date.parse(message.timestamp) : Number.NaN;
+    const ms = Number.isFinite(sent) ? Math.max(0, at - sent) : 0;
+    const resends = this.reissuePending && sendsToolCall(message);
+    if (message.stopReason === 'error' || message.stopReason === 'aborted' || resends) this.parseRetryMs += ms;
+    else this.generationMs += ms;
+    this.reissuePending = false;
+    this.turnCalls = 0;
+    this.turnRefused = 0;
+  }
+
+  toolStarted(at: number): void {
+    if (this.openTools === 0) this.toolSpanStart = at;
+    this.openTools += 1;
+    this.turnCalls += 1;
+  }
+
+  toolEnded(at: number, isError: boolean, resultText: string): void {
+    if (isRefusal(isError, resultText)) this.turnRefused += 1;
+    this.openTools = Math.max(0, this.openTools - 1);
+    if (this.openTools === 0) {
+      this.toolMs += Math.max(0, at - this.toolSpanStart);
+      if (this.turnCalls > 0 && this.turnRefused === this.turnCalls) this.reissuePending = true;
+    }
+  }
+
+  /** pi waits before re-sending a failed request (`auto_retry_start`). */
+  retryWait(delayMs: number): void {
+    if (Number.isFinite(delayMs) && delayMs > 0) this.parseRetryMs += delayMs;
+  }
+
+  /** The job's timing, given when it was queued, started and ended (ISO times or epoch milliseconds). */
+  finish(queuedAt: string | number, startedAt: string | number, endedAt: string | number): StepTiming {
+    const t = (v: string | number) => (typeof v === 'number' ? v : Date.parse(v));
+    const wallMs = Math.max(0, t(endedAt) - t(startedAt));
+    const queueMs = Math.max(0, t(startedAt) - t(queuedAt));
+    const known = this.generationMs + this.toolMs + this.parseRetryMs;
+    return {
+      wallMs, queueMs,
+      generationMs: Math.round(this.generationMs), toolMs: Math.round(this.toolMs), parseRetryMs: Math.round(this.parseRetryMs),
+      otherMs: Math.max(0, Math.round(wallMs - known)),
+    };
+  }
+}
+
+/**
+ * How many turns in a row the same call may be refused the same way before the step is ended. pi's tool loop has no
+ * bound of its own: a model that keeps re-sending a refused call goes on until the step's time limit (30 minutes for
+ * automatic work, none for the owner's). QC AX-1 observed exactly that — a call re-sent with the same missing field
+ * turn after turn, ended only by the test double's own six-turn safety valve. Eight is generous: a model that fixes its
+ * call within a few tries, or moves on to other calls, never reaches it.
+ */
+export const REPEATED_REFUSAL_LIMIT = 8;
+
+/** A call refused the same way in `turns` turns in a row; `alongside`: how many other calls reached the limit with it. */
+export interface RepeatedRefusal { readonly tool: string; readonly error: string; readonly turns: number; readonly alongside: number }
+
+/** One tool call of a turn as the guard reads it: the tool, the arguments the model sent, and how the call ended. */
+export interface TurnCall { readonly tool: string; readonly args: unknown; readonly isError: boolean; readonly resultText: string }
+
+/** One turn: how the reply stopped, and every tool call it sent with its result. */
+export interface GuardTurn { readonly stopReason?: string; readonly calls: readonly TurnCall[] }
+
+/** A refusal's error, without the arguments pi echoes after a validation error, whitespace collapsed. */
+function refusalError(resultText: string): string {
+  return (resultText.split(/\n\s*\nReceived arguments:/)[0] ?? resultText).replace(/\s+/g, ' ').trim();
+}
+
+/** The arguments with their keys in one order, so the same call sent twice reads the same however its keys came. */
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    const o = value as Record<string, unknown>;
+    return `{${Object.keys(o).sort().filter((k) => o[k] !== undefined).map((k) => `${JSON.stringify(k)}:${stableJson(o[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+/** Which refused call this is: its tool, its error, and — when they arrived whole — its arguments. */
+function refusedCallKey(call: TurnCall, error: string): string {
+  const refusal = `${call.tool}\u0000${error.replace(/\d+/g, '#')}`;
+  if (CUT_OFF.test(call.resultText)) return refusal;
+  return `${refusal}\u0000${createHash('sha256').update(stableJson(call.args)).digest('hex')}`;
+}
+
+/**
+ * The guard against a model that re-sends a refused call turn after turn (QC AX-1). It reads each turn whole — the
+ * reply and the result of every call it sent — at the turn's end. The rule:
+ *   - A refused call is itself: its tool, its arguments and its error (pi's echo of the arguments left off, numbers in
+ *     the error ignored). A call whose arguments did not arrive whole (pi's "was not executed": cut off at the output
+ *     limit, or not complete JSON) is its tool and its error alone: what arrived is not the call the model sent, and it
+ *     differs from one cut to the next, so a call re-sent cut off at another length is the same refused call.
+ *   - A turn in which every call was refused counts once for each distinct call in it: one refused in the turn before
+ *     too goes on counting, any other starts at one. The same call twice in one turn counts once.
+ *   - A turn in which any call ran, or that sent none, starts every count again: the model is doing something else.
+ *     A request that failed or was aborted is no turn of the model's and changes no count.
+ *   - The step ends when one call reaches REPEATED_REFUSAL_LIMIT turns.
+ * So calls to different targets refused for the same reason in one turn are that many calls counted once each, not
+ * one call refused that many times: test-D-1's skeleton ended Failed on ten parallel updates of ten work items, refused
+ * for one missing field, when the count was kept per result and keyed on the tool and the error alone. The same call,
+ * or the same batch, re-sent turn after turn still ends the step at the limit.
+ */
+export class RefusalStreak {
+  private counts = new Map<string, { readonly tool: string; readonly error: string; readonly turns: number }>();
+
+  /** A turn has ended: its reply's stop reason, and each call it sent with its result. */
+  turnEnded(turn: GuardTurn): void {
+    if (turn.stopReason === 'error' || turn.stopReason === 'aborted') return;
+    const refused = turn.calls.filter((c) => isRefusal(c.isError, c.resultText));
+    const next = new Map<string, { readonly tool: string; readonly error: string; readonly turns: number }>();
+    if (refused.length > 0 && refused.length === turn.calls.length) {
+      for (const call of refused) {
+        const error = refusalError(call.resultText);
+        const key = refusedCallKey(call, error);
+        if (!next.has(key)) next.set(key, { tool: call.tool, error, turns: (this.counts.get(key)?.turns ?? 0) + 1 });
+      }
+    }
+    this.counts = next;
+  }
+
+  /** The refused call that has now come back `REPEATED_REFUSAL_LIMIT` or more turns in a row, if there is one. */
+  get reached(): RepeatedRefusal | null {
+    const over = [...this.counts.values()].filter((c) => c.turns >= REPEATED_REFUSAL_LIMIT);
+    return over.length ? { ...over[0]!, alongside: over.length - 1 } : null;
+  }
+}
+
+/** pi's view of a finished turn, as far as the guard reads it (`finishTurn`'s argument). */
+interface PiTurn {
+  readonly message: { readonly stopReason?: string; readonly content?: readonly unknown[] };
+  readonly toolResults?: readonly { readonly toolCallId?: string; readonly isError?: boolean; readonly content?: readonly { readonly type: string; readonly text?: string }[] }[];
+}
+
+/** The guard's reading of a turn pi finished: each tool call of the reply, matched to its result by the call's id. */
+export function guardTurn(turn: PiTurn): GuardTurn {
+  const results = new Map((turn.toolResults ?? []).map((r) => [r.toolCallId, r]));
+  const calls = (turn.message.content ?? [])
+    .filter((c): c is { type: 'toolCall'; id: string; name: string; arguments?: unknown } => (c as { type?: unknown } | null)?.type === 'toolCall')
+    .map((c) => {
+      const result = results.get(c.id);
+      return { tool: c.name, args: c.arguments ?? {}, isError: result?.isError === true, resultText: result?.content?.find((x) => x.type === 'text')?.text ?? '' };
+    });
+  return { stopReason: turn.message.stopReason, calls };
+}
+
+/** Every pi built-in tool, on in every step (D87: 「自带的几个命令全部打开，grep find」; CKC-03 AC-25). */
+export function keeperBuiltinTools(platform: string = process.platform): string[] {
+  return ['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls', ...(platform === 'win32' ? ['powershell'] : [])];
+}