pi-extended-teams 2.2.10 → 2.3.0

package/src/results/completion-group-delivery.ts

@@ -0,0 +1,66 @@
+import { isDeepStrictEqual } from "node:util";
+import * as messaging from "../utils/messaging";
+import { resyncStoredTeamReportEvent } from "../utils/report-events";
+import type { TeamReportEvent } from "../utils/models";
+import { effectiveTaskOutcome } from "./report-result";
+import { CompletionGroup, type CompletionGroupState } from "./completion-group";
+
+type GroupMember = CompletionGroupState["members"][number];
+const compact = (text: string | undefined, limit = 400) => text && text.length > limit ? `${text.slice(0, limit)}…` : text;
+
+function assertReportBinding(group: CompletionGroup, member: GroupMember, event: TeamReportEvent): void {
+  if (event.teamName !== group.teamName || event.agentName !== member.name || !event.result
+    || event.result.reportId !== event.id || event.result.runId !== member.runId
+    || !isDeepStrictEqual(event.completionGroup, { groupId: group.groupId, slotId: member.slotId })) {
+    throw new Error("Completion report provenance binding has changed.");
+  }
+}
+
+async function indexMember(group: CompletionGroup, member: GroupMember) {
+  const identity = { name: member.name, slotId: member.slotId, status: member.status, runId: member.runId };
+  if (!member.report) return { ...identity, reason: compact(member.reason) };
+  const event = await resyncStoredTeamReportEvent(group.teamName, member.report.reportId);
+  assertReportBinding(group, member, event);
+  const result = event.result!;
+  if (result.outcome !== member.report.outcome || effectiveTaskOutcome(result) !== member.report.effectiveOutcome
+    || result.verification.state !== member.report.verification || event.status !== member.report.runtimeStatus) {
+    throw new Error("Completion report evidence differs from its receipt.");
+  }
+  return { ...identity, taskId: result.taskId, runtimeStatus: event.status, role: event.role, summary: compact(event.summary),
+    outcome: result.outcome, effectiveOutcome: effectiveTaskOutcome(result), verification: result.verification,
+    acceptance: result.acceptance, findings: result.findings?.map(finding => ({ ...finding, text: compact(finding.text) })),
+    questions: result.questions, report: { id: event.id, path: event.reportPath } };
+}
+
+export async function enqueueCompletionGroupDeliveries(group: CompletionGroup): Promise<number> {
+  let enqueued = 0;
+  for (const delivery of await group.prepareDeliveries()) {
+    const state = group.read();
+    const members = await Promise.all(delivery.slotIds.map(slotId => {
+      const member = state.members.find(candidate => candidate.slotId === slotId);
+      if (!member || member.suppressed) throw new Error("Invalid completion index member.");
+      return indexMember(group, member);
+    }));
+    const index = { version: 1, groupId: group.groupId, deliveryId: delivery.id, kind: delivery.kind, members };
+    const receipt = await messaging.sendPlainMessageOnce(group.teamName, "system", "team-lead", JSON.stringify(index),
+      `Completion group ${delivery.kind}: ${members.length} result(s)`, { id: delivery.id, operationId: delivery.id,
+        metadata: { finalReport: true, completionGroup: { groupId: group.groupId, deliveryId: delivery.id, journalPath: group.journalPath } } });
+    await group.markEnqueued(delivery.id);
+    if (receipt.delivered) enqueued++;
+  }
+  return enqueued;
+}
+
+export async function deliverCompletionGroupReport(event: TeamReportEvent, onDurableReport?: () => void): Promise<boolean> {
+  const binding = event.completionGroup;
+  if (!binding) return false;
+  const stored = await resyncStoredTeamReportEvent(event.teamName, event.id);
+  const group = new CompletionGroup(event.teamName, binding.groupId);
+  const member = group.read().members.find(candidate => candidate.slotId === binding.slotId);
+  if (!member) throw new Error("Unknown completion report slot.");
+  assertReportBinding(group, member, stored);
+  onDurableReport?.();
+  await group.recordReport(binding.slotId, stored.result!, stored.status);
+  await enqueueCompletionGroupDeliveries(group);
+  return true;
+}

