sdd-agent-platform 0.3.0 → 0.4.1

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

@@ -0,0 +1,195 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  AGENT_EXECUTION_RECORD_CONTRACT_VERSION,
+  TEAM_SESSION_RECORD_CONTRACT_VERSION
+} from '../contracts.js';
+import {
+  getLegacyAgentExecutionsDir,
+  getLegacyTeamSessionsDir
+} from '../runtime-paths.js';
+import { exists } from '../storage/json-io.js';
+import { listRuntimeAgentExecutions, listRuntimeTeamSessions, recordRuntimeAgentExecution, recordRuntimeTeamSession } from '../storage/runtime-store.js';
+import { BUILT_IN_SKILL_CAPABILITIES } from '../registries/skill-capabilities.js';
+import type { ArtifactResultIngestionRecord } from '../artifacts/ingestion.js';
+import type {
+  AgentExecutionRecord,
+  AgentExecutionRecordStatus,
+  AgentProfileId,
+  AgentRouterDecision,
+  TeamSessionRecord,
+  TeamSessionRecordStatus
+} from '../router/agent-runtime.js';
+
+export async function writeAgentExecutionRecord(projectRoot: string, record: AgentExecutionRecord): Promise<AgentExecutionRecord> {
+  await recordRuntimeAgentExecution(projectRoot, record);
+  return record;
+}
+
+export async function writeTeamSessionRecord(projectRoot: string, record: TeamSessionRecord): Promise<TeamSessionRecord> {
+  await recordRuntimeTeamSession(projectRoot, record);
+  return record;
+}
+
+export async function listAgentExecutionRecords(projectRoot: string, runId: string): Promise<AgentExecutionRecord[]> {
+  const runtimeRecords = await listRuntimeAgentExecutions(projectRoot, runId);
+  if (runtimeRecords.length > 0) {
+    return runtimeRecords;
+  }
+  const recordsDir = getLegacyAgentExecutionsDir(projectRoot, runId);
+  if (!await exists(recordsDir)) {
+    return [];
+  }
+  const entries = await readdir(recordsDir, { withFileTypes: true });
+  const records: AgentExecutionRecord[] = [];
+  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 AgentExecutionRecord);
+    } catch {
+      continue;
+    }
+  }
+  return records.sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.executionId.localeCompare(right.executionId));
+}
+
+export async function listTeamSessionRecords(projectRoot: string, runId: string): Promise<TeamSessionRecord[]> {
+  const runtimeRecords = await listRuntimeTeamSessions(projectRoot, runId);
+  if (runtimeRecords.length > 0) {
+    return runtimeRecords;
+  }
+  const recordsDir = getLegacyTeamSessionsDir(projectRoot, runId);
+  if (!await exists(recordsDir)) {
+    return [];
+  }
+  const entries = await readdir(recordsDir, { withFileTypes: true });
+  const records: TeamSessionRecord[] = [];
+  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 TeamSessionRecord);
+    } catch {
+      continue;
+    }
+  }
+  return records.sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.teamId.localeCompare(right.teamId));
+}
+
+export function routeRecordSnapshot(route: AgentRouterDecision): AgentExecutionRecord['routeDecision'] {
+  return {
+    version: route.version,
+    category: route.category,
+    recommendedProfile: route.recommendedProfile,
+    autonomyCeiling: route.autonomyCeiling,
+    requiredCapabilities: route.requiredCapabilities,
+    blockedReason: route.blockedReason
+  };
+}
+
+export function routeRecordId(route: AgentRouterDecision, profile: AgentProfileId): string {
+  const content = JSON.stringify({
+    version: route.version,
+    taskId: route.taskId,
+    branch: route.branch,
+    category: route.category,
+    profile,
+    recommendedProfile: route.recommendedProfile,
+    autonomyCeiling: route.autonomyCeiling,
+    requiredCapabilities: route.requiredCapabilities,
+    toolPermissionProfile: route.toolPermission?.profile ?? null,
+    toolPermissionPolicy: route.toolPermission?.policy ?? null,
+    blockedReason: route.blockedReason
+  });
+  return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+export function sourceAttributionForCapabilities(capabilityIds: string[], route?: AgentRouterDecision): string[] {
+  return capabilityIds.map((capabilityId) => {
+    const routeSource = route?.registrySources?.find((source) => source.kind === 'skill_capability' && source.id === capabilityId);
+    if (routeSource) {
+      return `${capabilityId}:${routeSource.sourceId ?? routeSource.origin}`;
+    }
+    const capability = BUILT_IN_SKILL_CAPABILITIES.find((candidate) => candidate.id === capabilityId);
+    return capability ? `${capability.id}:${capability.sourceRef}` : capabilityId;
+  });
+}
+
+export function executionProfile(agent: string, route: AgentRouterDecision): AgentProfileId {
+  const normalized = normalizeAgentToken(agent);
+  return route.allowedProfiles.find((profile) => normalizeAgentToken(profile) === normalized) ?? toAgentProfileId(agent) ?? route.recommendedProfile ?? 'implementer';
+}
+
+export function buildAgentExecutionRecord(input: { runId: string; taskId: string; agent: string; route: AgentRouterDecision; status: AgentExecutionRecordStatus; delegationId?: string | null; queueItemId?: string | null; artifactPath?: string | null; ingestion?: ArtifactResultIngestionRecord | null; evidenceSummary: string }): AgentExecutionRecord {
+  const now = new Date().toISOString();
+  const profile = executionProfile(input.agent, input.route);
+  return {
+    version: AGENT_EXECUTION_RECORD_CONTRACT_VERSION,
+    executionId: toSafeRecordId(input.delegationId ?? `${input.taskId}-${input.agent}`),
+    runId: input.runId,
+    taskId: input.taskId,
+    profile,
+    category: input.route.category,
+    host: 'sdd-cli',
+    hostSessionId: input.runId,
+    hostTaskId: input.delegationId ?? null,
+    modelPolicy: input.route.modelPolicy,
+    toolPermission: input.route.toolPermission,
+    capabilitiesUsed: input.route.requiredCapabilities,
+    sourceAttribution: sourceAttributionForCapabilities(input.route.requiredCapabilities, input.route),
+    artifacts: input.artifactPath ? [input.artifactPath] : input.ingestion?.artifactPath ? [input.ingestion.artifactPath] : [],
+    status: input.status,
+    delegationId: input.delegationId ?? null,
+    queueItemId: input.queueItemId ?? null,
+    ingestionStatus: input.ingestion?.status ?? null,
+    resultStatus: input.ingestion?.resultStatus ?? null,
+    routeId: routeRecordId(input.route, profile),
+    routeDecision: routeRecordSnapshot(input.route),
+    evidenceSummary: input.evidenceSummary,
+    createdAt: now,
+    updatedAt: now
+  };
+}
+
+export function buildTeamSessionRecord(input: { runId: string; taskId: string | null; route: AgentRouterDecision; status: TeamSessionRecordStatus; artifacts: string[]; evidenceSummary: string }): TeamSessionRecord {
+  const now = new Date().toISOString();
+  return {
+    version: TEAM_SESSION_RECORD_CONTRACT_VERSION,
+    teamId: toSafeRecordId(`team-${input.runId}-${input.taskId ?? 'branch'}`),
+    runId: input.runId,
+    taskId: input.taskId,
+    status: input.status,
+    chiefProfile: input.route.teamMode.chiefProfile,
+    memberProfiles: input.route.teamMode.memberProfiles,
+    hostLayout: null,
+    teamMode: input.route.teamMode,
+    waves: input.route.teamMode.allowedWaves,
+    messages: [{
+      sender: 'runtime',
+      receiver: 'team',
+      taskRef: input.taskId,
+      artifactRefs: input.artifacts,
+      blocker: input.route.teamMode.blockedReason,
+      evidenceSummary: input.evidenceSummary,
+      createdAt: now
+    }],
+    artifacts: input.artifacts,
+    evidenceSummary: input.evidenceSummary,
+    createdAt: now,
+    updatedAt: now
+  };
+}
+
+export function toSafeRecordId(value: string): string {
+  const sanitized = value.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return sanitized || 'record';
+}
+
+function normalizeAgentToken(value: string): string {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
+
+function toAgentProfileId(agent: string): AgentProfileId | null {
+  const normalized = normalizeAgentToken(agent);
+  return normalized.length > 0 ? normalized : null;
+}

package/node_modules/@sdd-agent-platform/core/src/execution/background-executor.test.ts

@@ -0,0 +1,187 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { initProject } from '../config/init-project.js';
+import { doctor } from '../doctor/doctor.js';
+import { writeArtifact } from '../run-state/artifacts.js';
+import { readRunState } from '../run-state/run-state.js';
+import { validResultArtifact, validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { writeVerifyContract } from '../verification/verify-contract.js';
+import { inspectBackgroundExecutor, runBackgroundExecutor } from './background-executor.js';
+
+test('background executor claims one delegation and persists background run state', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-claim-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    const result = await runBackgroundExecutor(root, { taskId: 'B1' });
+    const state = await readRunState(root, result.runId);
+    const inspection = await inspectBackgroundExecutor(root, result.runId);
+
+    assert.equal(result.version, 'phase-3.11-background-executor-v1');
+    assert.equal(result.status, 'claimed');
+    assert.equal(result.delegationId, 'B-B1-implementer-001');
+    assert.equal(state.status, 'running');
+    assert.equal(state.phase, 'background');
+    assert.equal(state.currentTask, 'B1');
+    assert.equal(inspection.runningDelegations, 1);
+    assert.equal(inspection.terminalDelegations, 0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('background executor ingests supplied artifact and reaches terminal state', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-ingest-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    const claimed = await runBackgroundExecutor(root, { taskId: 'B1' });
+    await writeArtifact(root, claimed.runId, 'implementer-B1.md', validResultArtifact('implementer', 'B1', 'PASS', 'artifacts/implementer-B1.md'));
+
+    const completed = await runBackgroundExecutor(root, {
+      runId: claimed.runId,
+      taskId: 'B1',
+      artifactPath: 'artifacts/implementer-B1.md'
+    });
+    const state = await readRunState(root, claimed.runId);
+    const inspection = await inspectBackgroundExecutor(root, claimed.runId);
+
+    assert.equal(completed.status, 'completed');
+    assert.equal(completed.ingestion?.delegationStatus, 'COMPLETED');
+    assert.equal(state.status, 'completed');
+    assert.equal(state.phase, 'background');
+    assert.equal(inspection.runningDelegations, 0);
+    assert.equal(inspection.terminalDelegations, 1);
+    assert.equal(inspection.artifactIngestions.length, 1);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('claude code subagent worker spawns host process and ingests stdout artifact', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-claude-host-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    const hostScript = path.join(root, 'fake-claude-host.mjs');
+    await writeFile(hostScript, [
+      "const prompt = process.argv[2] ?? '';",
+      "if (!prompt.includes('Queue item id:')) process.exit(2);",
+      "process.stdout.write('# implementer result\\n\\n```sdd-result\\ncontract: sdd-result-v1\\nversion: 1.3.0\\nagent: implementer\\ntask: B1\\nstatus: PASS\\nartifacts:\\n  - artifacts/implementer-B1.md\\n```\\n');"
+    ].join('\n'), 'utf8');
+
+    const completed = await runBackgroundExecutor(root, {
+      taskId: 'B1',
+      workerAdapterId: 'claude-code-subagent-worker',
+      timeoutSeconds: 10,
+      hostInvocation: { command: process.execPath, args: [hostScript, '{prompt}'] }
+    });
+    const state = await readRunState(root, completed.runId);
+    const inspection = await inspectBackgroundExecutor(root, completed.runId);
+
+    assert.equal(completed.status, 'completed');
+    assert.equal(completed.hostInvocation?.exitCode, 0);
+    assert.equal(completed.hostInvocation?.artifactPath, 'artifacts/implementer-B1.md');
+    assert.equal(completed.ingestion?.delegationStatus, 'COMPLETED');
+    assert.equal(state.delegations['B-B1-implementer-001']?.status, 'COMPLETED');
+    assert.equal(inspection.terminalDelegations, 1);
+    assert.equal(inspection.artifactIngestions.length, 1);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('background executor blocks invalid artifact evidence instead of completing silently', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-invalid-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    const claimed = await runBackgroundExecutor(root, { taskId: 'B1' });
+    await writeArtifact(root, claimed.runId, 'implementer-B1.md', '# Missing contract\n');
+
+    const blocked = await runBackgroundExecutor(root, {
+      runId: claimed.runId,
+      taskId: 'B1',
+      artifactPath: 'artifacts/implementer-B1.md'
+    });
+    const state = await readRunState(root, claimed.runId);
+
+    assert.equal(blocked.status, 'blocked');
+    assert.equal(blocked.issues.length > 0, true);
+    assert.equal(state.status, 'blocked');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('background executor requires approval for database manual gate and accepts approved artifact ingestion', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-approved-manual-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []).replace('risk: []', 'risk:\n  - database'));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    const blocked = await runBackgroundExecutor(root, { taskId: 'B1' });
+    assert.equal(blocked.status, 'blocked');
+    assert.equal(blocked.issues.some((issue) => issue.field === 'isolation' && /manual isolation gate/.test(issue.message)), true);
+    assert.equal(blocked.issues.some((issue) => issue.field === 'governance.confirmation' && /database/.test(issue.message)), true);
+
+    const claimed = await runBackgroundExecutor(root, { taskId: 'B1', approved: true });
+    await writeArtifact(root, claimed.runId, 'implementer-B1.md', validResultArtifact('implementer', 'B1', 'PASS', 'artifacts/implementer-B1.md'));
+    const completed = await runBackgroundExecutor(root, {
+      runId: claimed.runId,
+      taskId: 'B1',
+      artifactPath: 'artifacts/implementer-B1.md',
+      approved: true
+    });
+
+    assert.equal(claimed.status, 'claimed');
+    assert.equal(completed.status, 'completed');
+    assert.equal(completed.ingestion?.delegationStatus, 'COMPLETED');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('background executor blocks manual handoff worker adapters', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-manual-worker-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    const result = await runBackgroundExecutor(root, { taskId: 'B1', workerAdapterId: 'manual-handoff-worker' });
+
+    assert.equal(result.status, 'blocked');
+    assert.equal(result.delegationId, null);
+    assert.equal(result.issues.some((issue) => issue.field === 'workerAdapterId' && /manual handoff/.test(issue.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('doctor reports background executor contract visibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-doctor-'));
+  try {
+    await initProject(root);
+
+    const report = await doctor(root, { latestOnly: true });
+    const check = report.checks.find((item) => item.check === 'background_executor_contract');
+
+    assert.equal(check?.level, 'PASS');
+    assert.match(check?.message ?? '', /phase-3\.11-background-executor-v1/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/node_modules/@sdd-agent-platform/core/src/execution/background-executor.ts

@@ -0,0 +1,305 @@
+import { BACKGROUND_EXECUTOR_CONTRACT_VERSION } from '../contracts.js';
+import { contractIssue, type ContractValidationIssue } from '../contracts/issues.js';
+import { ingestArtifactResult, inspectArtifactResultIngestions } from '../artifacts/ingestion.js';
+import type { ArtifactResultIngestionRecord } from '../artifacts/ingestion.js';
+import { createDelegationRecord, isDelegationTerminal } from '../delegation/validation.js';
+import { listDelegationQueueItems } from '../delegation/queue.js';
+import { persistDelegation } from '../delegation/run-state.js';
+import { evaluateGovernancePolicy } from '../governance/policy.js';
+import { getRunRelativeArtifactPath, toArtifactRootRelativePath } from '../runtime-paths.js';
+import { appendEvent } from '../run-state/events.js';
+import { createRun, readRunState, writeRunState } from '../run-state/run-state.js';
+import type { DelegationQueueItem } from '../run-state/run-index.js';
+import { inspectWorkerAdapterContract } from '../registries/worker-adapters.js';
+import { resolveSddContext } from '../sdd-docs/context.js';
+import { bindRunStateToTaskContext } from '../sdd-docs/run-binding.js';
+import { inspectSddTask } from '../sdd-docs/task-inspection.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
+import { routeSddTask } from '../router/route-sdd-task.js';
+import { ensureExecutionOrchestration, completeExecutionOrchestration } from '../orchestration/runtime.js';
+import { inspectWorktreeIsolation } from '../worktree/isolation.js';
+import { buildAgentExecutionRecord, writeAgentExecutionRecord } from './agent-execution-records.js';
+import { invokeClaudeCodeSubagentHost, type HostInvocationCommandOptions, type HostInvocationResult } from './host-invocation.js';
+
+export type BackgroundExecutorStatus = 'claimed' | 'completed' | 'failed' | 'blocked';
+
+export interface BackgroundExecutorRunOptions {
+  branch?: string;
+  runId?: string;
+  taskId: string;
+  agent?: string;
+  workerAdapterId?: string;
+  artifactPath?: string;
+  delegationId?: string;
+  timeoutSeconds?: number;
+  hostInvocation?: HostInvocationCommandOptions;
+  approved?: boolean;
+}
+
+export interface BackgroundExecutorResult {
+  version: typeof BACKGROUND_EXECUTOR_CONTRACT_VERSION;
+  runId: string;
+  taskId: string;
+  delegationId: string | null;
+  queueItemId: string | null;
+  workerAdapterId: string;
+  status: BackgroundExecutorStatus;
+  artifactPath: string | null;
+  ingestion: ArtifactResultIngestionRecord | null;
+  hostInvocation: HostInvocationResult | null;
+  issues: ContractValidationIssue[];
+  message: string;
+}
+
+export interface BackgroundExecutorInspection {
+  version: typeof BACKGROUND_EXECUTOR_CONTRACT_VERSION;
+  runId: string;
+  delegations: DelegationQueueItem[];
+  artifactIngestions: ArtifactResultIngestionRecord[];
+  runningDelegations: number;
+  terminalDelegations: number;
+  valid: boolean;
+  issues: ContractValidationIssue[];
+}
+
+export async function inspectBackgroundExecutor(projectRoot: string, runId: string): Promise<BackgroundExecutorInspection> {
+  const [snapshot, ingestionInspection] = await Promise.all([
+    listDelegationQueueItems(projectRoot, { runId }),
+    inspectArtifactResultIngestions(projectRoot, runId)
+  ]);
+  const issues = [...ingestionInspection.issues];
+  return {
+    version: BACKGROUND_EXECUTOR_CONTRACT_VERSION,
+    runId,
+    delegations: snapshot.items,
+    artifactIngestions: ingestionInspection.records,
+    runningDelegations: snapshot.items.filter((item) => item.status === 'RUNNING').length,
+    terminalDelegations: snapshot.items.filter((item) => isDelegationTerminal(item.status)).length,
+    valid: issues.length === 0,
+    issues
+  };
+}
+
+export async function runBackgroundExecutor(projectRoot: string, options: BackgroundExecutorRunOptions): Promise<BackgroundExecutorResult> {
+  const context = await resolveSddContext(projectRoot, options.branch ? { branch: options.branch, branchSource: 'cli_option' } : {});
+  const branch = context.partition;
+  const agent = options.agent ?? 'implementer';
+  const workerAdapterId = options.workerAdapterId ?? 'sdd-cli-task-worker';
+  const model = await parseSddBranch(projectRoot, branch);
+  const inspected = inspectSddTask(model, options.taskId);
+  const runState = options.runId ? await readRunState(projectRoot, options.runId) : await createRun(projectRoot);
+  const boundRunState = await bindRunStateToTaskContext(projectRoot, runState, context, model, inspected.task ?? null, options.taskId);
+  const runId = boundRunState.runId;
+  const worker = await inspectWorkerAdapterContract(projectRoot, workerAdapterId);
+  const issues: ContractValidationIssue[] = [];
+
+  if (!worker) {
+    issues.push(contractIssue('workerAdapterId', `Worker adapter ${workerAdapterId} is not declared.`, 'Use a worker adapter declared by the Phase 3.5 worker adapter contract.'));
+  }
+  if (worker?.kind === 'manual_handoff') {
+    issues.push(contractIssue('workerAdapterId', `Worker adapter ${workerAdapterId} is manual handoff only.`, 'Use a runnable worker adapter for background executor claim/run/ingest.'));
+  }
+
+  const route = await routeSddTask(projectRoot, { taskId: options.taskId, branch, agent, approved: options.approved });
+  if (!inspected.task || inspected.gaps.some((gap) => gap.severity === 'blocking')) {
+    issues.push(...inspected.gaps.map((gap) => contractIssue(gap.field, gap.message, gap.recommendation)));
+  }
+  if (route.blockedReason) {
+    issues.push(contractIssue('agent_router', route.blockedReason, route.nextAction));
+  }
+  if (route.toolPermission?.policy === 'deny') {
+    issues.push(contractIssue('tool_permission', 'Agent router denied required tool permission for this task.', 'Change task scope, tool policy, or route through a permitted profile before execution.'));
+  }
+
+  const decision = await inspectWorktreeIsolation(projectRoot, { branch, taskId: options.taskId, capabilityId: worker?.capabilityId ?? 'sdd-cli' });
+  if (decision.mode === 'blocked' || decision.mode === 'manual' && options.approved !== true) {
+    for (const reason of decision.reasons) {
+      issues.push(contractIssue('isolation', reason, 'Resolve isolation gates or pass --approved after explicit user approval before running the background executor.'));
+    }
+  }
+
+  const delegationId = options.delegationId ?? `B-${options.taskId}-${agent}-001`;
+  const expectedArtifact = options.artifactPath ? getRunRelativeArtifactPath(toArtifactRootRelativePath(options.artifactPath)) : `artifacts/${agent}-${options.taskId}.md`;
+  const existingDelegation = boundRunState.delegations[delegationId];
+  if (existingDelegation && isDelegationTerminal(existingDelegation.status)) {
+    issues.push(contractIssue('delegationId', `Delegation ${delegationId} is already terminal.`, 'Create a new delegation id for retry instead of reopening a terminal delegation.'));
+  }
+
+  const governance = await evaluateGovernancePolicy(projectRoot, {
+    operation: 'background_executor',
+    runId,
+    taskId: options.taskId,
+    workerAdapterId,
+    riskTags: inspected.task?.risk ?? [],
+    approved: options.approved,
+    excludeQueueItemId: `${runId}:${delegationId}`
+  });
+  if (!governance.allowed) {
+    issues.push(...governance.issues);
+    await appendEvent(projectRoot, runId, { event: 'governance_policy_blocked', runId, summary: `Governance policy blocked background executor for ${options.taskId}`, data: { taskId: options.taskId, delegationId, decision: governance } });
+  }
+
+  if (issues.length > 0) {
+    await writeAgentExecutionRecord(projectRoot, buildAgentExecutionRecord({
+      runId,
+      taskId: options.taskId,
+      agent,
+      route,
+      status: 'blocked',
+      delegationId,
+      queueItemId: null,
+      artifactPath: options.artifactPath ?? null,
+      evidenceSummary: `Background executor blocked before delegation claim with ${issues.length} issue(s).`
+    }));
+    await appendEvent(projectRoot, runId, { event: 'background_executor_blocked', runId, summary: `Background executor blocked for ${options.taskId}`, data: { taskId: options.taskId, delegationId, issues } });
+    return {
+      version: BACKGROUND_EXECUTOR_CONTRACT_VERSION,
+      runId,
+      taskId: options.taskId,
+      delegationId: null,
+      queueItemId: null,
+      workerAdapterId,
+      status: 'blocked',
+      artifactPath: options.artifactPath ?? null,
+      ingestion: null,
+      issues,
+      hostInvocation: null,
+      message: 'Background executor blocked before delegation claim.'
+    };
+  }
+
+  await ensureExecutionOrchestration(projectRoot, model, inspected.task ?? null, {
+    branch,
+    runId,
+    taskId: options.taskId,
+    agent,
+    workerKind: worker?.kind ?? null,
+    delegationId,
+    expectedArtifact,
+    dispatchBlocking: worker?.kind === 'claude_code_subagent'
+  });
+
+  const delegation = existingDelegation ?? createDelegationRecord({
+    delegationId,
+    task: options.taskId,
+    agent,
+    runMode: 'background',
+    blocking: true,
+    requiredForPhaseExit: true,
+    expectedArtifact,
+    timeoutSeconds: options.timeoutSeconds
+  });
+  await persistDelegation(projectRoot, runId, delegation);
+  const claimedState = await readRunState(projectRoot, runId);
+  await writeRunState(projectRoot, {
+    ...claimedState,
+    status: 'running',
+    phase: 'background',
+    currentTask: options.taskId
+  });
+  await appendEvent(projectRoot, runId, {
+    event: existingDelegation ? 'background_executor_resumed' : 'delegation_started',
+    runId,
+    summary: `Background executor claimed ${delegationId} for ${options.taskId}`,
+    data: { delegationId, taskId: options.taskId, agent, workerAdapterId, expectedArtifact, queueItemId: `${runId}:${delegationId}` }
+  });
+  await writeAgentExecutionRecord(projectRoot, buildAgentExecutionRecord({
+    runId,
+    taskId: options.taskId,
+    agent,
+    route,
+    status: 'claimed',
+    delegationId,
+    queueItemId: `${runId}:${delegationId}`,
+    evidenceSummary: `Background executor claimed ${delegationId}; host execution remains provenance until artifact ingestion.`
+  }));
+
+  let hostInvocation: HostInvocationResult | null = null;
+  let artifactPath = options.artifactPath ?? null;
+
+  if (!artifactPath && worker?.kind === 'claude_code_subagent') {
+    hostInvocation = await invokeClaudeCodeSubagentHost({
+      projectRoot,
+      runId,
+      taskId: options.taskId,
+      agent,
+      delegationId,
+      queueItemId: `${runId}:${delegationId}`,
+      expectedArtifact,
+      timeoutSeconds: options.timeoutSeconds,
+      commandOptions: options.hostInvocation
+    });
+    artifactPath = hostInvocation.artifactPath;
+    await appendEvent(projectRoot, runId, {
+      event: 'host_invocation_completed',
+      runId,
+      summary: `Host invocation completed for ${delegationId}`,
+      data: { delegationId, taskId: options.taskId, workerAdapterId, artifactPath, exitCode: hostInvocation.exitCode, signal: hostInvocation.signal, timedOut: hostInvocation.timedOut }
+    });
+  }
+
+  if (!artifactPath) {
+    return {
+      version: BACKGROUND_EXECUTOR_CONTRACT_VERSION,
+      runId,
+      taskId: options.taskId,
+      delegationId,
+      queueItemId: `${runId}:${delegationId}`,
+      workerAdapterId,
+      status: 'claimed',
+      artifactPath: null,
+      ingestion: null,
+      hostInvocation: null,
+      issues: [],
+      message: `Background executor claimed ${delegationId}; provide ${expectedArtifact} and rerun with --artifact to ingest terminal evidence.`
+    };
+  }
+
+  const ingestion = await ingestArtifactResult(projectRoot, runId, { delegationId, artifactPath });
+  const executorStatus = ingestion.valid ? ingestion.record.delegationStatus === 'COMPLETED' ? 'completed' : 'failed' : 'blocked';
+  await completeExecutionOrchestration(projectRoot, model, inspected.task ?? null, {
+    branch,
+    runId,
+    taskId: options.taskId,
+    agent,
+    workerKind: worker?.kind ?? null,
+    delegationId,
+    expectedArtifact,
+    artifactPath: ingestion.record.artifactPath,
+    resultStatus: ingestion.record.resultStatus,
+    completed: executorStatus === 'completed',
+    dispatchBlocking: worker?.kind === 'claude_code_subagent'
+  });
+  const ingestedState = await readRunState(projectRoot, runId);
+  await writeRunState(projectRoot, {
+    ...ingestedState,
+    status: executorStatus === 'completed' ? 'completed' : executorStatus === 'failed' ? 'failed' : 'blocked',
+    phase: 'background',
+    currentTask: options.taskId
+  });
+  await writeAgentExecutionRecord(projectRoot, buildAgentExecutionRecord({
+    runId,
+    taskId: options.taskId,
+    agent,
+    route,
+    status: executorStatus,
+    delegationId,
+    queueItemId: `${runId}:${delegationId}`,
+    ingestion: ingestion.record,
+    evidenceSummary: ingestion.valid ? `Background executor ingested terminal artifact for ${delegationId}.` : `Background executor artifact ingestion blocked for ${delegationId}.`
+  }));
+  return {
+    version: BACKGROUND_EXECUTOR_CONTRACT_VERSION,
+    runId,
+    taskId: options.taskId,
+    delegationId,
+    queueItemId: `${runId}:${delegationId}`,
+    workerAdapterId,
+    status: executorStatus,
+    artifactPath: ingestion.record.artifactPath,
+    ingestion: ingestion.record,
+    hostInvocation,
+    issues: ingestion.record.issues,
+    message: ingestion.valid ? `Background executor ingested terminal artifact for ${delegationId}.` : `Background executor artifact ingestion blocked for ${delegationId}.`
+  };
+}