sdd-agent-platform 0.3.0 → 0.4.1

package/node_modules/@sdd-agent-platform/core/src/execution/resident-worker.ts

@@ -0,0 +1,436 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION } from '../contracts.js';
+import { contractIssue, messageFromError, type ContractValidationIssue } from '../contracts/issues.js';
+import { listDelegationQueueItems } from '../delegation/queue.js';
+import { isDelegationTerminal } from '../delegation/validation.js';
+import { getLegacyWorkerRuntimeRecordPath, getLegacyWorkerRuntimesDir } from '../runtime-paths.js';
+import { appendEvent } from '../run-state/events.js';
+import { readRunState, writeRunState } from '../run-state/run-state.js';
+import { exists } from '../storage/json-io.js';
+import { listRuntimeWorkerRuntimes, readRuntimeWorkerRuntime, recordRuntimeWorkerRuntime } from '../storage/runtime-store.js';
+import type { DelegationQueueItem } from '../run-state/run-index.js';
+import { inspectWorkerAdapterContract, type WorkerAdapterContract } from '../registries/worker-adapters.js';
+import { toSafeRecordId } from './agent-execution-records.js';
+import { runBackgroundExecutor } from './background-executor.js';
+
+const DEFAULT_RESIDENT_WORKER_LEASE_SECONDS = 900;
+
+export type ResidentWorkerRuntimeStatus = 'claimed' | 'active' | 'stale' | 'terminal' | 'blocked';
+
+export interface ResidentWorkerRuntimeRecord {
+  version: typeof RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION;
+  runtimeId: string;
+  runId: string;
+  taskId: string;
+  agent: string;
+  workerAdapterId: string;
+  delegationId: string;
+  queueItemId: string;
+  expectedArtifact: string;
+  status: ResidentWorkerRuntimeStatus;
+  claimedAt: string;
+  lastHeartbeatAt: string | null;
+  leaseSeconds: number;
+  leaseExpiresAt: string;
+  updatedAt: string;
+  evidenceSummary: string;
+}
+
+export interface ResidentWorkerRuntimeClaimOptions {
+  branch?: string;
+  runId?: string;
+  taskId: string;
+  runtimeId?: string;
+  agent?: string;
+  workerAdapterId?: string;
+  delegationId?: string;
+  leaseSeconds?: number;
+}
+
+export interface ResidentWorkerRuntimeClaimResult {
+  version: typeof RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION;
+  runId: string;
+  runtimeId: string | null;
+  taskId: string;
+  agent: string;
+  workerAdapterId: string;
+  delegationId: string | null;
+  queueItemId: string | null;
+  expectedArtifact: string | null;
+  status: ResidentWorkerRuntimeStatus;
+  leaseExpiresAt: string | null;
+  runtime: ResidentWorkerRuntimeRecord | null;
+  issues: ContractValidationIssue[];
+  message: string;
+}
+
+export interface ResidentWorkerRuntimeHeartbeatOptions {
+  runId: string;
+  runtimeId: string;
+  leaseSeconds?: number;
+}
+
+export interface ResidentWorkerRuntimeHeartbeatResult {
+  version: typeof RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION;
+  runId: string;
+  runtimeId: string;
+  status: ResidentWorkerRuntimeStatus;
+  leaseExpiresAt: string | null;
+  runtime: ResidentWorkerRuntimeRecord | null;
+  issues: ContractValidationIssue[];
+  message: string;
+}
+
+export interface ResidentWorkerRuntimeInspection {
+  version: typeof RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION;
+  runId: string;
+  runtimeId: string;
+  runtime: ResidentWorkerRuntimeRecord | null;
+  queueItem: DelegationQueueItem | null;
+  workerAdapter: WorkerAdapterContract | null;
+  status: ResidentWorkerRuntimeStatus;
+  leaseExpired: boolean;
+  valid: boolean;
+  issues: ContractValidationIssue[];
+  recommendedNextCommand: string;
+}
+
+export interface ResidentWorkerRuntimeList {
+  version: typeof RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION;
+  runId: string;
+  runtimes: ResidentWorkerRuntimeRecord[];
+  activeRuntimes: number;
+  staleRuntimes: number;
+  terminalRuntimes: number;
+  blockedRuntimes: number;
+  valid: boolean;
+  issues: ContractValidationIssue[];
+}
+
+export async function writeResidentWorkerRuntimeRecord(projectRoot: string, record: ResidentWorkerRuntimeRecord): Promise<ResidentWorkerRuntimeRecord> {
+  await recordRuntimeWorkerRuntime(projectRoot, record);
+  return record;
+}
+
+export async function readResidentWorkerRuntimeRecord(projectRoot: string, runId: string, runtimeId: string): Promise<ResidentWorkerRuntimeRecord> {
+  const runtimeRecord = await readRuntimeWorkerRuntime(projectRoot, runId, runtimeId);
+  if (runtimeRecord) {
+    return runtimeRecord;
+  }
+  const raw = await readFile(getLegacyWorkerRuntimeRecordPath(projectRoot, runId, runtimeId), 'utf8');
+  return JSON.parse(raw) as ResidentWorkerRuntimeRecord;
+}
+
+export async function listResidentWorkerRuntimeRecords(projectRoot: string, runId: string): Promise<ResidentWorkerRuntimeRecord[]> {
+  const runtimeRecords = await listRuntimeWorkerRuntimes(projectRoot, runId);
+  if (runtimeRecords.length > 0) {
+    return runtimeRecords;
+  }
+  const recordsDir = getLegacyWorkerRuntimesDir(projectRoot, runId);
+  if (!await exists(recordsDir)) {
+    return [];
+  }
+  const entries = await readdir(recordsDir, { withFileTypes: true });
+  const records: ResidentWorkerRuntimeRecord[] = [];
+  for (const entry of entries.filter((candidate) => candidate.isFile() && candidate.name.endsWith('.json'))) {
+    try {
+      const raw = await readFile(path.join(recordsDir, entry.name), 'utf8');
+      records.push(JSON.parse(raw) as ResidentWorkerRuntimeRecord);
+    } catch {
+      continue;
+    }
+  }
+  return records.sort((left, right) => left.updatedAt.localeCompare(right.updatedAt) || left.runtimeId.localeCompare(right.runtimeId));
+}
+
+export async function claimResidentWorkerRuntime(projectRoot: string, options: ResidentWorkerRuntimeClaimOptions): Promise<ResidentWorkerRuntimeClaimResult> {
+  const agent = options.agent ?? 'implementer';
+  const workerAdapterId = options.workerAdapterId ?? 'sdd-cli-task-worker';
+  const leaseSeconds = normalizeResidentWorkerLeaseSeconds(options.leaseSeconds);
+  const backgroundResult = await runBackgroundExecutor(projectRoot, {
+    branch: options.branch,
+    runId: options.runId,
+    taskId: options.taskId,
+    agent,
+    workerAdapterId,
+    delegationId: options.delegationId,
+    timeoutSeconds: leaseSeconds
+  });
+
+  if (backgroundResult.status === 'blocked' || backgroundResult.status === 'failed' || !backgroundResult.delegationId || !backgroundResult.queueItemId) {
+    return {
+      version: RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION,
+      runId: backgroundResult.runId,
+      runtimeId: null,
+      taskId: options.taskId,
+      agent,
+      workerAdapterId,
+      delegationId: backgroundResult.delegationId,
+      queueItemId: backgroundResult.queueItemId,
+      expectedArtifact: null,
+      status: 'blocked',
+      leaseExpiresAt: null,
+      runtime: null,
+      issues: backgroundResult.issues,
+      message: `Resident worker runtime blocked before claim: ${backgroundResult.message}`
+    };
+  }
+
+  const runtimeId = toSafeRecordId(options.runtimeId ?? `R-${options.taskId}-${agent}-001`);
+  const state = await readRunState(projectRoot, backgroundResult.runId);
+  const delegation = state.delegations[backgroundResult.delegationId];
+  const now = new Date().toISOString();
+  const runtime: ResidentWorkerRuntimeRecord = {
+    version: RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION,
+    runtimeId,
+    runId: backgroundResult.runId,
+    taskId: options.taskId,
+    agent,
+    workerAdapterId,
+    delegationId: backgroundResult.delegationId,
+    queueItemId: backgroundResult.queueItemId,
+    expectedArtifact: delegation?.expectedArtifact ?? `artifacts/${agent}-${options.taskId}.md`,
+    status: 'claimed',
+    claimedAt: now,
+    lastHeartbeatAt: null,
+    leaseSeconds,
+    leaseExpiresAt: residentWorkerLeaseExpiresAt(now, leaseSeconds),
+    updatedAt: now,
+    evidenceSummary: `Resident worker runtime ${runtimeId} claimed ${backgroundResult.delegationId}; completion still requires artifact ingestion and verify.`
+  };
+  await writeResidentWorkerRuntimeRecord(projectRoot, runtime);
+  await appendEvent(projectRoot, runtime.runId, {
+    event: 'worker_runtime_claimed',
+    runId: runtime.runId,
+    summary: `Resident worker runtime ${runtime.runtimeId} claimed ${runtime.delegationId}`,
+    data: { runtimeId: runtime.runtimeId, taskId: runtime.taskId, agent: runtime.agent, workerAdapterId: runtime.workerAdapterId, delegationId: runtime.delegationId, queueItemId: runtime.queueItemId, leaseExpiresAt: runtime.leaseExpiresAt }
+  });
+  return {
+    version: RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION,
+    runId: runtime.runId,
+    runtimeId: runtime.runtimeId,
+    taskId: runtime.taskId,
+    agent: runtime.agent,
+    workerAdapterId: runtime.workerAdapterId,
+    delegationId: runtime.delegationId,
+    queueItemId: runtime.queueItemId,
+    expectedArtifact: runtime.expectedArtifact,
+    status: runtime.status,
+    leaseExpiresAt: runtime.leaseExpiresAt,
+    runtime,
+    issues: [],
+    message: `Resident worker runtime ${runtime.runtimeId} claimed ${runtime.delegationId}; send heartbeat before ${runtime.leaseExpiresAt}.`
+  };
+}
+
+export async function heartbeatResidentWorkerRuntime(projectRoot: string, options: ResidentWorkerRuntimeHeartbeatOptions): Promise<ResidentWorkerRuntimeHeartbeatResult> {
+  let runtime: ResidentWorkerRuntimeRecord;
+  try {
+    runtime = await readResidentWorkerRuntimeRecord(projectRoot, options.runId, options.runtimeId);
+  } catch (error) {
+    return {
+      version: RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION,
+      runId: options.runId,
+      runtimeId: options.runtimeId,
+      status: 'blocked',
+      leaseExpiresAt: null,
+      runtime: null,
+      issues: [contractIssue('runtimeId', `Cannot read resident worker runtime ${options.runtimeId}: ${messageFromError(error)}`, 'Run sdd worker-runtime status --run <run_id> or claim a new resident worker runtime.')],
+      message: `Resident worker runtime ${options.runtimeId} is not readable.`
+    };
+  }
+
+  const now = new Date().toISOString();
+  const leaseSeconds = normalizeResidentWorkerLeaseSeconds(options.leaseSeconds ?? runtime.leaseSeconds);
+  const queueItem = await findResidentWorkerQueueItem(projectRoot, runtime);
+  if (queueItem && isDelegationTerminal(queueItem.status)) {
+    const terminalRuntime = await writeResidentWorkerRuntimeRecord(projectRoot, {
+      ...runtime,
+      status: 'terminal',
+      leaseSeconds,
+      updatedAt: now,
+      evidenceSummary: `Resident worker runtime ${runtime.runtimeId} is terminal because delegation ${runtime.delegationId} is ${queueItem.status}.`
+    });
+    await appendEvent(projectRoot, runtime.runId, { event: 'worker_runtime_terminal', runId: runtime.runId, summary: `Resident worker runtime ${runtime.runtimeId} observed terminal delegation ${runtime.delegationId}`, data: { runtimeId: runtime.runtimeId, delegationId: runtime.delegationId, status: queueItem.status } });
+    return {
+      version: RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION,
+      runId: runtime.runId,
+      runtimeId: runtime.runtimeId,
+      status: 'terminal',
+      leaseExpiresAt: terminalRuntime.leaseExpiresAt,
+      runtime: terminalRuntime,
+      issues: [],
+      message: `Resident worker runtime ${runtime.runtimeId} is terminal; create a new delegation id for retry instead of reactivating it.`
+    };
+  }
+
+  await heartbeatDelegationForRuntime(projectRoot, runtime, now, leaseSeconds);
+  const activeRuntime = await writeResidentWorkerRuntimeRecord(projectRoot, {
+    ...runtime,
+    status: 'active',
+    lastHeartbeatAt: now,
+    leaseSeconds,
+    leaseExpiresAt: residentWorkerLeaseExpiresAt(now, leaseSeconds),
+    updatedAt: now,
+    evidenceSummary: `Resident worker runtime ${runtime.runtimeId} heartbeat renewed until ${residentWorkerLeaseExpiresAt(now, leaseSeconds)}.`
+  });
+  await appendEvent(projectRoot, runtime.runId, { event: 'worker_runtime_heartbeat', runId: runtime.runId, summary: `Resident worker runtime ${runtime.runtimeId} heartbeat renewed`, data: { runtimeId: runtime.runtimeId, delegationId: runtime.delegationId, leaseExpiresAt: activeRuntime.leaseExpiresAt } });
+  return {
+    version: RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION,
+    runId: activeRuntime.runId,
+    runtimeId: activeRuntime.runtimeId,
+    status: activeRuntime.status,
+    leaseExpiresAt: activeRuntime.leaseExpiresAt,
+    runtime: activeRuntime,
+    issues: [],
+    message: `Resident worker runtime ${activeRuntime.runtimeId} active until ${activeRuntime.leaseExpiresAt}.`
+  };
+}
+
+export async function listResidentWorkerRuntimes(projectRoot: string, options: { runId: string }): Promise<ResidentWorkerRuntimeList> {
+  const records = await listResidentWorkerRuntimeRecords(projectRoot, options.runId);
+  const queueSnapshot = await listDelegationQueueItems(projectRoot, { runId: options.runId });
+  const queueItems = new Map(queueSnapshot.items.map((item) => [item.id, item]));
+  const runtimes = records.map((record) => withDerivedResidentWorkerStatus(record, queueItems.get(record.queueItemId) ?? null));
+  const issues: ContractValidationIssue[] = [];
+  for (const runtime of runtimes) {
+    issues.push(...await validateResidentWorkerRuntime(projectRoot, runtime, queueItems.get(runtime.queueItemId) ?? null));
+  }
+  return {
+    version: RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION,
+    runId: options.runId,
+    runtimes,
+    activeRuntimes: runtimes.filter((runtime) => runtime.status === 'active' || runtime.status === 'claimed').length,
+    staleRuntimes: runtimes.filter((runtime) => runtime.status === 'stale').length,
+    terminalRuntimes: runtimes.filter((runtime) => runtime.status === 'terminal').length,
+    blockedRuntimes: runtimes.filter((runtime) => runtime.status === 'blocked').length,
+    valid: issues.length === 0,
+    issues
+  };
+}
+
+export async function inspectResidentWorkerRuntime(projectRoot: string, options: { runId: string; runtimeId: string }): Promise<ResidentWorkerRuntimeInspection> {
+  let record: ResidentWorkerRuntimeRecord;
+  try {
+    record = await readResidentWorkerRuntimeRecord(projectRoot, options.runId, options.runtimeId);
+  } catch (error) {
+    const issues = [contractIssue('runtimeId', `Cannot read resident worker runtime ${options.runtimeId}: ${messageFromError(error)}`, 'Run sdd worker-runtime status --run <run_id> or claim a new resident worker runtime.')];
+    return {
+      version: RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION,
+      runId: options.runId,
+      runtimeId: options.runtimeId,
+      runtime: null,
+      queueItem: null,
+      workerAdapter: null,
+      status: 'blocked',
+      leaseExpired: false,
+      valid: false,
+      issues,
+      recommendedNextCommand: `sdd worker-runtime status --run ${options.runId}`
+    };
+  }
+  const queueItem = await findResidentWorkerQueueItem(projectRoot, record);
+  const workerAdapter = await inspectWorkerAdapterContract(projectRoot, record.workerAdapterId);
+  const runtime = withDerivedResidentWorkerStatus(record, queueItem);
+  const issues = await validateResidentWorkerRuntime(projectRoot, runtime, queueItem, workerAdapter);
+  return {
+    version: RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION,
+    runId: options.runId,
+    runtimeId: options.runtimeId,
+    runtime,
+    queueItem,
+    workerAdapter,
+    status: runtime.status,
+    leaseExpired: isResidentWorkerLeaseExpired(runtime),
+    valid: issues.length === 0,
+    issues,
+    recommendedNextCommand: residentWorkerRecommendedNextCommand(runtime)
+  };
+}
+
+function normalizeResidentWorkerLeaseSeconds(value: number | undefined): number {
+  if (value && Number.isFinite(value) && value > 0) {
+    return Math.floor(value);
+  }
+  return DEFAULT_RESIDENT_WORKER_LEASE_SECONDS;
+}
+
+function residentWorkerLeaseExpiresAt(fromIso: string, leaseSeconds: number): string {
+  const timestamp = Date.parse(fromIso);
+  const start = Number.isNaN(timestamp) ? Date.now() : timestamp;
+  return new Date(start + leaseSeconds * 1000).toISOString();
+}
+
+function isResidentWorkerLeaseExpired(runtime: ResidentWorkerRuntimeRecord, now = new Date()): boolean {
+  const timestamp = Date.parse(runtime.leaseExpiresAt);
+  return Number.isNaN(timestamp) || timestamp < now.getTime();
+}
+
+function withDerivedResidentWorkerStatus(runtime: ResidentWorkerRuntimeRecord, queueItem: DelegationQueueItem | null, now = new Date()): ResidentWorkerRuntimeRecord {
+  if (runtime.status === 'blocked') {
+    return runtime;
+  }
+  if (runtime.status === 'terminal' || (queueItem && isDelegationTerminal(queueItem.status))) {
+    return { ...runtime, status: 'terminal' };
+  }
+  if (isResidentWorkerLeaseExpired(runtime, now)) {
+    return { ...runtime, status: 'stale' };
+  }
+  if (runtime.lastHeartbeatAt) {
+    return { ...runtime, status: 'active' };
+  }
+  return { ...runtime, status: 'claimed' };
+}
+
+async function findResidentWorkerQueueItem(projectRoot: string, runtime: ResidentWorkerRuntimeRecord): Promise<DelegationQueueItem | null> {
+  const snapshot = await listDelegationQueueItems(projectRoot, { runId: runtime.runId });
+  return snapshot.items.find((item) => item.id === runtime.queueItemId) ?? snapshot.items.find((item) => item.delegationId === runtime.delegationId) ?? null;
+}
+
+async function heartbeatDelegationForRuntime(projectRoot: string, runtime: ResidentWorkerRuntimeRecord, heartbeatAt: string, leaseSeconds: number): Promise<void> {
+  const state = await readRunState(projectRoot, runtime.runId);
+  const delegation = state.delegations[runtime.delegationId];
+  if (!delegation || isDelegationTerminal(delegation.status)) {
+    return;
+  }
+  await writeRunState(projectRoot, {
+    ...state,
+    delegations: {
+      ...state.delegations,
+      [runtime.delegationId]: {
+        ...delegation,
+        lastHeartbeatAt: heartbeatAt,
+        timeoutSeconds: leaseSeconds
+      }
+    }
+  });
+}
+
+async function validateResidentWorkerRuntime(projectRoot: string, runtime: ResidentWorkerRuntimeRecord, queueItem: DelegationQueueItem | null, workerAdapter?: WorkerAdapterContract | null): Promise<ContractValidationIssue[]> {
+  const issues: ContractValidationIssue[] = [];
+  if (runtime.version !== RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION) {
+    issues.push(contractIssue('version', `Expected ${RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION}.`, 'Rewrite the resident worker runtime record through sdd worker-runtime claim.'));
+  }
+  const adapter = workerAdapter === undefined ? await inspectWorkerAdapterContract(projectRoot, runtime.workerAdapterId) : workerAdapter;
+  if (!adapter) {
+    issues.push(contractIssue('workerAdapterId', `Resident worker runtime ${runtime.runtimeId} references unknown worker adapter ${runtime.workerAdapterId}.`, 'Claim the runtime with a declared worker adapter.'));
+  }
+  if (!queueItem) {
+    issues.push(contractIssue('queueItemId', `Resident worker runtime ${runtime.runtimeId} references missing queue item ${runtime.queueItemId}.`, 'Inspect the run or claim a new resident worker runtime with a valid delegation.'));
+  }
+  if (runtime.status === 'stale' && queueItem?.status === 'RUNNING') {
+    issues.push(contractIssue('lease', `Resident worker runtime ${runtime.runtimeId} is stale while delegation ${runtime.delegationId} is still RUNNING.`, `Run sdd worker-runtime heartbeat ${runtime.runtimeId} --run ${runtime.runId}, or inspect/reclaim with a new delegation id if the worker stopped.`));
+  }
+  return issues;
+}
+
+function residentWorkerRecommendedNextCommand(runtime: ResidentWorkerRuntimeRecord): string {
+  if (runtime.status === 'stale') {
+    return `sdd worker-runtime heartbeat ${runtime.runtimeId} --run ${runtime.runId}`;
+  }
+  if (runtime.status === 'terminal') {
+    return `sdd background inspect ${runtime.runId}`;
+  }
+  return `sdd worker-runtime heartbeat ${runtime.runtimeId} --run ${runtime.runId}`;
+}

