@cydm/happy-elves 0.1.0-beta.80 → 0.1.0-beta.81

package/apps/cli/dist/commands/daemon.js

@@ -2,7 +2,7 @@ import { createHash, timingSafeEqual } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { daemonLifecycleRequestIdV1Schema, } from "../../../../packages/shared/dist/index.js";
-import { assertLocalDaemonRuntimeMatchesConfig, assertLocalDaemonVerified, assertNoPendingEnrollmentAuthority, canonicalRelayUrl, cliErrorFromFetch, CliError, compactText, ControllerClient, configDir, configPath, daemonPidPath, deriveOrchestration, diagnoseInstallation, emitDoctorResult, ensureDaemonRunning, localDaemonStatus, machineAvailabilityLabel, machineIsAvailable, ok, parsePairingClaimResponse, randomId, readConfig, readDaemonConfig, readDaemonProjectionBaseline, readLocalAuditLog, readRelayJson, redactedDaemonConfig, requirePositional, requireRelayUrl, requireString, restartDaemonForBootstrap, showMachine, startDaemonTimeoutMs, stopLocalDaemon, stopSpawnedDaemon, throwRelayHttpError, waitForDaemonReadiness, waitForDaemonSelfReadiness, wantsJson, withAccountConfigTransaction } from "./lib/index.js";
+import { assertLocalDaemonRuntimeMatchesConfig, assertLocalDaemonVerified, assertNoPendingEnrollmentAuthority, canonicalRelayUrl, cliErrorFromFetch, CliError, compactText, ControllerClient, configDir, configPath, daemonPidPath, deriveOrchestration, diagnoseInstallation, emitDoctorResult, ensureDaemonRunning, localDaemonStatus, machineAvailabilityLabel, machineIsAvailable, ok, parsePairingClaimResponse, randomId, readConfig, readDaemonConfig, readDaemonProjectionBaseline, readLocalAuditLog, readRelayJson, redactedDaemonConfig, requirePositional, requireRelayUrl, requireString, showMachine, startDaemonTimeoutMs, stopLocalDaemon, stopSpawnedDaemon, throwRelayHttpError, waitForDaemonReadiness, waitForDaemonSelfReadiness, wantsJson, withAccountConfigTransaction } from "./lib/index.js";
 function positiveLimit(flags, fallback) {
     const value = flags.limit;
     if (value === undefined)
@@ -328,8 +328,8 @@ export async function handleDaemon({ domain, action, flags }) {
             const baseline = client
                 ? await readDaemonProjectionBaseline(client, config.machineId, { timeoutMs: startDaemonTimeoutMs })
                 : undefined;
-            const daemon = await restartDaemonForBootstrap(config);
-            const readiness = await waitForLocalDaemonReadiness(client, config, baseline, daemon, true);
+            const daemon = await ensureDaemonRunning(config);
+            const readiness = await waitForLocalDaemonReadiness(client, config, baseline, daemon, daemon.started);
             return {
                 ...readiness.local,
                 started: daemon.started,

package/apps/cli/dist/commands/lib/bootstrap.js

@@ -10,7 +10,7 @@ import { assertLocalDaemonRuntimeMatchesConfig, assertLocalDaemonVerified, inspe
 import { redactedRelayUrl, withAccountConfigTransaction, } from "./config.js";
 import { cliErrorFromFetch } from "./relay-http.js";
 import { controllerBaseUrl, ensureControllerConfig, ensureDaemonPaired, readStartConfigPreflight } from "./bootstrap-config.js";
-import { readDaemonProjectionBaseline, restartDaemonForBootstrap, startFailureMayUseCommittedConfig, waitForDaemonReadiness, } from "./bootstrap-daemon.js";
+import { ensureDaemonRunning, readDaemonProjectionBaseline, startFailureMayUseCommittedConfig, waitForDaemonReadiness, } from "./bootstrap-daemon.js";
 import { openUrl, writeHumanStartOutput } from "./bootstrap-output.js";
 import { startJoinBootstrap } from "./bootstrap-join.js";
 import { reconcileSatisfiedDeviceRecoveryPending, startDeviceRecoveryBootstrap } from "./bootstrap-device-recovery.js";
@@ -194,7 +194,10 @@ export async function startBootstrap(flags) {
                     daemonProcessNeedsAttention,
                 };
             }
-            const daemon = await restartDaemonForBootstrap(daemonState.config, cwd);
+            const daemon = {
+                ...await ensureDaemonRunning(daemonState.config, cwd),
+                restarted: false,
+            };
             startedHandle = daemon.startedHandle;
             committedConfigMayBeInUse = daemon.committedConfigMayBeInUse === true;
             const readiness = await waitForDaemonReadiness(client, daemonState.config.machineId, {

package/apps/cli/dist/commands/lib/exit.js

@@ -146,6 +146,16 @@ export function renderCliError(error) {
         }
         return 1;
     }
+    const recoveryCommand = code === "RECOVERY_CONFIRMATION_REQUIRED" && enriched.sessionId && enriched.requestId
+        ? `happy-elves turn retry-unknown ${enriched.sessionId} --request-id ${enriched.requestId} --confirm-risk --json`
+        : undefined;
+    if (recoveryCommand && !wantsJsonOutput()) {
+        console.error(`Error: ${message}`);
+        console.error("");
+        console.error("Only the newly persisted continuation will run in a separate Recovery Session; the unknown prompt will not be replayed.");
+        printRunCommands([recoveryCommand]);
+        return 1;
+    }
     writeError(code, message, {
         requestId: enriched.requestId,
         machineId: enriched.machineId,
@@ -160,6 +170,7 @@ export function renderCliError(error) {
         staleRunningTurnId: enriched.staleRunningTurnId,
         lastTransientError,
         retryCount: enriched.retryCount,
+        diagnostics: recoveryCommand ? { recoveryCommand } : undefined,
     }, enriched.capability, enriched.retryable, detailCode);
     return 1;
 }

package/apps/cli/dist/commands/lib/session-output.d.ts

@@ -43,6 +43,8 @@ export type StructuredCommandOutput = {
     sessionId: string;
     turnId?: string;
     status?: string;
+    admission?: "accepted" | "replayed";
+    dispatch?: "queued" | "delivered";
     finalOutput?: string;
     error?: string;
     artifactPaths?: {
@@ -56,7 +58,7 @@ export declare function readStoredTurnOutput(sessionId: string, turnId?: string)
 export declare function summarizeTurns(events: DecodedSessionEvent[]): TurnSummary[];
 export declare function structuredOutputForTurn(sessionId: string, turn: TurnSummary): StructuredCommandOutput;
 export declare function structuredOutputForStoredTurn(output: StoredTurnOutput): StructuredCommandOutput;
-export declare function structuredOutputForRunningTurn(sessionId: string, turnId: string): StructuredCommandOutput;
+export declare function structuredOutputForRunningTurn(sessionId: string, turnId: string, dispatch?: "queued" | "delivered"): StructuredCommandOutput;
 export declare function collectExactTurnEvents(client: ControllerClient, sessionId: string, turnId: string, limit?: number): Promise<DecodedSessionEvent[]>;
 export declare function rebuildTurnOutput(client: ControllerClient, sessionId: string, turnId?: string): Promise<StoredTurnOutput>;
 export declare function conciseEvents(events: DecodedSessionEvent[]): Array<{

package/apps/cli/dist/commands/lib/session-output.js

@@ -294,12 +294,13 @@ export function structuredOutputForStoredTurn(output) {
         },
     };
 }
-export function structuredOutputForRunningTurn(sessionId, turnId) {
+export function structuredOutputForRunningTurn(sessionId, turnId, dispatch = "delivered") {
+    const status = dispatch === "queued" ? "queued" : "running";
     return {
-        state: "running",
+        state: status,
         sessionId,
         turnId,
-        status: "running",
+        status,
     };
 }
 function foldAliasedRuntimeEvents(events) {
@@ -393,7 +394,10 @@ export async function rebuildTurnOutput(client, sessionId, turnId) {
     if (exactTurnId) {
         events = await collectExactTurnEvents(client, sessionId, exactTurnId, 1000);
         folded = foldAliasedRuntimeEvents(events);
-        resolvedTurnId = turnId ? (folded.runtimeToRequest.get(turnId) ?? resolvedTurnId) : exactTurnId;
+        const canonicalExactTurnId = events[0]?.turnId ?? exactTurnId;
+        resolvedTurnId = turnId
+            ? (folded.runtimeToRequest.get(turnId) ?? canonicalExactTurnId)
+            : canonicalExactTurnId;
         turns = summarizeTurns(events);
         latestCompleted = turns.find((turn) => turn.status === "completed") ?? latestCompleted;
         summary = resolvedTurnId ? turns.find((turn) => turn.turnId === resolvedTurnId) : turns[0];

package/apps/cli/dist/commands/lib/session-view.d.ts

@@ -25,6 +25,12 @@ export declare function structuredSessionProjection(client: ControllerClient, se
     lastTurnId?: string;
     sourceSessionId?: string;
     sourceCheckpointId?: string;
+    daemon: SessionSnapshot["daemon"];
+    connection: SessionSnapshot["connection"];
+    supervision: SessionSnapshot["supervision"];
+    execution: SessionSnapshot["execution"];
+    admission: SessionSnapshot["admission"];
+    dispatch: SessionSnapshot["dispatch"];
     capabilities: SessionSnapshot["capabilities"];
     orchestration: OrchestrationSummary;
 }>;

package/apps/cli/dist/commands/lib/session-view.js

@@ -33,6 +33,8 @@ function orchestrationStateFromSnapshot(session) {
         return "blocked";
     if (session.execution.status === "failed")
         return "blocked";
+    if (session.execution.status === "idle" && (session.dispatch === "queued" || session.dispatch === "delivered"))
+        return "pending";
     if (session.execution.status === "active" || session.supervision.status === "watching")
         return "active";
     if (session.supervision.status === "reconciling" || session.supervision.status === "settling")
@@ -45,7 +47,7 @@ function orchestrationStateFromSnapshot(session) {
 }
 function canTrustVisibleRunningTurn(session) {
     return session.status !== "closed" &&
-        (session.execution.status === "active" || session.supervision.status === "watching");
+        (session.execution.status === "active" || session.dispatch === "started");
 }
 function operationalProjection(session) {
     return {
@@ -138,6 +140,12 @@ export async function structuredSessionProjection(client, session, events = [])
         lastTurnId: session.lastTurnId,
         sourceSessionId: session.sourceSessionId,
         sourceCheckpointId: session.sourceCheckpointId,
+        daemon: session.daemon,
+        connection: session.connection,
+        supervision: session.supervision,
+        execution: session.execution,
+        admission: session.admission,
+        dispatch: session.dispatch,
         capabilities: session.capabilities,
         orchestration,
     };

package/apps/cli/dist/commands/lib/usage.js

@@ -129,7 +129,7 @@ Session management:
   happy-elves turn wait <sessionId> <turnId> [--timeout 1000s] --json
   happy-elves turn cancel <sessionId> <turnId> [--reason <reason>] --json
   happy-elves turn reconcile <sessionId> <turnId> [--request-id <stable-id>] --json
-  happy-elves turn retry-unknown <sessionId> <turnId> --request-id <stable-id> --confirm-risk [--name <recovery-name>] --json
+  happy-elves turn retry-unknown <sessionId> [turnId] --request-id <original-continuation-request-id> --confirm-risk [--name <recovery-name>] --json
   happy-elves turn rewind <sessionId> <turn-or-checkpoint-id> --json
   happy-elves turn fork <sessionId> <turn-or-checkpoint-id> --name <name> --json
 
@@ -283,7 +283,7 @@ Core commands:
   turn result <sessionId> [<turnId>] [--json]
   turn cancel <sessionId> <turnId> [--reason <reason>] --json
   turn reconcile <sessionId> <turnId> [--request-id <id>] --json
-  turn retry-unknown <sessionId> <turnId> --request-id <id> --confirm-risk [--name <name>] --json
+  turn retry-unknown <sessionId> [turnId] --request-id <original-continuation-request-id> --confirm-risk [--name <name>] --json
   turn rewind <sessionId> <turn-or-checkpoint-id> --json
   turn fork <sessionId> <turn-or-checkpoint-id> --name <name> --json
 

package/apps/cli/dist/commands/orchestrator.js

@@ -505,14 +505,15 @@ async function readExactTurn(client, threadId, turnId, metadata) {
         collectExactTurnEvents(client, threadId, turnId, defaultTurnHistoryLimit),
         client.getTurn(threadId, turnId),
     ]);
-    const exact = summarizeTurns(events).find((turn) => turn.turnId === turnId);
+    const canonicalTurnId = turnSnapshot?.turnId ?? events[0]?.turnId ?? turnId;
+    const exact = summarizeTurns(events).find((turn) => turn.turnId === canonicalTurnId);
     const projectedExact = applyAuthoritativeTurnSnapshot(exact, turnSnapshot, turnId);
     if (projectedExact && projectedExact.status !== "running")
         return projectedExact;
     if (!metadata)
         return projectedExact;
     const allEvents = await client.history(threadId, defaultTurnHistoryLimit);
-    const folded = summarizeOrchestratorTurns(allEvents, metadata).find((turn) => turn.turnId === turnId);
+    const folded = summarizeOrchestratorTurns(allEvents, metadata).find((turn) => turn.turnId === canonicalTurnId);
     return applyAuthoritativeTurnSnapshot(folded ?? projectedExact, turnSnapshot, turnId);
 }
 async function readExactTurnOrThrow(client, threadId, turnId, metadata) {
@@ -538,12 +539,13 @@ async function rebuildOutputForTurn(client, threadId, turn) {
 }
 async function rebuildRuntimeTurnOutput(client, threadId, runtimeTurnId) {
     const events = await collectExactTurnEvents(client, threadId, runtimeTurnId, defaultTurnHistoryLimit);
-    const exact = events.filter((event) => event.turnId === runtimeTurnId);
-    const exactSummary = summarizeTurns(exact).find((turn) => turn.turnId === runtimeTurnId);
+    const canonicalTurnId = events[0]?.turnId ?? runtimeTurnId;
+    const exact = events.filter((event) => event.turnId === canonicalTurnId);
+    const exactSummary = summarizeTurns(exact).find((turn) => turn.turnId === canonicalTurnId);
     if (exactSummary?.output)
-        return await writeTurnOutput(threadId, runtimeTurnId, exact);
+        return await writeTurnOutput(threadId, canonicalTurnId, exact);
     const history = await client.history(threadId, defaultTurnHistoryLimit);
-    return await writeTurnOutput(threadId, runtimeTurnId, history.filter((event) => event.turnId === runtimeTurnId));
+    return await writeTurnOutput(threadId, canonicalTurnId, history.filter((event) => event.turnId === canonicalTurnId));
 }
 async function readTurnDetails(client, threadId, turnId, metadata) {
     const turn = await readExactTurnOrThrow(client, threadId, turnId, metadata);
@@ -827,7 +829,20 @@ async function waitForTurn(client, threadId, turnId, timeoutMs, metadata) {
         if (turn?.status === "running") {
             const session = await client.getSession(threadId).catch(() => undefined);
             if (session && classifyRunningTurn(session, [], turn).state === "stale") {
-                throw turnOrphaned(threadId, turnId, turn.status, operationalSessionStatus(session));
+                // The exact turn and Session projections are fetched independently.
+                // A provider terminal may commit between those reads, making the first
+                // turn snapshot look running while the Session already references the
+                // same completed execution. Re-read the immutable turn before calling
+                // it orphaned, and let that same-turn convergence window retry.
+                const refreshedTurn = await readExactTurn(client, threadId, turnId, metadata);
+                if (refreshedTurn && refreshedTurn.status !== "running")
+                    return refreshedTurn;
+                const canonicalTurnId = refreshedTurn?.turnId ?? turn.turnId;
+                const sameTerminalExecution = session.execution.turnId === canonicalTurnId &&
+                    ["completed", "failed", "cancelled"].includes(session.execution.status);
+                if (!sameTerminalExecution) {
+                    throw turnOrphaned(threadId, turnId, turn.status, operationalSessionStatus(session));
+                }
             }
         }
         if (Date.now() - startedAt >= timeoutMs) {
@@ -876,11 +891,20 @@ async function sendOrchestratorMessage(client, flags, input) {
         model,
         thoughtLevel,
     });
-    const self = await client.tokenSelf();
+    const [self, directSession] = await Promise.all([
+        client.tokenSelf(),
+        client.getSession(input.threadId),
+    ]);
     if (!self.full) {
         throw new OrchestratorError("orchestrator send-message requires a full controller token.", "SCOPED_TOKEN_FORBIDDEN", { retryable: false, sessionId: input.threadId, turnId });
     }
-    const { session } = await readThreadContext(client, input.threadId);
+    if (!directSession) {
+        throw new OrchestratorError(`Thread not found: ${input.threadId}`, "THREAD_NOT_FOUND", {
+            sessionId: input.threadId,
+            retryable: false,
+        });
+    }
+    const session = directSession;
     const metadata = await client.decodeSessionMetadata(session);
     const resolvedPermission = resolvePermissionMode(requestedPermissionMode, metadata);
     let activePermissionMode = resolvedPermission.permissionMode;
@@ -1053,6 +1077,85 @@ async function sendOrchestratorMessage(client, flags, input) {
             includeOutput: includeContextOutput,
         },
     } : {};
+    // Contract 7 makes the immutable Relay admission the sole idempotency
+    // authority. Older orchestrator versions stored a second request ledger in
+    // encrypted Session metadata and performed several read/CAS round trips
+    // before and after dispatch. Besides being redundant, that made a detached
+    // send take tens of seconds on a high-latency Relay. Dispatch directly with
+    // the stable request/turn identity; the Relay returns only after admission
+    // and its delivery outbox are durable.
+    if (!existingRequest) {
+        const inactivityTimeoutMs = parseDurationMs(flags["inactivity-timeout"], DEFAULT_COMMAND_TIMEOUT_MS);
+        let admissionResult;
+        try {
+            admissionResult = await client.run(input.threadId, text, {
+                wait: false,
+                permissionMode: activePermissionMode,
+                requestId: relayRequestId,
+                turnId,
+                model,
+                thoughtLevel,
+                ackTimeoutMs: 15_000,
+                inactivityTimeoutMs,
+            });
+        }
+        catch (error) {
+            const enriched = error;
+            if (enriched.code === "REQUEST_ID_CONFLICT" || enriched.code === "TURN_ADMISSION_CONFLICT") {
+                throw requestConflict(input.threadId, requestId, turnId);
+            }
+            if (enriched.code === "SESSION_BUSY") {
+                const activeTurnId = enriched.activeTurnId ?? session.execution.turnId;
+                throw new OrchestratorError(enriched.message, "THREAD_BUSY", {
+                    retryable: true,
+                    sessionId: input.threadId,
+                    turnId: activeTurnId ?? turnId,
+                    activeTurnId,
+                    latestCompletedTurnId: enriched.latestCompletedTurnId,
+                    rawStatus: "running",
+                });
+            }
+            throw error;
+        }
+        if (admissionResult.admission === "replayed") {
+            const replayed = await readExactTurn(client, input.threadId, turnId, metadata);
+            if (replayed && replayed.status !== "running") {
+                const output = await rebuildOutputForTurn(client, input.threadId, replayed);
+                ok(input.responseType, {
+                    threadId: input.threadId,
+                    sessionId: input.threadId,
+                    turnId,
+                    requestId,
+                    admission: "replayed",
+                    dispatch: admissionResult.dispatch ?? "delivered",
+                    status: terminalStatusForTurn(replayed),
+                    rawStatus: replayed.status,
+                    finalOutput: output.output || undefined,
+                    artifactPaths: {
+                        output: output.outputPath,
+                        latest: output.latestPath,
+                        metadata: output.metadataPath,
+                    },
+                    ...permissionEvidence(requestedPermissionMode, undefined, resolvedPermission),
+                    ...contextData,
+                }, { requestId, sessionId: input.threadId, turnId });
+                return;
+            }
+        }
+        ok(input.responseType, {
+            threadId: input.threadId,
+            sessionId: input.threadId,
+            turnId,
+            requestId,
+            admission: admissionResult.admission ?? "accepted",
+            dispatch: admissionResult.dispatch ?? "queued",
+            status: "inProgress",
+            rawStatus: admissionResult.dispatch ?? "queued",
+            ...permissionEvidence(requestedPermissionMode, undefined, resolvedPermission),
+            ...contextData,
+        }, { requestId, sessionId: input.threadId, turnId });
+        return;
+    }
     const events = await client.history(input.threadId, defaultTurnHistoryLimit);
     const turns = summarizeOrchestratorTurns(events, metadata);
     const existingTurn = await readExactTurn(client, input.threadId, turnId, metadata);
@@ -1134,11 +1237,12 @@ async function sendOrchestratorMessage(client, flags, input) {
         if (enriched.code === "REQUEST_ID_CONFLICT")
             throw requestConflict(input.threadId, requestId, turnId);
         if (enriched.code === "SESSION_BUSY") {
+            const activeTurnId = enriched.activeTurnId ?? session.execution.turnId;
             throw new OrchestratorError(enriched.message, "THREAD_BUSY", {
                 retryable: true,
                 sessionId: input.threadId,
-                turnId,
-                activeTurnId: enriched.activeTurnId,
+                turnId: activeTurnId ?? turnId,
+                activeTurnId,
                 latestCompletedTurnId: enriched.latestCompletedTurnId,
                 rawStatus: "running",
             });
@@ -1256,7 +1360,7 @@ export async function handleOrchestrator({ domain, action, positional, flags })
         ok("orchestrator.readTurn", {
             thread: await threadSummary(client, session, machines, { focusTurn: details.turn }),
             turn: projectTurn(threadId, details, includeOutput),
-        }, { sessionId: threadId, turnId });
+        }, { sessionId: threadId, turnId: details.turn.turnId });
         return true;
     }
     if (action === "send-message") {
@@ -1306,7 +1410,7 @@ export async function handleOrchestrator({ domain, action, positional, flags })
         ok("orchestrator.waitThread", {
             threadId,
             sessionId: threadId,
-            turnId,
+            turnId: turn.turnId,
             status: terminalStatusForTurn(turn),
             rawStatus: turn.status,
             finalOutput: output.output || undefined,
@@ -1315,7 +1419,7 @@ export async function handleOrchestrator({ domain, action, positional, flags })
                 latest: output.latestPath,
                 metadata: output.metadataPath,
             },
-        }, { sessionId: threadId, turnId });
+        }, { sessionId: threadId, turnId: turn.turnId });
         return true;
     }
     if (action === "set-thread-tags") {

package/apps/cli/dist/commands/session.js

@@ -506,7 +506,11 @@ export async function handleSession({ domain, action, positional, flags }) {
         // silently run in the controller's local repository.
         const cwd = requireString(flags, "cwd");
         const requestedRuntimeName = typeof flags.name === "string" ? flags.name : undefined;
-        const name = "main";
+        // Relay admission is now the create command's completion boundary. Keep
+        // the requested product-facing name in that durable projection instead
+        // of publishing a transient "main" name and relying on a later,
+        // blocking repair rename after provider readiness.
+        const name = requestedRuntimeName ?? "main";
         const permissionMode = parsePermissionMode(flags["permission-mode"] ?? flags.permission);
         const model = parseRuntimeSelection(flags.model, "model");
         const thoughtLevel = parseThoughtLevel(flags);
@@ -591,9 +595,10 @@ export async function handleSession({ domain, action, positional, flags }) {
                     session.execution.status === "unknown" ||
                     session.execution.status === "legacy-unresolved" ||
                     machine?.archivedAt !== undefined;
+                const verboseSession = wantsVerbose(flags) ? await showSession(client, session) : undefined;
                 return {
-                    ...(wantsVerbose(flags)
-                        ? await showSession(client, session)
+                    ...(verboseSession
+                        ? { ...verboseSession, state: verboseSession.orchestration.state }
                         : await compactSessionListItem(client, session, {
                             includeMachine,
                             includeCwd,
@@ -652,6 +657,8 @@ export async function handleSession({ domain, action, positional, flags }) {
             connection: session.connection,
             supervision: session.supervision,
             execution: session.execution,
+            admission: session.admission,
+            dispatch: session.dispatch,
             activeTurnId,
             latestCompletedTurnId: latestCompletedTurn?.turnId,
             latestTerminalTurnId: latestTerminalTurn?.turnId,

package/apps/cli/dist/commands/skill.js

@@ -6,6 +6,7 @@ import { pathToFileURL } from "node:url";
 import { ControllerClient, buildIdentity, CliExit, ok, machineIsAvailable, readConfig, redactedRelayUrl, requireString, } from "./lib/index.js";
 import { CliError } from "../errors.js";
 import { ORCHESTRATOR_SKILL_NAME, builtinSkillNames, resolveBuiltinSkill } from "../skills/registry.js";
+import { readSkillAutoAlignmentReport } from "../skills/auto-align.js";
 function optionalString(flags, name) {
     const value = flags[name];
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
@@ -303,6 +304,19 @@ async function skillDoctor(flags) {
         detail: String(skill.contractVersion),
     });
     await addInstalledSkillCheck(checks, warnings, flags, name, skill);
+    if (skill.doctorKind === "orchestrator") {
+        const alignment = await readSkillAutoAlignmentReport();
+        if (alignment?.contractVersion === skill.contractVersion) {
+            checks.push({
+                name: "skill-reload",
+                status: "warning",
+                compatible: true,
+                aligned: true,
+                detail: `Official skill was aligned at ${new Date(alignment.alignedAt).toISOString()}; reload Codex or open a fresh task to use it`,
+            });
+            warnings.push("The official orchestrator skill was updated. Reload Codex or open a fresh task before relying on the new guidance.");
+        }
+    }
     if (skill.doctorKind === "orchestrator") {
         await addOrchestratorChecks(checks, warnings, flags);
         await addGitCommitCapabilityCheck(checks, warnings);

package/apps/cli/dist/commands/turn.js

@@ -50,7 +50,8 @@ async function readTurnSummary(client, sessionId, turnId) {
         client.history(sessionId, 1000),
         client.getTurn(sessionId, turnId),
     ]);
-    const summary = summarizeTurns(events).find((turn) => turn.turnId === turnId);
+    const canonicalTurnId = turnSnapshot?.turnId ?? events[0]?.turnId ?? turnId;
+    const summary = summarizeTurns(events).find((turn) => turn.turnId === canonicalTurnId);
     return applyAuthoritativeTurnSnapshot(summary, turnSnapshot, turnId);
 }
 async function readExactTurnSummary(client, sessionId, turnId) {
@@ -58,7 +59,8 @@ async function readExactTurnSummary(client, sessionId, turnId) {
         collectExactTurnEvents(client, sessionId, turnId, 1000),
         client.getTurn(sessionId, turnId),
     ]);
-    const summary = summarizeTurns(events).find((turn) => turn.turnId === turnId);
+    const canonicalTurnId = turnSnapshot?.turnId ?? events[0]?.turnId ?? turnId;
+    const summary = summarizeTurns(events).find((turn) => turn.turnId === canonicalTurnId);
     return applyAuthoritativeTurnSnapshot(summary, turnSnapshot, turnId);
 }
 async function resolveTurnOrCheckpointId(client, sessionId, turnOrCheckpointId) {
@@ -134,7 +136,7 @@ export async function handleTurn({ domain, action, positional, flags }) {
         const turn = await readTurnSummary(client, sessionId, turnId);
         if (!turn)
             throw new CliError(`Turn not found: ${turnId}`, "TURN_NOT_FOUND");
-        ok("turn.status", wantsVerbose(flags) ? { sessionId, turn } : { sessionId, ...compactTurn(turn) }, { sessionId, turnId });
+        ok("turn.status", wantsVerbose(flags) ? { sessionId, turn } : { sessionId, ...compactTurn(turn) }, { sessionId, turnId: turn.turnId });
         return true;
     }
     if (action === "run") {
@@ -175,10 +177,12 @@ export async function handleTurn({ domain, action, positional, flags }) {
             const structured = output
                 ? structuredOutputForStoredTurn(output)
                 : result.turnId
-                    ? structuredOutputForRunningTurn(sessionId, result.turnId)
+                    ? structuredOutputForRunningTurn(sessionId, result.turnId, result.dispatch)
                     : { state: "accepted", sessionId };
             ok("turn.run", {
                 ...structured,
+                admission: result.admission ?? "accepted",
+                dispatch: result.dispatch ?? "delivered",
                 effectivePermissionMode: permissionMode,
                 permissionSource,
                 ...(wantsVerbose(flags) ? { events, output } : {}),
@@ -207,7 +211,7 @@ export async function handleTurn({ domain, action, positional, flags }) {
                 ...structuredOutputForTurn(sessionId, turn),
                 until: "turn",
                 ...(wantsVerbose(flags) ? { turn } : {}),
-            }, { sessionId, turnId });
+            }, { sessionId, turnId: turn.turnId });
         }
         else {
             console.log(`Turn ${turn.turnId} ${turn.status}`);
@@ -270,7 +274,6 @@ export async function handleTurn({ domain, action, positional, flags }) {
     }
     if (action === "retry-unknown") {
         const sessionId = requirePositional(positional[0], "sessionId");
-        const turnId = requirePositional(positional[1], "turnId");
         if (flags["confirm-risk"] !== true) {
             throw new CliError("Retrying an unknown execution can duplicate external side effects. Re-run with --confirm-risk to create a Recovery Session.", "CONFIRMATION_REQUIRED");
         }
@@ -278,15 +281,22 @@ export async function handleTurn({ domain, action, positional, flags }) {
         const session = await client.getSession(sessionId);
         if (!session)
             throw new CliError("Session not found", "SESSION_NOT_FOUND");
-        if (session.supervision.status !== "failed" || session.execution.status !== "unknown") {
-            throw new CliError("Unknown-turn retry requires supervision=failed and execution=unknown", "TURN_NOT_RETRYABLE");
+        const sourceTurnId = positional[1]?.trim() ||
+            session.execution.turnId ||
+            session.supervision.turnId ||
+            session.historyRecovery?.turnId;
+        const legacyRiskRequired = session.historyRecovery?.state === "risk-required" ||
+            session.historyRecovery?.state === "uninspectable";
+        if (!legacyRiskRequired && (session.supervision.status !== "failed" || session.execution.status !== "unknown")) {
+            throw new CliError("Unknown-turn retry requires failed supervision with unknown execution, or an uninspectable history recovery", "TURN_NOT_RETRYABLE");
         }
-        const recoverySessionId = deterministicRecoverySessionId(sessionId, turnId, requestId);
-        const recoveryTurnId = deterministicRecoveryTurnId(sessionId, turnId, requestId);
+        const recoveryIdentity = sourceTurnId ?? "legacy-uninspectable";
+        const recoverySessionId = deterministicRecoverySessionId(sessionId, recoveryIdentity, requestId);
+        const recoveryTurnId = deterministicRecoveryTurnId(sessionId, recoveryIdentity, requestId);
         const sourceCheckpointId = session.currentHead && isProviderCheckpoint(session.currentHead) ? session.currentHead : undefined;
         const name = typeof flags.name === "string" && flags.name.trim() ? flags.name.trim() : `Recovery: ${session.name}`;
         const result = await client.retryUnknownTurn(sessionId, {
-            turnId,
+            ...(sourceTurnId ? { turnId: sourceTurnId } : {}),
             requestId,
             riskAcknowledged: true,
             recoverySessionId,
@@ -295,7 +305,7 @@ export async function handleTurn({ domain, action, positional, flags }) {
             ...(sourceCheckpointId ? { sourceCheckpointId } : {}),
             context: {
                 sourceSessionId: sessionId,
-                sourceTurnId: turnId,
+                ...(sourceTurnId ? { sourceTurnId } : {}),
                 sourceExecution: "unknown",
                 riskAcknowledged: true,
                 checkpointAvailable: Boolean(sourceCheckpointId),
@@ -303,20 +313,20 @@ export async function handleTurn({ domain, action, positional, flags }) {
             metadata: {
                 name,
                 recoverySourceSessionId: sessionId,
-                recoverySourceTurnId: turnId,
+                ...(sourceTurnId ? { recoverySourceTurnId: sourceTurnId } : {}),
                 recoveryRiskAcknowledged: true,
             },
         });
         ok("turn.retryUnknown", {
             sourceSessionId: sessionId,
-            sourceTurnId: turnId,
+            sourceTurnId,
             sessionId: result.sessionId ?? recoverySessionId,
             recoverySessionId: result.sessionId ?? recoverySessionId,
-            recoveryTurnId,
+            recoveryTurnId: result.turnId ?? recoveryTurnId,
             sourceCheckpointId,
             status: "accepted",
             riskAcknowledged: true,
-        }, { requestId: result.requestId, sessionId: result.sessionId ?? recoverySessionId, turnId: recoveryTurnId });
+        }, { requestId: result.requestId, sessionId: result.sessionId ?? recoverySessionId, turnId: result.turnId ?? recoveryTurnId });
         return true;
     }
     if (action === "rewind") {

package/apps/cli/dist/index.js

@@ -2,6 +2,7 @@
 import { main } from "./commands/app.js";
 import { renderCliError } from "./commands/lib/exit.js";
 import { isCliExit } from "./commands/lib/cli-exit.js";
+import { autoAlignOfficialOrchestratorSkill } from "./skills/auto-align.js";
 async function flushWritable(stream) {
     await new Promise((resolve) => {
         stream.write("", () => resolve());
@@ -11,4 +12,10 @@ async function exitAfterFlush(code) {
     await Promise.all([flushWritable(process.stdout), flushWritable(process.stderr)]);
     process.exit(code);
 }
-void main().then(() => exitAfterFlush(0), (error) => exitAfterFlush(isCliExit(error) ? error.exitCode : renderCliError(error)));
+void autoAlignOfficialOrchestratorSkill().then((report) => {
+    if (report && process.stderr.isTTY && !process.argv.includes("--json")) {
+        const backups = report.actions.flatMap((action) => action.backupPath ? [action.backupPath] : []);
+        console.error(`Happy Elves aligned the official orchestrator skill to contract ${report.contractVersion}. Reload Codex to use it.${backups.length > 0 ? ` Modified copies were backed up at: ${backups.join(", ")}` : ""}`);
+    }
+    return main();
+}).then(() => exitAfterFlush(0), (error) => exitAfterFlush(isCliExit(error) ? error.exitCode : renderCliError(error)));

package/apps/cli/dist/skills/auto-align.d.ts

@@ -0,0 +1,21 @@
+type SkillAutoAlignmentAction = {
+    path: string;
+    action: "installed" | "updated" | "updated-with-backup";
+    backupPath?: string;
+};
+export type SkillAutoAlignmentReport = {
+    version: 1;
+    cliVersion: string;
+    contractVersion: number;
+    alignedAt: number;
+    reloadRequired: boolean;
+    actions: SkillAutoAlignmentAction[];
+};
+/**
+ * Keeps only the official orchestrator skill aligned with the installed CLI.
+ * Other skill directories are never enumerated or modified. The operation is
+ * idempotent and each replacement is committed with an atomic rename.
+ */
+export declare function autoAlignOfficialOrchestratorSkill(): Promise<SkillAutoAlignmentReport | undefined>;
+export declare function readSkillAutoAlignmentReport(): Promise<SkillAutoAlignmentReport | undefined>;
+export {};