package/src/results/completion-group-recovery.ts

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+import * as paths from "../utils/paths";
+import { peekInbox } from "../utils/messaging";
+import { listStoredTeamReportEvents } from "../utils/report-events";
+import type { Member } from "../utils/models";
+import { CompletionGroup } from "./completion-group";
+import { deliverCompletionGroupReport, enqueueCompletionGroupDeliveries } from "./completion-group-delivery";
+
+type Reference = { session?: string; completionGroup?: { groupId?: string; teamName?: string } };
+type HistoryReference = { type?: string; details?: Reference; message?: { role?: string; toolName?: string; details?: Reference } };
+export async function recoverCompletionGroups(
+  teamName: string, sessionId: string, members: readonly Pick<Member, "name" | "lifecycleRunId" | "completionGroup">[],
+  entries: readonly HistoryReference[], currentGroupIds: ReadonlySet<string>,
+): Promise<string[]> {
+  const root = paths.teamDir(teamName);
+  const directory = path.join(root, "completion-groups");
+  const reports = fs.existsSync(path.join(root, "reports.json")) ? await listStoredTeamReportEvents(teamName) : [];
+  const inbox = await peekInbox(teamName, "team-lead");
+  const ids = new Set(fs.existsSync(directory) ? fs.readdirSync(directory)
+    .filter(file => /^[a-f0-9]{64}\.json$/.test(file)).map(file => `group:${file.slice(0, -5)}`) : []);
+  const references = [...members.map(member => member.completionGroup), ...reports.map(report => report.completionGroup),
+    ...inbox.map(message => message.metadata?.completionGroup), ...entries.flatMap(entry => [
+      entry.type === "custom_message" && entry.details?.completionGroup?.teamName === teamName ? entry.details.completionGroup : undefined,
+      entry.message?.role === "toolResult" && entry.message.toolName === "spawn_swarm_agents" && entry.message.details?.session === teamName
+        ? entry.message.details.completionGroup : undefined])];
+  for (const reference of references) if (reference?.groupId) ids.add(reference.groupId);
+  const errors: string[] = [];
+  for (const id of ids) {
+    try {
+      const group = new CompletionGroup(teamName, id);
+      const state = group.read();
+      if (state.sessionId !== sessionId || currentGroupIds.has(id)) continue;
+      for (const slot of state.members) {
+        if (["cancelled", "interrupted", "rejected"].includes(slot.status)) continue;
+        const owner = members.find(member => member.name === slot.name
+          && member.completionGroup?.groupId === id && member.completionGroup.slotId === slot.slotId);
+        if (!slot.runId && owner?.lifecycleRunId) {
+          await group.apply({ type: "running", slotId: slot.slotId, runId: owner.lifecycleRunId });
+        }
+        const current = group.read().members.find(member => member.slotId === slot.slotId)!;
+        const report = reports.find(event => event.agentName === current.name && event.result?.runId === current.runId
+          && event.completionGroup?.groupId === id && event.completionGroup.slotId === current.slotId);
+        if (report) await deliverCompletionGroupReport(report);
+        else if (["pending", "queued"].includes(current.status) && !owner) {
+          await group.apply({ type: "interrupted", slotId: current.slotId,
+            reason: "Assignment was not retained across extension reload; no work was restarted." });
+        } else if (current.status === "reported") throw new Error(`Full grouped report is unavailable: ${current.report?.reportId}.`);
+        else errors.push(`Completion group ${id}: ${current.name} (${current.runId ?? "unbound"}) remains unresolved after reload; no work was restarted.`);
+      }
+      await group.seal();
+      await enqueueCompletionGroupDeliveries(group);
+      for (const delivery of group.read().deliveries) if (delivery.wake?.state === "pending") {
+        errors.push(`Completion group wake is unconfirmed (${delivery.id}). Use read_inbox for the saved index; no automatic retry. Journal: ${group.journalPath}`);
+      }
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return errors;
+}

package/src/results/completion-group-wake.ts

@@ -0,0 +1,62 @@
+import { findInboxMessageByOperation, markInboxMessagesRead } from "../utils/messaging";
+import type { InboxMessage } from "../utils/models";
+import { CompletionGroup } from "./completion-group";
+
+type WakeBinding = { teamName: string; groupId: string; deliveryId: string };
+export interface CompletionWakeEntry {
+  type: string; id: string; customType?: string; content?: unknown;
+  details?: { completionGroup?: WakeBinding };
+}
+const wakeContent = (message: InboxMessage) => `Completion group index:\n${message.text}\nUse the referenced full reports as needed, integrate the evidence, and continue the active task. Group settlement is not task success or lead acceptance. Do not stop self-exiting reporting agents.`;
+
+async function boundIndex(teamName: string, sessionId: string, binding: Pick<WakeBinding, "groupId" | "deliveryId">) {
+  const group = new CompletionGroup(teamName, binding?.groupId);
+  const state = group.read();
+  const delivery = state.deliveries.find(item => item.id === binding.deliveryId);
+  const message = await findInboxMessageByOperation(teamName, "team-lead", binding.deliveryId);
+  if (state.sessionId !== sessionId || delivery?.status !== "enqueued" || !message
+    || message.id !== delivery.id || message.operationId !== delivery.id
+    || message.metadata?.completionGroup?.groupId !== group.groupId
+    || message.metadata?.completionGroup?.deliveryId !== delivery.id) {
+    throw new Error("Completion wake index binding is unavailable or changed.");
+  }
+  return { group, delivery, message };
+}
+
+export async function requestCompletionGroupWake(
+  teamName: string, sessionId: string, message: InboxMessage,
+  send: (content: string, details: { completionGroup: WakeBinding }) => void,
+): Promise<boolean> {
+  const binding = message.metadata?.completionGroup as WakeBinding;
+  const bound = await boundIndex(teamName, sessionId, binding);
+  if (message.id !== bound.message.id || message.text !== bound.message.text) throw new Error("Completion wake message binding has changed.");
+  if (!await bound.group.reserveWake(binding.deliveryId)) return false;
+  try {
+    send(wakeContent(bound.message), { completionGroup: { teamName, groupId: bound.group.groupId, deliveryId: binding.deliveryId } });
+  } catch (error) {
+    await bound.group.recordWakeEvidence(binding.deliveryId, { error: error instanceof Error ? error.message : String(error) });
+    throw error;
+  }
+  return true;
+}
+
+export async function observeCompletionGroupWakes(
+  teamName: string, sessionId: string, entries: readonly CompletionWakeEntry[],
+): Promise<{ observed: string[]; errors: string[] }> {
+  const observed: string[] = [];
+  const errors: string[] = [];
+  for (const entry of entries) {
+    const binding = entry.details?.completionGroup;
+    if (entry.type !== "custom_message" || entry.customType !== "pi-extended-teams-wake" || binding?.teamName !== teamName) continue;
+    try {
+      const bound = await boundIndex(teamName, sessionId, binding);
+      if (entry.content !== wakeContent(bound.message)) throw new Error("Completion wake history binding has changed.");
+      await bound.group.recordWakeEvidence(binding.deliveryId, { entryId: entry.id });
+      await markInboxMessagesRead(teamName, "team-lead", [binding.deliveryId]);
+      observed.push(entry.id);
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return { observed, errors };
+}

package/src/results/completion-group.ts

@@ -0,0 +1,290 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import * as paths from "../utils/paths";
+import { withLock } from "../utils/lock";
+import { createReportResult, effectiveTaskOutcome, ReportedTaskDetailsSchema, type ReportResult } from "./report-result";
+import { syncPathAndParents, writeJsonDurably } from "./durable-json";
+
+const reference = Type.String({ minLength: 1 });
+const variants = <T extends string>(...values: T[]) => Type.Union(values.map(value => Type.Literal(value)));
+export const CompletionGroupPolicySchema = Type.Object({
+  delivery: variants("immediate", "all-settled"),
+}, { additionalProperties: false });
+export type CompletionGroupPolicy = Static<typeof CompletionGroupPolicySchema>;
+export function normalizeCompletionGroupPolicy(value: unknown): CompletionGroupPolicy | undefined {
+  if (value === undefined) return undefined;
+  if (!Value.Check(CompletionGroupPolicySchema, value)) throw new Error("Invalid completion group policy.");
+  return structuredClone(value);
+}
+const SeedSchema = Type.Object({
+  name: reference, suppressed: Type.Optional(Type.Boolean()), assignmentKey: Type.Optional(reference),
+}, { additionalProperties: false });
+const seed = (member: Static<typeof SeedSchema>) => ({
+  name: member.name, suppressed: member.suppressed === true,
+  ...(member.assignmentKey ? { assignmentKey: member.assignmentKey } : {}),
+});
+const OptionsSchema = Type.Object({
+  teamName: reference, sessionId: reference, submissionId: reference,
+  policy: CompletionGroupPolicySchema, members: Type.Array(SeedSchema, { minItems: 1 }),
+}, { additionalProperties: false });
+export interface CompletionGroupOptions extends Omit<Static<typeof OptionsSchema>, "policy"> {
+  policy?: CompletionGroupPolicy;
+}
+export interface CompletionGroupBinding { groupId: string; slotId: string; }
+const ReportSchema = Type.Object({
+  runId: reference, reportId: reference, runtimeStatus: Type.Optional(variants("completed", "failed")),
+  outcome: ReportedTaskDetailsSchema.properties.outcome,
+  effectiveOutcome: ReportedTaskDetailsSchema.properties.outcome,
+  verification: variants("not-requested", "pending", "passed", "failed", "stale"),
+}, { additionalProperties: false });
+const MemberSchema = Type.Object({
+  slotId: reference, name: reference, suppressed: Type.Boolean(), assignmentKey: Type.Optional(reference),
+  status: variants("pending", "queued", "running", "reported", "rejected", "cancelled", "interrupted"),
+  queueId: Type.Optional(reference), runId: Type.Optional(reference),
+  report: Type.Optional(ReportSchema), reason: Type.Optional(reference),
+}, { additionalProperties: false });
+const DeliverySchema = Type.Object({
+  id: reference, kind: variants("member", "urgent", "settled"),
+  slotIds: Type.Array(reference, { minItems: 1, uniqueItems: true }), status: variants("pending", "enqueued"),
+  wake: Type.Optional(Type.Object({ state: variants("pending", "observed"), entryId: Type.Optional(reference),
+    error: Type.Optional(reference) }, { additionalProperties: false })),
+}, { additionalProperties: false });
+const LedgerSchema = Type.Object({
+  version: Type.Literal(1), groupId: reference, teamName: reference, sessionId: reference, submissionId: reference,
+  policy: CompletionGroupPolicySchema, sealed: Type.Boolean(),
+  members: Type.Array(MemberSchema, { minItems: 1 }), deliveries: Type.Array(DeliverySchema),
+}, { additionalProperties: false });
+export type CompletionGroupState = Static<typeof LedgerSchema>;
+export type CompletionDelivery = Static<typeof DeliverySchema>;
+const eventBinding = { slotId: reference, groupId: Type.Optional(reference) };
+const EventSchema = Type.Union([
+  Type.Object({ ...eventBinding, type: Type.Literal("queued"), queueId: reference }, { additionalProperties: false }),
+  Type.Object({ ...eventBinding, type: Type.Literal("running"), runId: reference }, { additionalProperties: false }),
+  Type.Object({ ...eventBinding, type: Type.Literal("reported"), report: ReportSchema }, { additionalProperties: false }),
+  Type.Object({ ...eventBinding, type: variants("rejected", "cancelled", "interrupted"),
+    runId: Type.Optional(reference), reason: reference }, { additionalProperties: false }),
+  Type.Object({ ...eventBinding, type: variants("rejected", "cancelled"),
+    queueId: reference, reason: reference }, { additionalProperties: false }),
+]);
+export type CompletionGroupEvent = Static<typeof EventSchema>;
+const digest = (value: unknown) => crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export const completionGroupIdentity = (options: Pick<CompletionGroupOptions, "teamName" | "sessionId" | "submissionId">) =>
+  `group:${digest([options.teamName, options.sessionId, options.submissionId])}`;
+const terminal = (member: CompletionGroupState["members"][number]) =>
+  !["pending", "queued", "running"].includes(member.status);
+const urgent = (member: CompletionGroupState["members"][number]) => member.status === "rejected" || (!!member.report &&
+  (member.report.runtimeStatus === "failed" || ["blocked", "failed"].includes(member.report.effectiveOutcome ?? member.report.outcome ?? "") || ["failed", "stale"].includes(member.report.verification)));
+const deliveryIdentity = (groupId: string, kind: CompletionDelivery["kind"], slots: string[]) =>
+  `delivery:${digest([groupId, kind, slots])}`;
+
+export class CompletionGroup {
+  readonly journalPath: string;
+  private newlyCreated = false;
+  get created(): boolean { return this.newlyCreated; }
+
+  constructor(readonly teamName: string, readonly groupId: string) {
+    if (!teamName || !/^group:[a-f0-9]{64}$/.test(groupId)) throw new Error("Invalid completion group identity.");
+    this.journalPath = path.join(paths.teamDir(teamName), "completion-groups", `${groupId.slice(6)}.json`);
+  }
+
+  static async create(options: CompletionGroupOptions): Promise<CompletionGroup | undefined> {
+    if (normalizeCompletionGroupPolicy(options.policy) === undefined) return undefined;
+    if (!Value.Check(OptionsSchema, options)) throw new Error("Invalid completion group assignment.");
+    const bound = structuredClone(options);
+    const group = new CompletionGroup(bound.teamName, completionGroupIdentity(bound));
+    const seeds = bound.members.map(seed);
+    fs.mkdirSync(path.dirname(group.journalPath), { recursive: true, mode: 0o700 });
+    await withLock(group.journalPath, async () => {
+      if (fs.existsSync(group.journalPath)) {
+        const existing = group.read();
+        if (!isDeepStrictEqual(existing.policy, bound.policy)
+          || !isDeepStrictEqual(existing.members.map(seed), seeds)) {
+          throw new Error("Completion group assignment binding has changed.");
+        }
+        syncPathAndParents(group.journalPath);
+        return;
+      }
+      writeJsonDurably(group.journalPath, {
+        version: 1, groupId: group.groupId, teamName: bound.teamName, sessionId: bound.sessionId,
+        submissionId: bound.submissionId, policy: bound.policy, sealed: false, deliveries: [],
+        members: seeds.map((member, index) => ({ ...member, slotId: `${group.groupId}:${index}`, status: "pending" })),
+      });
+      group.newlyCreated = true;
+    });
+    return group;
+  }
+
+  read(): CompletionGroupState {
+    let state: unknown;
+    try { state = JSON.parse(fs.readFileSync(this.journalPath, "utf8")); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        throw new Error(`Referenced completion group is unavailable; inspect ${this.journalPath}.`);
+      }
+      throw new Error(`Corrupt completion group; inspect ${this.journalPath}.`);
+    }
+    if (!Value.Check(LedgerSchema, state) || state.groupId !== this.groupId
+      || state.teamName !== this.teamName || completionGroupIdentity(state) !== this.groupId) {
+      throw new Error("Corrupt completion group binding.");
+    }
+    for (const [index, member] of state.members.entries()) {
+      const reportId = member.runId && createReportResult(state.teamName, member.name, member.runId, {}).reportId;
+      if (member.slotId !== `${this.groupId}:${index}`
+        || (member.status === "pending" && (member.runId || member.queueId))
+        || (member.status === "queued" && (!member.queueId || member.runId))
+        || (member.status === "running" && !member.runId)
+        || ((member.status === "reported") !== !!member.report)
+        || (member.report && (member.report.runId !== member.runId || member.report.reportId !== reportId))) {
+        throw new Error("Corrupt completion member binding.");
+      }
+    }
+    if (new Set(state.deliveries.map(delivery => delivery.id)).size !== state.deliveries.length) {
+      throw new Error("Corrupt completion delivery identity.");
+    }
+    for (const delivery of state.deliveries) {
+      if ((delivery.wake && (delivery.status !== "enqueued" || ((delivery.wake.state === "observed") !== !!delivery.wake.entryId)))
+        || delivery.id !== deliveryIdentity(this.groupId, delivery.kind, delivery.slotIds)
+        || (delivery.kind !== "settled" && delivery.slotIds.length !== 1)
+        || (delivery.kind === "settled" && (!state.sealed || !state.members.every(terminal)))
+        || delivery.slotIds.some(id => !state.members.some(member => member.slotId === id && terminal(member) && !member.suppressed))) {
+        throw new Error("Corrupt completion delivery binding.");
+      }
+    }
+    return state;
+  }
+
+  binding(index: number): CompletionGroupBinding {
+    const member = this.read().members[index];
+    if (!member) throw new Error("Unknown completion group slot.");
+    return { groupId: this.groupId, slotId: member.slotId };
+  }
+
+  private plan(state: CompletionGroupState): void {
+    const visible = state.members.filter(member => terminal(member) && !member.suppressed);
+    const covered = new Set(state.deliveries.flatMap(delivery => delivery.slotIds));
+    const due = visible.filter(member => !covered.has(member.slotId));
+    const append = (kind: CompletionDelivery["kind"], slotIds: string[]) => {
+      state.deliveries.push({ id: deliveryIdentity(this.groupId, kind, slotIds), kind, slotIds, status: "pending" });
+    };
+    if (due.length === 0) return;
+    if (state.policy.delivery === "all-settled" && state.sealed && state.members.every(terminal)) {
+      append("settled", visible.map(member => member.slotId));
+      return;
+    }
+    for (const member of due) {
+      if (state.policy.delivery === "immediate") append("member", [member.slotId]);
+      else if (urgent(member)) append("urgent", [member.slotId]);
+    }
+  }
+
+  private async update(change: (state: CompletionGroupState) => void): Promise<CompletionGroupState> {
+    this.read();
+    return withLock(this.journalPath, async () => {
+      const state = this.read();
+      const before = JSON.stringify(state);
+      change(state);
+      this.plan(state);
+      if (JSON.stringify(state) !== before) writeJsonDurably(this.journalPath, state);
+      else syncPathAndParents(this.journalPath);
+      return state;
+    });
+  }
+
+  async apply(event: CompletionGroupEvent): Promise<void> {
+    if (!Value.Check(EventSchema, event) || (event.groupId && event.groupId !== this.groupId)) {
+      throw new Error("Invalid completion event binding.");
+    }
+    const input = structuredClone(event);
+    if (input.type === "reported") {
+      if (input.report.outcome === undefined) delete input.report.outcome;
+      if (input.report.effectiveOutcome === undefined) delete input.report.effectiveOutcome;
+    }
+    await this.update(state => {
+      const member = state.members.find(item => item.slotId === input.slotId);
+      if (!member) throw new Error("Unknown completion slot binding.");
+      if (input.type === "queued") {
+        if (member.queueId === input.queueId) return;
+        if (member.status !== "pending") throw new Error("Completion slot is already admitted or settled.");
+        Object.assign(member, { queueId: input.queueId, status: "queued" });
+      } else if (input.type === "running") {
+        if (member.runId) {
+          if (member.runId !== input.runId) throw new Error("Completion run binding has changed.");
+          return;
+        }
+        if (terminal(member)) throw new Error("Completion slot is already settled.");
+        Object.assign(member, { runId: input.runId, status: "running" });
+      } else if (input.type === "reported") {
+        const expected = member.runId && createReportResult(this.teamName, member.name, member.runId, {}).reportId;
+        if (input.report.runId !== member.runId || input.report.reportId !== expected) {
+          throw new Error("Completion report binding has changed.");
+        }
+        if (member.report) {
+          if (!isDeepStrictEqual(member.report, input.report)) throw new Error("Conflicting completion report binding.");
+          return;
+        }
+        if (member.status !== "running") throw new Error("Completion slot is already settled.");
+        Object.assign(member, { report: input.report, status: "reported" });
+      } else {
+        if ("queueId" in input) {
+          // Queue identity is immutable across admission. Resolve its terminal
+          // state under this lock, retaining any run bound while removal waited.
+          if (member.queueId !== input.queueId) throw new Error("Completion settlement queue binding has changed.");
+        } else if (member.runId !== input.runId) throw new Error("Completion settlement run binding has changed.");
+        if (terminal(member)) return;
+        Object.assign(member, { status: input.type, reason: input.reason });
+      }
+    });
+  }
+
+  async recordReport(slotId: string, result: ReportResult, runtimeStatus?: "completed" | "failed"): Promise<void> {
+    await this.apply({ type: "reported", slotId, report: { reportId: result.reportId, runId: result.runId,
+      ...(runtimeStatus ? { runtimeStatus } : {}),
+      outcome: result.outcome, effectiveOutcome: effectiveTaskOutcome(result), verification: result.verification.state } });
+  }
+
+  async seal(): Promise<void> { await this.update(state => { state.sealed = true; }); }
+
+  async prepareDeliveries(): Promise<CompletionDelivery[]> {
+    const state = await this.update(() => {});
+    return state.deliveries.filter(delivery => delivery.status === "pending");
+  }
+
+  async reserveWake(deliveryId: string): Promise<boolean> {
+    let reserved = false;
+    await this.update(state => {
+      const delivery = state.deliveries.find(item => item.id === deliveryId);
+      if (delivery?.status !== "enqueued") throw new Error("Completion wake requires an enqueued index.");
+      if (!delivery.wake) {
+        delivery.wake = { state: "pending" };
+        reserved = true;
+      }
+    });
+    return reserved;
+  }
+
+  async recordWakeEvidence(deliveryId: string, evidence: { entryId: string } | { error: string }): Promise<void> {
+    await this.update(state => {
+      const wake = state.deliveries.find(item => item.id === deliveryId)?.wake;
+      if (!wake) throw new Error("Completion wake has no reserved request.");
+      if ("entryId" in evidence) {
+        if (!evidence.entryId || (wake.entryId && wake.entryId !== evidence.entryId)) throw new Error("Completion wake observation binding has changed.");
+        Object.assign(wake, { state: "observed", entryId: evidence.entryId });
+      } else {
+        if (!evidence.error) throw new Error("Completion wake error is unavailable.");
+        wake.error = evidence.error;
+      }
+    });
+  }
+
+  async markEnqueued(deliveryId: string): Promise<void> {
+    await this.update(state => {
+      const delivery = state.deliveries.find(item => item.id === deliveryId);
+      if (!delivery) throw new Error("Unknown completion delivery identity.");
+      delivery.status = "enqueued";
+    });
+  }
+}

package/src/results/continuation-recipient.ts

@@ -0,0 +1,37 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import * as paths from "../utils/paths";
+
+export function freshContinuationName(prefix: string, nonce?: string): string {
+  paths.sanitizeName(prefix);
+  if (!prefix || prefix.length > 128) throw new Error("Continuation name prefix must contain 1–128 characters.");
+  const suffix = nonce === undefined ? crypto.randomUUID() : crypto.createHash("sha256").update(nonce).digest("hex").slice(0, 32);
+  return `${prefix}-${suffix}`;
+}
+
+export function assertUnusedContinuationRecipient(teamName: string, candidate: string): void {
+  paths.sanitizeName(candidate);
+  const directory = paths.teamDir(teamName);
+  const collision = () => { throw new Error(`Continuation recipient ${candidate} is not unused; choose a new prefix and retry.`); };
+  const exists = (file: string) => !!fs.lstatSync(file, { throwIfNoEntry: false });
+  for (const file of [paths.inboxPath(teamName, candidate), paths.runtimeStatusPath(teamName, candidate), paths.lifecycleTombstonePath(teamName, candidate),
+    path.join(directory, `${candidate}.pid`), path.join(directory, "agent-sessions", candidate)]) if (exists(file)) collision();
+  for (const [folder, matches] of [
+    [path.join(directory, "session-context"), (name: string) => name.startsWith(`${candidate.toLowerCase()}--`)],
+    [path.join(paths.reportFilesDir(), paths.sanitizeName(teamName)), (name: string) => name === `${candidate.toLowerCase()}.md` || name.startsWith(`${candidate.toLowerCase()}-v`)],
+  ] as const) if (exists(folder) && fs.readdirSync(folder).some(name => matches(name.toLowerCase()))) collision();
+  for (const [file, key, array] of [[paths.claimsPath(teamName), "agent", false], [paths.writeQueuePath(teamName), "name", true],
+    [paths.readHelperQueuePath(teamName), "name", true], [path.join(directory, "reports.json"), "agentName", true]] as const) {
+    if (!exists(file)) continue;
+    let rows: unknown[];
+    try {
+      if (!fs.lstatSync(file).isFile() || fs.lstatSync(file).isSymbolicLink()) throw new Error("Not a regular namespace record");
+      const value = JSON.parse(fs.readFileSync(file, "utf8"));
+      if (!value || typeof value !== "object" || Array.isArray(value) !== array) throw new Error("Invalid namespace record");
+      rows = array ? value : Object.values(value);
+      if (rows.some(row => !row || typeof row !== "object" || typeof Reflect.get(row, key) !== "string")) throw new Error("Invalid namespace owner");
+    } catch { throw new Error(`Cannot establish an unused continuation namespace; inspect ${file}.`); }
+    if (rows.some(row => String(Reflect.get(row as object, key)).toLowerCase() === candidate.toLowerCase())) collision();
+  }
+}

package/src/results/durable-json.ts

@@ -0,0 +1,29 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+function syncPath(file: string): void {
+  const descriptor = fs.openSync(file, "r");
+  try { fs.fsyncSync(descriptor); }
+  finally { fs.closeSync(descriptor); }
+}
+
+export function syncPathAndParents(file: string): void {
+  for (let current = file; ; current = path.dirname(current)) {
+    syncPath(current);
+    if (path.dirname(current) === current) return;
+  }
+}
+
+export function writeJsonDurably(file: string, value: unknown): void {
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${crypto.randomUUID()}.tmp`);
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(value, null, 2), { flag: "wx", mode: 0o600 });
+    syncPath(temporary);
+    fs.renameSync(temporary, file);
+    syncPathAndParents(path.dirname(file));
+  } catch (error) {
+    try { fs.unlinkSync(temporary); } catch {}
+    throw error;
+  }
+}

package/src/results/repair-policy.ts

@@ -0,0 +1,24 @@
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+
+export const RepairPolicySchema = Type.Object({
+  maxAttempts: Type.Integer({ minimum: 0, maximum: 5, description: "Maximum additional repair attempts after initial verification. Zero disables automatic repair. Only the lead or a trusted integration may authorize this policy." }),
+}, { additionalProperties: false });
+export type RepairPolicy = Static<typeof RepairPolicySchema>;
+export type RepairState = "pending" | "not-needed" | "requested" | "repaired" | "exhausted" | "cancelled" | "declined" | "blocked";
+export interface RepairResult {
+  controllerId: string;
+  journalPath?: string;
+  state: RepairState;
+  attemptsUsed?: number;
+  maxAttempts?: number;
+  requestIds?: string[];
+  outcome?: "blocked";
+  error?: string;
+}
+
+export function normalizeRepairPolicy(value: unknown): RepairPolicy | undefined {
+  if (value === undefined) return undefined;
+  if (!Value.Check(RepairPolicySchema, value)) throw new Error("Invalid repair policy.");
+  return value.maxAttempts ? structuredClone(value) : undefined;
+}

package/src/results/report-result.ts

@@ -0,0 +1,77 @@
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import type { RepairResult } from "./repair-policy";
+
+const reference = Type.String({ minLength: 1 });
+
+export const ReportedTaskDetailsSchema = Type.Object({
+  outcome: Type.Optional(Type.Union([
+    Type.Literal("succeeded"), Type.Literal("blocked"), Type.Literal("failed"), Type.Literal("cancelled"),
+  ], { description: "Reported task outcome, separate from clean exit, verification, and lead acceptance. Omit when unspecified." })),
+  changedPaths: Type.Optional(Type.Array(reference)),
+  inspectedEvidence: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 2048, pattern: "\\S" }), { maxItems: 128 })),
+  artifacts: Type.Optional(Type.Array(Type.Object({
+    path: reference,
+    label: Type.Optional(Type.String()),
+  }, { additionalProperties: false }))),
+  findings: Type.Optional(Type.Array(Type.Object({
+    id: reference,
+    text: reference,
+    evidence: Type.Array(reference),
+  }, { additionalProperties: false }))),
+  questions: Type.Optional(Type.Array(reference)),
+}, { additionalProperties: false });
+
+export type ReportedTaskDetails = Static<typeof ReportedTaskDetailsSchema>;
+export type TaskOutcome = NonNullable<ReportedTaskDetails["outcome"]>;
+export type VerificationState = "not-requested" | "pending" | "passed" | "failed" | "stale";
+
+export interface ReportResult extends ReportedTaskDetails {
+  version: 1;
+  taskId: string;
+  runId: string;
+  reportId: string;
+  checkpointId?: string;
+  verification: { state: VerificationState; checkIds?: string[]; error?: string };
+  acceptance: { state: "pending" | "accepted" | "rejected"; decidedAt?: number; reason?: string };
+  repair?: RepairResult;
+}
+
+export function effectiveTaskOutcome(result: ReportResult): TaskOutcome | undefined {
+  return result.repair?.outcome ?? result.outcome;
+}
+
+export function normalizeReportedTaskDetails(value: unknown): ReportedTaskDetails {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("Reported task details must be an object.");
+  }
+  const input = value as Record<string, unknown>;
+  const details = Object.fromEntries(Object.keys(ReportedTaskDetailsSchema.properties)
+    .filter(key => input[key] !== undefined)
+    .map(key => [key, input[key]]));
+  if (!Value.Check(ReportedTaskDetailsSchema, details)) throw new Error("Invalid reported task details.");
+  const findingIds = details.findings?.map(finding => finding.id) ?? [];
+  if (new Set(findingIds).size !== findingIds.length) throw new Error("Reported finding IDs must be unique.");
+  return structuredClone(details);
+}
+
+export function createReportResult(
+  teamName: string,
+  agentName: string,
+  runId: string,
+  reported: ReportedTaskDetails,
+): ReportResult {
+  if (![teamName, agentName, runId].every(value => typeof value === "string" && value.length > 0)) {
+    throw new Error("Report identity requires the bound team, agent and lifecycle run.");
+  }
+  const identity = [teamName, agentName, runId].map(encodeURIComponent).join(":");
+  return {
+    ...normalizeReportedTaskDetails(reported),
+    version: 1,
+    taskId: `task:${identity}`,
+    runId,
+    reportId: `report:${identity}`,
+    verification: { state: "not-requested" },
+    acceptance: { state: "pending" },
+  };
+}