package/node_modules/@sdd-agent-platform/core/src/execution/stage-team-runtime.test.ts

@@ -0,0 +1,102 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { STAGE_TEAM_RUNTIME_CONTRACT_VERSION } from '../contracts.js';
+import { assertAdvisoryAssessment, assertValidFanInEvidenceSet, assertValidStageRoleResult, buildFanInEvidenceSet, describeStageTeamActivation, type FanInEvidenceSetRecord, type LlmAdvisorAssessmentRecord, type StageRoleResultRecord } from './stage-team-runtime.js';
+
+test('stage role results reject lifecycle transition authority fields', () => {
+  const result = roleResult({ payload: { final_pass: true } });
+
+  assert.throws(() => assertValidStageRoleResult(result), /final_pass/);
+  assert.throws(() => assertValidStageRoleResult({ ...roleResult(), syncBackApproved: true }), /syncBackApproved/);
+  assert.doesNotThrow(() => assertValidStageRoleResult(roleResult()));
+});
+
+test('advisor assessments are advisory-only and cannot carry lifecycle transitions', () => {
+  assert.throws(() => assertAdvisoryAssessment(advisor({ advisoryOnly: false } as unknown as Partial<LlmAdvisorAssessmentRecord>)), /advisoryOnly=true/);
+  assert.throws(() => assertAdvisoryAssessment(advisor({ payload: { ship_ready: true } })), /ship_ready/);
+  assert.doesNotThrow(() => assertAdvisoryAssessment(advisor()));
+  assert.throws(() => assertAdvisoryAssessment(advisor({ validity: 'unknown' } as unknown as Partial<LlmAdvisorAssessmentRecord>)), /validity/);
+  assert.throws(() => assertAdvisoryAssessment(advisor({ confidence: 'none' } as unknown as Partial<LlmAdvisorAssessmentRecord>)), /confidence/);
+});
+
+test('fan-in evidence set is gate input only and deduplicates referenced inputs', () => {
+  const fanIn = buildFanInEvidenceSet({
+    fanInId: 'fanin-001',
+    partition: 'feature',
+    runId: 'run-001',
+    taskId: 'T1',
+    stage: 'test',
+    roleResultIds: ['role-result-2', 'role-result-1', 'role-result-1'],
+    durableGapIds: ['gap-1'],
+    proposalRefs: ['proposal.md'],
+    advisorAssessmentIds: ['advisor-1'],
+    evidenceRefs: ['artifacts/validation-T1.md'],
+    canonicalEvidenceRefs: ['payload-1'],
+    createdAt: '2026-01-01T00:00:00.000Z',
+    payload: { note: 'input only' }
+  });
+
+  assert.equal(fanIn.gateInputOnly, true);
+  assert.deepEqual(fanIn.roleResultIds, ['role-result-1', 'role-result-2']);
+  assert.throws(() => buildFanInEvidenceSet({ ...fanIn, payload: { stagePassed: true } }), /stagePassed/);
+  assert.throws(() => assertValidFanInEvidenceSet({ ...fanIn, gateInputOnly: false } as unknown as FanInEvidenceSetRecord), /gateInputOnly=true/);
+});
+
+test('lifecycle profiles explain team activation without requiring direct team mode', () => {
+  const direct = describeStageTeamActivation('direct');
+  const recover = describeStageTeamActivation('recover');
+
+  assert.equal(direct.requiredTeam, false);
+  assert.equal(direct.roles.length, 0);
+  assert.equal(recover.requiredTeam, true);
+  assert.equal(recover.roles.some((role) => role.roleId === 'role.sync-risk-reviewer' && role.required), true);
+});
+
+function roleResult(overrides: Partial<StageRoleResultRecord> & Record<string, unknown> = {}): StageRoleResultRecord & Record<string, unknown> {
+  return {
+    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
+    resultId: 'role-result-001',
+    sessionId: 'session-001',
+    assignmentId: 'assignment-001',
+    partition: 'feature',
+    runId: 'run-001',
+    taskId: 'T1',
+    roleId: 'role.evidence-runner',
+    agentId: 'validator',
+    outputKind: 'evidence',
+    authorityCeiling: 'gate_input',
+    status: 'accepted',
+    summary: 'Collected validation evidence.',
+    evidenceRefs: ['artifacts/validation-T1.md'],
+    durableGapIds: [],
+    proposalRefs: [],
+    advisorAssessmentIds: [],
+    createdAt: '2026-01-01T00:00:00.000Z',
+    payload: {},
+    ...overrides
+  };
+}
+
+function advisor(overrides: Partial<LlmAdvisorAssessmentRecord> & Record<string, unknown> = {}): LlmAdvisorAssessmentRecord & Record<string, unknown> {
+  return {
+    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
+    assessmentId: 'advisor-001',
+    sessionId: 'session-001',
+    partition: 'feature',
+    runId: 'run-001',
+    taskId: 'T1',
+    kind: 'evidence_sufficiency',
+    concern: 'medium',
+    validity: 'valid',
+    confidence: 'high',
+    advisoryOnly: true,
+    summary: 'Evidence is sufficient for gate input, pending deterministic checks.',
+    evidenceRefs: ['artifacts/validation-T1.md'],
+    durableGapIds: [],
+    proposalRefs: [],
+    createdAt: '2026-01-01T00:00:00.000Z',
+    payload: {},
+    ...overrides
+  };
+}