@prjct.app/pi-team 0.6.1 → 0.7.0

package/src/dynamic/peer-log.ts

@@ -0,0 +1,39 @@
+import { appendFile, chmod, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { metadata } from './domain.ts';
+
+/** Kinds an Expert may send another Expert directly. */
+export const PEER_KINDS = ['blocker', 'question', 'info', 'handoff'] as const;
+export type PeerKind = (typeof PEER_KINDS)[number];
+
+/** One Expert-to-Expert message, as the orchestrator and /team show it. */
+export type PeerEntry = { readonly at: string; readonly from: string; readonly to: string; readonly kind: PeerKind; readonly body: string };
+
+const LOG = 'peer-messages.jsonl';
+const KEEP = 200;
+
+/**
+ * Append-only record of direct messages, so the person (and the orchestrator)
+ * can see who talked to whom. The message itself travels through the durable
+ * inbox; this is only the trace. Private to the user (0600).
+ */
+export async function recordPeerMessage(directory: string, entry: PeerEntry): Promise<void> {
+  const path = join(directory, LOG);
+  const line = JSON.stringify({ ...entry, body: metadata(entry.body, 600) });
+  await appendFile(path, `${line}\n`, { mode: 0o600 });
+  await chmod(path, 0o600).catch(() => {});
+}
+
+/** The most recent direct messages, newest last. */
+export async function recentPeerMessages(directory: string, limit = 20): Promise<PeerEntry[]> {
+  const text = await readFile(join(directory, LOG), 'utf8').catch(() => '');
+  return text.split('\n').filter(Boolean).slice(-KEEP).flatMap(line => {
+    try {
+      const value = JSON.parse(line) as PeerEntry;
+      return typeof value.from === 'string' && typeof value.to === 'string' && (PEER_KINDS as readonly string[]).includes(value.kind) ? [value] : [];
+    } catch { return []; }
+  }).slice(-limit);
+}
+
+/** "fty-4 → fty-26 blocker: needs the /api/demo route merged first" */
+export const peerLine = (entry: PeerEntry): string => `${entry.from} → ${entry.to} ${entry.kind}: ${entry.body.replace(/\s+/g, ' ').slice(0, 200)}`;

package/src/dynamic/runner.ts

@@ -0,0 +1,196 @@
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { ensurePrivateTree, createAtomicJson } from '../storage/atomic.ts';
+import { TeamPaths } from '../storage/paths.ts';
+import { TeamRuntime } from '../runtime/team-runtime.ts';
+import type { Lease } from '../domain/lease.ts';
+import type { Membership } from '../runtime/membership.ts';
+import { TeamSupervisor, type SupervisorOptions } from '../supervisor/supervisor.ts';
+import type { ExpertExecution, ExpertOutcome, ExpertRunner } from './service.ts';
+import { DynamicStore } from './store.ts';
+import { metadata } from './domain.ts';
+import { expertWorkspace, isGitCheckout } from './workspace.ts';
+import { expertMemory, expertStance, type ExpertStance } from './memory.ts';
+
+export type SupervisorPort = Pick<TeamSupervisor, 'launch' | 'stop' | 'close' | 'owner'>;
+type RunnerSetup = { readonly membership: Membership; readonly supervisor: SupervisorPort };
+export type RunnerOptions = {
+  readonly runtime?: TeamRuntime;
+  readonly supervisor?: (options: SupervisorOptions) => SupervisorPort;
+  readonly command?: readonly [string, ...string[]];
+  readonly environment?: Readonly<Record<string, string | undefined>>;
+  readonly pollMs?: number;
+  readonly timeoutMs?: number;
+  /** Where a write-capable Expert works. Defaults to its own Git worktree when the project is a checkout. */
+  readonly workspace?: (input: ExpertExecution) => Promise<string>;
+  /** Project memory for the Expert's stance and task. Defaults to the view pi-memory publishes. */
+  readonly memory?: (stance: ExpertStance, query: string) => Promise<string>;
+};
+const WRITE_TOOLS = ['edit', 'write', 'bash'];
+// The compiled local build ships index.js; source checkouts execute index.ts directly.
+const ENTRY = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../../index.ts' : '../../index.js', import.meta.url));
+
+/**
+ * Why an Expert did not start, safe to show: a failed child command's message
+ * repeats its arguments (tmux -e carries control and lease tokens), so it is
+ * replaced, and anything token-shaped is masked.
+ */
+export function safeReason(error: unknown): string {
+  if (!(error instanceof Error)) return 'unknown error';
+  const code = (error as { code?: unknown }).code;
+  const text = /Command failed|spawn|tmux\s/i.test(error.message) ? 'tmux could not start the Expert session' : error.message;
+  return metadata(`${text.replace(/[A-Za-z0-9_+/=-]{32,}/g, '…')}${typeof code === 'string' ? ` (${code})` : ''}`, 240);
+}
+
+/** Durable request/reply transport; a launch or a model turn alone is never success. */
+export class ProductionExpertRunner implements ExpertRunner {
+  readonly runtime: TeamRuntime;
+  private setup?: Promise<RunnerSetup>;
+  private refresh?: Promise<RunnerSetup>;
+  private readonly closing = new AbortController();
+  private readonly pending = new Set<Promise<ExpertOutcome>>();
+  constructor(readonly store: DynamicStore, private readonly options: RunnerOptions = {}) {
+    this.runtime = options.runtime ?? new TeamRuntime(new TeamPaths(join(store.root, 'transport')));
+  }
+  private initialize(input: ExpertExecution) {
+    return this.setup ??= (async () => {
+      const at = new Date().toISOString();
+      if (!await this.runtime.teams.read(input.teamId)) {
+        await this.runtime.teams.create({ schemaVersion: 2, teamId: input.teamId, state: 'open', createdAt: at, updatedAt: at });
+      }
+      const membership = await this.runtime.memberships.join({ teamId: input.teamId, alias: 'orchestrator',
+        sessionId: input.owner.sessionId, cwd: input.projectPath, kind: 'external' });
+      const options: SupervisorOptions = { teamId: input.teamId, ownerSessionId: input.owner.sessionId,
+        ownerInstanceId: input.owner.instanceId, ownerEpoch: input.owner.epoch,
+        paths: this.runtime.paths, teams: this.runtime.teams, runtimes: this.runtime.runtimes };
+      return { membership, supervisor: this.options.supervisor?.(options) ?? new TeamSupervisor(options) };
+    })();
+  }
+  private async activeSetup(input: ExpertExecution): Promise<RunnerSetup> {
+    const setup = await this.initialize(input);
+    try {
+      await this.runtime.memberships.heartbeat(setup.membership);
+      return setup;
+    } catch (error) {
+      if ((error as { code?: string }).code !== 'FENCED') throw error;
+      this.refresh ??= (async () => {
+        const membership = await this.runtime.memberships.join({ teamId: input.teamId, alias: 'orchestrator',
+          sessionId: input.owner.sessionId, cwd: input.projectPath, kind: 'external' });
+        const refreshed = { ...setup, membership };
+        this.setup = Promise.resolve(refreshed);
+        return refreshed;
+      })().finally(() => { this.refresh = undefined; });
+      return this.refresh;
+    }
+  }
+  private readonly defaultWorkspace = async (input: ExpertExecution): Promise<string> =>
+    await isGitCheckout(input.projectPath)
+      ? expertWorkspace({ root: this.store.root, teamId: input.teamId, expertId: input.expert.id, projectPath: input.projectPath })
+      : input.projectPath;
+  run(input: ExpertExecution, signal: AbortSignal): Promise<ExpertOutcome> {
+    const operation = this.execute(input, AbortSignal.any([signal, this.closing.signal, AbortSignal.timeout(this.options.timeoutMs ?? 600_000)]));
+    this.pending.add(operation);
+    void operation.finally(() => this.pending.delete(operation)).catch(() => {});
+    return operation;
+  }
+  private async execute(input: ExpertExecution, signal: AbortSignal): Promise<ExpertOutcome> {
+    const state: { runtimeId?: string; requestId?: string; peer?: Membership; supervisor?: SupervisorPort; owner?: Membership;
+      resource?: Lease; outcome: ExpertOutcome } = { outcome: { status: 'failed', summary: 'Expert execution failed; inspect /team doctor.', stopped: false } };
+    try {
+      signal.throwIfAborted();
+      const { membership, supervisor } = await this.activeSetup(input);
+      state.owner = membership; state.supervisor = supervisor;
+      await ensurePrivateTree(this.store.root, 'projects', input.teamId, 'sessions');
+      const session = this.store.sessionPath(input.teamId, input.expert.sessionRef);
+      const info = await lstat(session).catch(error => {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+        throw error;
+      });
+      if (info && (!info.isFile() || info.isSymbolicLink() || (info.mode & 0o077) !== 0)) throw new Error('Unsafe Expert session.');
+      const writer = input.expert.policy.tools.some(tool => WRITE_TOOLS.includes(tool));
+      const cwd = writer ? await (this.options.workspace ?? this.defaultWorkspace)(input) : input.projectPath;
+      if (!info) await createAtomicJson(session, { type: 'session', version: 3, id: input.expert.sessionRef,
+        timestamp: new Date().toISOString(), cwd });
+      state.peer = await this.runtime.memberships.join({ teamId: input.teamId, alias: `e-${input.expert.id}`,
+        sessionId: input.expert.sessionRef, cwd, kind: 'supervised' });
+      if (writer) {
+        state.resource = await this.runtime.resources.claim(state.peer, '.', undefined, signal);
+      }
+      signal.throwIfAborted();
+      const command: readonly [string, ...string[]] = this.options.command ?? (process.argv[1]
+        ? [process.execPath, process.argv[1]] : ['pi']);
+      const launched = await supervisor.launch({ memberId: state.peer.memberId, cwd,
+        workerMembership: state.peer, autoRequests: true, environment: this.options.environment ?? process.env,
+        command: [...command,
+          '--no-approve', '--no-extensions', '--no-skills', '--no-prompt-templates', '--no-context-files',
+          '--extension', ENTRY, '--team-store', this.store.root,
+          '--session', session, '--tools', [...input.expert.policy.tools, 'team_reply', 'team_peers', 'team_message'].join(','),
+          '--name', `expert:${input.expert.role}`] as [string, ...string[]] });
+      state.runtimeId = launched.runtimeId;
+      signal.throwIfAborted();
+      const memory = await (this.options.memory ?? expertMemory)(expertStance(input.expert.role, input.expert.policy.tools),
+        input.assignment.task).catch(() => '');
+      signal.throwIfAborted();
+      const request = await this.runtime.requests.send(membership, { to: state.peer.alias, kind: 'request',
+        body: JSON.stringify({ assignmentId: input.assignment.id, generation: input.assignment.generation,
+          ownerEpoch: input.assignment.ownerEpoch, task: input.assignment.task, ...(memory ? { memory } : {}) }), signal });
+      state.requestId = request.messageId;
+      const heartbeat = { at: 0 };
+      while (!signal.aborted) {
+        if (Date.now() - heartbeat.at >= 10_000) {
+          await this.runtime.memberships.heartbeat(membership);
+          if (state.resource && state.peer) state.resource = await this.runtime.resources.renew(state.peer, '.',
+            state.resource.token, state.resource.generation);
+          heartbeat.at = Date.now();
+        }
+        const receipt = await this.runtime.receipts.read(input.teamId, state.peer.memberId, request.messageId);
+        if (receipt?.status === 'replied') {
+          const reply = await this.runtime.requests.receive(membership, `reply-${request.messageId}`, signal);
+          if (!reply.discarded && reply.message?.kind === 'reply' && reply.message.requestId === request.messageId &&
+              reply.message.fromMemberId === state.peer.memberId && reply.message.senderGeneration === state.peer.memberGeneration) {
+            state.outcome = { status: 'completed', summary: metadata(reply.message.body), stopped: false };
+          }
+          break;
+        }
+        if (receipt && ['failed', 'cancelled', 'expired'].includes(receipt.status)) break;
+        const record = await this.runtime.runtimes.read(input.teamId, launched.runtimeId);
+        if (!record || ['lost', 'terminated'].includes(record.state)) break;
+        await delay(this.options.pollMs ?? 250, undefined, { signal });
+      }
+    } catch (error) {
+      // Never expose command stderr: tmux arguments contain control/lease
+      // credentials. The error's own message and code are safe and say why.
+      const reason = safeReason(error);
+      state.outcome = { status: signal.aborted ? 'cancelled' : 'failed', summary: signal.aborted
+        ? 'Expert execution interrupted or timed out.' : `Expert could not start: ${reason}. Inspect /team doctor.`, stopped: false };
+    } finally {
+      if (state.requestId && state.owner && state.outcome.status !== 'completed') {
+        await this.runtime.requests.cancel(state.owner, state.requestId).catch(() => {});
+      }
+      const stopped = state.runtimeId && state.supervisor
+        ? await state.supervisor.stop(state.runtimeId, 'stop').then(r => r.status === 'terminated', () => false)
+        : true;
+      state.outcome = { ...state.outcome, stopped };
+      if (stopped) {
+        if (state.resource && state.peer) await this.runtime.resources.release(state.peer, '.',
+          state.resource.token, state.resource.generation).catch(() => {});
+        if (state.peer) await this.runtime.requests.leave(state.peer).catch(() => {});
+        if (state.runtimeId && state.supervisor) {
+          await this.runtime.runtimes.removeTerminated(input.teamId, state.runtimeId, state.supervisor.owner).catch(() => {});
+        }
+      }
+    }
+    return state.outcome;
+  }
+  async close(): Promise<void> {
+    this.closing.abort();
+    await Promise.allSettled([...this.pending]);
+    const setup = await this.setup?.catch(() => undefined);
+    if (setup) {
+      try { await setup.supervisor.close(); }
+      finally { await this.runtime.requests.leave(setup.membership).catch(() => {}); }
+    }
+  }
+}

package/src/dynamic/service.ts

@@ -0,0 +1,292 @@
+import { randomUUID } from 'node:crypto';
+import { Value } from 'typebox/value';
+import { inspectProcess, sameProcess, type ProcessIdentity } from '../process-identity.ts';
+import { DispatchSchema, LIMITS, bounded, metadata, normalizeTag, terminalAssignment, terminalRun,
+  type Assignment, type Dispatch, type Expert, type Owner, type Run, type TeamState } from './domain.ts';
+import { DynamicStore, type Project } from './store.ts';
+
+export type ExpertExecution = { readonly teamId: string; readonly projectPath: string; readonly owner: Owner; readonly expert: Expert; readonly assignment: Assignment };
+export type ExpertOutcome = { readonly status: 'completed' | 'failed' | 'cancelled'; readonly summary: string; readonly stopped: boolean };
+export interface ExpertRunner {
+  run(input: ExpertExecution, signal: AbortSignal): Promise<ExpertOutcome>;
+  close(): Promise<void>;
+}
+export type ServiceOptions = {
+  readonly sessionId: string;
+  readonly identity: ProcessIdentity;
+  readonly instanceId?: string;
+  readonly now?: () => number;
+  readonly ownerAlive?: (owner: Owner) => Promise<boolean>;
+  readonly onRun?: (run: Run, state: TeamState) => void;
+  readonly onResult?: (assignment: Assignment) => void;
+  /**
+   * Write-capable Experts each work in their own Git worktree, so they may run
+   * in parallel. Without isolation they share one checkout and run one at a time.
+   */
+  readonly isolatedWriters?: boolean;
+};
+export async function ownerAlive(owner: Owner): Promise<boolean> {
+  const identity = await inspectProcess(owner.processPid);
+  if (identity) return sameProcess(owner, identity);
+  // Inability to inspect is not proof of death (permissions/platform failure).
+  try { process.kill(owner.processPid, 0); return true; }
+  catch (error) { return (error as NodeJS.ErrnoException).code !== 'ESRCH'; }
+}
+const owns = (state: TeamState, owner?: Owner): boolean => !!owner && state.owner?.instanceId === owner.instanceId && state.owner.epoch === owner.epoch;
+const timestamp = (now: () => number): string => new Date(now()).toISOString();
+
+function prune(state: TeamState): TeamState {
+  const removable = state.runs.filter(run => terminalRun(run) && !state.assignments.some(a => a.runId === run.id && a.status === 'cancelled_waiting'));
+  const remove = new Set(removable.slice(0, Math.max(0, state.runs.length - LIMITS.runs + 1)).map(run => run.id));
+  const assignments = state.assignments.filter(a => !remove.has(a.runId));
+  const excess = Math.max(0, assignments.length - LIMITS.assignments + 1);
+  const old = new Set(assignments.filter(a => terminalAssignment(a) && a.status !== 'cancelled_waiting').slice(0, excess).map(a => a.id));
+  return { ...state, runs: state.runs.filter(run => !remove.has(run.id)), assignments: assignments.filter(a => !old.has(a.id)) };
+}
+
+export class DynamicTeamService {
+  private owner?: Owner;
+  private closed = false;
+  private readonly executions = new Map<string, { controller: AbortController; promise: Promise<void> }>();
+  private readonly now: () => number;
+  private readonly instanceId: string;
+  constructor(readonly store: DynamicStore, readonly project: Project, readonly runner: ExpertRunner, private readonly options: ServiceOptions) {
+    this.now = options.now ?? Date.now;
+    this.instanceId = options.instanceId ?? randomUUID();
+  }
+  get isOwner(): boolean { return !!this.owner && !this.closed; }
+  snapshot(): Promise<TeamState | undefined> { return this.store.read(this.project.teamId); }
+  private assertOwner(state: TeamState | undefined): asserts state is TeamState {
+    if (this.closed || !state || !owns(state, this.owner)) throw new Error('Run owner is fenced; use /team doctor.');
+  }
+  async submit(objective: string): Promise<Run> {
+    if (this.closed) throw new Error('Team session is shutting down.');
+    bounded(objective, 8192, 'Objective');
+    if (!objective.trim()) throw new Error('An objective is required.');
+    const at = timestamp(this.now);
+    const run: Run = { id: randomUUID(), objective: metadata(objective, 8192), summary: '', status: 'queued', createdAt: at, updatedAt: at };
+    const result = await this.store.update(this.project, async current => {
+      const state = prune(current ?? {
+        schemaVersion: 1, teamId: this.project.teamId, projectPath: this.project.path, epoch: 0,
+        orchestrator: { summary: '' }, experts: [], assignments: [], runs: [], createdAt: at, updatedAt: at,
+      });
+      if (state.runs.length >= LIMITS.runs) throw new Error('Run queue quota reached. Cancel queued Runs first.');
+      const claim = !state.owner || owns(state, this.owner) || !await (this.options.ownerAlive ?? ownerAlive)(state.owner);
+      if (!claim) return { state: { ...state, runs: [...state.runs, run], updatedAt: at }, result: undefined };
+      const owner: Owner = owns(state, this.owner) ? this.owner! : {
+        ...this.options.identity, sessionId: this.options.sessionId, instanceId: this.instanceId, epoch: state.epoch + 1,
+      };
+      const interrupted = !owns(state, this.owner);
+      const abandoned = state.assignments.filter(a => a.status === 'running');
+      return { state: {
+        ...state, owner, epoch: owner.epoch, updatedAt: at,
+        orchestrator: { ...state.orchestrator, lastSessionId: owner.sessionId },
+        runs: [...state.runs.map(r => interrupted && r.status === 'active' ? {
+          ...r, status: 'interrupted' as const, summary: 'Previous owner ended; no automatic retry.', updatedAt: at, endedAt: at,
+        } : r), run],
+        assignments: state.assignments.map(a => interrupted && !terminalAssignment(a) ? {
+          ...a, status: a.status === 'running' ? 'cancelled_waiting' as const : 'cancelled' as const,
+          task: '', error: 'Previous owner ended; execution is not retried.', updatedAt: at, endedAt: at,
+        } : a),
+        experts: state.experts.map(e => interrupted && abandoned.some(a => a.expertId === e.id) ? { ...e, status: 'blocked' as const, updatedAt: at } : e),
+      }, result: owner };
+    });
+    if (result) this.owner = result;
+    return run;
+  }
+  async tick(startRun = true): Promise<void> {
+    if (!this.isOwner) return;
+    if (startRun) {
+      const activated = await this.store.update(this.project, state => {
+        this.assertOwner(state);
+        if (state.runs.some(r => r.status === 'active')) return { state, result: undefined };
+        const next = state.runs.find(r => r.status === 'queued');
+        if (!next) return { state, result: undefined };
+        const at = timestamp(this.now);
+        const run: Run = { ...next, status: 'active', startedAt: at, updatedAt: at };
+        const updated = { ...state, runs: state.runs.map(r => r.id === run.id ? run : r), updatedAt: at };
+        return { state: updated, result: { run, state: updated } };
+      });
+      if (activated) {
+        try { this.options.onRun?.(activated.run, activated.state); }
+        catch { await this.cancelRun(activated.run.id, 'Orchestrator turn could not start; no retry.'); }
+      }
+    }
+    await this.pump();
+  }
+  async dispatch(input: Dispatch): Promise<{ expertId: string; sessionRef: string; assignmentId: string; decision: 'created' | 'reused' }> {
+    if (!Value.Check(DispatchSchema, input)) throw new Error('Invalid dispatch.');
+    bounded(input.task, 8192, 'Task'); bounded(input.instructions ?? '', 4096, 'Instructions');
+    const role = normalizeTag(input.role);
+    const capabilities = [...new Set(input.capabilities.map(normalizeTag))].sort();
+    const result = await this.store.update(this.project, current => {
+      this.assertOwner(current);
+      const state = prune(current);
+      const run = state.runs.find(r => r.status === 'active');
+      if (!run) throw new Error('No active Run. Start with /team <objective>.');
+      if (state.assignments.length >= LIMITS.assignments) throw new Error('Assignment quota reached.');
+      // A role is one Expert: the same role is reused (and queues while busy),
+      // a different role is a new Expert that can run in parallel. Matching on
+      // capabilities put every "implement/test/pr" task on one Expert, in series.
+      const existing = state.experts.find(e => e.role === role);
+      if (existing && !capabilities.every(c => existing.capabilities.includes(c))) throw new Error('Existing role lacks these capabilities; duplicate-role capacity is disabled.');
+      if (existing && (existing.policy.tools.length !== input.policy.tools.length || input.policy.tools.some(t => !existing.policy.tools.includes(t)))) {
+        throw new Error('Existing Expert tool policy differs; implicit policy changes are forbidden.');
+      }
+      if (!existing && state.experts.length >= LIMITS.experts) throw new Error('Expert registry quota reached.');
+      const at = timestamp(this.now);
+      const expert: Expert = existing ?? {
+        id: randomUUID(), role, capabilities, instructions: metadata(input.instructions ?? ''), policy: input.policy,
+        sessionRef: randomUUID(), generation: 0, status: 'idle', memory: '', history: [], createdAt: at, updatedAt: at,
+      };
+      if (expert.status === 'blocked') throw new Error('Expert has unresolved execution; /team doctor. No duplicate will be created.');
+      const assignment: Assignment = {
+        id: randomUUID(), runId: run.id, expertId: expert.id, generation: 0, ownerEpoch: this.owner!.epoch,
+        status: 'queued', task: metadata(input.task, 8192), result: '', error: '', createdAt: at, updatedAt: at,
+      };
+      const updatedExpert = { ...expert, history: [...expert.history, assignment.id].slice(-LIMITS.history), updatedAt: at };
+      return { state: { ...state,
+        experts: existing ? state.experts.map(e => e.id === expert.id ? updatedExpert : e) : [...state.experts, updatedExpert],
+        assignments: [...state.assignments, assignment], updatedAt: at,
+      }, result: { expertId: expert.id, sessionRef: expert.sessionRef, assignmentId: assignment.id, decision: existing ? 'reused' as const : 'created' as const } };
+    });
+    await this.pump();
+    return result;
+  }
+  private async pump(): Promise<void> {
+    if (!this.isOwner) return;
+    const launches = await this.store.update(this.project, state => {
+      this.assertOwner(state);
+      const active = state.runs.find(r => r.status === 'active');
+      const free = LIMITS.concurrent - state.experts.filter(e => e.status === 'busy' || e.status === 'blocked').length;
+      const selected: Assignment[] = [];
+      const isolated = this.options.isolatedWriters === true;
+      const writerBusy = !isolated && state.experts.some(e => e.status === 'busy' && e.policy.tools.some(tool => ['edit', 'write', 'bash'].includes(tool)));
+      for (const a of state.assignments) {
+        const expert = state.experts.find(e => e.id === a.expertId);
+        const writer = expert?.policy.tools.some(tool => ['edit', 'write', 'bash'].includes(tool)) ?? false;
+        if (selected.length >= free) break;
+        if (a.runId === active?.id && a.status === 'queued' && expert?.status === 'idle' &&
+            !selected.some(s => s.expertId === a.expertId) && !(writer && !isolated && (writerBusy || selected.some(s => {
+              const candidate = state.experts.find(e => e.id === s.expertId);
+              return candidate?.policy.tools.some(tool => ['edit', 'write', 'bash'].includes(tool));
+            })))) selected.push(a);
+      }
+      const at = timestamp(this.now);
+      const experts = state.experts.map(e => selected.some(a => a.expertId === e.id) ? { ...e, generation: e.generation + 1, status: 'busy' as const, updatedAt: at } : e);
+      const assignments = state.assignments.map(a => selected.some(s => s.id === a.id) ? {
+        ...a, generation: experts.find(e => e.id === a.expertId)!.generation, status: 'running' as const, updatedAt: at,
+      } : a);
+      const executions = assignments.filter(a => selected.some(s => s.id === a.id)).map(assignment => ({
+        teamId: state.teamId, projectPath: state.projectPath, owner: this.owner!, expert: experts.find(e => e.id === assignment.expertId)!, assignment,
+      }));
+      return { state: { ...state, experts, assignments, updatedAt: at }, result: executions };
+    });
+    for (const execution of launches) {
+      if (!this.isOwner) break;
+      const controller = new AbortController();
+      // The durable running transition precedes model exposure. Even a crash here never retries it.
+      const promise = Promise.resolve().then(() => this.runner.run(execution, controller.signal))
+        .catch((): ExpertOutcome => ({ status: 'failed', summary: 'Worker execution failed; inspect /team doctor.', stopped: false }))
+        .then(outcome => this.settle(execution.assignment, outcome))
+        .catch(() => {})
+        .finally(() => { this.executions.delete(execution.assignment.id); });
+      this.executions.set(execution.assignment.id, { controller, promise });
+    }
+  }
+  private async settle(original: Assignment, outcome: ExpertOutcome): Promise<void> {
+    const settled = await this.store.update(this.project, state => {
+      if (!state || !owns(state, this.owner)) return { state: state!, result: undefined };
+      const assignment = state.assignments.find(a => a.id === original.id);
+      const expert = state.experts.find(e => e.id === original.expertId);
+      if (!assignment || !expert || assignment.generation !== original.generation || expert.generation !== original.generation || assignment.ownerEpoch !== this.owner?.epoch) return { state, result: undefined };
+      const at = timestamp(this.now);
+      if (terminalAssignment(assignment)) {
+        // A proved stop can release capacity, but a late result never changes the cancelled outcome.
+        if (assignment.status !== 'cancelled_waiting' || !outcome.stopped) return { state, result: undefined };
+        return { state: { ...state,
+          assignments: state.assignments.map(a => a.id === assignment.id ? { ...a, status: 'cancelled' as const, updatedAt: at } : a),
+          experts: state.experts.map(e => e.id === expert.id ? { ...e, status: 'idle' as const, updatedAt: at } : e),
+        }, result: undefined };
+      }
+      if (state.runs.find(r => r.id === assignment.runId)?.status !== 'active') return { state, result: undefined };
+      const success = outcome.status === 'completed' && outcome.stopped;
+      const next: Assignment = { ...assignment, task: '', status: success ? 'completed' : 'failed',
+        result: success ? metadata(outcome.summary) : '', error: success ? '' : metadata(outcome.summary, 512), endedAt: at, updatedAt: at };
+      return { state: { ...state, updatedAt: at,
+        assignments: state.assignments.map(a => a.id === next.id ? next : a),
+        experts: state.experts.map(e => e.id === expert.id ? { ...e, status: outcome.stopped ? 'idle' as const : 'blocked' as const,
+          memory: success ? next.result : e.memory, updatedAt: at } : e),
+      }, result: next };
+    });
+    if (settled && !this.closed) this.options.onResult?.(settled);
+    if (!this.closed) await this.pump();
+  }
+  async finish(summary: string): Promise<void> {
+    bounded(summary, 4096, 'Summary');
+    await this.store.update(this.project, state => {
+      this.assertOwner(state);
+      const run = state.runs.find(r => r.status === 'active');
+      if (!run) throw new Error('No active Run.');
+      if (state.assignments.some(a => a.runId === run.id && (!terminalAssignment(a) || a.status === 'cancelled_waiting'))) throw new Error('Assignments remain outstanding; finish is blocked.');
+      const at = timestamp(this.now);
+      return { state: { ...state, updatedAt: at, orchestrator: { ...state.orchestrator, summary: metadata(summary) },
+        runs: state.runs.map(r => r.id === run.id ? { ...r, status: 'completed' as const, summary: metadata(summary), updatedAt: at, endedAt: at } : r),
+      }, result: undefined };
+    });
+  }
+  async cancelAssignment(id: string, reason = 'Cancelled by orchestrator.'): Promise<void> {
+    await this.store.update(this.project, state => {
+      this.assertOwner(state);
+      const a = state.assignments.find(a => a.id === id);
+      if (!a) throw new Error('Unknown assignment.');
+      if (terminalAssignment(a)) return { state, result: undefined };
+      const at = timestamp(this.now);
+      return { state: { ...state, updatedAt: at,
+        assignments: state.assignments.map(item => item.id === id ? { ...item, status: a.status === 'running' ? 'cancelled_waiting' as const : 'cancelled' as const,
+          task: '', error: metadata(reason, 512), updatedAt: at, endedAt: at } : item),
+        experts: state.experts.map(e => e.id === a.expertId && a.status === 'running' ? { ...e, status: 'blocked' as const, updatedAt: at } : e),
+      }, result: undefined };
+    });
+    this.executions.get(id)?.controller.abort();
+  }
+  async cancelRun(id?: string, reason = 'Cancelled by user.'): Promise<void> {
+    const cancelled = await this.store.update(this.project, state => {
+      this.assertOwner(state);
+      const run = id ? state.runs.find(r => r.id === id) : state.runs.find(r => r.status === 'active');
+      if (!run) throw new Error('Unknown Run.');
+      if (terminalRun(run)) return { state, result: [] as string[] };
+      const at = timestamp(this.now);
+      const targets = state.assignments.filter(a => a.runId === run.id && !terminalAssignment(a));
+      return { state: { ...state, updatedAt: at,
+        runs: state.runs.map(r => r.id === run.id ? { ...r, status: 'cancelled' as const, summary: metadata(reason), updatedAt: at, endedAt: at } : r),
+        assignments: state.assignments.map(a => targets.some(t => t.id === a.id) ? { ...a, task: '',
+          status: a.status === 'running' ? 'cancelled_waiting' as const : 'cancelled' as const,
+          error: metadata(reason, 512), updatedAt: at, endedAt: at } : a),
+        experts: state.experts.map(e => targets.some(a => a.expertId === e.id && a.status === 'running') ? { ...e, status: 'blocked' as const, updatedAt: at } : e),
+      }, result: targets.map(a => a.id) };
+    });
+    for (const assignmentId of cancelled) this.executions.get(assignmentId)?.controller.abort();
+  }
+  async close(reason: string): Promise<void> {
+    if (this.closed) return;
+    const state = await this.snapshot();
+    if (state && owns(state, this.owner)) {
+      const active = state.runs.find(r => r.status === 'active');
+      if (active) await this.cancelRun(active.id, `Session ${reason}; safe interruption, no automatic retry.`);
+    }
+    this.closed = true;
+    for (const execution of this.executions.values()) execution.controller.abort();
+    try {
+      await this.runner.close();
+      await Promise.all([...this.executions.values()].map(execution => execution.promise));
+    } finally {
+      if (this.owner) await this.store.update(this.project, current => {
+        if (!current || !owns(current, this.owner)) return { state: current!, result: undefined };
+        const { owner: _owner, ...retained } = current;
+        return { state: { ...retained, epoch: current.epoch + 1, updatedAt: timestamp(this.now) }, result: undefined };
+      });
+      this.owner = undefined;
+    }
+  }
+}

package/src/dynamic/store.ts

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+import { lstat, realpath } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { ensurePrivateDirectory, ensurePrivateTree, readJson, replaceAtomicJson, withStorageLock } from '../storage/atomic.ts';
+import { defaultStorageRoot } from '../storage/paths.ts';
+import { assertState, LIMITS, type TeamState } from './domain.ts';
+
+export type Project = { readonly teamId: string; readonly path: string };
+export async function resolveProject(cwd: string): Promise<Project> {
+  const canonical = await realpath(cwd);
+  const repository = async (path: string): Promise<string | undefined> => {
+    const marker = await lstat(join(path, '.git')).catch(error => {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+      throw error;
+    });
+    if (marker && !marker.isSymbolicLink() && (marker.isDirectory() || marker.isFile())) return path;
+    return dirname(path) === path ? undefined : repository(dirname(path));
+  };
+  const path = await repository(canonical) ?? canonical;
+  return { teamId: `p-${createHash('sha256').update(path).digest('hex').slice(0, 40)}`, path };
+}
+
+export class DynamicStore {
+  readonly root: string;
+  constructor(root = join(defaultStorageRoot(), 'orchestration-v2')) { this.root = resolve(root); }
+  directory(teamId: string): string {
+    if (!/^p-[a-f0-9]{40}$/.test(teamId)) throw new Error('Invalid project Team identity.');
+    return join(this.root, 'projects', teamId);
+  }
+  sessionPath(teamId: string, sessionRef: string): string {
+    if (!/^[a-zA-Z0-9-]{1,128}$/.test(sessionRef)) throw new Error('Invalid Expert session reference.');
+    return join(this.directory(teamId), 'sessions', `${sessionRef}.jsonl`);
+  }
+  async read(teamId: string): Promise<TeamState | undefined> {
+    const directory = this.directory(teamId);
+    for (const path of [this.root, join(this.root, 'projects'), directory]) {
+      const present = await ensurePrivateDirectory(path, false).then(() => true, error => {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+        throw error;
+      });
+      if (!present) return undefined;
+    }
+    return readJson(join(directory, 'state.json'), assertState, LIMITS.recordBytes);
+  }
+  async update<T>(project: Project, action: (current: TeamState | undefined) => Promise<{ state: TeamState; result: T }> | { state: TeamState; result: T }): Promise<T> {
+    const directory = this.directory(project.teamId);
+    await ensurePrivateTree(this.root, 'projects', project.teamId);
+    return withStorageLock(join(directory, 'state.lock'), async () => {
+      const current = await this.read(project.teamId);
+      if (current && current.projectPath !== project.path) throw new Error('Project binding mismatch.');
+      const { state, result } = await action(current);
+      assertState(state);
+      await replaceAtomicJson(join(directory, 'state.json'), state, { maxBytes: LIMITS.recordBytes });
+      return result;
+    });
+  }
+}

package/src/dynamic/view.ts

@@ -0,0 +1,21 @@
+import { metadata, LIMITS, type TeamState } from './domain.ts';
+
+/** Explicit projection only: never serialize owner, lease, control, or process tokens. */
+export function teamView(state: TeamState | undefined, mode: 'status' | 'history' | 'doctor' = 'status'): string {
+  if (!state) return 'No project Team yet. Start with /team <objective>.';
+  const runs = mode === 'history' ? state.runs.slice(-20) : state.runs.filter(r => ['active', 'queued'].includes(r.status)).slice(0, 20);
+  const lines = [
+    `Team ${state.teamId}`,
+    `Runs: ${state.runs.length} | Experts: ${state.experts.length} | Parallel limit: ${LIMITS.concurrent}`,
+    ...runs.map(r => `Run ${r.id} [${r.status}] ${metadata(r.objective, 160).replace(/\s+/g, ' ')}`),
+    ...state.experts.map(e => `Expert ${e.id} ${e.role} [${e.status}] generation ${e.generation} | history ${e.history.length}`),
+    ...state.assignments.slice(-20).map(a => `Assignment ${a.id} [${a.status}] expert ${a.expertId}`),
+  ];
+  if (mode === 'doctor') lines.push(
+    `Owner: ${state.owner ? 'recorded (not a liveness guarantee)' : 'none'} | epoch ${state.epoch}`,
+    `Blocked experts: ${state.experts.filter(e => e.status === 'blocked').length}`,
+    'Production execution requires authenticated Pi and tmux. No automatic retry or worker adoption.',
+    'Blocked execution requires manual process-identity verification; never signal by name or unverified PID.',
+  );
+  return metadata(lines.join('\n'), 16384);
+}