@telora/daemon 0.18.25 → 0.18.33

package/dist/focus-executor.js

@@ -271,69 +271,18 @@ export function buildAgentArgs(backend, config, worktreePath, pipelineConfig, re
         : backend.buildSpawnArgs(base);
 }
 /**
- * Spawn a focus team to execute all deliveries in a focus.
+ * Phase 1: fetch all spawn context (deliveries / issues / product-context /
+ * deployment-profile / loop-context) in one Promise.all, then resolve the PRD
+ * milestone push-down. Returns null when the context fetch rejects -- the
+ * caller treats null as "tear down the freshly-inserted team and return"
+ * (activeTeams.delete). The PRD push-down deliberately propagates on throw,
+ * matching the pre-extraction behavior (it sits after the try/catch).
  *
- * Creates a single Agent Team (lead process) that reads all deliveries
- * and issues, builds a task DAG, and coordinates worker execution.
+ * Behavior-preserving extraction of the original inline block; the log lines,
+ * the deployment-profile .catch fallback, the loop-context try/catch fallback,
+ * and the manifest accumulation order are byte-identical.
  */
-export async function spawnFocusTeam(params) {
-    const { config, focusId, focusName, role, pipelineConfig, readOnly = false, claudeSessionIds, engineOverride, localModelOverride, orgDefaultEngine, forceSpawn = false } = params;
-    const activeTeams = getActiveTeams();
-    // The agent backend is resolved per-pass below, once the spawn's lineage
-    // (coding vs review) is known -- see resolveBackend() after lineage resolution.
-    // Prevent double-spawn
-    if (activeTeams.has(focusId)) {
-        console.warn(`[focus-executor] Team already active for focus "${focusName}", skipping spawn`);
-        return;
-    }
-    if (await applyRespawnGuard(focusId, focusName))
-        return;
-    const executionConfig = deriveExecutionConfig(pipelineConfig);
-    const branchName = generateFocusBranchName(role, focusName, focusId);
-    // Initialize team state
-    const teamState = {
-        focusId,
-        focusName,
-        roleId: role.id,
-        roleName: role.name,
-        organizationId: config.organizationId,
-        productId: config.productId,
-        executionConfig,
-        pipelineConfig,
-        startedAt: new Date(),
-        phase: 'initializing',
-        knownDeliveryIds: new Set(),
-        mergedDeliveryIds: new Set(),
-        planningPhase: false,
-        shutdownReason: null,
-        deliveryStageIds: new Map(),
-        leadSessionId: null,
-        leadPid: null,
-        leadStdin: null,
-        branchName,
-        worktreePath: null,
-        resolvingMergeConflict: false,
-        readOnly,
-        completionDetector: null,
-        claudeSessionId: null,
-        lastProgressSnapshot: null,
-        noProgressCycles: 0,
-        lastConsumedDirectiveHash: null,
-        sessionType: 'coding',
-        lineage: 'coding',
-    };
-    activeTeams.set(focusId, teamState);
-    const currentProduct = config.products.find(p => p.id === config.productId);
-    const productTag = config.products.length > 1 && currentProduct ? ` [${productLabel(currentProduct)}]` : '';
-    console.log(`[focus-executor] Spawning team for focus "${focusName}"${readOnly ? ' [READ-ONLY]' : ''}${productTag}`);
-    console.log(`  Role: ${role.name}`);
-    console.log(`  Model: ${pipelineConfig?.model ?? '(CLI default)'}`);
-    console.log(`  Max workers: ${executionConfig.maxWorkers}`);
-    console.log(`  Branch: ${branchName}`);
-    if (config.products.length > 1) {
-        console.log(`  Product: ${currentProduct ? productLabel(currentProduct) : config.productId.slice(0, 8)}`);
-        console.log(`  Repo: ${config.repoPath}`);
-    }
+export async function fetchSpawnContext(config, focusId, focusName) {
     // Accumulates the assembly manifest (one entry per resolved source) across
     // every recipe composed for this spawn, persisted after the session exists.
     const assemblyManifest = [];
@@ -376,8 +325,7 @@ export async function spawnFocusTeam(params) {
     }
     catch (err) {
         console.error(`[focus-executor] Failed to fetch context for focus "${focusName}":`, err.message);
-        activeTeams.delete(focusId);
-        return;
+        return null;
     }
     // PRD push-down: if this focus was armed by a PRD, resolve the parent PRD's
     // prd.context (milestone goal/expansion/vision + frontier position) and carry
@@ -398,6 +346,21 @@ export async function spawnFocusTeam(params) {
         prdMilestoneContext = milestoneResult.content;
         assemblyManifest.push(...milestoneResult.manifest);
     }
+    return { deliveries, issues, productContextDocs, deploymentProfileSnapshot, loopContext, prdMilestoneContext, assemblyManifest };
+}
+/**
+ * Phase 2: consume any pending spawn directive, enforce the rank-ordered
+ * pre-spawn guard, and record known-delivery bookkeeping on the team state.
+ *
+ * Mutates `teamState` exactly as the original inline block did
+ * (lastConsumedDirectiveHash, sessionType, planningPhase, knownDeliveryIds,
+ * deliveryStageIds, mergedDeliveryIds) and emits the same log lines. Returns
+ * 'skip' for the findActionableDeliveries skip case (the caller owns the
+ * activeTeams.delete + return so the team-state map stays the orchestrator's
+ * responsibility). Behavior byte-identical.
+ */
+export function resolveActionableDeliveries(args) {
+    const { focusId, focusName, deliveries, issues, forceSpawn, teamState } = args;
     // Check for pending spawn directive (e.g., review stage spawn).
     // Record its content hash on team state so the spawn-guard in
     // executeSpawnDirective can detect divergent directives within the 60s
@@ -426,8 +389,7 @@ export async function spawnFocusTeam(params) {
     else {
         const decision = findActionableDeliveries(deliveries, focusName);
         if (decision.kind === 'skip') {
-            activeTeams.delete(focusId);
-            return;
+            return { kind: 'skip' };
         }
         if (decision.kind === 'planning') {
             isPlanningSpawn = true;
@@ -456,126 +418,28 @@ export async function spawnFocusTeam(params) {
         console.log(`  Deliveries: ${deliveries.length} (${actionableDeliveries.length} queued)`);
     }
     console.log(`  Issues: ${issues.length}`);
-    // Ensure log directory exists
-    if (!existsSync(config.logDir)) {
-        mkdirSync(config.logDir, { recursive: true, mode: 0o700 });
-    }
-    // Reuse persistent focus worktree (created by ensureFocusWorktrees in poll loop)
-    let worktreePath;
-    const existingWorktree = getFocusWorktree(focusId);
-    if (existingWorktree) {
-        worktreePath = existingWorktree.worktreePath;
-        // Rebase onto integration to pick up latest changes from other focuses
-        const rebaseResult = runGitSync(['rebase', config.integrationBranch], worktreePath);
-        if (!rebaseResult.success) {
-            runGitSync(['rebase', '--abort'], worktreePath);
-            console.warn(`[focus-executor] Rebase failed for "${focusName}", continuing with existing state`);
-        }
-        console.log(`  Worktree (reused): ${worktreePath}`);
-        // Re-assert read-only audit guards on the reused worktree. ensureFocusWorktrees
-        // installs them at provisioning time, but a read-only focus may reuse a
-        // persistent worktree across daemon restarts -- re-applying here (idempotent)
-        // guarantees the deny overlay + pre-commit hook are present before spawn.
-        if (readOnly) {
-            installReadOnlyAuditGuards(worktreePath);
-            console.log(`  Re-asserted read-only audit guards (reused worktree)`);
-        }
-    }
-    else {
-        // Guard: can't create worktrees in a repo with no commits
-        if (!repoHasCommits(config.repoPath)) {
-            console.warn(`[focus-executor] Repository has no commits -- cannot create worktree for "${focusName}"`);
-            activeTeams.delete(focusId);
-            recordFocusTeardown(focusId);
-            return;
-        }
-        // Fallback: worktree doesn't exist yet (race condition or first poll)
-        console.warn(`[focus-executor] No persistent worktree for "${focusName}", creating inline`);
-        try {
-            worktreePath = await createWorktree(config, branchName);
-            setFocusWorktree(focusId, {
-                focusId,
-                focusName,
-                worktreePath,
-                branchName,
-                createdAt: new Date(),
-            });
-            console.log(`  Worktree (created inline): ${worktreePath}`);
-            // Install read-only audit guards (pre-commit hook + write-deny overlay)
-            if (readOnly) {
-                installReadOnlyAuditGuards(worktreePath);
-                console.log(`  Installed read-only audit guards (read-only mode)`);
-            }
-        }
-        catch (err) {
-            console.error(`[focus-executor] Failed to create worktree for focus "${focusName}":`, err instanceof Error ? err.message : String(err));
-            activeTeams.delete(focusId);
-            recordFocusTeardown(focusId);
-            return;
-        }
-    }
-    teamState.worktreePath = worktreePath;
-    // Create session record for the team lead
-    let session;
-    try {
-        session = await createSession({
-            organizationId: config.organizationId,
-            roleId: role.id,
-            issueId: null,
-            focusId,
-            branchName,
-            sessionType: pendingDirective?.sessionType ?? 'coding',
-        });
-        teamState.leadSessionId = session.id;
-        // Confirm the session is durably persisted so its telemetry (tagged with
-        // telora.session_id = session.id at spawn) passes the writer's emission
-        // gate. Emission paths carrying an unpersisted id (e.g. the audit assessor's
-        // raw Claude session id) have that id nulled instead of FK-violating.
-        markSessionPersisted(session.id);
-    }
-    catch (err) {
-        console.error(`[focus-executor] Failed to create session for focus "${focusName}":`, err.message);
-        // Worktree is focus-owned and persists even if session creation fails
-        activeTeams.delete(focusId);
-        return;
-    }
-    recordActivity();
-    // Build the team lead prompt.
-    // Priority: pending spawn directive > current stage directive > legacy full prompt.
-    // When a directive exists, compose: role framework + assembled directive content.
-    // This ensures the workflow stage controls what the agent does.
-    // If this focus has a recorded review_requested_at and there are open
-    // review-filed issues, compute the count so the team prompt includes the
-    // remediation directive. Best-effort -- a fetch failure leaves the count
-    // at zero and the directive is omitted (the team behaves as a normal
-    // execution team rather than a remediation team).
-    let reviewFiledOpenCount = 0;
-    let priorFindings = [];
-    let focusDescription = null;
-    try {
-        const activeFocuses = await fetchActiveFocusesForReviewState(config.organizationId, config.productId);
-        const current = activeFocuses.find(f => f.focus_id === focusId);
-        const reviewRequestedAt = current?.review_requested_at ?? null;
-        if (reviewRequestedAt) {
-            priorFindings = filterReviewFiledIssues(issues, reviewRequestedAt);
-            reviewFiledOpenCount = priorFindings.length;
-        }
-        focusDescription = current?.focus_description ?? null;
-    }
-    catch (err) {
-        console.debug(`[focus-executor] Could not compute review-filed open count for "${focusName}":`, err.message);
-    }
-    // --- Phase A: resolve the directive body + spawn metadata (no prompt yet) ---
-    // The engine backend is resolved per-pass (Phase B) before the prompt is
-    // built (Phase C), so the lead prompt's orchestration vocabulary matches the
-    // engine that will actually run this pass.
+    return { kind: 'proceed', pendingDirective, actionableDeliveries, isPlanningSpawn };
+}
+/**
+ * Phase A: resolve the team-lead directive body + spawn metadata (no prompt
+ * yet). Priority: pending spawn directive > current-stage directive > legacy
+ * full prompt. Pushes any assembled directive manifest entries onto the shared
+ * `assemblyManifest` accumulator.
+ *
+ * Behavior-preserving extraction of the original inline Phase A block -- the
+ * "Using pending spawn directive" / "Using stage directive" log lines, the
+ * "LEGACY PROMPT FALLBACK" warning and every fallbackReason string, and the
+ * directive-manifest accumulation are byte-identical.
+ */
+export async function resolveDirectiveOrFallback(args) {
+    const { config, focusId, focusName, worktreePath, pendingDirective, assemblyManifest } = args;
     let directiveBody = null; // appended after the role framework
     let useLegacyFullPrompt = false; // legacy full prompt (no directive)
     let directiveModel = null;
     // Workflow stage active at spawn -- stamped onto telemetry as the .stage lever.
     let spawnStageName = null;
     // Lineage + continuity declared by whatever is firing this spawn (pending
-    // directive, current stage directive, or none). Resolved uniformly below
+    // directive, current stage directive, or none). Resolved uniformly later
     // (INJ-B). For a pending directive these are already resolved upstream, so
     // resolveLineageSpec is idempotent.
     let spawnDirectiveDeclared = null;
@@ -621,7 +485,7 @@ export async function spawnFocusTeam(params) {
             else {
                 spawnStageName = currentStage.name ?? null;
                 // The current stage's directive declares its own lineage + continuity
-                // (INJ-B); resolved uniformly below.
+                // (INJ-B); resolved uniformly later.
                 spawnDirectiveDeclared = currentStage.agentDirective;
                 const { content: directiveContent, manifest: directiveManifest } = await assembleDirectiveContentWithManifest(config, focusId, currentStage.agentDirective, worktreePath);
                 if (directiveContent.trim()) {
@@ -647,25 +511,17 @@ export async function spawnFocusTeam(params) {
             useLegacyFullPrompt = true;
         }
     }
-    // --- Phase B: resolve the session lineage (pass) and the engine backend ---
-    // The lineage is the session-id map slot; sessionType stays the review-exit
-    // gate signal, derived from the lineage (INJ-B). The engine is then resolved
-    // for this pass via the single resolveBackend() selection point (D3).
-    const spawnSpec = resolveLineageSpec({ declared: spawnDirectiveDeclared, stageName: spawnStageName });
-    teamState.lineage = spawnSpec.lineage;
-    teamState.sessionType = spawnSpec.lineage === 'review' ? 'review' : 'coding';
-    const enginePass = spawnSpec.lineage === 'review' ? 'review' : 'coding';
-    const resolvedEngine = resolveBackend({
-        focusOverride: engineOverride,
-        pass: enginePass,
-        productDefault: config.defaultCodingEngine,
-        orgDefault: orgDefaultEngine,
-    });
-    const backend = getBackend(resolvedEngine.engineId);
-    console.log(`[focus-executor] Engine for "${focusName}" pass=${enginePass}: ` +
-        `${resolvedEngine.engineId} (source: ${resolvedEngine.source})`);
-    // --- Phase C: build the prompt with the resolved engine's vocabulary ---
-    const promptContext = {
+    return { directiveBody, directiveModel, spawnStageName, spawnDirectiveDeclared, useLegacyFullPrompt };
+}
+/**
+ * Phase C input: assemble the FocusTeamPromptContext threaded into both the
+ * directive and legacy prompt builders. Pure factory -- byte-identical to the
+ * original inline object literal; extracted so the orchestrator reads as ordered
+ * phase calls rather than inlining the context shape.
+ */
+export function buildFocusPromptContext(args) {
+    const { config, focusId, focusName, focusDescription, deliveries, issues, executionConfig, pipelineConfig, productContextDocs, deploymentProfileSnapshot, readOnly, loopContext, reviewFiledOpenCount, engineId, } = args;
+    return {
         focusId,
         focusName,
         focusDescription,
@@ -680,8 +536,17 @@ export async function spawnFocusTeam(params) {
         readOnly,
         loopContext,
         reviewFiledOpenCount,
-        engineId: backend.id,
+        engineId,
     };
+}
+/**
+ * Phase C: compose the final team-lead message -- role framework + remediation
+ * framing + directive body (or the legacy full focus prompt), then the PRD
+ * milestone push-down appended last so it reaches BOTH prompt paths. Pure +
+ * testable. Byte-identical to the original inline composition.
+ */
+export function buildSpawnPrompt(args) {
+    const { role, promptContext, useLegacyFullPrompt, directiveBody, prdMilestoneContext } = args;
     let prompt;
     if (!useLegacyFullPrompt && directiveBody !== null) {
         const framing = buildRemediationFramingSection(directiveBody).join('\n');
@@ -700,121 +565,398 @@ export async function spawnFocusTeam(params) {
     if (prdMilestoneContext.trim()) {
         prompt += '\n\n' + prdMilestoneContext;
     }
-    // Set up log file streams
-    const logs = setupTeamLogStreams(config.logDir, branchName, focusName);
-    // Build args and env.
-    // Resolve the resume id from the focus's per-lineage session map (INJ-A),
-    // keyed by the spawn's declared lineage, honoring its declared continuity
-    // policy (INJ-B). continuity=fresh -> null; resume -> the lineage's stored id.
-    const resumeId = resolveResumeId({
-        sessionMap: claudeSessionIds,
-        lineage: spawnSpec.lineage,
-        continuity: spawnSpec.continuity,
+    return prompt;
+}
+/**
+ * Phase: resolve the per-pass local-model routing for a codex spawn.
+ *
+ * Wraps the fetch (getLocalModel / getLocalModelSecret) + the pure decision
+ * (selectLocalModelRef -> decideLocalModelRouting) and, on 'route', provisions
+ * the per-model CODEX_HOME (writeLocalModelCodexHome) -- returning the codexHome
+ * the caller points the spawn at. The key VALUE comes from Telora (D8), never a
+ * host env var. Behavior byte-identical to the original inline block; only the
+ * apply-side (session-terminal write on skip, env injection on route) stays in
+ * the caller.
+ */
+export async function resolveLocalModelConfig(args, deps = {}) {
+    const getModel = deps.getLocalModel ?? getLocalModel;
+    const getSecret = deps.getLocalModelSecret ?? getLocalModelSecret;
+    const writeCodexHome = deps.writeLocalModelCodexHome ?? writeLocalModelCodexHome;
+    const localModelRef = selectLocalModelRef(args.engineId, args.enginePass, args.localModelOverride);
+    // getLocalModel + getLocalModelSecret (the DB calls) run only when a ref
+    // exists; decideLocalModelRouting is the pure decision over their results.
+    const coords = localModelRef ? await getModel(localModelRef) : null;
+    const apiKey = localModelRef ? await getSecret(localModelRef) : null;
+    const routing = decideLocalModelRouting(localModelRef, coords, apiKey);
+    switch (routing.kind) {
+        case 'none':
+            return { kind: 'none' };
+        case 'fallback':
+            return { kind: 'fallback', ref: localModelRef };
+        case 'skip':
+            return { kind: 'skip', coords: routing.coords };
+        case 'route': {
+            const { codexHome } = writeCodexHome(routing.coords.id, {
+                baseUrl: routing.coords.baseUrl,
+                model: routing.coords.model,
+                wireApi: routing.coords.wireApi ?? undefined,
+            });
+            return {
+                kind: 'route',
+                codexHome,
+                codexModel: routing.coords.model,
+                apiKey: routing.apiKey,
+                coords: routing.coords,
+            };
+        }
+    }
+}
+/**
+ * The terminal session-update payload written when a local-model pass is skipped
+ * for a missing bearer key (fail-closed). Pure -- the caller adds `ended_at` and
+ * calls updateSession. Exported so the skip exit_category contract is unit-pinned.
+ */
+export function localModelKeyUnsetSessionUpdate(coords) {
+    return {
+        status: 'failed',
+        exit_reason: `No API key configured in Telora for local model "${coords.name}"`,
+        exit_category: 'local_model_key_unset',
+    };
+}
+/**
+ * The terminal session-update payload written when the resource governor denies a
+ * slot for this spawn. Pure -- the caller adds `ended_at` and calls updateSession.
+ * Exported so the governor-denied exit_category contract is unit-pinned (the
+ * apply-side -- updateSession + governor.releaseSlot + activeTeams.delete -- stays
+ * in spawnTeamProcess, exercised by spawn-path-unified.test.ts).
+ */
+export function governorDeniedSessionUpdate() {
+    return {
+        status: 'failed',
+        exit_reason: 'Governor denied slot',
+        exit_category: 'governor_denied',
+    };
+}
+/**
+ * The terminal session-update payload written when a required OS sandbox cannot
+ * initialize and the spawn is refused (fail-closed). Pure -- the caller adds
+ * `ended_at` and calls updateSession. Exported so the sandbox-unavailable
+ * exit_category contract is unit-pinned.
+ */
+export function sandboxUnavailableSessionUpdate(message) {
+    return {
+        status: 'failed',
+        exit_reason: message,
+        exit_category: 'sandbox_unavailable',
+    };
+}
+/**
+ * Log the spawn header (focus / role / model / workers / branch, plus the
+ * product line in multi-product mode). Side-effect-only; byte-identical to the
+ * original inline logging.
+ */
+export function logSpawnHeader(args) {
+    const { config, focusName, role, pipelineConfig, executionConfig, branchName, readOnly } = args;
+    const currentProduct = config.products.find(p => p.id === config.productId);
+    const productTag = config.products.length > 1 && currentProduct ? ` [${productLabel(currentProduct)}]` : '';
+    console.log(`[focus-executor] Spawning team for focus "${focusName}"${readOnly ? ' [READ-ONLY]' : ''}${productTag}`);
+    console.log(`  Role: ${role.name}`);
+    console.log(`  Model: ${pipelineConfig?.model ?? '(CLI default)'}`);
+    console.log(`  Max workers: ${executionConfig.maxWorkers}`);
+    console.log(`  Branch: ${branchName}`);
+    if (config.products.length > 1) {
+        console.log(`  Product: ${currentProduct ? productLabel(currentProduct) : config.productId.slice(0, 8)}`);
+        console.log(`  Repo: ${config.repoPath}`);
+    }
+}
+/**
+ * Build the initial FocusTeamState for a spawn. Pure factory -- no side effects;
+ * the caller inserts it into the activeTeams map.
+ */
+export function createInitialTeamState(args) {
+    const { focusId, focusName, role, config, executionConfig, pipelineConfig, branchName, readOnly } = args;
+    return {
+        focusId,
+        focusName,
+        roleId: role.id,
+        roleName: role.name,
+        organizationId: config.organizationId,
+        productId: config.productId,
+        executionConfig,
+        pipelineConfig,
+        startedAt: new Date(),
+        phase: 'initializing',
+        knownDeliveryIds: new Set(),
+        mergedDeliveryIds: new Set(),
+        planningPhase: false,
+        shutdownReason: null,
+        deliveryStageIds: new Map(),
+        leadSessionId: null,
+        leadPid: null,
+        leadStdin: null,
+        branchName,
+        worktreePath: null,
+        resolvingMergeConflict: false,
+        readOnly,
+        completionDetector: null,
+        claudeSessionId: null,
+        lastProgressSnapshot: null,
+        noProgressCycles: 0,
+        lastConsumedDirectiveHash: null,
+        sessionType: 'coding',
+        lineage: 'coding',
+    };
+}
+/**
+ * Phase: resolve the focus worktree to spawn into. Reuses the persistent
+ * worktree (rebasing onto integration + re-asserting read-only guards) when one
+ * exists, else creates one inline. Returns null when the spawn cannot proceed
+ * (repo has no commits, or inline creation failed) -- owning its own teardown
+ * (activeTeams.delete + recordFocusTeardown) so the caller just returns.
+ * Behavior byte-identical to the original inline block.
+ */
+export async function resolveSpawnWorktree(args) {
+    const { config, focusId, focusName, branchName, readOnly } = args;
+    const activeTeams = getActiveTeams();
+    // Reuse persistent focus worktree (created by ensureFocusWorktrees in poll loop)
+    const existingWorktree = getFocusWorktree(focusId);
+    if (existingWorktree) {
+        const worktreePath = existingWorktree.worktreePath;
+        // Rebase onto integration to pick up latest changes from other focuses
+        const rebaseResult = runGitSync(['rebase', config.integrationBranch], worktreePath);
+        if (!rebaseResult.success) {
+            runGitSync(['rebase', '--abort'], worktreePath);
+            console.warn(`[focus-executor] Rebase failed for "${focusName}", continuing with existing state`);
+        }
+        console.log(`  Worktree (reused): ${worktreePath}`);
+        // Re-assert read-only audit guards on the reused worktree. ensureFocusWorktrees
+        // installs them at provisioning time, but a read-only focus may reuse a
+        // persistent worktree across daemon restarts -- re-applying here (idempotent)
+        // guarantees the deny overlay + pre-commit hook are present before spawn.
+        if (readOnly) {
+            installReadOnlyAuditGuards(worktreePath);
+            console.log(`  Re-asserted read-only audit guards (reused worktree)`);
+        }
+        return worktreePath;
+    }
+    // Guard: can't create worktrees in a repo with no commits
+    if (!repoHasCommits(config.repoPath)) {
+        console.warn(`[focus-executor] Repository has no commits -- cannot create worktree for "${focusName}"`);
+        activeTeams.delete(focusId);
+        recordFocusTeardown(focusId);
+        return null;
+    }
+    // Fallback: worktree doesn't exist yet (race condition or first poll)
+    console.warn(`[focus-executor] No persistent worktree for "${focusName}", creating inline`);
+    try {
+        const worktreePath = await createWorktree(config, branchName);
+        setFocusWorktree(focusId, {
+            focusId,
+            focusName,
+            worktreePath,
+            branchName,
+            createdAt: new Date(),
+        });
+        console.log(`  Worktree (created inline): ${worktreePath}`);
+        // Install read-only audit guards (pre-commit hook + write-deny overlay)
+        if (readOnly) {
+            installReadOnlyAuditGuards(worktreePath);
+            console.log(`  Installed read-only audit guards (read-only mode)`);
+        }
+        return worktreePath;
+    }
+    catch (err) {
+        console.error(`[focus-executor] Failed to create worktree for focus "${focusName}":`, err instanceof Error ? err.message : String(err));
+        activeTeams.delete(focusId);
+        recordFocusTeardown(focusId);
+        return null;
+    }
+}
+/**
+ * Phase: create the team-lead session row + register it with the telemetry
+ * persistence gate, stamping its id onto the team state. Returns null when
+ * createSession fails (owning its own activeTeams.delete teardown). The worktree
+ * is focus-owned and persists even when session creation fails.
+ */
+export async function createTeamSession(args) {
+    const { config, role, focusId, focusName, branchName, pendingDirective, teamState } = args;
+    try {
+        const session = await createSession({
+            organizationId: config.organizationId,
+            roleId: role.id,
+            issueId: null,
+            focusId,
+            branchName,
+            sessionType: pendingDirective?.sessionType ?? 'coding',
+        });
+        teamState.leadSessionId = session.id;
+        // Confirm the session is durably persisted so its telemetry (tagged with
+        // telora.session_id = session.id at spawn) passes the writer's emission
+        // gate. Emission paths carrying an unpersisted id (e.g. the audit assessor's
+        // raw Claude session id) have that id nulled instead of FK-violating.
+        markSessionPersisted(session.id);
+        return session;
+    }
+    catch (err) {
+        console.error(`[focus-executor] Failed to create session for focus "${focusName}":`, err.message);
+        // Worktree is focus-owned and persists even if session creation fails
+        getActiveTeams().delete(focusId);
+        return null;
+    }
+}
+/**
+ * Phase: best-effort review context. When the focus has a recorded
+ * review_requested_at, count the open review-filed issues (the remediation
+ * directive's working set) and carry the prior findings; also resolve the focus
+ * description. A fetch failure leaves the count at zero (normal execution team).
+ */
+export async function resolveReviewContext(args) {
+    const { config, focusId, focusName, issues } = args;
+    let reviewFiledOpenCount = 0;
+    let priorFindings = [];
+    let focusDescription = null;
+    try {
+        const activeFocuses = await fetchActiveFocusesForReviewState(config.organizationId, config.productId);
+        const current = activeFocuses.find(f => f.focus_id === focusId);
+        const reviewRequestedAt = current?.review_requested_at ?? null;
+        if (reviewRequestedAt) {
+            priorFindings = filterReviewFiledIssues(issues, reviewRequestedAt);
+            reviewFiledOpenCount = priorFindings.length;
+        }
+        focusDescription = current?.focus_description ?? null;
+    }
+    catch (err) {
+        console.debug(`[focus-executor] Could not compute review-filed open count for "${focusName}":`, err.message);
+    }
+    return { reviewFiledOpenCount, priorFindings, focusDescription };
+}
+/**
+ * Phase B: resolve the session lineage (pass) and the engine backend for it,
+ * stamping lineage + sessionType onto the team state. Returns the lineage spec,
+ * the derived engine pass, the resolved engine, and the backend object.
+ */
+export function resolveEngineForPass(args) {
+    const { spawnDirectiveDeclared, spawnStageName, engineOverride, config, orgDefaultEngine, focusName, teamState } = args;
+    const spawnSpec = resolveLineageSpec({ declared: spawnDirectiveDeclared, stageName: spawnStageName });
+    teamState.lineage = spawnSpec.lineage;
+    teamState.sessionType = spawnSpec.lineage === 'review' ? 'review' : 'coding';
+    const enginePass = spawnSpec.lineage === 'review' ? 'review' : 'coding';
+    const resolvedEngine = resolveBackend({
+        focusOverride: engineOverride,
+        pass: enginePass,
+        productDefault: config.defaultCodingEngine,
+        orgDefault: orgDefaultEngine,
     });
+    const backend = getBackend(resolvedEngine.engineId);
+    console.log(`[focus-executor] Engine for "${focusName}" pass=${enginePass}: ` +
+        `${resolvedEngine.engineId} (source: ${resolvedEngine.source})`);
+    return { spawnSpec, enginePass, resolvedEngine, backend };
+}
+/**
+ * Phase: resolve the per-product CODEX_HOME default, apply per-pass local-model
+ * routing (fallback / skip / route), select the effective model, and build the
+ * CLI args. Returns 'skip' (fail-closed, no key) for the caller to finalize, or
+ * 'ready' with the args + the model/env bits the spawn needs. Byte-identical to
+ * the original inline local-model + model-selection + args blocks.
+ */
+export async function resolveSpawnModel(args) {
+    const { resolvedEngine, enginePass, localModelOverride, config, directiveModel, pipelineConfig, backend, worktreePath, resumeId, role, readOnly, focusName, } = args;
     // Resolve the per-product isolated CODEX_HOME for this spawn (undefined for
     // claude engines and cloud products with no provisioned codexHome -- those
     // spawns are byte-for-byte unaffected).
     let spawnCodexHome = codexHomeForSpawn(resolvedEngine.engineId, config);
     let spawnCodexModel = config.codexModel;
-    // Per-pass local model routing (D3): if this codex pass selected a registered
-    // local model, resolve it to coordinates, provision a per-model CODEX_HOME,
-    // and route the spawn there -- overriding the per-product codexHome/codexModel
-    // for this pass only. Absent ref => the per-product default above is kept, so
-    // existing spawns are unaffected. Coding and review can resolve different
-    // models within one focus because resolution is keyed on enginePass.
-    const localModelRef = selectLocalModelRef(resolvedEngine.engineId, enginePass, localModelOverride);
-    // getLocalModel + getLocalModelSecret (the DB calls) stay here;
-    // decideLocalModelRouting is the pure decision over their results. Both are
-    // fetched only when a ref exists. The key VALUE is fetched from Telora (D8) --
-    // no host env var -- and injected into the spawn env below.
-    const localModelCoords = localModelRef ? await getLocalModel(localModelRef) : null;
-    const localModelApiKey = localModelRef ? await getLocalModelSecret(localModelRef) : null;
-    const localModelRouting = decideLocalModelRouting(localModelRef, localModelCoords, localModelApiKey);
+    // Per-pass local model routing: if this codex pass selected a registered local
+    // model, resolve it to coordinates, provision a per-model CODEX_HOME, and route
+    // the spawn there -- overriding the per-product codexHome/codexModel for this
+    // pass only. Absent ref => the per-product default above is kept.
+    const localModelConfig = await resolveLocalModelConfig({
+        engineId: resolvedEngine.engineId,
+        enginePass,
+        localModelOverride,
+    });
     // The Telora-resolved key VALUE injected into the spawn env (under the fixed
     // TELORA_LOCAL_API_KEY name) for a routed local-model pass; null otherwise.
     let spawnLocalModelKey = null;
-    if (localModelRouting.kind === 'fallback') {
+    if (localModelConfig.kind === 'fallback') {
         console.warn(`[focus-executor] Focus "${focusName}" ${enginePass} pass selected local model ` +
-            `${(localModelRef ?? '').slice(0, 8)} but it is not in the registry; falling back to the ` +
+            `${(localModelConfig.ref ?? '').slice(0, 8)} but it is not in the registry; falling back to the ` +
             `per-product default model.`);
     }
-    else if (localModelRouting.kind === 'skip') {
-        const { coords } = localModelRouting;
-        // Fail closed: never spawn a local-model pass against a server with no bearer
-        // key configured in Telora. Mark the already-created session terminal
-        // (mirroring the governor-denied / sandbox-unavailable paths so the row does
-        // not linger non-terminal), clean up the registered team state, and skip this
-        // spawn (a later poll retries once an admin sets the key under Settings ->
-        // Local Models). Surfaced loudly so the misconfiguration is actionable.
-        console.error(`[focus-executor] Cannot route "${focusName}" ${enginePass} pass to local model ` +
-            `"${coords.name}" (${coords.model} @ ${coords.baseUrl}): no API key is configured for it ` +
-            `in Telora. Set the key under Settings -> Local Models and re-run; skipping spawn.`);
-        await updateSession(session.id, {
-            status: 'failed',
-            exit_reason: `No API key configured in Telora for local model "${coords.name}"`,
-            exit_category: 'local_model_key_unset',
-            ended_at: new Date().toISOString(),
-        }).catch(updateErr => {
-            console.warn(`[focus-executor] Failed to update session after local-model key-unset:`, updateErr.message);
-        });
-        activeTeams.delete(focusId);
-        return;
+    else if (localModelConfig.kind === 'skip') {
+        return { kind: 'skip', coords: localModelConfig.coords };
     }
-    else if (localModelRouting.kind === 'route') {
-        const { coords, apiKey } = localModelRouting;
-        const { codexHome } = writeLocalModelCodexHome(coords.id, {
-            baseUrl: coords.baseUrl,
-            model: coords.model,
-            wireApi: coords.wireApi ?? undefined,
-        });
+    else if (localModelConfig.kind === 'route') {
+        const { codexHome, codexModel, apiKey, coords } = localModelConfig;
         spawnCodexHome = codexHome;
-        spawnCodexModel = coords.model;
+        spawnCodexModel = codexModel;
         spawnLocalModelKey = apiKey;
         console.log(`[focus-executor] Routing "${focusName}" ${enginePass} pass to local model ` +
             `"${coords.name}" (${coords.model} @ ${coords.baseUrl}); CODEX_HOME=${codexHome}, ` +
             `key from Telora (env ${TELORA_LOCAL_API_KEY_ENV}).`);
     }
     // Model selection: focus-selected pass model > directive fallback.
-    // resolveEffectiveModel is exported for unit testing.
     const focusSelectedModel = selectPipelineModelForSpawn(resolvedEngine.engineId, spawnCodexHome, pipelineConfig?.model);
     const effectiveDirectiveModel = selectDirectiveModelForSpawn(resolvedEngine.engineId, directiveModel, spawnCodexModel ?? focusSelectedModel);
     const effectiveModel = resolveEffectiveModel(effectiveDirectiveModel, spawnCodexHome, spawnCodexModel, focusSelectedModel);
     const effectivePipelineConfig = effectiveModel !== (pipelineConfig?.model ?? null)
         ? { ...pipelineConfig, model: effectiveModel }
         : pipelineConfig;
-    const args = buildAgentArgs(backend, config, worktreePath, effectivePipelineConfig, resumeId, role.allowed_tools, readOnly);
-    // On resume, send an incremental delta (what changed + prior findings to
-    // verify) instead of the full role-framework + assembly: the resumed session
-    // already holds its role and accumulated context (INJ-D). On a fresh spawn
-    // the full prompt is sent unchanged.
-    let messageToSend = prompt;
-    if (resumeId) {
-        let gitDiff = '';
-        try {
-            const diffCtx = {
-                focusId,
-                deliveryIds: deliveries.map(d => d.id),
-                worktreePath,
-                config,
-                organizationId: config.organizationId,
-                productId: config.productId,
-            };
-            const { content } = await resolveAssemblyRecipeWithManifest(['git.diff_against_base'], diffCtx);
-            gitDiff = content;
-        }
-        catch (err) {
-            console.debug(`[focus-executor] Resume-delta diff assembly failed (non-fatal):`, err.message);
-        }
-        messageToSend = buildResumeDeltaMessage({
-            lineage: spawnSpec.lineage,
-            focusName,
-            gitDiff,
-            priorFindings,
-        });
-        console.log(`[focus-executor] Resuming Claude session ${resumeId} for "${focusName}" ` +
-            `-- sending incremental delta (lineage ${spawnSpec.lineage}, ${messageToSend.length} chars, ` +
-            `${priorFindings.length} prior finding(s))`);
+    const args2 = buildAgentArgs(backend, config, worktreePath, effectivePipelineConfig, resumeId, role.allowed_tools, readOnly);
+    return { kind: 'ready', args: args2, effectiveModel, spawnCodexHome, spawnLocalModelKey };
+}
+/**
+ * Phase: choose the stdin message. A fresh spawn sends the full composed prompt;
+ * a resume sends an incremental delta (git diff + prior findings to verify) since
+ * the resumed session already holds its role + accumulated context (INJ-D).
+ */
+export async function buildSpawnMessage(args) {
+    const { prompt, resumeId, spawnSpec, config, focusId, focusName, deliveries, worktreePath, priorFindings } = args;
+    if (!resumeId)
+        return prompt;
+    let gitDiff = '';
+    try {
+        const diffCtx = {
+            focusId,
+            deliveryIds: deliveries.map(d => d.id),
+            worktreePath,
+            config,
+            organizationId: config.organizationId,
+            productId: config.productId,
+        };
+        const { content } = await resolveAssemblyRecipeWithManifest(['git.diff_against_base'], diffCtx);
+        gitDiff = content;
     }
+    catch (err) {
+        console.debug(`[focus-executor] Resume-delta diff assembly failed (non-fatal):`, err.message);
+    }
+    const messageToSend = buildResumeDeltaMessage({
+        lineage: spawnSpec.lineage,
+        focusName,
+        gitDiff,
+        priorFindings,
+    });
+    console.log(`[focus-executor] Resuming Claude session ${resumeId} for "${focusName}" ` +
+        `-- sending incremental delta (lineage ${spawnSpec.lineage}, ${messageToSend.length} chars, ` +
+        `${priorFindings.length} prior finding(s))`);
+    return messageToSend;
+}
+/**
+ * Final phase: build the levered spawn environment, persist the assembly
+ * manifest, write the session lifecycle (starting -> running), acquire the
+ * governor slot, wrap the command in the sandbox (fail-closed), spawn the
+ * child, write its stdin, and attach the completion/close/error handlers.
+ *
+ * Owns ALL of its early-return cleanups so the team-state map and governor slot
+ * never leak: governor-denied (exit_category 'governor_denied') and
+ * sandbox-unavailable (exit_category 'sandbox_unavailable') both mark the
+ * session terminal, release the governor slot where one was held, remove the
+ * team from activeTeams, and return without spawning. Behavior byte-identical
+ * to the original inline tail of spawnFocusTeam.
+ */
+export async function spawnTeamProcess(spec) {
+    const { config, focusId, focusName, session, teamState, backend, args, messageToSend, logs, worktreePath, resumeId, assemblyManifest, spawnCodexHome, spawnLocalModelKey, effectiveModel, pendingDirective, spawnStageName, params, } = spec;
+    const activeTeams = getActiveTeams();
     // Tag spend with the lever: the team-lead spawn runs the focus's execute
     // phase (review directives run the gate); the workflow stage is carried
     // separately. The audit phase tags its own spawn elsewhere.
@@ -878,9 +1020,7 @@ export async function spawnFocusTeam(params) {
             console.warn(`[focus-executor] Governor denied slot for "${focusName}":`, err.message);
             // Mark session as failed so it doesn't linger in `starting` status
             await updateSession(session.id, {
-                status: 'failed',
-                exit_reason: 'Governor denied slot',
-                exit_category: 'governor_denied',
+                ...governorDeniedSessionUpdate(),
                 ended_at: new Date().toISOString(),
             }).catch(updateErr => {
                 console.warn(`[focus-executor] Failed to update session after governor denial:`, updateErr.message);
@@ -908,9 +1048,7 @@ export async function spawnFocusTeam(params) {
         if (err instanceof SandboxUnavailableError) {
             console.error(`[focus-executor] Refusing spawn for "${focusName}": ${err.message}`);
             await updateSession(session.id, {
-                status: 'failed',
-                exit_reason: err.message,
-                exit_category: 'sandbox_unavailable',
+                ...sandboxUnavailableSessionUpdate(err.message),
                 ended_at: new Date().toISOString(),
             }).catch(updateErr => {
                 console.warn(`[focus-executor] Failed to update session after sandbox refusal:`, updateErr.message);
@@ -997,4 +1135,143 @@ export async function spawnFocusTeam(params) {
         activeTeams.delete(focusId);
     });
 }
+/**
+ * Spawn a focus team to execute all deliveries in a focus.
+ *
+ * Creates a single Agent Team (lead process) that reads all deliveries
+ * and issues, builds a task DAG, and coordinates worker execution.
+ */
+export async function spawnFocusTeam(params) {
+    const { config, focusId, focusName, role, pipelineConfig, readOnly = false, claudeSessionIds, engineOverride, localModelOverride, orgDefaultEngine, forceSpawn = false } = params;
+    const activeTeams = getActiveTeams();
+    // The agent backend is resolved per-pass below, once the spawn's lineage
+    // (coding vs review) is known -- see resolveBackend() after lineage resolution.
+    // Prevent double-spawn
+    if (activeTeams.has(focusId)) {
+        console.warn(`[focus-executor] Team already active for focus "${focusName}", skipping spawn`);
+        return;
+    }
+    if (await applyRespawnGuard(focusId, focusName))
+        return;
+    const executionConfig = deriveExecutionConfig(pipelineConfig);
+    const branchName = generateFocusBranchName(role, focusName, focusId);
+    // Initialize team state
+    const teamState = createInitialTeamState({
+        focusId, focusName, role, config, executionConfig, pipelineConfig, branchName, readOnly,
+    });
+    activeTeams.set(focusId, teamState);
+    logSpawnHeader({ config, focusName, role, pipelineConfig, executionConfig, branchName, readOnly });
+    // --- Phase 1: fetch all spawn context (deliveries/issues/product-context/
+    // deployment-profile/loop-context) + PRD milestone push-down. null => the
+    // context fetch rejected; tear down the freshly-inserted team and return.
+    const spawnContext = await fetchSpawnContext(config, focusId, focusName);
+    if (!spawnContext) {
+        activeTeams.delete(focusId);
+        return;
+    }
+    const { deliveries, issues, productContextDocs, deploymentProfileSnapshot, loopContext, prdMilestoneContext, assemblyManifest, } = spawnContext;
+    // --- Phase 2: consume any pending directive, run the rank-ordered pre-spawn
+    // guard, and record known-delivery bookkeeping on the team state. 'skip' =>
+    // no actionable work; tear down and return (the map stays orchestrator-owned).
+    const resolution = resolveActionableDeliveries({
+        focusId, focusName, deliveries, issues, forceSpawn, teamState,
+    });
+    if (resolution.kind === 'skip') {
+        activeTeams.delete(focusId);
+        return;
+    }
+    const { pendingDirective } = resolution;
+    // Ensure log directory exists
+    if (!existsSync(config.logDir)) {
+        mkdirSync(config.logDir, { recursive: true, mode: 0o700 });
+    }
+    // --- Phase: resolve the focus worktree (reuse + rebase, or inline-create).
+    // null => cannot spawn (no commits / create failed); the helper already tore
+    // down (activeTeams.delete + recordFocusTeardown).
+    const worktreePath = await resolveSpawnWorktree({ config, focusId, focusName, branchName, readOnly });
+    if (!worktreePath)
+        return;
+    teamState.worktreePath = worktreePath;
+    // --- Phase: create the team-lead session. null => createSession failed (the
+    // helper already removed the team from activeTeams; worktree is focus-owned).
+    const session = await createTeamSession({
+        config, role, focusId, focusName, branchName, pendingDirective, teamState,
+    });
+    if (!session)
+        return;
+    recordActivity();
+    // Best-effort review context: review-filed open count + prior findings (the
+    // remediation working set) + the focus description for the prompt.
+    const { reviewFiledOpenCount, priorFindings, focusDescription } = await resolveReviewContext({
+        config, focusId, focusName, issues,
+    });
+    // --- Phase A: resolve the directive body + spawn metadata (no prompt yet) ---
+    // The engine backend is resolved per-pass (Phase B) before the prompt is
+    // built (Phase C), so the lead prompt's orchestration vocabulary matches the
+    // engine that will actually run this pass.
+    const { directiveBody, directiveModel, spawnStageName, spawnDirectiveDeclared, useLegacyFullPrompt, } = await resolveDirectiveOrFallback({
+        config, focusId, focusName, worktreePath, pendingDirective, assemblyManifest,
+    });
+    // --- Phase B: resolve the session lineage (pass) and the engine backend
+    // (stamps lineage + sessionType onto the team state). ---
+    const { spawnSpec, enginePass, resolvedEngine, backend } = resolveEngineForPass({
+        spawnDirectiveDeclared, spawnStageName, engineOverride, config, orgDefaultEngine, focusName, teamState,
+    });
+    // --- Phase C: build the prompt with the resolved engine's vocabulary ---
+    const promptContext = buildFocusPromptContext({
+        config, focusId, focusName, focusDescription, deliveries, issues, executionConfig,
+        pipelineConfig, productContextDocs, deploymentProfileSnapshot, readOnly, loopContext,
+        reviewFiledOpenCount, engineId: backend.id,
+    });
+    const prompt = buildSpawnPrompt({
+        role, promptContext, useLegacyFullPrompt, directiveBody, prdMilestoneContext,
+    });
+    // Set up log file streams
+    const logs = setupTeamLogStreams(config.logDir, branchName, focusName);
+    // Build args and env.
+    // Resolve the resume id from the focus's per-lineage session map (INJ-A),
+    // keyed by the spawn's declared lineage, honoring its declared continuity
+    // policy (INJ-B). continuity=fresh -> null; resume -> the lineage's stored id.
+    const resumeId = resolveResumeId({
+        sessionMap: claudeSessionIds,
+        lineage: spawnSpec.lineage,
+        continuity: spawnSpec.continuity,
+    });
+    // --- Phase: resolve CODEX_HOME + per-pass local-model routing + model
+    // selection + CLI args. 'skip' => fail-closed local-model pass (no bearer key);
+    // mark the session terminal (local_model_key_unset) and tear down.
+    const modelResolution = await resolveSpawnModel({
+        resolvedEngine, enginePass, localModelOverride, config, directiveModel,
+        pipelineConfig, backend, worktreePath, resumeId, role, readOnly, focusName,
+    });
+    if (modelResolution.kind === 'skip') {
+        const { coords } = modelResolution;
+        console.error(`[focus-executor] Cannot route "${focusName}" ${enginePass} pass to local model ` +
+            `"${coords.name}" (${coords.model} @ ${coords.baseUrl}): no API key is configured for it ` +
+            `in Telora. Set the key under Settings -> Local Models and re-run; skipping spawn.`);
+        await updateSession(session.id, {
+            ...localModelKeyUnsetSessionUpdate(coords),
+            ended_at: new Date().toISOString(),
+        }).catch(updateErr => {
+            console.warn(`[focus-executor] Failed to update session after local-model key-unset:`, updateErr.message);
+        });
+        activeTeams.delete(focusId);
+        return;
+    }
+    const { args, effectiveModel, spawnCodexHome, spawnLocalModelKey } = modelResolution;
+    // On resume, send an incremental delta instead of the full prompt (INJ-D);
+    // a fresh spawn sends the composed prompt unchanged.
+    const messageToSend = await buildSpawnMessage({
+        prompt, resumeId, spawnSpec, config, focusId, focusName, deliveries, worktreePath, priorFindings,
+    });
+    // --- Final phase: build the spawn env, persist the manifest, write the
+    // session lifecycle, acquire the governor slot, sandbox-wrap, spawn the child,
+    // write stdin, and attach handlers. Owns its governor-denied / sandbox-
+    // unavailable cleanups (session failed-write + slot release + activeTeams.delete).
+    await spawnTeamProcess({
+        config, focusId, focusName, session, teamState, backend, args, messageToSend,
+        logs, worktreePath, resumeId, assemblyManifest, spawnCodexHome, spawnLocalModelKey,
+        effectiveModel, pendingDirective, spawnStageName, params,
+    });
+}
 //# sourceMappingURL=focus-executor.js.map