sdd-agent-platform 0.2.0 → 0.4.0

package/node_modules/@sdd-agent-platform/core/src/subagents/runtime.test.ts

@@ -0,0 +1,232 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { MODEL_PRODUCED_ARTIFACT_CONTRACT_VERSION, SUBAGENT_DEFINITION_CONTRACT_VERSION, SUBAGENT_DISPATCH_CONTRACT_VERSION, SUBAGENT_RESULT_CONTRACT_VERSION, type RuntimeRef, type RuntimeScope } from '../contracts.js';
+import { initProject } from '../config/init-project.js';
+import { archiveRun, createRun } from '../run-state/run-state.js';
+import type { SubagentDefinition, SubagentDispatch, SubagentResult } from './contracts.js';
+import { consumeSubagentResult, inspectSubagentDispatches, recordSubagentDefinitionProjection, recordSubagentDispatchProjection, recordSubagentResultProjection, readSubagentDispatchProjection, readSubagentResultProjection, subagentDispatchBlocksGate, validateSubagentDefinition, validateSubagentWrite } from './runtime.js';
+import { buildClaudeCodeSubagentPrompt } from '../execution/host-invocation.js';
+
+const scope: RuntimeScope = { branch: 'master', taskId: 'PHASE8-10', runId: 'run-1' };
+const contextRef: RuntimeRef = { kind: 'projection', ref: 'sdd-scoped-context-handoff:PHASE8-10' };
+const artifactRef: RuntimeRef = { kind: 'artifact', ref: 'artifacts/subagent-result.md' };
+const evidenceRef: RuntimeRef = { kind: 'evidence', ref: 'artifacts/subagent-validation.md#AC-1' };
+
+test('subagent definition policy rejects lifecycle ownership and production edit authority', () => {
+  const valid = validateSubagentDefinition(definition());
+  const unsafe = validateSubagentDefinition({ ...definition(), canEditProduction: true, canOwnLifecycle: true } as unknown as SubagentDefinition);
+
+  assert.equal(valid.allowed, true);
+  assert.equal(unsafe.allowed, false);
+  assert.equal(unsafe.issues.some((issue) => /production edit authority/.test(issue)), true);
+  assert.equal(unsafe.issues.some((issue) => /lifecycle control/.test(issue)), true);
+});
+
+test('subagent write policy allows test paths and rejects production paths', () => {
+  const testPath = validateSubagentWrite(definition(), 'packages/core/src/subagents/runtime.test.ts');
+  const specPath = validateSubagentWrite(definition({ allowedWritePaths: ['**/*.spec.ts'] }), 'packages/core/src/subagents/runtime.spec.ts');
+  const productionPath = validateSubagentWrite(definition(), 'packages/core/src/subagents/runtime.ts');
+  const traversalPath = validateSubagentWrite(definition(), '../specs/master/tasks.test.ts');
+  const prefixBypassPath = validateSubagentWrite(definition({ allowedWritePaths: ['artifacts/**'] }), 'artifacts-malicious/payload.txt');
+
+  assert.equal(testPath.allowed, true);
+  assert.equal(specPath.allowed, true);
+  assert.equal(productionPath.allowed, false);
+  assert.match(productionPath.issues[0], /cannot write/);
+  assert.equal(traversalPath.allowed, false);
+  assert.equal(prefixBypassPath.allowed, false);
+
+  const broadProductionPattern = validateSubagentDefinition(definition({ allowedWritePaths: ['packages/core/src/subagents/**'] }));
+  assert.equal(broadProductionPattern.allowed, false);
+  assert.match(broadProductionPattern.issues.join('\n'), /broad production\/source write path/);
+
+  const workflowDocPattern = validateSubagentDefinition(definition({ allowedWritePaths: ['specs/master/tasks.md'] }));
+  assert.equal(workflowDocPattern.allowed, false);
+  assert.match(workflowDocPattern.issues.join('\n'), /unsupported write path/);
+
+});
+test('subagent dispatch gate semantics respect blocking and completed results', () => {
+  const queued = dispatch({ status: 'queued', blocking: true, requiredBefore: 'handoff' });
+  const completed = dispatch({ status: 'completed', blocking: true, requiredBefore: 'handoff' });
+
+  assert.equal(subagentDispatchBlocksGate(queued, null), true);
+  assert.equal(subagentDispatchBlocksGate({ ...queued, blocking: false, requiredBefore: 'never' }, null), false);
+  assert.equal(subagentDispatchBlocksGate(completed, result({ status: 'completed' })), false);
+  assert.equal(subagentDispatchBlocksGate(completed, result({ status: 'failed' })), true);
+});
+
+test('subagent result consumption is non-authoritative', () => {
+  const consumed = consumeSubagentResult(result({ authority: 'evidence-candidate' }));
+
+  assert.equal(consumed.authority, 'evidence-candidate');
+  assert.equal(consumed.authoritative, false);
+  assert.deepEqual(consumed.artifactRefs, [artifactRef]);
+  assert.deepEqual(consumed.evidenceRefs, [evidenceRef]);
+});
+
+test('subagent projections can be written read and inspected', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-subagent-runtime-'));
+  try {
+    await initProject(root);
+    await recordSubagentDefinitionProjection(root, definition());
+    await recordSubagentDispatchProjection(root, dispatch({ status: 'queued', blocking: true, requiredBefore: 'handoff' }));
+    const blocked = await inspectSubagentDispatches(root, 'master');
+
+    await recordSubagentResultProjection(root, result({ status: 'completed' }));
+    await recordSubagentDispatchProjection(root, dispatch({ status: 'completed', blocking: true, requiredBefore: 'handoff', updatedAt: '2026-05-18T00:02:00.000Z' }));
+    const restoredDispatch = await readSubagentDispatchProjection(root, scope, 'dispatch-1');
+    const restoredResult = await readSubagentResultProjection(root, 'dispatch-1');
+    const fresh = await inspectSubagentDispatches(root, 'master');
+
+    assert.equal(blocked.status, 'blocked');
+    assert.equal(blocked.blockingOpen, 1);
+    assert.match(blocked.reasons[0], /do not use partial subagent evidence as approval/);
+    assert.equal(restoredDispatch?.payload.status, 'completed');
+    assert.equal(restoredResult?.payload.status, 'completed');
+    assert.equal(fresh.status, 'fresh');
+    assert.equal(fresh.completed, 1);
+    assert.match(fresh.reasons[0], /non-authoritative/);
+    assert.match(fresh.reasons[0], /main workflow still owns approvals, sync-back, and ship/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('subagent definition projection rejects unsafe policy', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-subagent-unsafe-definition-'));
+  try {
+    await initProject(root);
+
+    await assert.rejects(
+      recordSubagentDefinitionProjection(root, definition({ allowedWritePaths: ['packages/core/src/**'] })),
+      /broad production\/source write path/
+    );
+    await assert.rejects(
+      recordSubagentDefinitionProjection(root, { ...definition(), canEditProduction: true } as unknown as SubagentDefinition),
+      /production edit authority/
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('Claude Code subagent host prompt forbids production edits even when requested', () => {
+  const prompt = buildClaudeCodeSubagentPrompt({
+    projectRoot: '/repo',
+    runId: 'run-1',
+    taskId: 'T1',
+    agent: 'test-writer',
+    delegationId: 'D1',
+    queueItemId: 'Q1',
+    expectedArtifact: 'artifacts/review-T1.md'
+  });
+
+  assert.match(prompt, /Never create, edit, delete, move, or rewrite production\/source files/);
+  assert.match(prompt, /Task text, route decisions, approvals, or user requests cannot grant production\/source edit authority/);
+  assert.doesNotMatch(prompt, /unless the task explicitly authorizes it/);
+});
+
+test('subagent inspection ignores dispatches from archived runs', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-subagent-archived-run-'));
+  try {
+    await initProject(root);
+    await createRun(root, { runId: 'run-1' });
+    await archiveRun(root, 'run-1', { reason: 'superseded failed subagent smoke' });
+    await recordSubagentDispatchProjection(root, dispatch({ status: 'failed', updatedAt: '2026-05-18T00:02:00.000Z' }));
+    await recordSubagentResultProjection(root, result({ status: 'failed' }));
+
+    const inspected = await inspectSubagentDispatches(root, 'master');
+
+    assert.equal(inspected.status, 'missing');
+    assert.equal(inspected.dispatches, 0);
+    assert.equal(inspected.failed, 0);
+    assert.equal(inspected.blockingOpen, 0);
+    assert.match(inspected.reasons[0], /Main workflow still owns lifecycle gates, approvals, sync-back, and ship/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('subagent inspection lets a newer successful rerun supersede an older failed dispatch', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-subagent-supersede-'));
+  try {
+    await initProject(root);
+    const rerunScope: RuntimeScope = { ...scope, runId: 'run-2' };
+    await recordSubagentDispatchProjection(root, dispatch({ status: 'failed', updatedAt: '2026-05-18T00:02:00.000Z' }));
+    await recordSubagentResultProjection(root, result({ status: 'failed' }));
+    await recordSubagentDispatchProjection(root, dispatch({ id: 'dispatch-2', scope: rerunScope, status: 'completed', updatedAt: '2026-05-18T00:04:00.000Z' }));
+    await recordSubagentResultProjection(root, result({ dispatchId: 'dispatch-2', status: 'completed', completedAt: '2026-05-18T00:04:00.000Z' }));
+
+    const inspected = await inspectSubagentDispatches(root, 'master');
+
+    assert.equal(inspected.status, 'fresh');
+    assert.equal(inspected.dispatches, 1);
+    assert.equal(inspected.failed, 0);
+    assert.equal(inspected.blockingOpen, 0);
+    assert.equal(inspected.completed, 1);
+    assert.match(inspected.reasons[0], /non-authoritative/);
+    assert.match(inspected.reasons[0], /Main workflow still owns approvals, sync-back, and ship/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+function definition(overrides: Partial<SubagentDefinition> = {}): SubagentDefinition {
+  return {
+    contract: SUBAGENT_DEFINITION_CONTRACT_VERSION,
+    name: 'test-writer',
+    description: 'Writes bounded test evidence candidates.',
+    promptRef: { kind: 'document', ref: '.claude/agents/test-writer.md' },
+    allowedToolRefs: [{ kind: 'external', ref: 'tool:read' }],
+    canEditProduction: false,
+    canOwnLifecycle: false,
+    allowedWritePaths: ['**/*.test.ts', '**/*.spec.ts'],
+    resultAuthority: 'evidence-candidate',
+    ...overrides
+  };
+}
+
+function dispatch(overrides: Partial<SubagentDispatch> = {}): SubagentDispatch {
+  return {
+    contract: SUBAGENT_DISPATCH_CONTRACT_VERSION,
+    id: 'dispatch-1',
+    scope,
+    workUnitId: 'wu-subagent-1',
+    definitionName: 'test-writer',
+    mode: 'background',
+    status: 'queued',
+    blocking: true,
+    requiredBefore: 'handoff',
+    contextRef,
+    createdAt: '2026-05-18T00:00:00.000Z',
+    updatedAt: '2026-05-18T00:01:00.000Z',
+    ...overrides
+  };
+}
+
+function result(overrides: Partial<SubagentResult> = {}): SubagentResult {
+  return {
+    contract: SUBAGENT_RESULT_CONTRACT_VERSION,
+    dispatchId: 'dispatch-1',
+    status: 'completed',
+    authority: 'evidence-candidate',
+    summary: 'Candidate test evidence collected.',
+    artifactRefs: [artifactRef],
+    evidenceRefs: [evidenceRef],
+    modelArtifacts: [{
+      contract: MODEL_PRODUCED_ARTIFACT_CONTRACT_VERSION,
+      producer: 'subagent',
+      authority: 'candidate',
+      allowedUse: ['summary', 'test-suggestion', 'evidence-candidate'],
+      forbiddenUse: ['final-risk-decision', 'stage-completion', 'ship-gate-pass'],
+      artifactRefs: [artifactRef.ref],
+      reviewedByRuntime: false
+    }],
+    completedAt: '2026-05-18T00:02:00.000Z',
+    ...overrides
+  };
+}

package/node_modules/@sdd-agent-platform/core/src/subagents/runtime.ts

@@ -0,0 +1,307 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+import type { RuntimeProjectionEnvelope, RuntimeRef, RuntimeScope } from '../contracts.js';
+import { listRuntimeProjections, readRuntimeProjectionEnvelope, recordRuntimeProjectionEnvelope, runtimeProjectionStaleness, type RuntimeProjectionEnvelopeWriteResult } from '../storage/runtime-store.js';
+import { readAllRunStates } from '../run-state/run-state.js';
+import type { SubagentDefinition, SubagentDispatch, SubagentResult } from './contracts.js';
+
+export const SUBAGENT_RUNTIME_PRODUCER_VERSION = 'phase8-subagent-runtime-v1';
+export const SUBAGENT_DEFINITION_PROJECTION_TYPE = 'phase8_subagent_definition';
+export const SUBAGENT_DISPATCH_PROJECTION_TYPE = 'phase8_subagent_dispatch';
+export const SUBAGENT_RESULT_PROJECTION_TYPE = 'phase8_subagent_result';
+
+export type SubagentDispatchDiagnosticStatus = 'missing' | 'fresh' | 'blocked' | 'failed' | 'stale' | 'incompatible';
+
+export interface SubagentPolicyResult {
+  allowed: boolean;
+  issues: string[];
+}
+
+export interface SubagentDispatchDiagnostic {
+  status: SubagentDispatchDiagnosticStatus;
+  branch: string;
+  dispatches: number;
+  blockingOpen: number;
+  failed: number;
+  stale: number;
+  completed: number;
+  archived: number;
+  superseded: number;
+  reasons: string[];
+}
+
+export function validateSubagentDefinition(definition: SubagentDefinition): SubagentPolicyResult {
+  const unsafe = definition as SubagentDefinition & { canEditProduction?: boolean; canOwnLifecycle?: boolean };
+  const issues: string[] = [];
+  if (unsafe.canEditProduction !== false) {
+    issues.push(`Subagent ${definition.name} cannot receive production edit authority.`);
+  }
+  if (unsafe.canOwnLifecycle !== false) {
+    issues.push(`Subagent ${definition.name} cannot own lifecycle control.`);
+  }
+  if (definition.resultAuthority !== 'non-authoritative' && definition.resultAuthority !== 'diagnostic-only' && definition.resultAuthority !== 'evidence-candidate') {
+    issues.push(`Subagent ${definition.name} has unknown result authority ${definition.resultAuthority}.`);
+  }
+  for (const pattern of definition.allowedWritePaths) {
+    const normalizedPattern = normalizeSubagentRelativePath(pattern);
+    if (!normalizedPattern) {
+      issues.push(`Subagent ${definition.name} has invalid allowed write path ${pattern}.`);
+    } else if (unsafeAllowedWritePattern(normalizedPattern)) {
+      issues.push(`Subagent ${definition.name} cannot receive broad production/source write path ${pattern}.`);
+    } else if (!safeAllowedWritePattern(normalizedPattern)) {
+      issues.push(`Subagent ${definition.name} cannot receive unsupported write path ${pattern}.`);
+    }
+  }
+  return { allowed: issues.length === 0, issues };
+}
+
+export function validateSubagentWrite(definition: SubagentDefinition, relativePath: string): SubagentPolicyResult {
+  const base = validateSubagentDefinition(definition);
+  const normalized = normalizeSubagentRelativePath(relativePath);
+  const allowedByPath = normalized !== null && definition.allowedWritePaths.some((pattern) => matchesWritePattern(normalized, pattern));
+  const issues = [...base.issues];
+  if (!allowedByPath) {
+    issues.push(`Subagent ${definition.name} cannot write ${relativePath}; allowed paths: ${definition.allowedWritePaths.join(', ') || 'none'}.`);
+  }
+  return { allowed: issues.length === 0, issues };
+}
+
+export function consumeSubagentResult(result: SubagentResult): { authority: SubagentResult['authority']; summary: string; artifactRefs: RuntimeRef[]; evidenceRefs: RuntimeRef[]; authoritative: false } {
+  return {
+    authority: result.authority,
+    summary: result.summary,
+    artifactRefs: result.artifactRefs,
+    evidenceRefs: result.evidenceRefs,
+    authoritative: false
+  };
+}
+
+export function subagentDispatchBlocksGate(dispatch: SubagentDispatch, result: SubagentResult | null): boolean {
+  if (!dispatch.blocking || dispatch.requiredBefore === 'never') {
+    return false;
+  }
+  if (!result) {
+    return dispatch.status !== 'completed';
+  }
+  return result.status !== 'completed';
+}
+
+export function subagentDefinitionScopeKey(name: string): string {
+  return name;
+}
+
+export function subagentDispatchScopeKey(scope: RuntimeScope, dispatchId: string): string {
+  return [scope.branch, scope.taskId ?? 'all', scope.runId ?? 'none', scope.changeRef ?? 'none', dispatchId].join(':');
+}
+
+export function subagentResultScopeKey(dispatchId: string): string {
+  return dispatchId;
+}
+
+export async function recordSubagentDefinitionProjection(projectRoot: string, definition: SubagentDefinition): Promise<RuntimeProjectionEnvelopeWriteResult<SubagentDefinition>> {
+  const policy = validateSubagentDefinition(definition);
+  if (!policy.allowed) {
+    throw new Error(`Unsafe subagent definition ${definition.name}: ${policy.issues.join(' ')}`);
+  }
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: SUBAGENT_DEFINITION_PROJECTION_TYPE,
+    scopeKey: subagentDefinitionScopeKey(definition.name),
+    inputHash: stableHash(JSON.stringify(definition)),
+    producer: 'phase8-subagent-runtime',
+    producerVersion: SUBAGENT_RUNTIME_PRODUCER_VERSION,
+    payload: definition
+  });
+}
+
+export async function recordSubagentDispatchProjection(projectRoot: string, dispatch: SubagentDispatch): Promise<RuntimeProjectionEnvelopeWriteResult<SubagentDispatch>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: SUBAGENT_DISPATCH_PROJECTION_TYPE,
+    scopeKey: subagentDispatchScopeKey(dispatch.scope, dispatch.id),
+    inputHash: stableHash(JSON.stringify(dispatch)),
+    producer: 'phase8-subagent-runtime',
+    producerVersion: SUBAGENT_RUNTIME_PRODUCER_VERSION,
+    generatedAt: dispatch.updatedAt,
+    payload: dispatch
+  });
+}
+
+export async function readSubagentDispatchProjection(projectRoot: string, scope: RuntimeScope, dispatchId: string): Promise<RuntimeProjectionEnvelope<SubagentDispatch> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, SUBAGENT_DISPATCH_PROJECTION_TYPE, subagentDispatchScopeKey(scope, dispatchId));
+}
+
+export async function recordSubagentResultProjection(projectRoot: string, result: SubagentResult): Promise<RuntimeProjectionEnvelopeWriteResult<SubagentResult>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: SUBAGENT_RESULT_PROJECTION_TYPE,
+    scopeKey: subagentResultScopeKey(result.dispatchId),
+    inputHash: stableHash(JSON.stringify(result)),
+    producer: 'phase8-subagent-runtime',
+    producerVersion: SUBAGENT_RUNTIME_PRODUCER_VERSION,
+    generatedAt: result.completedAt,
+    payload: result
+  });
+}
+
+export async function readSubagentResultProjection(projectRoot: string, dispatchId: string): Promise<RuntimeProjectionEnvelope<SubagentResult> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, SUBAGENT_RESULT_PROJECTION_TYPE, subagentResultScopeKey(dispatchId));
+}
+
+export async function inspectSubagentDispatches(projectRoot: string, branch: string): Promise<SubagentDispatchDiagnostic> {
+  const projections = await listRuntimeProjections(projectRoot, [SUBAGENT_DISPATCH_PROJECTION_TYPE, SUBAGENT_RESULT_PROJECTION_TYPE]);
+  const resultEnvelopes = projections
+    .filter((projection) => projection.projectionType === SUBAGENT_RESULT_PROJECTION_TYPE)
+    .map((projection) => projection.payload as RuntimeProjectionEnvelope<SubagentResult>);
+  const resultByDispatch = new Map(resultEnvelopes.map((envelope) => [envelope.payload.dispatchId, envelope.payload]));
+  const archivedRunIds = new Set((await readAllRunStates(projectRoot))
+    .filter((state) => state.status === 'archived')
+    .map((state) => state.runId));
+  const branchDispatchEnvelopes = projections
+    .filter((projection) => projection.projectionType === SUBAGENT_DISPATCH_PROJECTION_TYPE)
+    .map((projection) => projection.payload as RuntimeProjectionEnvelope<SubagentDispatch>)
+    .filter((envelope) => envelope?.payload?.scope?.branch === branch);
+  const archived = branchDispatchEnvelopes.filter((envelope) => dispatchBelongsToArchivedRun(envelope.payload, archivedRunIds)).length;
+  const activeDispatches = suppressSupersededDispatches(branchDispatchEnvelopes
+    .filter((envelope) => !dispatchBelongsToArchivedRun(envelope.payload, archivedRunIds)), resultByDispatch);
+  const dispatchEnvelopes = activeDispatches.envelopes;
+  const incompatible = dispatchEnvelopes.some((envelope) => runtimeProjectionStaleness(envelope, { inputHash: stableHash(JSON.stringify(envelope.payload)), producerVersion: SUBAGENT_RUNTIME_PRODUCER_VERSION }) === 'incompatible');
+  const stale = dispatchEnvelopes.filter((envelope) => envelope.payload.status === 'stale').length;
+  const failed = dispatchEnvelopes.filter((envelope) => envelope.payload.status === 'failed' || resultByDispatch.get(envelope.payload.id)?.status === 'failed').length;
+  const blockingOpen = dispatchEnvelopes.filter((envelope) => subagentDispatchBlocksGate(envelope.payload, resultByDispatch.get(envelope.payload.id) ?? null)).length;
+  const completed = dispatchEnvelopes.filter((envelope) => envelope.payload.status === 'completed' && resultByDispatch.get(envelope.payload.id)?.status === 'completed').length;
+  const status: SubagentDispatchDiagnosticStatus = dispatchEnvelopes.length === 0
+    ? 'missing'
+    : incompatible
+      ? 'incompatible'
+      : stale > 0
+        ? 'stale'
+        : failed > 0
+          ? 'failed'
+          : blockingOpen > 0
+            ? 'blocked'
+            : 'fresh';
+  return {
+    status,
+    branch,
+    dispatches: dispatchEnvelopes.length,
+    blockingOpen,
+    failed,
+    stale,
+    completed,
+    archived,
+    superseded: activeDispatches.superseded,
+    reasons: subagentDispatchReasons(status, blockingOpen, failed, stale, archived, activeDispatches.superseded)
+  };
+}
+
+function dispatchBelongsToArchivedRun(dispatch: SubagentDispatch, archivedRunIds: Set<string>): boolean {
+  return typeof dispatch.scope.runId === 'string' && archivedRunIds.has(dispatch.scope.runId);
+}
+
+function suppressSupersededDispatches(dispatchEnvelopes: RuntimeProjectionEnvelope<SubagentDispatch>[], resultByDispatch: Map<string, SubagentResult>): { envelopes: RuntimeProjectionEnvelope<SubagentDispatch>[]; superseded: number } {
+  const successfulByKey = new Map<string, SubagentDispatch>();
+  const active: RuntimeProjectionEnvelope<SubagentDispatch>[] = [];
+  let superseded = 0;
+  for (const envelope of [...dispatchEnvelopes].sort((left, right) => timestamp(right.payload.updatedAt) - timestamp(left.payload.updatedAt))) {
+    const key = dispatchSupersedeKey(envelope.payload);
+    const successful = successfulByKey.get(key);
+    if (successful && timestamp(successful.updatedAt) >= timestamp(envelope.payload.updatedAt)) {
+      superseded += 1;
+      continue;
+    }
+    active.push(envelope);
+    if (dispatchCompleted(envelope.payload, resultByDispatch.get(envelope.payload.id) ?? null)) {
+      successfulByKey.set(key, envelope.payload);
+    }
+  }
+  return { envelopes: active, superseded };
+}
+
+function dispatchCompleted(dispatch: SubagentDispatch, result: SubagentResult | null): boolean {
+  return dispatch.status === 'completed' && (!result || result.status === 'completed');
+}
+
+function dispatchSupersedeKey(dispatch: SubagentDispatch): string {
+  return [dispatch.scope.branch, dispatch.scope.taskId ?? 'all', dispatch.definitionName, dispatch.requiredBefore, dispatch.contextRef.ref].join(':');
+}
+
+function timestamp(value: string): number {
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+function subagentDispatchReasons(status: SubagentDispatchDiagnosticStatus, blockingOpen: number, failed: number, stale: number, archived: number, superseded: number): string[] {
+  const recoveryHint = 'Archive failed exploratory runs with sdd run archive <run_id> --reason <text>, or rerun the subagent worker to supersede the failed dispatch; subagent evidence still cannot approve high-risk execution, sync-back, or ship.';
+  if (status === 'missing') {
+    return archived > 0 || superseded > 0
+      ? [`No active subagent dispatch projections block the main workflow; ignored archived=${archived} superseded=${superseded}. Main workflow still owns lifecycle gates, approvals, sync-back, and ship.`]
+      : ['No subagent dispatch projections recorded; main workflow remains unblocked and still owns lifecycle gates, approvals, sync-back, and ship.'];
+  }
+  if (status === 'blocked') {
+    return [`${blockingOpen} blocking subagent dispatch(es) are incomplete. Complete, rerun, or archive stale exploratory runs before doctor/ship; do not use partial subagent evidence as approval.`];
+  }
+  if (status === 'failed') {
+    return [`${failed} active subagent dispatch(es) failed. ${recoveryHint}`];
+  }
+  if (status === 'stale') {
+    return [`${stale} subagent dispatch(es) are stale. ${recoveryHint}`];
+  }
+  if (status === 'incompatible') {
+    return [`Subagent dispatch projection producer is incompatible with ${SUBAGENT_RUNTIME_PRODUCER_VERSION}; refresh the subagent projection before relying on its diagnostic evidence.`];
+  }
+  return archived > 0 || superseded > 0
+    ? [`Subagent dispatch projections are fresh and non-authoritative; ignored archived=${archived} superseded=${superseded}. Main workflow still owns approvals, sync-back, and ship.`]
+    : ['Subagent dispatch projections are fresh and non-authoritative; main workflow still owns approvals, sync-back, and ship.'];
+}
+
+function normalizeSubagentRelativePath(relativePath: string): string | null {
+  const normalized = relativePath.replace(/\\/g, '/');
+  if (normalized.length === 0 || /^[A-Za-z]:/.test(normalized)) {
+    return null;
+  }
+  const resolved = path.posix.normalize(normalized).replace(/^\.\//, '');
+  if (resolved === '' || resolved === '.' || resolved === '..' || resolved.startsWith('../') || path.posix.isAbsolute(resolved)) {
+    return null;
+  }
+  return resolved;
+}
+
+function unsafeAllowedWritePattern(pattern: string): boolean {
+  if (safeAllowedWritePattern(pattern)) {
+    return false;
+  }
+  return pattern === 'packages/*/src/**'
+    || pattern === 'packages/**/src/**'
+    || /^packages\/[^/]+\/src\/\*\*$/.test(pattern)
+    || /^packages\/[^/]+\/src\//.test(pattern) && pattern.includes('*');
+}
+
+function safeAllowedWritePattern(pattern: string): boolean {
+  return pattern === '**/*.test.ts'
+    || pattern === '**/*.spec.ts'
+    || /(^|\/)\*\*\/\*\.(test|spec)\.ts$/.test(pattern)
+    || /(^|\*)\.(test|spec)\.ts$/.test(pattern)
+    || pattern.startsWith('artifacts/')
+    || pattern.startsWith('.sdd/runs/');
+}
+
+function matchesWritePattern(relativePath: string, pattern: string): boolean {
+  const normalizedPattern = pattern.replace(/\\/g, '/');
+  if (normalizedPattern === relativePath) {
+    return true;
+  }
+  if (normalizedPattern === '**/*.test.ts') {
+    return relativePath.endsWith('.test.ts');
+  }
+  if (normalizedPattern === '**/*.spec.ts') {
+    return relativePath.endsWith('.spec.ts');
+  }
+  if (normalizedPattern.endsWith('/**')) {
+    const prefix = normalizedPattern.slice(0, -3);
+    return relativePath.startsWith(`${prefix}/`);
+  }
+  return false;
+}
+
+function stableHash(value: string): string {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}

package/node_modules/@sdd-agent-platform/core/src/subagents.ts

@@ -0,0 +1,2 @@
+export * from './subagents/contracts.js';
+export * from './subagents/runtime.js';