pi-extended-teams 2.2.9 → 2.3.0

package/src/results/checkpoint-report.ts

@@ -0,0 +1,109 @@
+import { isDeepStrictEqual } from "node:util";
+import type { Member, TeamReportEvent } from "../utils/models";
+import { normalizeFavoriteModelSlot } from "../utils/settings";
+import { readStoredTeamReportEvent, recordReportCheckpoint, resyncStoredTeamReportEvent } from "../utils/report-events";
+import { captureSourceIdentity, type SourceIdentity } from "./source-identity";
+import { checkpointId, checkpointReportPayload, isSpecialistCheckpoint, MAX_CHECKPOINT_BYTES, MAX_CHECKPOINT_REPORT_PATH_LENGTH, saveCheckpoint, type SpecialistCheckpoint } from "./specialist-checkpoint";
+import type { ReportResult } from "./report-result";
+
+function author(teamName: string, member: Member) {
+  return { teamName, agentName: member.name, runId: member.lifecycleRunId!, modelSlot: normalizeFavoriteModelSlot(member.modelSlot)! };
+}
+
+export function checkpointReference(teamName: string, member: Member): TeamReportEvent["checkpoint"] {
+  return member.checkpointAssignment ? { id: checkpointId(author(teamName, member)) } : undefined;
+}
+
+function requireDraft(event: TeamReportEvent): SpecialistCheckpoint {
+  const draft = event.checkpoint?.draft;
+  if (!isSpecialistCheckpoint(draft) || draft.id !== event.checkpoint?.id || draft.reportId !== event.id
+    || draft.author.teamName !== event.teamName || draft.author.agentName !== event.agentName || draft.author.runId !== event.result?.runId
+    || draft.reports.find(report => report.id === event.id)?.path !== event.reportPath) throw new Error("Checkpoint report provenance is unavailable or changed.");
+  return draft;
+}
+
+function checkpointBytes(record: SpecialistCheckpoint): number {
+  return Buffer.byteLength(JSON.stringify(record, null, 2));
+}
+
+export function preflightReportCheckpoint(teamName: string, member: Member, result: ReportResult): void {
+  const assignment = member.checkpointAssignment;
+  if (!assignment) return;
+  if (!assignment.sourceBefore) throw new Error("Checkpoint assignment provenance is unavailable.");
+  // JSON may escape each path character as six bytes; the final versioned path is allocated later.
+  const reservedBytes = 6 * MAX_CHECKPOINT_REPORT_PATH_LENGTH;
+  const event: TeamReportEvent = {
+    id: result.reportId, teamName, agentName: member.name, status: "completed", source: "read-agent", report: "",
+    createdAt: Number.MAX_SAFE_INTEGER - assignment.policy.retentionDays * 86_400_000,
+    reportPath: "/", checkpoint: checkpointReference(teamName, member),
+    result: { ...result, verification: { ...result.verification, state: "not-requested" }, acceptance: { state: "accepted" } },
+  };
+  // Native capture uses SHA-1/SHA-256 and an array length; stable path/scope fields must match sourceBefore.
+  const after = { ...assignment.sourceBefore, head: "f".repeat(64), fileCount: Number.MAX_SAFE_INTEGER };
+  const record = snapshot(teamName, member, event, after, reservedBytes);
+  if (checkpointBytes(record) + reservedBytes > MAX_CHECKPOINT_BYTES) {
+    throw new Error(`Checkpoint exceeds ${MAX_CHECKPOINT_BYTES} bytes including assignment and retained provenance. Correct the report fields and resubmit report_and_exit.`);
+  }
+}
+
+function snapshot(teamName: string, member: Member, event: TeamReportEvent, after: SourceIdentity, reservedBytes = 0): SpecialistCheckpoint {
+  const { originalPrompt, policy, sourceBefore, parent } = member.checkpointAssignment!;
+  const result = event.result!;
+  if (!sourceBefore || (parent && !isSpecialistCheckpoint(parent))) throw new Error("Checkpoint assignment provenance is unavailable.");
+  const previous = (parent ? [parent.reports[0], ...parent.reports.slice(1).slice(-14)] : []).map(report => ({ ...report,
+    ...(report.id === parent?.reportId && !report.leadDecisions ? { leadDecisions: parent.policy.decisions } : {}) }));
+  const retained = new Set(previous.map(report => report.id));
+  const { findings, inspectedEvidence: inspected, questions } = checkpointReportPayload(result);
+  const updated = new Set(findings.map(finding => finding.id));
+  const record: SpecialistCheckpoint = {
+    version: 1, state: "ready", id: event.checkpoint!.id, author: author(teamName, member),
+    createdAt: event.createdAt, expiresAt: event.createdAt + policy.retentionDays * 86_400_000,
+    ...(parent ? { parentId: parent.id } : {}), assignment: { original: originalPrompt, current: member.prompt! }, policy,
+    reportId: event.id, reports: [...previous, { id: event.id, path: event.reportPath!, source: { before: sourceBefore, after },
+      verification: result.verification.state, acceptance: result.acceptance.state, leadDecisions: policy.decisions }],
+    findings: [...findings, ...(parent?.findings.filter(finding => retained.has(finding.reportId) && !updated.has(finding.id)) ?? []).slice(0, Math.max(0, 100 - findings.length))],
+    inspectedEvidence: [...inspected, ...(parent?.inspectedEvidence.filter(item => retained.has(item.reportId)) ?? []).slice(0, Math.max(0, 128 - inspected.length))],
+    questions: [...questions, ...(parent?.questions.filter(question => !questions.includes(question)) ?? []).slice(0, Math.max(0, 32 - questions.length))],
+  };
+  const oversized = () => checkpointBytes(record) + reservedBytes > MAX_CHECKPOINT_BYTES;
+  while (oversized() && record.reports.length > 2) {
+    const removed = record.reports.splice(1, 1)[0].id;
+    record.findings = record.findings.filter(finding => finding.reportId !== removed);
+    record.inspectedEvidence = record.inspectedEvidence.filter(item => item.reportId !== removed);
+  }
+  while (oversized() && record.questions.length > questions.length) record.questions.pop();
+  return structuredClone(record);
+}
+
+export async function saveReportCheckpoint(teamName: string, member: Member, event: TeamReportEvent, signal?: AbortSignal) {
+  const reference = checkpointReference(teamName, member);
+  if (!reference && !event.checkpoint) return undefined;
+  if (!reference || event.checkpoint?.id !== reference.id || event.teamName !== teamName || event.agentName !== member.name
+    || !event.result || event.result.runId !== member.lifecycleRunId || event.id !== event.result.reportId) throw new Error("Checkpoint report binding changed.");
+  let stored = await readStoredTeamReportEvent(teamName, event.id);
+  if (stored?.checkpoint?.id !== reference.id) throw new Error("Checkpoint report provenance is unavailable.");
+  if (!stored.checkpoint.draft) {
+    const assignment = structuredClone(member.checkpointAssignment!);
+    if (!assignment.sourceBefore) throw new Error("Checkpoint assignment provenance is unavailable.");
+    const captureSignal = AbortSignal.any([AbortSignal.timeout(30_000), ...(signal ? [signal] : [])]);
+    captureSignal.throwIfAborted();
+    const after = await captureSourceIdentity(member.cwd, assignment.policy.inputs, captureSignal);
+    captureSignal.throwIfAborted();
+    await resyncStoredTeamReportEvent(teamName, event.id);
+    stored = await recordReportCheckpoint(teamName, event.id, snapshot(teamName, { ...member, checkpointAssignment: assignment }, stored, after));
+  } else stored = await resyncStoredTeamReportEvent(teamName, event.id);
+  const draft = requireDraft(stored);
+  if (!isDeepStrictEqual(draft.author, author(teamName, member)) || !isDeepStrictEqual(draft.policy, member.checkpointAssignment!.policy)
+    || draft.assignment.original !== member.checkpointAssignment!.originalPrompt || draft.assignment.current !== member.prompt
+    || !isDeepStrictEqual(draft.reports.find(report => report.id === event.id)?.source.before, member.checkpointAssignment!.sourceBefore)) {
+    throw new Error("Checkpoint assignment binding changed.");
+  }
+  return saveCheckpoint(draft);
+}
+
+export async function resyncReportCheckpoint(event: TeamReportEvent) {
+  if (!event.checkpoint) return undefined;
+  const stored = await resyncStoredTeamReportEvent(event.teamName, event.id);
+  if (stored.checkpoint?.id !== event.checkpoint.id) throw new Error("Checkpoint report binding changed.");
+  return saveCheckpoint(requireDraft(stored));
+}

package/src/results/checkpoint-retention.ts

@@ -0,0 +1,15 @@
+import { listCheckpointRecords, retireCheckpoint } from "./specialist-checkpoint";
+
+export async function expireCheckpoints(now = Date.now()): Promise<string[]> {
+  const { records, errors } = listCheckpointRecords();
+  const diagnostics = errors.map(error => error.message);
+  for (const record of records) {
+    if (record.state !== "ready" || record.expiresAt > now) continue;
+    try {
+      await retireCheckpoint(record.id, "expired", now);
+    } catch (error) {
+      diagnostics.push(`Checkpoint ${record.id}: ${String(error)}`);
+    }
+  }
+  return diagnostics;
+}

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();
+  }
+}