@piagent/platform 1.3.1 → 1.4.0

package/packages/piagent-core/runtime/inspection/workspace-file-reader.ts

@@ -0,0 +1,132 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export class WorkspaceReadError extends Error {
+  readonly code: "outside-root" | "symlink-ancestor" | "not-file" | "oversized" | "changed-during-read";
+
+  constructor(code: WorkspaceReadError["code"], message: string) {
+    super(message);
+    this.name = "WorkspaceReadError";
+    this.code = code;
+  }
+}
+
+type SafeCandidate = { root: string; absolute: string; parent: string };
+
+function inside(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function safeCandidate(repoRoot: string, repoPath: string): SafeCandidate {
+  const root = fs.realpathSync.native(repoRoot);
+  const segments = repoPath.split("/");
+  if (!repoPath || path.posix.isAbsolute(repoPath) || segments.includes("..") || segments.includes("")) {
+    throw new WorkspaceReadError("outside-root", "Workspace path is not a safe repository-relative path");
+  }
+  let parent = root;
+  for (const segment of segments.slice(0, -1)) {
+    parent = path.join(parent, segment);
+    const stat = fs.lstatSync(parent);
+    if (stat.isSymbolicLink()) throw new WorkspaceReadError("symlink-ancestor", "Workspace path traverses a symbolic link");
+    if (!stat.isDirectory()) throw new WorkspaceReadError("not-file", "Workspace path has a non-directory ancestor");
+  }
+  const canonicalParent = fs.realpathSync.native(parent);
+  if (!inside(root, canonicalParent)) throw new WorkspaceReadError("outside-root", "Workspace path resolves outside its repository root");
+  const absolute = path.join(canonicalParent, segments.at(-1) as string);
+  if (!inside(root, absolute)) throw new WorkspaceReadError("outside-root", "Workspace path escapes its repository root");
+  return { root, absolute, parent: canonicalParent };
+}
+
+function sameFile(left: fs.Stats, right: fs.Stats): boolean {
+  return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode;
+}
+
+function openRegularFile(repoRoot: string, repoPath: string): { descriptor: number; stat: fs.Stats; candidate: SafeCandidate } {
+  const candidate = safeCandidate(repoRoot, repoPath);
+  const descriptor = fs.openSync(candidate.absolute, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile()) throw new WorkspaceReadError("not-file", "Workspace entry is not a regular file");
+    const canonical = fs.realpathSync.native(candidate.absolute);
+    const current = fs.lstatSync(candidate.absolute);
+    if (!inside(candidate.root, canonical) || !sameFile(stat, current)) {
+      throw new WorkspaceReadError("changed-during-read", "Workspace path changed while it was opened");
+    }
+    return { descriptor, stat, candidate };
+  } catch (error) {
+    fs.closeSync(descriptor);
+    throw error;
+  }
+}
+
+function verifyAfterRead(descriptor: number, before: fs.Stats, candidate: SafeCandidate): void {
+  const after = fs.fstatSync(descriptor);
+  const current = fs.lstatSync(candidate.absolute);
+  const canonical = fs.realpathSync.native(candidate.absolute);
+  if (
+    !sameFile(before, after)
+    || !sameFile(after, current)
+    || before.size !== after.size
+    || before.mtimeMs !== after.mtimeMs
+    || before.ctimeMs !== after.ctimeMs
+    || !inside(candidate.root, canonical)
+  ) {
+    throw new WorkspaceReadError("changed-during-read", "Workspace file changed during inspection");
+  }
+}
+
+export function inspectWorkspaceEntry(repoRoot: string, repoPath: string): fs.Stats {
+  const candidate = safeCandidate(repoRoot, repoPath);
+  return fs.lstatSync(candidate.absolute);
+}
+
+export function readWorkspaceLink(repoRoot: string, repoPath: string): string {
+  const candidate = safeCandidate(repoRoot, repoPath);
+  const before = fs.lstatSync(candidate.absolute);
+  if (!before.isSymbolicLink()) throw new WorkspaceReadError("not-file", "Workspace entry is not a symbolic link");
+  const target = fs.readlinkSync(candidate.absolute);
+  const after = fs.lstatSync(candidate.absolute);
+  if (!sameFile(before, after) || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) {
+    throw new WorkspaceReadError("changed-during-read", "Workspace link changed during inspection");
+  }
+  return target;
+}
+
+export function readWorkspaceFile(repoRoot: string, repoPath: string, maxBytes: number): Buffer {
+  const opened = openRegularFile(repoRoot, repoPath);
+  try {
+    if (opened.stat.size > maxBytes) throw new WorkspaceReadError("oversized", "Workspace file exceeds its read cap");
+    const content = Buffer.allocUnsafe(opened.stat.size);
+    let position = 0;
+    while (position < content.length) {
+      const count = fs.readSync(opened.descriptor, content, position, content.length - position, position);
+      if (count <= 0) throw new WorkspaceReadError("changed-during-read", "Workspace file ended during inspection");
+      position += count;
+    }
+    verifyAfterRead(opened.descriptor, opened.stat, opened.candidate);
+    return content;
+  } finally {
+    fs.closeSync(opened.descriptor);
+  }
+}
+
+export function hashWorkspaceFile(repoRoot: string, repoPath: string): string {
+  const opened = openRegularFile(repoRoot, repoPath);
+  try {
+    const state = createHash("sha256");
+    const buffer = Buffer.allocUnsafe(256 * 1024);
+    let position = 0;
+    while (position < opened.stat.size) {
+      const count = fs.readSync(opened.descriptor, buffer, 0, Math.min(buffer.length, opened.stat.size - position), position);
+      if (count <= 0) throw new WorkspaceReadError("changed-during-read", "Workspace file ended during hashing");
+      state.update(buffer.subarray(0, count));
+      position += count;
+    }
+    verifyAfterRead(opened.descriptor, opened.stat, opened.candidate);
+    return state.digest("hex");
+  } finally {
+    fs.closeSync(opened.descriptor);
+  }
+}

