@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.3

package/src/team-evaluation.js

@@ -0,0 +1,243 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, open, readFile, readdir, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { CODEFLOW_HOME } from "./config.js";
+const finite = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+const interval = (start, end) => finite(start) && finite(end) && end >= start ? [[start, end]] : [];
+function intervalDuration(intervals) {
+  let total = 0, start = -1, end = -1;
+  for (const [a, b] of [...intervals].sort((a2, b2) => a2[0] - b2[0])) {
+    if (a > end) {
+      if (start >= 0) total += end - start;
+      start = a;
+      end = b;
+    } else end = Math.max(end, b);
+  }
+  return total + (start < 0 ? 0 : end - start);
+}
+function buildTeamEvaluation(run, options = {}) {
+  const team = run.team;
+  const turns = run.steps.filter((step) => step.kind === "agent");
+  const coordinator = (step) => step.coordination === true || !team && step.role === "supervisor";
+  const workers = turns.filter((step) => {
+    if (!team) return step.role === "workers" || step.role === "worker";
+    const member = team.members.find((item) => item.id === step.memberId);
+    if (member) return member.role === "worker" && !coordinator(step);
+    return !!step.taskId && !coordinator(step) && step.role !== "coordinator" && step.role !== "reviewer";
+  });
+  const invocations = team?.metrics.invocations ?? turns.reduce((sum, step) => sum + (step.invocations ?? 1), 0);
+  const coordination = team?.metrics.coordinatorInvocations ?? turns.filter(coordinator).reduce((sum, step) => sum + (step.invocations ?? 1), 0);
+  const peer = (team?.messages ?? []).filter((message) => message.kind === "question" && message.recipient !== "user" && message.originalRecipient !== "user");
+  const peerIntervals = peer.flatMap((message) => interval(message.createdAt, message.answeredAt));
+  const barriers = [];
+  for (const message of peer) {
+    if (!finite(message.answeredAt)) continue;
+    const task = team?.tasks.find((item) => item.id === message.taskId);
+    if (!task || !task.dependsOn.every((id) => {
+      const dependency = team?.tasks.find((item) => item.id === id);
+      return finite(dependency?.finishedAt) && dependency.finishedAt <= message.answeredAt;
+    })) continue;
+    const next = workers.filter((step) => step.taskId === task.id && step.startedAt >= message.answeredAt).sort((a, b) => a.startedAt - b.startedAt)[0];
+    if (next) barriers.push([message.answeredAt, next.startedAt]);
+  }
+  const usage = turns.filter((step) => step.usage);
+  const integrityFlags = Object.values(run.integrity ?? {}).reduce((sum, issues) => sum + issues.length, 0);
+  const check = team?.verification?.check === "not_required" ? "not_required" : run.verdict === "passed" ? "passed" : run.verdict === "failing" ? "failed" : "unknown";
+  const approved = team ? !!team.verification?.reviewed && !!team.verification.approved : run.facts?.approved === true;
+  const requirements = team?.requirements.length ?? 0;
+  const covered = team?.requirements.filter((requirement) => {
+    const tasks = team.tasks.filter((task) => task.requirements.includes(requirement.id));
+    return tasks.length > 0 && tasks.every((task) => task.status === "completed" && !task.evidenceStale && (!task.retainedBaseline || approved));
+  }).length ?? 0;
+  const gaps = team?.gaps.length ?? 0;
+  const unchangedRerun = !!run.teamRerun && run.facts?.proofNotRequired === "unchanged-rerun" && check === "passed" && approved;
+  const documentationOnly = run.facts?.proofNotRequired === "documentation-only" && check === "passed" && approved;
+  const verified = run.status === "done" && approved && (check === "passed" || check === "not_required") && !gaps && !integrityFlags && (!team || team.status === "completed" && covered === requirements) && (run.prove === false || check === "not_required" || run.facts?.proof === "proven" || unchangedRerun || documentationOnly);
+  const mode = options.mode ?? "unknown";
+  const approvalAnswers = options.journal ? [...options.journal].filter(([key]) => key.startsWith("approval:")).map(([, value]) => value) : void 0;
+  const rated = options.memoryEntries?.flatMap((entry) => entry.feedback?.filter((feedback) => feedback.runId === run.id && run.memoryManifest?.included.some((ref) => ref.id === entry.id && ref.revision === feedback.revision)) ?? []);
+  return {
+    version: 1,
+    id: `evaluation-${run.id}`,
+    runId: run.id,
+    at: run.endedAt ?? Date.now(),
+    mode,
+    caseId: options.caseId ?? "unspecified",
+    pairId: options.pairId ?? run.group?.id,
+    taskHash: createHash("sha256").update(run.task).digest("hex"),
+    baseRef: run.baseRef,
+    pattern: run.pattern,
+    cliVersions: { ...options.cliVersions },
+    status: run.status,
+    verified,
+    reproducibility: {
+      nodeVersion: process.version,
+      platform: `${process.platform}/${process.arch}`,
+      ...options.reproducibility,
+      requestedSettings: Object.fromEntries(Object.entries(run.agentSettings ?? {}).filter((entry) => entry[1] !== void 0).map(([id, settings]) => [id, structuredClone(settings)])),
+      stepSettings: [...new Map(turns.filter((step) => step.agent).map((step) => {
+        const settings = { provider: step.agent, model: step.settings?.model, effort: step.settings?.effort };
+        return [JSON.stringify(settings), settings];
+      })).values()]
+    },
+    verification: { checks: check, review: approved ? "approved" : run.facts?.approved === false || team?.verification?.reviewed ? "rejected" : "unknown", proof: run.facts?.proof, proofNotRequired: run.facts?.proofNotRequired, gaps, requirements, covered, integrityFlags, ...run.teamRerun ? { proofNotRequired: run.facts?.proofNotRequired, retainedTasks: team?.tasks.filter((task) => task.retainedBaseline).length ?? 0, newlyExecutedTasks: team?.tasks.filter((task) => !task.retainedBaseline && (task.attempts ?? 0) > 0).length ?? 0, requirementsUsingBaseline: team?.requirements.filter((requirement) => team.tasks.some((task) => task.retainedBaseline && task.requirements.includes(requirement.id))).length ?? 0 } : {} },
+    metrics: {
+      invocations,
+      coordinatorInvocations: coordination,
+      coordinatorFraction: invocations ? coordination / invocations : null,
+      workerTurns: workers.length,
+      multiWorker: new Set(workers.map((step) => team ? step.memberId ?? step.agent : step.worktree ?? step.agent)).size > 1,
+      elapsedMs: run.endedAt === void 0 ? void 0 : Math.max(0, run.endedAt - run.createdAt),
+      activeWorkMs: intervalDuration(run.steps.flatMap((step) => interval(step.startedAt, step.endedAt))),
+      coordinatorMs: turns.some(coordinator) ? turns.filter(coordinator).reduce((sum, step) => sum + (finite(step.endedAt) ? Math.max(0, step.endedAt - step.startedAt) : 0), 0) : void 0,
+      reportedTokens: usage.length ? usage.reduce((sum, step) => sum + step.usage.inputTokens + (step.usage.cacheReadTokens ?? 0) + step.usage.outputTokens, 0) : void 0,
+      reportedApiCostUsd: usage.some((step) => step.usage.costUsd > 0) ? usage.reduce((sum, step) => sum + step.usage.costUsd, 0) : void 0,
+      tokenReportingTurns: usage.length,
+      questions: team?.metrics.questionCount ?? 0,
+      peerQuestions: peer.length,
+      blockedTurns: team?.metrics.blockedTurns ?? 0,
+      peerYieldRate: workers.length ? new Set(peer.filter((message) => message.blocking).map((message) => `${message.sender}:${message.taskId}:${message.sourceAttempt ?? message.sourceStepId ?? message.id}`)).size / workers.length : null,
+      peerWaitingMs: peerIntervals.length ? peerIntervals.reduce((sum, [a, b]) => sum + b - a, 0) : peer.length ? void 0 : 0,
+      peerWaitingWallMs: peerIntervals.length ? intervalDuration(peerIntervals) : peer.length ? void 0 : 0,
+      avoidableBarrierEstimateMs: barriers.length ? intervalDuration(barriers) : peer.length ? void 0 : 0,
+      timedPeerQuestions: peerIntervals.length,
+      repairTurns: turns.filter((step) => !step.taskId && /repair|fix/i.test(step.title)).length,
+      // engine-titled repair/fix steps, never model-titled task names
+      selectedMemories: run.memoryManifest?.included.length ?? 0,
+      omittedMemories: run.memoryManifest?.omitted.length ?? 0,
+      coordinatorRevisions: team?.metrics.revisions ?? 0,
+      approvals: approvalAnswers ? { approved: approvalAnswers.filter((answer) => answer.decision === "approve").length, revised: approvalAnswers.filter((answer) => answer.decision === "revise").length, rejected: approvalAnswers.filter((answer) => answer.decision === "reject").length, withReason: approvalAnswers.filter((answer) => !!answer.note?.trim()).length } : void 0,
+      memoryFeedback: rated ? { useful: rated.filter((item) => item.rating === "useful").length, irrelevant: rated.filter((item) => item.rating === "irrelevant").length, stale: rated.filter((item) => item.rating === "stale").length, incorrect: rated.filter((item) => item.rating === "incorrect").length } : void 0,
+      replay: options.replay
+    },
+    limitations: [
+      ...mode !== "real" ? [mode === "fake" ? "Deterministic fake CLIs validate orchestration, not model quality or subscription savings." : "Execution provenance is unknown; excluded from real-run rollout evidence."] : [],
+      "API-equivalent cost is not a subscription charge; unreported values remain unknown.",
+      "Model identities record requested CLI settings. A provider default or alias is not an immutable model snapshot and may change between trials.",
+      "Avoidable barrier time is a counterfactual upper-bound estimate after answered peer questions; it does not prove spare process capacity or an asynchronous speedup.",
+      "Active work is the union of observed step intervals; it excludes gaps and is not a full run-clock measurement.",
+      ...run.teamRerun ? ["Selective reruns retain explicitly pinned source task inputs. Baseline task counts are not newly executed work; final review still covers every original requirement."] : [],
+      ...!team ? ["Supervisor coordination includes its planning, integration and repair turns; legacy requirements have no structured coverage manifest."] : []
+    ]
+  };
+}
+function assessTeamRollout(reports) {
+  const real = reports.filter((report) => report.mode === "real" && report.status !== "running");
+  const auto = real.filter((report) => report.pattern === "auto-team");
+  const pairs = /* @__PURE__ */ new Map();
+  for (const report of real) if (report.pairId) {
+    const key = `${report.pairId}:${report.caseId}:${report.taskHash}:${report.baseRef}`;
+    pairs.set(key, [...pairs.get(key) ?? [], report]);
+  }
+  const matched = [...pairs.values()].filter((items) => items.some((item) => item.pattern === "auto-team") && items.some((item) => item.pattern === "supervisor"));
+  const verifiedMatch = matched.some((items) => items.some((item) => item.pattern === "auto-team" && item.verified));
+  const pairedQuality = matched.every((items) => !items.some((item) => item.pattern === "supervisor" && item.verified) || items.some((item) => item.pattern === "auto-team" && item.verified));
+  const multi = auto.filter((report) => report.metrics.multiWorker);
+  const denominator = multi.reduce((sum, report) => sum + report.metrics.invocations, 0);
+  const overhead = denominator ? multi.reduce((sum, report) => sum + report.metrics.coordinatorInvocations, 0) / denominator : null;
+  const workerTurns = auto.reduce((sum, report) => sum + report.metrics.workerTurns, 0);
+  const peerYields = auto.reduce((sum, report) => sum + (report.metrics.peerYieldRate ?? 0) * report.metrics.workerTurns, 0);
+  const blockers = [];
+  if (auto.length < 20) blockers.push(`Need 20 real Auto runs; recorded ${auto.length}.`);
+  if (workerTurns < 100) blockers.push(`Need 100 real worker turns; recorded ${workerTurns}.`);
+  if (matched.length < 20) blockers.push(`Need 20 matched Auto/Supervisor comparisons; recorded ${matched.length}.`);
+  if (!pairedQuality) blockers.push("Auto verification regressed against a matched Supervisor result.");
+  if (auto.some((report) => !report.verified)) blockers.push("Some real Auto results are incomplete or unverified.");
+  if (overhead === null || overhead > 0.25) blockers.push(overhead === null ? "No multi-worker coordinator overhead sample." : "Observed multi-worker coordinator calls exceed 25% of invocations.");
+  if (real.some((report) => !Object.keys(report.cliVersions).length)) blockers.push("Some real results have no recorded CLI versions.");
+  return { realRuns: real.length, realAutoRuns: auto.length, realWorkerTurns: workerTurns, matchedPairs: matched.length, verifiedAutoRuns: auto.filter((report) => report.verified).length, overheadFraction: overhead, peerYieldRate: workerTurns ? peerYields / workerTurns : null, eligibleBeta: verifiedMatch && pairedQuality && real.every((report) => Object.keys(report.cliVersions).length > 0), eligibleDefault: blockers.length === 0, blockers };
+}
+class TeamEvaluationStore {
+  constructor(directory = join(CODEFLOW_HOME, "team-evaluations")) {
+    this.directory = directory;
+  }
+  queue = Promise.resolve();
+  async write(file, value) {
+    await mkdir(this.directory, { recursive: true });
+    const temporary = join(this.directory, `.${file}.${randomBytes(8).toString("hex")}.tmp`);
+    try {
+      const handle = await open(temporary, "wx", 384);
+      try {
+        await handle.writeFile(JSON.stringify(value, null, 2) + "\n");
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename(temporary, join(this.directory, file));
+      if (process.platform !== "win32") {
+        const dir = await open(this.directory, "r");
+        try {
+          await dir.sync();
+        } finally {
+          await dir.close();
+        }
+      }
+    } finally {
+      await rm(temporary, { force: true });
+    }
+  }
+  async list() {
+    const names = await readdir(this.directory).catch((error) => {
+      if (error.code === "ENOENT") return [];
+      throw error;
+    });
+    const reports = await Promise.all(names.filter((name) => /^evaluation-[\w-]+\.json$/.test(name)).map(async (name) => {
+      const value = JSON.parse(await readFile(join(this.directory, name), "utf8"));
+      if (value.version !== 1 || value.id + ".json" !== name) throw new Error(`Unsupported or damaged evaluation ${name}`);
+      return value;
+    }));
+    return reports.sort((a, b) => b.at - a.at || a.id.localeCompare(b.id));
+  }
+  async record(report) {
+    if (report.version !== 1 || !/^evaluation-[\w-]+$/.test(report.id) || !["fake", "real", "unknown"].includes(report.mode)) throw new Error("Invalid evaluation report");
+    const operation = this.queue.then(async () => {
+      const previous = await readFile(join(this.directory, `${report.id}.json`), "utf8").catch((error) => {
+        if (error.code === "ENOENT") return void 0;
+        throw error;
+      });
+      if (previous) {
+        if (JSON.stringify(JSON.parse(previous)) !== JSON.stringify(report)) throw new Error("An evaluation is immutable; use a new run for another trial");
+        return report;
+      }
+      await this.write(`${report.id}.json`, report);
+      return report;
+    });
+    this.queue = operation.catch(() => void 0);
+    return operation;
+  }
+  async rollout(enabled = true) {
+    const decision = await readFile(join(this.directory, "rollout.json"), "utf8").then((text) => JSON.parse(text), (error) => {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    if (decision && (!["experimental", "beta", "default"].includes(decision.stage) || !Array.isArray(decision.evaluationIds))) throw new Error("Damaged team rollout decision");
+    return { enabled, stage: decision?.stage ?? "experimental", reason: enabled ? decision?.rationale ?? "No evaluation promotion decision has been recorded. The application default is configured separately." : "New Auto teams are disabled. Existing teams can still be viewed and resumed.", decision };
+  }
+  async decide(input) {
+    if (!["experimental", "beta", "default"].includes(input.stage) || typeof input.rationale !== "string" || !input.rationale.trim() || input.rationale.length > 4e3 || !Array.isArray(input.evaluationIds)) throw new Error("Choose a stage, evaluation reports and a written rationale");
+    const operation = this.queue.then(async () => {
+      const all = await this.list();
+      const ids = [...new Set(input.evaluationIds)];
+      if (ids.some((id) => !all.some((report) => report.id === id))) throw new Error("Unknown evaluation report");
+      const selected = all.filter((report) => ids.includes(report.id));
+      const assessment = assessTeamRollout(all);
+      if (input.stage === "beta" && !assessment.eligibleBeta) throw new Error("Beta needs a verified real Auto result and a matched Supervisor comparison with CLI versions and no verification regression");
+      if (input.stage === "default" && !assessment.eligibleDefault) throw new Error(`Default rollout is not supported: ${assessment.blockers.join(" ")}`);
+      if (input.stage !== "experimental" && !selected.length) throw new Error("Cite the evaluation reports the decision rests on");
+      const decision = { at: Date.now(), stage: input.stage, rationale: input.rationale.trim(), evaluationIds: ids };
+      await this.write(`decision-${decision.at}-${randomBytes(4).toString("hex")}.json`, decision);
+      await this.write("rollout.json", decision);
+      return this.rollout();
+    });
+    this.queue = operation.catch(() => void 0);
+    return operation;
+  }
+}
+const teamEvaluationStore = new TeamEvaluationStore();
+export {
+  TeamEvaluationStore,
+  assessTeamRollout,
+  buildTeamEvaluation,
+  intervalDuration,
+  teamEvaluationStore
+};

package/src/team-mailbox.js

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+const TYPES = /* @__PURE__ */ new Set(["send_message", "ask_member", "reply_request", "yield_task", "publish_finding", "propose_contract", "submit_task", "request_help"]);
+const FIELDS = /* @__PURE__ */ new Set(["type", "operationId", "recipient", "body", "requestId", "blocking", "deadlineMs", "checkpoint", "evidence", "title", "paths", "artifacts"]);
+const nonempty = (v, max) => typeof v === "string" && !!v.trim() && v.length <= max;
+const list = (v, max) => v === void 0 || Array.isArray(v) && v.length <= max && v.every((x) => nonempty(x, 2e3));
+const stable = (value) => JSON.stringify(value, (_key, v) => v && !Array.isArray(v) && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((key) => [key, v[key]])) : v);
+function mailboxCommandProblem(command) {
+  if (!command || !TYPES.has(command.type) || Object.keys(command).some((key) => !FIELDS.has(key))) return "Unknown collaboration command or field";
+  if (!nonempty(command.operationId, 240)) return "operationId must be a stable nonempty ID of at most 240 characters";
+  if (command.body !== void 0 && !nonempty(command.body, 8e3)) return "body must contain 1\u20138000 characters";
+  if (command.checkpoint !== void 0 && !nonempty(command.checkpoint, 12e3)) return "checkpoint must contain 1\u201312000 characters";
+  if (command.title !== void 0 && !nonempty(command.title, 200)) return "title must contain 1\u2013200 characters";
+  if (!list(command.evidence, 16) || !list(command.artifacts, 24) || !list(command.paths, 24)) return "Message evidence, artifacts, or paths exceed bounds";
+  if (command.recipient !== void 0 && !nonempty(command.recipient, 40)) return "Invalid recipient";
+  if (command.requestId !== void 0 && !nonempty(command.requestId, 300)) return "Invalid request ID";
+  if (command.blocking !== void 0 && typeof command.blocking !== "boolean") return "blocking must be boolean";
+  if (command.deadlineMs !== void 0 && (!Number.isSafeInteger(command.deadlineMs) || command.deadlineMs < 1e3 || command.deadlineMs > 36e5)) return "deadlineMs must be between 1000 and 3600000";
+  if (["send_message", "ask_member", "reply_request", "publish_finding", "propose_contract", "request_help"].includes(command.type) && !command.body) return "This command needs a body";
+  if (["send_message", "ask_member"].includes(command.type) && !command.recipient) return "This command needs an addressed recipient";
+  if (command.type === "reply_request" && (!command.requestId || !command.evidence?.length)) return "A reply needs a request ID and evidence";
+  if (["yield_task", "submit_task"].includes(command.type) && !command.checkpoint) return "Task transitions need a portable checkpoint";
+  if (["publish_finding", "propose_contract"].includes(command.type) && !command.evidence?.length) return "Shared proposals need supporting evidence";
+  return void 0;
+}
+function applyMailboxCommand(input, command, authority, now) {
+  const state = structuredClone(input);
+  return { state, receipt: applyMailboxCommandInPlace(state, command, authority, now) };
+}
+function applyMailboxCommandInPlace(state, command, authority, now) {
+  const problem = mailboxCommandProblem(command);
+  if (problem) throw new Error(problem);
+  const { stepId: _physicalStep, ...logicalAuthority } = authority;
+  const fingerprint = createHash("sha256").update(stable({ command, authority: logicalAuthority })).digest("hex");
+  const previous = state.commandReceipts?.find((r) => r.operationId === command.operationId);
+  if (previous) {
+    if (previous.fingerprint !== fingerprint) throw new Error("operationId was already used for different collaboration content");
+    return previous;
+  }
+  if ((state.commandReceipts?.length ?? 0) >= 4096) throw new Error("Run collaboration command limit reached");
+  state.commandReceipts ??= [];
+  state.waits ??= [];
+  const receipt = { operationId: command.operationId, fingerprint, status: "accepted" };
+  const done = () => {
+    state.commandReceipts.push(receipt);
+    return receipt;
+  };
+  const stale = (reason) => {
+    receipt.status = "stale";
+    receipt.reason = reason;
+    return done();
+  };
+  const member = state.members.find((m) => m.id === authority.memberId);
+  const task = state.tasks.find((t) => t.id === authority.taskId);
+  if (authority.origin === "agent" && (!member || member.status === "retired")) return stale("The sending member is absent or retired");
+  if (authority.origin === "user" && authority.memberId !== "user") throw new Error("User origin requires authenticated user identity");
+  if (authority.taskId && (!task || task.owner !== authority.memberId || authority.attempt !== task.attempts)) return stale("The task has been reassigned or this attempt is no longer current");
+  const messageId = `mail:${createHash("sha256").update(command.operationId).digest("hex").slice(0, 24)}`;
+  const effectiveRecipient = (requested) => requested === "user" ? "user" : state.members.some((m) => m.id === requested && m.status !== "retired") ? requested : "coordinator";
+  const add = (kind, recipient, body, blocking = false) => {
+    const target = effectiveRecipient(recipient);
+    const message = { id: messageId, kind, sender: authority.memberId, recipient: target, taskId: task?.id ?? "", body, blocking, evidence: command.evidence ?? [], status: kind === "question" ? "open" : "answered", sourceStepId: authority.stepId ?? "collaboration", origin: authority.origin, sourceAttempt: authority.attempt, revision: state.revision, createdAt: now, delivery: { status: "queued" }, ...target !== recipient ? { originalRecipient: recipient } : {} };
+    state.messages.push(message);
+    receipt.messageId = messageId;
+    return message;
+  };
+  if (command.type === "reply_request") {
+    const question = state.messages.find((m) => m.id === command.requestId && m.kind === "question");
+    if (!question) throw new Error("Unknown request ID");
+    if (question.recipient === "user" ? authority.origin !== "user" : authority.memberId !== question.recipient && authority.memberId !== "coordinator") throw new Error("Only the addressed member or coordinator may answer this request");
+    if (question.status !== "open") return stale("The request already has an accepted answer");
+    const owner = state.tasks.find((t) => t.id === question.taskId);
+    const reply = add("reply", owner?.owner ?? question.sender, command.body);
+    reply.taskId = question.taskId;
+    reply.requestId = question.id;
+    question.status = "answered";
+    question.answeredAt = now;
+    receipt.requestId = question.id;
+    for (const wait of state.waits) if (wait.requestId === question.id && wait.status !== "resolved") {
+      wait.status = "resolved";
+      wait.resolvedAt = now;
+    }
+    if (owner?.status === "needs_info" && !state.messages.some((m) => m.kind === "question" && m.taskId === owner.id && m.blocking && m.status === "open")) owner.status = "pending";
+  } else if (command.type === "ask_member" || command.type === "request_help") {
+    if (!task) throw new Error("Questions must belong to a current task");
+    if (command.recipient === authority.memberId) throw new Error("A member cannot ask itself");
+    const question = add("question", command.recipient ?? "coordinator", command.body, command.blocking ?? true);
+    question.deadlineAt = now + (command.deadlineMs ?? 12e4);
+    receipt.requestId = question.id;
+    state.metrics.questionCount++;
+    if (question.blocking) {
+      state.waits.push({ requestId: question.id, taskId: task.id, memberId: member.id, attempt: authority.attempt, status: "waiting", createdAt: now, deadlineAt: question.deadlineAt });
+      task.waitingSince ??= now;
+    }
+  } else if (command.type === "yield_task") {
+    if (!task || !member) throw new Error("yield_task needs a current assignment");
+    if (task.status !== "running" && task.status !== "needs_info") return stale("The assignment already finished");
+    if (!state.messages.some((m) => m.kind === "question" && m.taskId === task.id && m.blocking && m.status === "open")) throw new Error("Yield requires an unresolved blocking request");
+    task.checkpoint = command.checkpoint;
+    task.checkpointOwner = member.id;
+    task.error = "Yield requested; waiting for the current turn to release its process slot";
+  } else if (command.type === "submit_task") {
+    if (!task || !member) throw new Error("submit_task needs a current assignment");
+    if (task.status !== "running") return stale("The assignment is not running");
+    if (state.messages.some((m) => m.kind === "question" && m.taskId === task.id && m.blocking && m.status === "open")) throw new Error("Cannot submit with an unanswered blocking request");
+    task.checkpoint = command.checkpoint;
+    task.checkpointOwner = member.id;
+    task.artifacts = command.artifacts ?? [];
+    add("message", "coordinator", "Task submission proposed; artifact verification is pending.");
+  } else {
+    const kind = command.type === "publish_finding" ? "finding" : command.type === "propose_contract" ? "contract" : "message";
+    add(kind, command.recipient ?? "coordinator", `${command.title ? `${command.title}
+` : ""}${command.body}`);
+  }
+  return done();
+}
+function applyMailboxProjection(target, next) {
+  const tasks = next.tasks.map((t) => {
+    const previous = target.tasks.find((old) => old.id === t.id);
+    return previous ? Object.assign(previous, t) : t;
+  });
+  const members = next.members.map((m) => {
+    const previous = target.members.find((old) => old.id === m.id);
+    return previous ? Object.assign(previous, m) : m;
+  });
+  Object.assign(target, next, { tasks, members });
+}
+function escalateMailbox(state, now, unavailable = /* @__PURE__ */ new Set()) {
+  const reasons = [];
+  const open = state.messages.filter((m) => m.kind === "question" && m.status === "open" && m.recipient !== "user");
+  const edges = /* @__PURE__ */ new Map();
+  for (const q of open.filter((q2) => q2.blocking)) edges.set(q.sender, [...edges.get(q.sender) ?? [], q.recipient]);
+  const reaches = (from, target, visited = /* @__PURE__ */ new Set()) => {
+    if (from === target) return true;
+    if (visited.has(from)) return false;
+    visited.add(from);
+    return (edges.get(from) ?? []).some((next) => reaches(next, target, visited));
+  };
+  for (const question of open) {
+    const wait = state.waits?.find((w) => w.requestId === question.id);
+    if (wait?.status === "escalated") continue;
+    const recipient = state.members.find((m) => m.id === question.recipient);
+    const reason = !recipient || recipient.status === "retired" || unavailable.has(question.recipient) ? "recipient unavailable" : question.deadlineAt !== void 0 && question.deadlineAt <= now ? "request deadline elapsed" : reaches(question.recipient, question.sender) ? "cyclic member wait" : void 0;
+    if (!reason) continue;
+    question.originalRecipient ??= question.recipient;
+    question.recipient = "coordinator";
+    if (wait) {
+      wait.status = "escalated";
+      wait.reason = reason;
+    }
+    reasons.push(`${question.id}: ${reason}`);
+  }
+  return reasons;
+}
+export {
+  applyMailboxCommand,
+  applyMailboxCommandInPlace,
+  applyMailboxProjection,
+  escalateMailbox,
+  mailboxCommandProblem
+};

package/src/team-memory.js

@@ -0,0 +1,84 @@
+import { git, isAncestor, resolveCommit } from "./git.js";
+import { memoryStore } from "./memory.js";
+const empty = () => ({ entries: [], manifest: { included: [], omitted: [] } });
+function memoryAuthorityForRun(run, memberId) {
+  const sourceTrust = run.lockdown || run.source?.trusted === false || run.source?.untrustedText || run.inheritedSourceTrust === "untrusted" ? "untrusted" : run.source && run.source.trusted !== true || run.inheritedSourceTrust === "unknown" ? "unknown" : "trusted";
+  return { kind: "run", runId: run.id, repo: run.repo, projectId: run.project, memberId, lockedDown: !!run.lockdown, sourceTrust };
+}
+async function projectMemoryForRun(run, memberId, taskId, paths, options = {}) {
+  if (!memberOfProject(run, options)) return empty();
+  return (options.store ?? memoryStore).retrieve(await projectQuery(run, memberId, taskId, paths, options), memoryAuthorityForRun(run, memberId));
+}
+async function projectMemoryFromManifest(run, manifest, memberId, taskId, paths, options = {}) {
+  if (!memberOfProject(run, options)) return { entries: [], manifest: { included: [], omitted: [...manifest.omitted, ...manifest.included.map((ref) => ({ ...ref, reason: "project membership changed" }))] } };
+  return (options.store ?? memoryStore).resolveSelection(await projectQuery(run, memberId, taskId, paths, options), manifest, memoryAuthorityForRun(run, memberId));
+}
+async function projectQuery(run, memberId, taskId, paths, options) {
+  const store = options.store ?? memoryStore;
+  const authority = memoryAuthorityForRun(run, memberId);
+  const head = options.head ?? run.baseRef;
+  const branch = options.branch ?? await runBaseBranch(run);
+  const entries = await store.list({ repo: run.repo, projectId: run.project, scope: "project" }, authority);
+  const commits = [...new Set(entries.flatMap((entry) => entry.applicability.kind === "branch" && entry.applicability.branch === branch && entry.applicability.commit ? [entry.applicability.commit] : []))].slice(0, 128);
+  const allowedCommits = [];
+  for (const commit of commits) if (commit === head || await isAncestor(run.repo, commit, head)) allowedCommits.push(commit);
+  return {
+    repo: run.repo,
+    projectId: run.project,
+    scope: "project",
+    runId: run.id,
+    memberId,
+    branch,
+    commit: head,
+    allowedCommits,
+    paths,
+    query: options.query ?? `${run.task}
+${taskId ?? ""}`,
+    maxEntries: options.maxEntries ?? 8,
+    maxChars: options.maxChars ?? 8e3
+  };
+}
+async function proposeProjectMemories(run, findings, taskId, head, memberId, options = {}) {
+  if (!memberOfProject(run, options) || run.learn === false || !findings.length) return [];
+  if (!/^[0-9a-f]{40,64}$/i.test(head)) throw new Error("Memory findings require a full result commit SHA");
+  const store = options.store ?? memoryStore;
+  const authority = memoryAuthorityForRun(run, memberId);
+  const branch = options.branch ?? run.worktrees.find((tree) => tree.name === "integrated")?.branch ?? run.worktrees.find((tree) => tree.name === "integration")?.branch ?? `${run.branchPrefix}/integrated`;
+  const shown = run.memoryManifest?.included.map(({ id, revision }) => ({ id, revision })) ?? [];
+  const created = [];
+  for (const [index, finding] of findings.slice(0, 32).entries()) {
+    const refs = [...new Map((finding.derivedFrom ?? shown).map((ref) => [`${ref.id}@${ref.revision}`, ref])).values()];
+    created.push(await store.propose({
+      scope: "project",
+      repo: run.repo,
+      projectId: run.project,
+      runId: run.id,
+      memberId,
+      title: finding.title,
+      body: finding.body,
+      paths: finding.paths,
+      applicability: { kind: "branch", branch, commit: head },
+      derivedFrom: refs,
+      sourceRefs: [`run:${run.id}`, `task:${taskId}`, `commit:${head}`, ...finding.evidenceRefs ?? []],
+      operationId: `${run.id}:${taskId}:${head}:${index}`
+    }, authority));
+  }
+  return created;
+}
+function memberOfProject(run, options) {
+  if (!run.project) return false;
+  if (!options.projects) return true;
+  return options.projects.get(run.project)?.repos.includes(run.repo) ?? false;
+}
+async function runBaseBranch(run) {
+  if (run.baseLabel && run.baseLabel !== "HEAD" && !/^[0-9a-f]{40,64}$/i.test(run.baseLabel)) return run.baseLabel.replace(/^refs\/heads\//, "");
+  if (await resolveCommit(run.repo).catch(() => void 0) !== run.baseRef) return void 0;
+  const result = await git(["symbolic-ref", "--quiet", "--short", "HEAD"], run.repo);
+  return result.code === 0 ? result.stdout.trim() || void 0 : void 0;
+}
+export {
+  memoryAuthorityForRun,
+  projectMemoryForRun,
+  projectMemoryFromManifest,
+  proposeProjectMemories
+};

package/src/team-rerun-graph.js

@@ -0,0 +1,15 @@
+function dependentTaskClosure(tasks, selected) {
+  const included = new Set(selected);
+  for (let pass = 0; pass < tasks.length; pass++) {
+    let changed = false;
+    for (const task of tasks) if (!included.has(task.id) && task.dependsOn.some((id) => included.has(id))) {
+      included.add(task.id);
+      changed = true;
+    }
+    if (!changed) break;
+  }
+  return included;
+}
+export {
+  dependentTaskClosure
+};