@fitlab-ai/agent-infra 0.11.11 → 0.11.13

package/lib/task/commands/ls.ts

@@ -75,9 +75,9 @@ type TaskRow = {
 function collectTasks(repoRoot: string, state: 'active' | 'blocked' | 'completed'): TaskRow[] {
   const dir = path.join(repoRoot, '.agents', 'workspace', state);
   if (!fs.existsSync(dir)) return [];
-  // Short ids live only in the registry and only for active tasks; archived
-  // (blocked/completed) tasks have released their short id and render '-'.
-  const shortIdByTaskId = state === 'active' ? loadShortIdByTaskId(repoRoot) : new Map<string, string>();
+  const shortIdByTaskId = state === 'active' || state === 'completed'
+    ? loadShortIdByTaskId(repoRoot)
+    : new Map<string, string>();
   const rows: TaskRow[] = [];
   for (const entry of fs.readdirSync(dir).sort()) {
     if (!TASK_ID_RE.test(entry)) continue;

package/lib/task/control-authority.ts

@@ -1,5 +1,4 @@
 import path from 'node:path';
-import crypto from 'node:crypto';
 
 import { normalizeAgentToken } from '../agent-clients/tokens.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
@@ -29,6 +28,7 @@ import {
 } from './finalization.ts';
 import {
   applyTaskLifecycle,
+  applyTaskLifecycleWithinTaskLock,
   taskLifecycleFailure,
   type TaskLifecycleRequest,
   type TaskLifecycleResult
@@ -37,331 +37,9 @@ import type {
   AgentClientLifecycleRecoveryRequest as LifecycleRecoveryRequest,
   AgentClientLifecycleRecoveryResult as LifecycleRecoveryResult
 } from '../agent-clients/adapter.ts';
-import { resolveTaskRef, TASK_ID_RE } from './resolve-ref.ts';
+import { resolveTaskContext, resolveTaskRef, TASK_ID_RE } from './resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import { verifyTaskEvent } from './verification.ts';
-import { createCodexCapabilityStore } from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
-import {
-  computeLifecycleBuildIdentity,
-  type LifecycleBuildIdentity
-} from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
-
-export type LifecycleAuthorityPhase =
-  | 'orchestration.prepare'
-  | 'artifact.finalize-local'
-  | 'task-event.completed';
-
-export type LifecycleAuthorityRequestV1 = Readonly<{
-  version: 1;
-  requestId: string;
-  operationId: string;
-  phase: LifecycleAuthorityPhase;
-  taskId: string;
-  family: 'analysis' | 'plan' | 'code';
-  artifact: string;
-  round: number;
-  lifecycleRequestId: string;
-  authorityRef: string;
-  expectedControlGeneration: string;
-  expectedControllerInstanceDigest: string;
-  expectedBuildIdentityDigest: string;
-  expectedHookDefinitionHash: string;
-}>;
-
-export type LifecycleRecoveryAttestationV1 = Readonly<{
-  version: 1;
-  attestationId: string;
-  authorityRefDigest: string;
-  operationId: string;
-  phase: LifecycleAuthorityPhase;
-  requestId: string;
-  lifecycleRequestId: string;
-  taskId: string;
-  family: 'analysis' | 'plan' | 'code';
-  artifact: string;
-  round: number;
-  controlGeneration: string;
-  controllerInstanceDigest: string;
-  sessionId: string;
-  turnId: string;
-  toolUseId: string;
-  buildIdentityDigest: string;
-  hookDefinitionHash: string;
-  issuedAt: number;
-  expiresAt: number;
-}>;
-
-export type LifecycleAuthorityResponseV1 = Readonly<{
-  version: 1;
-  requestId: string;
-  operationId: string;
-  phase: LifecycleAuthorityPhase;
-  status: 'issued' | 'already-completed' | 'rejected';
-  attestation: LifecycleRecoveryAttestationV1 | null;
-  error: { code: string; message: string } | null;
-}>;
-
-type LifecycleAuthorityIssuerOptions = Readonly<{
-  controllerBinding?: TaskControlControllerBinding | null;
-  capabilityStore?: ReturnType<typeof createCodexCapabilityStore>;
-  buildIdentity?: LifecycleBuildIdentity;
-  now?: () => number;
-  operationAttestations?: Map<string, LifecycleRecoveryAttestationV1>;
-}>;
-
-export type LifecycleRecoveryOperationQueryV1 = Readonly<{
-  version: 1;
-  operationId: string;
-  status: 'unknown' | 'in-progress' | 'committed';
-  capabilityState: 'unknown' | 'reserved' | 'consumed';
-  phases: readonly Readonly<{
-    phase: LifecycleAuthorityPhase;
-    requestId: string;
-    attestationId: string | null;
-    state: 'issued' | 'consumed' | 'observed';
-  }>[];
-}>;
-
-const lifecycleAuthorityPhases: readonly LifecycleAuthorityPhase[] = [
-  'orchestration.prepare', 'artifact.finalize-local', 'task-event.completed'
-];
-const lifecycleAuthorityFamilies = ['analysis', 'plan', 'code'] as const;
-const lifecycleAuthorityArtifact = /^(?:analysis|plan|code)(?:-r[1-9]\d*)?\.md$/u;
-const lifecycleAuthorityDigest = (value: string): string => crypto.createHash('sha256').update(value, 'utf8').digest('hex');
-const lifecycleAuthorityBuildDigest = (value: LifecycleBuildIdentity): string => lifecycleAuthorityDigest(JSON.stringify(value));
-
-export function lifecycleRecoveryAttestationDigest(value: LifecycleRecoveryAttestationV1): string {
-  return lifecycleAuthorityDigest(JSON.stringify(value));
-}
-
-function authorityExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
-  return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
-}
-
-export function validateLifecycleAuthorityRequest(value: unknown): LifecycleAuthorityRequestV1 {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('LIFECYCLE_AUTHORITY_REQUEST_INVALID');
-  const request = value as Record<string, unknown>;
-  if (!authorityExactKeys(request, [
-    'artifact', 'authorityRef', 'expectedBuildIdentityDigest', 'expectedControlGeneration',
-    'expectedControllerInstanceDigest', 'expectedHookDefinitionHash', 'family', 'lifecycleRequestId',
-    'operationId', 'phase', 'requestId', 'round', 'taskId', 'version'
-  ])
-    || request.version !== 1
-    || typeof request.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(request.requestId)
-    || typeof request.operationId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(request.operationId)
-    || !lifecycleAuthorityPhases.includes(request.phase as LifecycleAuthorityPhase)
-    || typeof request.taskId !== 'string' || !/^TASK-\d{8}-\d{6}$/u.test(request.taskId)
-    || !lifecycleAuthorityFamilies.includes(request.family as typeof lifecycleAuthorityFamilies[number])
-    || typeof request.artifact !== 'string' || !lifecycleAuthorityArtifact.test(request.artifact)
-    || !Number.isSafeInteger(request.round) || (request.round as number) < 1
-    || typeof request.lifecycleRequestId !== 'string' || !request.lifecycleRequestId || /[\r\n]/u.test(request.lifecycleRequestId)
-    || typeof request.authorityRef !== 'string' || !request.authorityRef || /[\r\n]/u.test(request.authorityRef)
-    || typeof request.expectedControlGeneration !== 'string' || !request.expectedControlGeneration
-    || typeof request.expectedControllerInstanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(request.expectedControllerInstanceDigest)
-    || typeof request.expectedBuildIdentityDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(request.expectedBuildIdentityDigest)
-    || typeof request.expectedHookDefinitionHash !== 'string' || !/^[a-f0-9]{64}$/u.test(request.expectedHookDefinitionHash)) {
-    throw new Error('LIFECYCLE_AUTHORITY_REQUEST_INVALID');
-  }
-  const expectedArtifactFamily = request.artifact as string;
-  if (!expectedArtifactFamily.startsWith(request.family as string)) throw new Error('LIFECYCLE_AUTHORITY_REQUEST_INVALID');
-  return request as LifecycleAuthorityRequestV1;
-}
-
-export function validateLifecycleRecoveryAttestation(
-  value: unknown,
-  now = Date.now()
-): LifecycleRecoveryAttestationV1 {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('LIFECYCLE_AUTHORITY_ATTESTATION_INVALID');
-  const attestation = value as Record<string, unknown>;
-  if (!authorityExactKeys(attestation, [
-    'artifact', 'attestationId', 'authorityRefDigest', 'buildIdentityDigest', 'controlGeneration',
-    'controllerInstanceDigest', 'expiresAt', 'family', 'hookDefinitionHash', 'issuedAt',
-    'lifecycleRequestId', 'operationId', 'phase', 'requestId', 'round', 'sessionId',
-    'taskId', 'toolUseId', 'turnId', 'version'
-  ])
-    || attestation.version !== 1
-    || typeof attestation.attestationId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(attestation.attestationId)
-    || typeof attestation.authorityRefDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(attestation.authorityRefDigest)
-    || typeof attestation.operationId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(attestation.operationId)
-    || !lifecycleAuthorityPhases.includes(attestation.phase as LifecycleAuthorityPhase)
-    || typeof attestation.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(attestation.requestId)
-    || typeof attestation.lifecycleRequestId !== 'string' || !attestation.lifecycleRequestId
-    || typeof attestation.taskId !== 'string' || !/^TASK-\d{8}-\d{6}$/u.test(attestation.taskId)
-    || !lifecycleAuthorityFamilies.includes(attestation.family as typeof lifecycleAuthorityFamilies[number])
-    || typeof attestation.artifact !== 'string' || !lifecycleAuthorityArtifact.test(attestation.artifact)
-    || !Number.isSafeInteger(attestation.round) || (attestation.round as number) < 1
-    || typeof attestation.controlGeneration !== 'string' || !attestation.controlGeneration
-    || typeof attestation.controllerInstanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(attestation.controllerInstanceDigest)
-    || typeof attestation.sessionId !== 'string' || !attestation.sessionId
-    || typeof attestation.turnId !== 'string' || !attestation.turnId
-    || typeof attestation.toolUseId !== 'string' || !attestation.toolUseId
-    || typeof attestation.buildIdentityDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(attestation.buildIdentityDigest)
-    || typeof attestation.hookDefinitionHash !== 'string' || !/^[a-f0-9]{64}$/u.test(attestation.hookDefinitionHash)
-    || !Number.isSafeInteger(attestation.issuedAt) || !Number.isSafeInteger(attestation.expiresAt)
-    || (attestation.expiresAt as number) <= (attestation.issuedAt as number)
-    || (attestation.expiresAt as number) <= now) {
-    throw new Error('LIFECYCLE_AUTHORITY_ATTESTATION_INVALID');
-  }
-  return attestation as LifecycleRecoveryAttestationV1;
-}
-
-const authorityOperationMap = new WeakMap<object, Map<string, LifecycleRecoveryAttestationV1>>();
-const authorityRecords = new Map<string, Readonly<{
-  store: ReturnType<typeof createCodexCapabilityStore>;
-  capabilityRef: string;
-  expected: Readonly<{
-    taskId: string;
-    hookDefinitionHash: string;
-    buildIdentity: LifecycleBuildIdentity;
-    controller: TaskControlControllerBinding;
-  }>;
-}>>();
-const consumedAuthorityPhases = new Set<string>();
-
-export function issueLifecycleRecoveryAttestation(
-  input: LifecycleAuthorityRequestV1,
-  options: LifecycleAuthorityIssuerOptions = {}
-): LifecycleAuthorityResponseV1 {
-  let request: LifecycleAuthorityRequestV1;
-  try { request = validateLifecycleAuthorityRequest(input); }
-  catch (error) {
-    return { version: 1, requestId: String((input as { requestId?: unknown })?.requestId ?? ''), operationId: String((input as { operationId?: unknown })?.operationId ?? ''), phase: (input as { phase?: LifecycleAuthorityPhase })?.phase ?? 'artifact.finalize-local', status: 'rejected', attestation: null, error: { code: 'LIFECYCLE_AUTHORITY_REQUEST_INVALID', message: error instanceof Error ? error.message : String(error) } };
-  }
-  const binding = options.controllerBinding ?? null;
-  if (!binding) return authorityRejected(request, 'LOCAL_EXECUTION_AUTHORITY_UNAVAILABLE', 'current controller authority is unavailable');
-  if (binding.controlGeneration !== request.expectedControlGeneration
-    || binding.instanceDigest !== request.expectedControllerInstanceDigest) {
-    return authorityRejected(request, 'LIFECYCLE_AUTHORITY_CONTROLLER_MISMATCH', 'current controller binding does not match the request');
-  }
-  const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(process.cwd());
-  if (lifecycleAuthorityBuildDigest(buildIdentity) !== request.expectedBuildIdentityDigest) {
-    return authorityRejected(request, 'LIFECYCLE_AUTHORITY_BUILD_MISMATCH', 'current lifecycle build does not match the request');
-  }
-  const store = options.capabilityStore ?? createCodexCapabilityStore();
-  const registry = options.operationAttestations ?? authorityOperationMap.get(store) ?? new Map<string, LifecycleRecoveryAttestationV1>();
-  authorityOperationMap.set(store, registry);
-  const key = `${request.requestId}\0${request.operationId}\0${request.phase}`;
-  const prior = registry.get(key);
-  if (prior) return { version: 1, requestId: request.requestId, operationId: request.operationId, phase: request.phase, status: 'already-completed', attestation: prior, error: null };
-  try {
-    const expected = {
-      taskId: request.taskId,
-      hookDefinitionHash: request.expectedHookDefinitionHash,
-      buildIdentity,
-      controller: binding
-    };
-    const record = store.reserveReference(request.authorityRef, request.operationId, expected);
-    if (!record.sessionId || !record.turnId || !record.toolUseId) throw new Error('CODEX_CAPABILITY_IDENTITY_INVALID: capability hook attestation is incomplete');
-    const now = (options.now ?? Date.now)();
-    const attestation = validateLifecycleRecoveryAttestation({
-      version: 1,
-      attestationId: crypto.randomUUID(),
-      authorityRefDigest: lifecycleAuthorityDigest(request.authorityRef),
-      operationId: request.operationId,
-      phase: request.phase,
-      requestId: request.requestId,
-      lifecycleRequestId: request.lifecycleRequestId,
-      taskId: request.taskId,
-      family: request.family,
-      artifact: request.artifact,
-      round: request.round,
-      controlGeneration: binding.controlGeneration,
-      controllerInstanceDigest: binding.instanceDigest,
-      sessionId: record.sessionId,
-      turnId: record.turnId,
-      toolUseId: record.toolUseId,
-      buildIdentityDigest: lifecycleAuthorityBuildDigest(buildIdentity),
-      hookDefinitionHash: request.expectedHookDefinitionHash,
-      issuedAt: now,
-      expiresAt: Math.min(record.expiresAt, now + 30_000)
-    }, now);
-    store.reserveRecoveryPhase(
-      request.authorityRef,
-      request.operationId,
-      request.phase,
-      request.requestId,
-      expected
-    );
-    registry.set(key, attestation);
-    authorityRecords.set(attestation.attestationId, { store, capabilityRef: request.authorityRef, expected });
-    return { version: 1, requestId: request.requestId, operationId: request.operationId, phase: request.phase, status: 'issued', attestation, error: null };
-  } catch (error) {
-    return authorityRejected(request, error instanceof Error && error.name.startsWith('CODEX_') ? error.name : 'LIFECYCLE_AUTHORITY_REJECTED', error instanceof Error ? error.message : String(error));
-  }
-}
-
-export function consumeLifecycleRecoveryAttestation(
-  value: LifecycleRecoveryAttestationV1,
-  now = Date.now()
-): void {
-  const attestation = validateLifecycleRecoveryAttestation(value, now);
-  if (consumedAuthorityPhases.has(attestation.attestationId)) return;
-  const record = authorityRecords.get(attestation.attestationId);
-  if (!record) throw new Error('LIFECYCLE_AUTHORITY_ATTESTATION_UNKNOWN');
-  record.store.consumeRecoveryPhase(
-    record.capabilityRef,
-    attestation.operationId,
-    attestation.phase,
-    attestation.requestId,
-    record.expected
-  );
-  if (attestation.phase === 'task-event.completed') {
-    record.store.consumeReference(record.capabilityRef, attestation.operationId, record.expected);
-  }
-  consumedAuthorityPhases.add(attestation.attestationId);
-}
-
-export function queryLifecycleRecoveryOperation(
-  operationId: string,
-  options: Readonly<{
-    capabilityStore?: ReturnType<typeof createCodexCapabilityStore>;
-  }> = {}
-): LifecycleRecoveryOperationQueryV1 {
-  if (!/^[a-f0-9-]{16,64}$/u.test(operationId)) {
-    throw new Error('LIFECYCLE_RECOVERY_OPERATION_INVALID');
-  }
-  const store = options.capabilityStore ?? createCodexCapabilityStore();
-  const registry = authorityOperationMap.get(store);
-  const known = [...(registry?.values() ?? [])].filter((value) => value.operationId === operationId);
-  const capabilities = store.findByRecoveryOperation(operationId);
-  const phaseMap = new Map<string, LifecycleRecoveryOperationQueryV1['phases'][number]>();
-  for (const capability of capabilities) {
-    for (const phase of capability.recoveryPhases) {
-      phaseMap.set(`${phase.phase}\0${phase.requestId}`, {
-        phase: phase.phase,
-        requestId: phase.requestId,
-        attestationId: null,
-        state: phase.state === 'consumed' ? 'consumed' : 'observed'
-      });
-    }
-  }
-  for (const attestation of known) {
-    const key = `${attestation.phase}\0${attestation.requestId}`;
-    const durable = phaseMap.get(key);
-    phaseMap.set(key, {
-      phase: attestation.phase,
-      requestId: attestation.requestId,
-      attestationId: attestation.attestationId,
-      state: durable?.state === 'consumed' || consumedAuthorityPhases.has(attestation.attestationId)
-        ? 'consumed' : 'issued'
-    });
-  }
-  const capabilityState = capabilities.some((record) => record.recoveryState === 'consumed')
-    ? 'consumed'
-    : capabilities.some((record) => record.recoveryState === 'reserved') ? 'reserved' : 'unknown';
-  const committed = capabilityState === 'consumed';
-  return {
-    version: 1,
-    operationId,
-    status: committed ? 'committed' : capabilityState === 'reserved' || phaseMap.size > 0 ? 'in-progress' : 'unknown',
-    capabilityState,
-    phases: Object.freeze([...phaseMap.values()])
-  };
-}
-
-function authorityRejected(request: LifecycleAuthorityRequestV1, code: string, message: string): LifecycleAuthorityResponseV1 {
-  return { version: 1, requestId: request.requestId, operationId: request.operationId, phase: request.phase, status: 'rejected', attestation: null, error: { code, message } };
-}
 
 export type TaskControlControllerBinding = Readonly<{
   instanceDigest: string;
@@ -375,7 +53,6 @@ export type TaskControlExecutionContext =
       repoRoot: string;
       runtimeDir?: string;
       controllerBinding?: TaskControlControllerBinding | null;
-      lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
     }>
   | Readonly<{
       source: 'sandbox-executor';
@@ -388,7 +65,6 @@ export type TaskControlExecutionContext =
       manifestPath: string;
       requestId: string;
       controllerBinding?: TaskControlControllerBinding | null;
-      lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
     }>;
 
 export type TaskControlOrchestrationIntent =
@@ -448,7 +124,6 @@ export function createDirectHostExecutionContext(params: Readonly<{
   repoRoot: string;
   runtimeDir?: string;
   controllerBinding?: TaskControlControllerBinding | null;
-  lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
 }>): TaskControlExecutionContext {
   return {
     source: 'direct-host',
@@ -456,10 +131,6 @@ export function createDirectHostExecutionContext(params: Readonly<{
     repoRoot: absolute('repoRoot', params.repoRoot),
     ...(params.runtimeDir === undefined ? {} : { runtimeDir: absolute('runtimeDir', params.runtimeDir) }),
     ...(params.controllerBinding === undefined ? {} : { controllerBinding: binding(params.controllerBinding) }),
-    ...(params.lifecycleRecoveryAttestation === undefined ? {} : {
-      lifecycleRecoveryAttestation: params.lifecycleRecoveryAttestation === null
-        ? null : validateLifecycleRecoveryAttestation(params.lifecycleRecoveryAttestation)
-    })
   };
 }
 
@@ -472,7 +143,6 @@ export function createSandboxExecutorExecutionContext(params: Readonly<{
   manifestPath: string;
   requestId: string;
   controllerBinding?: TaskControlControllerBinding | null;
-  lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
 }>): TaskControlExecutionContext {
   if (!/^TASK-\d{8}-\d{6}$/u.test(params.taskId) || !params.generation || !params.requestId) {
     invalidContext('sandbox binding is incomplete');
@@ -492,10 +162,6 @@ export function createSandboxExecutorExecutionContext(params: Readonly<{
     manifestPath: absolute('manifestPath', params.manifestPath),
     requestId: params.requestId,
     ...(params.controllerBinding === undefined ? {} : { controllerBinding: binding(params.controllerBinding) }),
-    ...(params.lifecycleRecoveryAttestation === undefined ? {} : {
-      lifecycleRecoveryAttestation: params.lifecycleRecoveryAttestation === null
-        ? null : validateLifecycleRecoveryAttestation(params.lifecycleRecoveryAttestation)
-    })
   };
 }
 
@@ -505,7 +171,6 @@ export function assertTaskControlExecutionContext(context: TaskControlExecutionC
     absolute('repoRoot', context.repoRoot);
     if (context.runtimeDir !== undefined) absolute('runtimeDir', context.runtimeDir);
     binding(context.controllerBinding);
-    if (context.lifecycleRecoveryAttestation) validateLifecycleRecoveryAttestation(context.lifecycleRecoveryAttestation);
     return;
   }
   if (context.mode !== 'task-bound-sandbox' || !/^TASK-\d{8}-\d{6}$/u.test(context.taskId)
@@ -520,13 +185,20 @@ export function assertTaskControlExecutionContext(context: TaskControlExecutionC
     invalidContext('runtimeDir is not bound to the manifest control root');
   }
   binding(context.controllerBinding);
-  if (context.lifecycleRecoveryAttestation) validateLifecycleRecoveryAttestation(context.lifecycleRecoveryAttestation);
 }
 
-function operationTaskId(context: TaskControlExecutionContext, taskRef: string): void {
-  if (context.source === 'sandbox-executor' && taskRef !== context.taskId) {
-    throw new Error('TASK_CONTROL_CONTEXT_TASK_MISMATCH: operation task does not match the sandbox manifest');
-  }
+function boundTaskRef(context: TaskControlExecutionContext, taskRef: string): string {
+  return context.source === 'sandbox-executor' ? context.taskId : taskRef;
+}
+
+function autoTaskOptions(
+  context: TaskControlExecutionContext,
+  options: OrchestrationOptions
+): OrchestrationOptions {
+  if (context.source === 'sandbox-executor') return { ...options, taskId: context.taskId };
+  const resolved = resolveTaskContext(undefined, { repoRoot: context.repoRoot });
+  if (!resolved.ok) throw new Error(`${resolved.code}: ${resolved.message}`);
+  return { ...options, taskId: resolved.taskId };
 }
 
 function domainOptions(
@@ -553,7 +225,7 @@ async function applyLifecycleWithAuthority(
   context: TaskControlExecutionContext,
   request: TaskLifecycleControlRequest
 ): Promise<TaskLifecycleResult | LifecycleRecoveryResult> {
-  const execute = async (): Promise<TaskLifecycleResult | LifecycleRecoveryResult> => {
+  const execute = async (underTaskLock = false): Promise<TaskLifecycleResult | LifecycleRecoveryResult> => {
     if (request.intent === 'recover-started') {
       const adapter = isAgentClientId(request.agent)
         ? getAgentClientAdapter(request.agent).orchestrationAdapter
@@ -567,7 +239,9 @@ async function applyLifecycleWithAuthority(
       }
       return adapter.recoverStarted(request as LifecycleRecoveryRequest, { repoRoot: context.repoRoot });
     }
-    return applyTaskLifecycle(request, { repoRoot: context.repoRoot });
+    return underTaskLock
+      ? applyTaskLifecycleWithinTaskLock(request, { repoRoot: context.repoRoot }, taskId!)
+      : applyTaskLifecycle(request, { repoRoot: context.repoRoot });
   };
   const taskId = lifecycleTaskId(request, context.repoRoot);
   if (!taskId) return await execute();
@@ -576,7 +250,7 @@ async function applyLifecycleWithAuthority(
       context.repoRoot,
       taskId,
       `task-lifecycle.${request.intent}`,
-      execute
+      () => execute(true)
     );
   } catch (error) {
     if (!(error instanceof TaskExecutionLockError)) throw error;
@@ -596,51 +270,40 @@ function orchestration(
   context: TaskControlExecutionContext,
   operation: Extract<TaskControlOperation, { family: 'task-orchestration' }>
 ): OrchestrationResult | Promise<OrchestrationResult> {
-  operationTaskId(context, operation.taskRef);
+  const taskRef = boundTaskRef(context, operation.taskRef);
   const input = operation.input;
   const options = domainOptions(context, operation.options);
   switch (operation.intent) {
     case 'begin-or-resume':
-      return beginOrResumeOrchestration(operation.taskRef, {
+      return beginOrResumeOrchestration(taskRef, {
         ...options,
         client: input.client as AgentClientId,
         maxSteps: input.maxSteps as number | undefined,
         modelPolicy: input.modelPolicy as OrchestrationOptions['modelPolicy']
       });
-    case 'route': return routeOrchestration(operation.taskRef, options);
-    case 'status': return statusOrchestration(operation.taskRef, options);
-    case 'prepare': {
-      const prepareInput = {
-        client: input.client as AgentClientId,
-        requestedModel: input.requestedModel as string | undefined,
-        requestedReasoningEffort: input.requestedReasoningEffort as string | undefined,
-      };
-      const prepareDelegation = getAgentClientAdapter(prepareInput.client)
-        .orchestrationAdapter?.prepareDelegation;
-      if (prepareDelegation) {
-        return prepareDelegation(operation.taskRef, prepareInput, {
-          repoRoot: context.repoRoot,
-          orchestrationOptions: options,
-        });
-      }
-      return prepareOrchestrationDelegation(operation.taskRef, prepareInput, options);
-    }
-    case 'dispatch': return dispatchOrchestrationDelegation(operation.taskRef, options);
+    case 'route': return routeOrchestration(taskRef, options);
+    case 'status': return statusOrchestration(taskRef, options);
+    case 'prepare': return prepareTaskOrchestration(context, { ...operation, taskRef }, options);
+    case 'dispatch': return dispatchOrchestrationDelegation(taskRef, options);
     case 'await-activation':
-      return awaitOrchestrationDelegationActivation(operation.taskRef, input.event as never, options);
-    case 'recover-prepared': return recoverPreparedOrchestrationDelegation(operation.taskRef, options);
+      return awaitOrchestrationDelegationActivation(taskRef, input.event as never, options);
+    case 'recover-prepared': return recoverPreparedOrchestrationDelegation(taskRef, options);
     case 'hook-start':
       return input.auto === true
-        ? activateMatchingOrchestrationDelegation(input.client as AgentClientId, input.event as never, options)
-        : activateOrchestrationDelegation(operation.taskRef, input.event as never, options);
+        ? activateMatchingOrchestrationDelegation(
+            input.client as AgentClientId, input.event as never, autoTaskOptions(context, options)
+          )
+        : activateOrchestrationDelegation(taskRef, input.event as never, options);
     case 'hook-stop':
       return input.auto === true
-        ? sealMatchingOrchestrationDelegation(input.client as AgentClientId, input.event as never, options)
-        : sealOrchestrationDelegation(operation.taskRef, input.event as never, options);
-    case 'advance': return advanceOrchestration(operation.taskRef, options);
+        ? sealMatchingOrchestrationDelegation(
+            input.client as AgentClientId, input.event as never, autoTaskOptions(context, options)
+          )
+        : sealOrchestrationDelegation(taskRef, input.event as never, undefined, options);
+    case 'advance': return advanceOrchestration(taskRef, options);
     case 'pause':
       return pauseOrchestration(
-        operation.taskRef,
+        taskRef,
         input.code as string,
         input.message as string,
         input.recoverable as boolean,
@@ -649,6 +312,26 @@ function orchestration(
   }
 }
 
+function prepareTaskOrchestration(
+  context: TaskControlExecutionContext,
+  operation: Extract<TaskControlOperation, { family: 'task-orchestration' }>,
+  options: OrchestrationOptions
+): OrchestrationResult | Promise<OrchestrationResult> {
+  const input = operation.input;
+  const prepareInput = {
+    client: input.client as AgentClientId,
+    requestedModel: input.requestedModel as string | undefined,
+    requestedReasoningEffort: input.requestedReasoningEffort as string | undefined,
+  };
+  const prepareDelegation = getAgentClientAdapter(prepareInput.client).orchestrationAdapter?.prepareDelegation;
+  return prepareDelegation
+    ? prepareDelegation(operation.taskRef, prepareInput, {
+      repoRoot: context.repoRoot,
+      orchestrationOptions: options,
+    })
+    : prepareOrchestrationDelegation(operation.taskRef, prepareInput, options);
+}
+
 function orchestrationFailure(error: unknown): OrchestrationResult {
   if (error instanceof OrchestrationStateError) {
     return {
@@ -678,12 +361,16 @@ export function dispatchTaskControlOperation(
   assertTaskControlExecutionContext(context);
   assertTaskControlOperation(operation);
   if (operation.family === 'task-lifecycle') {
-    operationTaskId(context, operation.request.taskRef);
-    return applyLifecycleWithAuthority(context, operation.request);
+    return applyLifecycleWithAuthority(context, {
+      ...operation.request,
+      taskRef: boundTaskRef(context, operation.request.taskRef)
+    });
   }
   if (operation.family === 'task-finalization') {
-    operationTaskId(context, operation.request.taskRef);
-    return applyTaskFinalization(operation.request, {
+    return applyTaskFinalization({
+      ...operation.request,
+      taskRef: boundTaskRef(context, operation.request.taskRef)
+    }, {
       repoRoot: context.repoRoot,
       ...(context.source === 'sandbox-executor' ? {
         controlBinding: { generation: context.generation, requestId: context.requestId },
@@ -790,6 +477,7 @@ export function parseTaskControlOperation(
   const taskRef = args[0]!;
   const intent = args[1]!;
   if (family === 'task-lifecycle') {
+    if (intent === 'complete') operationInvalid('complete must use task-finalization');
     const values = parseValues(args, 2, LIFECYCLE_FLAGS);
     const agent = normalizeAgentToken(value(values, '--agent') ?? '');
     if (!agent) operationInvalid('lifecycle agent is invalid');

package/lib/task/control-recovery.ts

@@ -13,7 +13,7 @@ export function parseControlOutput(output: string | null): Record<string, unknow
 }
 
 export type ControlRecoveryOperation = Readonly<{
-  family: 'task-lifecycle' | 'task-finalization' | 'task-create' | 'codex-controller';
+  family: 'task-lifecycle' | 'task-create' | 'agent-client';
   intent: string;
   class: string;
 }>;
@@ -51,12 +51,11 @@ export type ControlRecoveryDecision = Readonly<{
   reasonCode: string;
 }>;
 
-const LIFECYCLE_INTENTS = ['block', 'activate', 'cancel', 'complete', 'close-codescan', 'close-dependabot', 'restore', 'recover-started'] as const;
+const LIFECYCLE_INTENTS = ['block', 'activate', 'cancel', 'close-codescan', 'close-dependabot', 'restore', 'recover-started'] as const;
 export const SANDBOX_CONTROL_RECOVERY_OPERATIONS: readonly ControlRecoveryOperation[] = Object.freeze([
   ...LIFECYCLE_INTENTS.map((intent) => ({ family: 'task-lifecycle' as const, intent, class: 'lifecycle-mutation' })),
-  { family: 'task-finalization', intent: 'complete', class: 'finalization' },
   { family: 'task-create', intent: 'create', class: 'task-create' },
-  ...(['open', 'close', 'verify'] as const).map((intent) => ({ family: 'codex-controller' as const, intent, class: 'codex-controller' }))
+  ...(['controller.close', 'controller.verify'] as const).map((intent) => ({ family: 'agent-client' as const, intent, class: 'agent-client-operation' }))
 ]);
 
 export function digestControlRecoveryIntent(family: string, intent: string): string {

package/lib/task/create.ts

@@ -11,8 +11,8 @@ import { buildUnboundFact, encodePrDeliveryFact } from './pr-delivery-fact.ts';
 import { CANDIDATE_COLUMNS, CONSTRAINT_COLUMNS, parseTaskQualification } from './qualification-audit.ts';
 import { enumerateAllTaskDirs } from './resolve-ref.ts';
 import { parseTaskFrontmatter } from './frontmatter.ts';
+import { AGENT_TOKEN_VALUES, type AgentToken } from '../agent-clients/tokens.ts';
 
-const AGENTS = ['claude', 'codex', 'antigravity', 'opencode', 'cursor'] as const;
 const TYPES = ['feature', 'bugfix', 'refactor', 'docs', 'chore'] as const;
 const PRIORITIES = ['Urgent', 'High', 'Medium', 'Low'] as const;
 const EFFORTS = ['High', 'Medium', 'Low'] as const;
@@ -21,7 +21,7 @@ const TASK_INPUT_KEYS = [
   'acceptanceCriteria', 'openQuestions'
 ] as const;
 
-type TaskAgent = typeof AGENTS[number];
+type TaskAgent = AgentToken;
 type TaskType = typeof TYPES[number];
 type TaskPriority = typeof PRIORITIES[number];
 type TaskEffort = typeof EFFORTS[number];
@@ -122,7 +122,7 @@ function validateTaskCreateCandidate(value: unknown): TaskCreateCandidateV1 {
   return {
     version: 1,
     idempotencyKey,
-    agent: enumValue(candidate.agent, AGENTS, 'agent'),
+    agent: enumValue(candidate.agent, AGENT_TOKEN_VALUES, 'agent'),
     title,
     type: enumValue(candidate.type, TYPES, 'type'),
     branchSlug,