package/packages/piagent-core/runtime/inspection/workspace-source-projection.ts

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+
+import {
+  collectSourceChangeViews,
+  type SourceChangeDocument,
+  type SourceChangeViews,
+  type SourceProjectionOptions
+} from "./source-change-projection.ts";
+
+export type WorkspaceSourceProjectionOptions = Omit<SourceProjectionOptions, "cwd" | "pageLimit"> & {
+  roots: string[];
+  pageLimit?: number;
+};
+
+function token(prefix: string, value: string): string {
+  return `${prefix}.${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function combineDocuments(
+  documents: SourceChangeDocument[],
+  view: SourceChangeDocument["view"],
+  pageLimit: number
+): SourceChangeDocument {
+  const template = structuredClone(documents[0]);
+  const viewRevision = token("workspace-view", JSON.stringify(documents.map((document) => document.viewRevision)));
+  const bases = documents.flatMap((document) => document.bases as Array<Record<string, unknown>>);
+  const states = documents.map((document) => document.availability.state);
+  const anyUnavailable = states.includes("unavailable");
+  const anyStale = states.includes("stale");
+  const exact = !anyUnavailable && !anyStale;
+  const allFiles = exact
+    ? documents.flatMap((document) => document.files).sort((left, right) => {
+        const repo = String(left.repoRef).localeCompare(String(right.repoRef), "en");
+        return repo || String(left.path).localeCompare(String(right.path), "en");
+      })
+    : [];
+  const files = allFiles.slice(0, pageLimit);
+  const childTruncated = documents.some((document) => (document.page as any).truncated === true);
+  const rawTotal = exact ? documents.reduce((total, document) => total + Number((document.page as any).total ?? 0), 0) : 0;
+  const total = Math.min(1_000_000, rawTotal);
+  const truncated = exact && (childTruncated || files.length < allFiles.length || rawTotal > total);
+  const reasonCode = anyUnavailable ? "repository-view-unavailable" : anyStale ? "git-race" : null;
+  const rawRemoved = documents.reduce((sum, document) => sum + Number((document.redaction as any).valuesRemoved ?? 0), 0);
+  const valuesRemoved = Math.min(10_000, rawRemoved);
+  return {
+    ...template,
+    view,
+    viewRevision,
+    bases,
+    availability: exact
+      ? { state: "current", reasonCode: null, message: null }
+      : anyUnavailable
+        ? { state: "unavailable", reasonCode, message: "At least one repository view is unavailable" }
+        : { state: "stale", reasonCode, message: "At least one repository changed during collection" },
+    files,
+    page: {
+      cursor: null,
+      nextCursor: truncated ? token("workspace-page", `${viewRevision}:${pageLimit}`) : null,
+      total,
+      returned: files.length,
+      truncated
+    },
+    truncationReason: truncated ? "page-limit" : null,
+    redaction: {
+      applied: documents.some((document) => (document.redaction as any).applied === true),
+      valuesRemoved,
+      truncated: rawRemoved > valuesRemoved || documents.some((document) => (document.redaction as any).truncated === true)
+    },
+    health: exact
+      ? documents.some((document) => (document.health as any).state !== "ok")
+        ? { state: "degraded", reasonCode: "repository-view-degraded", message: "At least one repository view is degraded" }
+        : { state: "ok", reasonCode: null, message: null }
+      : anyUnavailable
+        ? { state: "unavailable", reasonCode, message: "At least one repository view is unavailable" }
+        : { state: "degraded", reasonCode, message: "At least one repository view is stale" },
+    issues: documents.flatMap((document) => document.issues as Array<Record<string, unknown>>).slice(0, 64)
+  };
+}
+
+export async function collectWorkspaceSourceChangeViews(options: WorkspaceSourceProjectionOptions): Promise<SourceChangeViews> {
+  const roots = [...new Set(options.roots)];
+  if (roots.length === 0) throw new Error("At least one workspace Git root is required");
+  if (roots.length > 32) throw new Error("Workspace source projection supports at most 32 Git roots");
+  const pageLimit = Number.isInteger(options.pageLimit) ? Math.max(1, Math.min(2_000, options.pageLimit as number)) : 300;
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+  const raw = await Promise.all(roots.map((cwd) => collectSourceChangeViews({ ...options, cwd, pageLimit: 2_000, generatedAt })));
+  const collected = [...new Map(raw.map((views) => [String((views.workingTree.bases as any[])[0]?.repoRef), views])).values()];
+  const working = collected.map((views) => views.workingTree);
+  const staged = collected.map((views) => views.staged);
+  const task = collected.map((views) => views.task).filter((document): document is SourceChangeDocument => document !== null);
+  return {
+    workingTree: combineDocuments(working, "working-tree", pageLimit),
+    staged: combineDocuments(staged, "staged", pageLimit),
+    task: task.length === collected.length ? combineDocuments(task, "task", pageLimit) : null
+  };
+}

package/packages/piagent-core/runtime/inspection/zero-turn-conformance.ts

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+
+export const ZERO_TURN_CONFORMANCE_VERSION = "piagent-webui-zero-turn-v1" as const;
+
+const EFFECT_KEYS = [
+  "providerRequests", "userMessages", "assistantMessages", "inputTokens", "outputTokens",
+  "cacheReadTokens", "cacheWriteTokens", "costMicros", "continuationConsumed", "turnTriggers"
+] as const;
+type EffectKey = typeof EFFECT_KEYS[number];
+export type ZeroTurnEffects = Record<EffectKey, number>;
+export type ZeroTurnCausalEvent = {
+  sequence: number;
+  correlationId: string | null;
+  attribution: "ui-command" | "unrelated-operation" | "unknown";
+  effects: Partial<ZeroTurnEffects>;
+};
+export type ZeroTurnObservation = {
+  providerRequests: number;
+  userMessages: number;
+  assistantMessages: number;
+  usage: { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number; costMicros: number };
+  continuationConsumed: number;
+  turnTriggers: number;
+  sessionRef: string;
+  leafMessageRef: string | null;
+  messageSetDigest: string;
+  taskContractDigest: string | null;
+  journalHead: string | null;
+  promptDigest: string;
+  toolSchemaDigest: string;
+  latestCausalSequence: number;
+  causalEvents: ZeroTurnCausalEvent[];
+};
+export type ZeroTurnOptions = {
+  action: string;
+  commandId: string;
+  concurrency: "quiescent" | "concurrent";
+  mutationClass: "view" | "control";
+  allowedDigestChanges?: Array<"taskContractDigest" | "journalHead">;
+};
+export type ZeroTurnReport<T = unknown> = {
+  version: typeof ZERO_TURN_CONFORMANCE_VERSION;
+  passed: boolean;
+  action: string;
+  commandId: string;
+  concurrency: ZeroTurnOptions["concurrency"];
+  mutationClass: ZeroTurnOptions["mutationClass"];
+  violations: string[];
+  delta: ZeroTurnEffects;
+  result?: T;
+};
+
+const REF = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+
+function hash(value: string): string { return createHash("sha256").update(value).digest("hex"); }
+function plain(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function canonical(value: unknown, seen = new Set<object>()): unknown {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (Array.isArray(value)) {
+    if (seen.has(value)) throw new Error("Cyclic value cannot be digested");
+    seen.add(value); const output = value.map((item) => canonical(item, seen)); seen.delete(value); return output;
+  }
+  if (!plain(value)) throw new Error("Only JSON-compatible facts can be digested");
+  if (seen.has(value)) throw new Error("Cyclic value cannot be digested");
+  seen.add(value);
+  const output = Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key], seen)]));
+  seen.delete(value); return output;
+}
+function nonnegativeInteger(value: unknown): value is number {
+  return Number.isInteger(value) && (value as number) >= 0 && (value as number) <= Number.MAX_SAFE_INTEGER;
+}
+function zeroEffects(): ZeroTurnEffects {
+  return { providerRequests: 0, userMessages: 0, assistantMessages: 0, inputTokens: 0, outputTokens: 0,
+    cacheReadTokens: 0, cacheWriteTokens: 0, costMicros: 0, continuationConsumed: 0, turnTriggers: 0 };
+}
+function counters(value: ZeroTurnObservation): ZeroTurnEffects {
+  return { providerRequests: value.providerRequests, userMessages: value.userMessages, assistantMessages: value.assistantMessages,
+    inputTokens: value.usage.inputTokens, outputTokens: value.usage.outputTokens, cacheReadTokens: value.usage.cacheReadTokens,
+    cacheWriteTokens: value.usage.cacheWriteTokens, costMicros: value.usage.costMicros,
+    continuationConsumed: value.continuationConsumed, turnTriggers: value.turnTriggers };
+}
+function observationErrors(value: ZeroTurnObservation): string[] {
+  const errors: string[] = [], values = counters(value);
+  for (const key of EFFECT_KEYS) if (!nonnegativeInteger(values[key])) errors.push(`invalid-observation:${key}`);
+  if (!REF.test(value.sessionRef) || !(value.leafMessageRef === null || REF.test(value.leafMessageRef))) errors.push("invalid-observation:session-identity");
+  for (const [key, digest] of [["messageSetDigest", value.messageSetDigest], ["promptDigest", value.promptDigest], ["toolSchemaDigest", value.toolSchemaDigest]] as const) {
+    if (!DIGEST.test(digest)) errors.push(`invalid-observation:${key}`);
+  }
+  for (const [key, digest] of [["taskContractDigest", value.taskContractDigest], ["journalHead", value.journalHead]] as const) {
+    if (!(digest === null || DIGEST.test(digest) || REF.test(digest))) errors.push(`invalid-observation:${key}`);
+  }
+  if (!nonnegativeInteger(value.latestCausalSequence)) errors.push("invalid-observation:causal-sequence");
+  let previous = -1;
+  for (const event of value.causalEvents) {
+    if (!nonnegativeInteger(event.sequence) || event.sequence <= previous || event.sequence > value.latestCausalSequence) errors.push("invalid-observation:causal-event-order");
+    previous = event.sequence;
+    if (!(event.correlationId === null || REF.test(event.correlationId)) || !["ui-command", "unrelated-operation", "unknown"].includes(event.attribution)) errors.push("invalid-observation:causal-event-identity");
+    for (const [key, effect] of Object.entries(event.effects)) {
+      if (!EFFECT_KEYS.includes(key as EffectKey) || !nonnegativeInteger(effect)) errors.push(`invalid-observation:causal-effect:${key}`);
+    }
+  }
+  return errors;
+}
+
+export function digestZeroTurnFact(domain: string, value: unknown): string {
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(domain)) throw new Error("Invalid fact digest domain");
+  return `sha256:${hash(`piagent-webui-zero-turn:${domain}\n${JSON.stringify(canonical(value))}`)}`;
+}
+
+export function providerVisibleToolSchemaDigest(tools: Array<{ name: string; description?: string; parameters?: unknown }>): string {
+  const projected = tools.map((tool) => {
+    if (!REF.test(tool.name)) throw new Error(`Invalid provider-visible tool name: ${tool.name}`);
+    return { name: tool.name, description: String(tool.description ?? ""), parameters: canonical(tool.parameters ?? {}) };
+  }).sort((left, right) => left.name.localeCompare(right.name));
+  if (new Set(projected.map((tool) => tool.name)).size !== projected.length) throw new Error("Provider-visible tool names must be unique");
+  return digestZeroTurnFact("tool-schema", projected);
+}
+
+export function evaluateZeroTurn<T>(options: ZeroTurnOptions, before: ZeroTurnObservation, after: ZeroTurnObservation, result?: T): ZeroTurnReport<T> {
+  const violations = [...observationErrors(before).map((error) => `before:${error}`), ...observationErrors(after).map((error) => `after:${error}`)];
+  const beforeCounters = counters(before), afterCounters = counters(after), delta = zeroEffects();
+  for (const key of EFFECT_KEYS) {
+    delta[key] = afterCounters[key] - beforeCounters[key];
+    if (delta[key] < 0) violations.push(`counter-regressed:${key}`);
+  }
+  if (after.latestCausalSequence < before.latestCausalSequence) violations.push("causal-sequence-regressed");
+  const events = after.causalEvents.filter((event) => event.sequence > before.latestCausalSequence);
+  if (events.some((event) => event.sequence > after.latestCausalSequence)) violations.push("causal-event-after-observation");
+  if (options.concurrency === "quiescent") {
+    for (const key of EFFECT_KEYS) if (delta[key] !== 0) violations.push(`quiescent-counter-changed:${key}`);
+    if (events.some((event) => EFFECT_KEYS.some((key) => (event.effects[key] ?? 0) > 0))) violations.push("quiescent-causal-effect-observed");
+  } else {
+    const reconciled = zeroEffects();
+    for (const event of events) {
+      for (const key of EFFECT_KEYS) reconciled[key] += event.effects[key] ?? 0;
+      if (EFFECT_KEYS.some((key) => (event.effects[key] ?? 0) > 0)
+        && (event.attribution !== "unrelated-operation" || event.correlationId === options.commandId)) violations.push(`prohibited-causal-attribution:${event.sequence}`);
+    }
+    for (const key of EFFECT_KEYS) if (reconciled[key] !== delta[key]) violations.push(`unreconciled-concurrent-delta:${key}`);
+  }
+  if (before.sessionRef !== after.sessionRef) violations.push("session-replaced");
+  const unrelatedMessagesSettled = options.concurrency === "concurrent" && delta.userMessages + delta.assistantMessages > 0;
+  if (before.leafMessageRef !== after.leafMessageRef && !unrelatedMessagesSettled) violations.push("leaf-message-changed");
+  if (before.messageSetDigest !== after.messageSetDigest && !unrelatedMessagesSettled) violations.push("message-set-changed");
+  if (before.promptDigest !== after.promptDigest) violations.push("prompt-changed");
+  if (before.toolSchemaDigest !== after.toolSchemaDigest) violations.push("provider-tool-schema-changed");
+  const allowed = new Set(options.allowedDigestChanges ?? []);
+  if (before.taskContractDigest !== after.taskContractDigest && !allowed.has("taskContractDigest")) violations.push("task-contract-changed");
+  if (before.journalHead !== after.journalHead && !allowed.has("journalHead")) violations.push("journal-head-changed");
+  if (options.mutationClass === "view" && allowed.size > 0) violations.push("view-action-cannot-allow-authoritative-mutation");
+  return { version: ZERO_TURN_CONFORMANCE_VERSION, passed: violations.length === 0, action: options.action, commandId: options.commandId,
+    concurrency: options.concurrency, mutationClass: options.mutationClass, violations: [...new Set(violations)], delta, ...(result === undefined ? {} : { result }) };
+}
+
+export async function runZeroTurnConformance<T>(
+  options: ZeroTurnOptions,
+  observe: () => ZeroTurnObservation | Promise<ZeroTurnObservation>,
+  action: () => T | Promise<T>
+): Promise<ZeroTurnReport<T>> {
+  const before = structuredClone(await observe());
+  let result: T;
+  try { result = await action(); } catch (error) {
+    const after = structuredClone(await observe());
+    const report = evaluateZeroTurn<T>(options, before, after);
+    return { ...report, passed: false, violations: [...report.violations, `action-failed:${error instanceof Error ? error.name : "unknown"}`] };
+  }
+  const after = structuredClone(await observe());
+  return evaluateZeroTurn(options, before, after, result);
+}

package/packages/piagent-core/runtime/orchestration/owned-work-budget.ts

@@ -13,15 +13,19 @@ export const AUTOMATIC_OWNED_WORK_CEILINGS: OwnedWorkCeilings = Object.freeze({
 const LOCK_WAIT_MS = 5;
 const LOCK_WAIT_CEILING_MS = 250;
 const STALE_LOCK_MS = 30_000;
-type Reservation = { id: string; deduplicationKey: string; role: HelperRole; authority: string; status: "active" | "succeeded" | "failed" | "cancelled" | "orphaned"; reservedAt: string; expiresAt: string; completedAt: string | null; usageRef: { calls: number; tokens: number; outputDigest: string | null } | null };
-type BudgetState = { version: typeof OWNED_WORK_BUDGET_VERSION; taskId: string; taskRunId: string; terminal: boolean; reservations: Reservation[]; updatedAt: string };
-export type HelperReleaseResult = { accepted: boolean; status: Reservation["status"] | "stale"; reason: "released" | "helper-call-budget-exceeded" | "helper-token-budget-exceeded" | "reservation-not-active" };
+export type OwnedWorkReservation = { id: string; deduplicationKey: string; role: HelperRole; authority: "read-only" | "single-writer"; status: "active" | "succeeded" | "failed" | "cancelled" | "orphaned"; reservedAt: string; expiresAt: string; completedAt: string | null; usageRef: { calls: number; tokens: number; outputDigest: string | null } | null };
+type BudgetState = { version: typeof OWNED_WORK_BUDGET_VERSION; taskId: string; taskRunId: string; terminal: boolean; reservations: OwnedWorkReservation[]; updatedAt: string };
+export type OwnedWorkBudgetInspection = {
+  state: "missing" | "ready" | "corrupt"; terminal: boolean | null; reservations: OwnedWorkReservation[];
+  updatedAt: string | null; derivedOrphans: number; reasonCode: string | null;
+};
+export type HelperReleaseResult = { accepted: boolean; status: OwnedWorkReservation["status"] | "stale"; reason: "released" | "helper-call-budget-exceeded" | "helper-token-budget-exceeded" | "reservation-not-active" };
 
 function digest(value: unknown): string { return crypto.createHash("sha256").update(String(value ?? "")).digest("hex"); }
 function statePath(cwd: string, taskRunId: string): string { return path.join(cwd, ".pi", "piagent-state", "helper-budgets", `${safeTaskId(taskRunId)}.json`); }
 function lockPath(cwd: string, taskRunId: string): string { return `${statePath(cwd, taskRunId)}.lock`; }
 function empty(request: HelperRequest, now: string): BudgetState { return { version: OWNED_WORK_BUDGET_VERSION, taskId: request.taskId, taskRunId: request.taskRunId, terminal: false, reservations: [], updatedAt: now }; }
-function active(state: BudgetState): Reservation[] { return state.reservations.filter((item) => item.status === "active"); }
+function active(state: BudgetState): OwnedWorkReservation[] { return state.reservations.filter((item) => item.status === "active"); }
 function roleLimit(role: HelperRole): number { return role === "scout" || role === "retriever" || role === "researcher" ? 1 : role === "planner" ? 1 : role === "reviewer" ? 1 : role === "oracle" ? 1 : role === "worker" ? 1 : 0; }
 
 function read(cwd: string, request: HelperRequest, now: string): BudgetState {
@@ -63,6 +67,66 @@ function recoverOrphans(state: BudgetState, now: string): number {
   return recovered;
 }
 
+function exactTimestamp(value: unknown): value is string {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)
+    && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+function exactFields(value: Record<string, unknown>, fields: string[]): boolean {
+  return Object.keys(value).length === fields.length && fields.every((field) => field in value);
+}
+function validInspectionState(value: unknown, taskId: string, taskRunId: string): value is BudgetState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const state = value as Record<string, any>;
+  if (!exactFields(state, ["version", "taskId", "taskRunId", "terminal", "reservations", "updatedAt"])
+    || state.version !== OWNED_WORK_BUDGET_VERSION || state.taskId !== taskId || state.taskRunId !== taskRunId
+    || typeof state.terminal !== "boolean" || !exactTimestamp(state.updatedAt) || !Array.isArray(state.reservations)
+    || state.reservations.length > 64) return false;
+  const ids = new Set<string>(); let activeWriters = 0;
+  for (const item of state.reservations) {
+    if (!item || typeof item !== "object" || Array.isArray(item)
+      || !exactFields(item, ["id", "deduplicationKey", "role", "authority", "status", "reservedAt", "expiresAt", "completedAt", "usageRef"])
+      || typeof item.id !== "string" || !/^[a-f0-9]{32}$/.test(item.id) || ids.has(item.id)
+      || typeof item.deduplicationKey !== "string" || !/^[a-f0-9]{64}$/.test(item.deduplicationKey)
+      || !["retriever", "scout", "planner", "worker", "reviewer", "oracle", "researcher"].includes(item.role)
+      || !["read-only", "single-writer"].includes(item.authority)
+      || !["active", "succeeded", "failed", "cancelled", "orphaned"].includes(item.status)
+      || !exactTimestamp(item.reservedAt) || !exactTimestamp(item.expiresAt) || Date.parse(item.expiresAt) < Date.parse(item.reservedAt)
+      || item.completedAt !== null && !exactTimestamp(item.completedAt)
+      || item.status === "active" && item.completedAt !== null || item.status !== "active" && item.completedAt === null) return false;
+    ids.add(item.id); if (item.status === "active" && item.authority === "single-writer") activeWriters += 1;
+    if (item.usageRef !== null) {
+      if (typeof item.usageRef !== "object" || Array.isArray(item.usageRef)
+        || !exactFields(item.usageRef, ["calls", "tokens", "outputDigest"])
+        || !Number.isInteger(item.usageRef.calls) || item.usageRef.calls < 0 || item.usageRef.calls > 101
+        || !Number.isInteger(item.usageRef.tokens) || item.usageRef.tokens < 0 || item.usageRef.tokens > 100001
+        || item.usageRef.outputDigest !== null && (typeof item.usageRef.outputDigest !== "string" || !/^[a-f0-9]{64}$/.test(item.usageRef.outputDigest))) return false;
+    }
+  }
+  return activeWriters <= 1 && (!state.terminal || !state.reservations.some((item: any) => item.status === "active"));
+}
+
+/** Read-only projection input. It never repairs, locks, or writes helper state. */
+export function inspectOwnedWorkBudget(cwd: string, taskId: string, taskRunId: string, now = new Date().toISOString()): OwnedWorkBudgetInspection {
+  try {
+    if (!exactTimestamp(now)) return { state: "corrupt", terminal: null, reservations: [], updatedAt: null, derivedOrphans: 0, reasonCode: "invalid-inspection-time" };
+    const target = statePath(cwd, taskRunId); if (!fs.existsSync(target)) return { state: "missing", terminal: null, reservations: [], updatedAt: null, derivedOrphans: 0, reasonCode: "helper-budget-missing" };
+    const resolved = resolveLocalStatePath(cwd, target, { label: "Helper budget state", kind: "file" });
+    const descriptor = fs.openSync(resolved, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0)); let value;
+    try {
+      const before = fs.fstatSync(descriptor, { bigint: true }); if (!before.isFile() || before.size > BigInt(1024 * 1024)) throw new Error("helper-budget-size");
+      value = JSON.parse(fs.readFileSync(descriptor, "utf8")); const after = fs.fstatSync(descriptor, { bigint: true });
+      const fields = ["dev", "ino", "mode", "size", "mtimeNs", "ctimeNs"] as const;
+      if (fields.some((field) => before[field] !== after[field])) throw new Error("helper-budget-changed");
+    } finally { fs.closeSync(descriptor); }
+    if (!validInspectionState(value, taskId, taskRunId)) return { state: "corrupt", terminal: null, reservations: [], updatedAt: null, derivedOrphans: 0, reasonCode: "helper-budget-invalid" };
+    const clone = structuredClone(value), derivedOrphans = recoverOrphans(clone, now);
+    return { state: "ready", terminal: clone.terminal, reservations: clone.reservations, updatedAt: clone.updatedAt, derivedOrphans,
+      reasonCode: derivedOrphans ? "expired-helper-derived-orphan" : null };
+  } catch {
+    return { state: "corrupt", terminal: null, reservations: [], updatedAt: null, derivedOrphans: 0, reasonCode: "helper-budget-unreadable" };
+  }
+}
+
 export class OwnedWorkBudgetController {
   reserve(cwd: string, requestInput: HelperRequest, now = new Date().toISOString(), ceilings: OwnedWorkCeilings = DEFAULT_OWNED_WORK_CEILINGS): { decision: "reserved" | "duplicate" | "blocked"; reason: string; reservationId: string | null; recoveredOrphans: number } {
     const request = validateHelperRequest(structuredClone(requestInput));