@trycadence/cli 0.1.14-dev.0 → 0.1.16-dev.0

package/dist/cadence

@@ -1520,7 +1520,7 @@ import { createInterface } from "readline/promises";
 // package.json
 var package_default = {
   name: "@trycadence/cli",
-  version: "0.1.14-dev.0",
+  version: "0.1.16-dev.0",
   private: false,
   type: "module",
   bin: {
@@ -1554,6 +1554,8 @@ var workLogParentSelectors = ["last", "ticket-last", "session-last", "last-decis
 var changesetPrNoteSources = ["agent", "human", "system"];
 var hookScopes = ["repo", "global", "both"];
 var agentEventSources = ["codex", "claude-code", "opencode", "openrouter", "unknown"];
+var agentRunMemoryModes = ["checkpoint", "closeout"];
+var closeoutSessionActions = ["handoff", "end", "keep"];
 var defaultLeaseTtlSeconds = 15 * 60;
 var defaultCliApiBaseUrl = "https://cadenceapi.deploy.lvl8studios.com";
 var defaultCliWebBaseUrl = "https://cadence.deploy.lvl8studios.com";
@@ -1599,6 +1601,7 @@ var knownCommandPaths = [
   ["changesets", "notes", "put"],
   ["changesets", "notes", "apply"],
   ["agent-run", "ingest-stop"],
+  ["agent-run", "route"],
   ["agent-run", "checkpoint"],
   ["agent-run", "closeout"],
   ["agent-run", "sweep"],
@@ -2279,7 +2282,9 @@ function helpText() {
     "  cadence changesets notes put [--changeset <id>|--branch current|<branch>] --title <text> --body-file <path> [--head-sha <sha>] [--base-sha <sha>] [--pr-url <url>] [--pr-number <n>] [--project <project-id>] [--json]",
     "  cadence changesets notes apply [--changeset <id>|--branch current|<branch>] --provider github --pr-number <n> --pr-url <url> [--project <project-id>] [--json]",
     "  cadence agent-run ingest-stop --source <codex|claude-code|opencode|openrouter> [--event <event>] [--threshold <n>] [--dry-run true|false] [--project <project-id>] [--json]",
+    "  cadence agent-run route --agent-session-key <key> --reason <missing_context|checkpoint_reroute|manual> [--event-file <path>] [--checkpoint-provider codex] [--checkpoint-model <model>] [--json]",
     "  cadence agent-run checkpoint --agent-session-key <key> [--reason <threshold|idle|manual>] [--event-file <path>] [--ticket <ticket-id>] [--session <session-id>] [--changeset <changeset-id>] [--checkpoint-provider codex] [--checkpoint-model <model>] [--log-kind <kind>] [--update-summary true|false] [--json]",
+    "  cadence agent-run closeout --agent-session-key <key> [--session-action handoff|end|keep] [--complete-ticket true|false] [--event-file <path>] [--ticket <ticket-id>] [--session <session-id>] [--changeset <changeset-id>] [--checkpoint-provider codex] [--checkpoint-model <model>] [--update-summary true|false] [--json]",
     "  cadence agent-run sweep [--idle-after-seconds <n>] [--dry-run true|false] [--json]",
     "  cadence agent-run doctor [--json]",
     "  cadence hooks install --provider codex [--scope global] [--command <command>] [--json]",
@@ -3085,9 +3090,10 @@ function normalizeGenericAgentEvent(input, base) {
 function agentSessionKey(source, agentSessionId) {
   return `${source}:${stableHash(agentSessionId)}`;
 }
-function checkpointWorkLogMetadata(settings, tokenAccounting) {
+function checkpointWorkLogMetadata(settings, mode, tokenAccounting) {
   return {
     checkpoint: {
+      ...mode ? { mode } : {},
       provider: settings.provider,
       ...settings.model ? { model: settings.model } : {},
       ...tokenAccounting ? { tokenAccounting } : {}
@@ -3248,12 +3254,54 @@ function readAgentLoopSessions(rawSessions) {
       ...recentTurns ? { recentTurns } : {},
       ...typeof record.lastCheckpointAt === "string" ? { lastCheckpointAt: record.lastCheckpointAt } : {},
       ...typeof record.lastCheckpointFingerprint === "string" ? { lastCheckpointFingerprint: record.lastCheckpointFingerprint } : {},
+      ...readAgentRunFingerprints(record.lastCheckpointFingerprints),
+      ...typeof record.lastCheckpointMode === "string" && agentRunMemoryModes.includes(record.lastCheckpointMode) ? { lastCheckpointMode: record.lastCheckpointMode } : {},
+      ...readAgentRunCoverage(record.lastCheckpointCoverage),
       ...typeof record.previousCheckpointSummary === "string" ? { previousCheckpointSummary: record.previousCheckpointSummary } : {},
       ...typeof record.lastCheckpointAuditFile === "string" ? { lastCheckpointAuditFile: record.lastCheckpointAuditFile } : {}
     };
   }
   return sessions;
 }
+function readAgentRunFingerprints(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  const record = value;
+  const event = typeof record.event === "string" ? record.event : undefined;
+  const git = typeof record.git === "string" ? record.git : undefined;
+  const cadenceContext = typeof record.cadenceContext === "string" ? record.cadenceContext : undefined;
+  if (!event || !git || !cadenceContext) {
+    return {};
+  }
+  return {
+    lastCheckpointFingerprints: {
+      event,
+      git,
+      cadenceContext,
+      ...typeof record.verification === "string" ? { verification: record.verification } : {},
+      ...typeof record.coverageDebt === "string" ? { coverageDebt: record.coverageDebt } : {}
+    }
+  };
+}
+function readAgentRunCoverage(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  const record = value;
+  const coverage = {
+    outcome: record.outcome === true,
+    implementation: record.implementation === true,
+    decisions: record.decisions === true,
+    corrections: record.corrections === true,
+    verification: record.verification === true,
+    blockers: record.blockers === true,
+    scope: record.scope === true,
+    handoff: record.handoff === true,
+    hasDebt: record.hasDebt === true
+  };
+  return { lastCheckpointCoverage: coverage };
+}
 function readAgentSessionCadenceContext(record) {
   const value = record.cadenceContext;
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -3396,7 +3444,7 @@ function currentCliWorkerInvocation() {
     argsPrefix: []
   };
 }
-async function spawnAgentRunCheckpoint(args, options) {
+async function spawnAgentRunWorker(args, options) {
   const cwd = options.cwd ?? process.cwd();
   const invocation = currentCliWorkerInvocation();
   const env = {
@@ -3415,6 +3463,9 @@ async function spawnAgentRunCheckpoint(args, options) {
   });
   child.unref();
 }
+async function spawnAgentRunCheckpoint(args, options) {
+  await spawnAgentRunWorker(args, options);
+}
 function currentRecordTime(value, keys) {
   for (const key of keys) {
     const candidate = value[key];
@@ -3756,9 +3807,6 @@ function parseCheckpointPlanFiles(value) {
     };
   });
 }
-function routeRequiresHighConfidence(route, session) {
-  return highAutonomyRouteActions.has(route.action) || session?.action === "complete_ticket";
-}
 function forceNeedsHuman(plan, reason) {
   return {
     ...plan,
@@ -3771,9 +3819,6 @@ function forceNeedsHuman(plan, reason) {
   };
 }
 function normalizeCheckpointPlan(plan) {
-  if (routeRequiresHighConfidence(plan.route, plan.session) && plan.route.confidence !== "high") {
-    return forceNeedsHuman(plan, "Lifecycle mutation requires high confidence.");
-  }
   if (plan.route.action === "noop") {
     return {
       ...plan,
@@ -3782,6 +3827,24 @@ function normalizeCheckpointPlan(plan) {
   }
   return plan;
 }
+function checkpointPlanWithRoute(plan, route, warning) {
+  return {
+    ...plan,
+    route,
+    ...route.action === "noop" ? { entries: [] } : {},
+    validationWarnings: warning ? [...plan.validationWarnings, warning] : plan.validationWarnings
+  };
+}
+function safeAutomaticRoutePlan(plan, hasCurrentContext, reason) {
+  return checkpointPlanWithRoute(plan, {
+    action: hasCurrentContext ? "current" : "noop",
+    confidence: plan.route.confidence,
+    reason
+  }, reason);
+}
+function routePlanAllowsLifecycle(plan) {
+  return checkpointRouteRequiresIntake(plan.route.action) && plan.route.confidence === "high";
+}
 function parseCheckpointPlanRecord(record, rawText, fallbackKind) {
   if (!("route" in record)) {
     const legacy = parseCheckpointRecord(record, rawText, fallbackKind);
@@ -3977,23 +4040,39 @@ function buildCheckpointTokenAccounting(event, prompt, tokenUsage) {
 function buildCheckpointPrompt(input) {
   const recentTurns = checkpointRecentTurns(input.event);
   const recentTurnsText = recentTurns.length ? formatCheckpointRecentTurns(recentTurns) : "";
+  const modeInstructions = input.mode === "closeout" ? [
+    "Mode: closeout. Produce final session memory, not an interim pulse.",
+    "Closeout should cover the completed work segment: outcome, reviewable implementation actions, decisions/corrections, verification, blockers/follow-ups, scope or attribution notes, and handoff when needed.",
+    "Write the minimum entries needed for coverage. Target 2-6 entries; avoid more than 8 by merging related facts or writing one concise session catch-up entry.",
+    "Use session.action handoff, end, or keep when appropriate. Use complete_ticket only when explicit completion evidence is present."
+  ] : [
+    "Mode: checkpoint. Produce sparse incremental memory for an active session, not a full-session closeout.",
+    "Checkpoint should commonly return route.action noop with entries [] when there is nothing durable to record.",
+    "Target 0-2 entries. Only exceed that for a blocker or failed verification. Do not repeat unchanged intent, repeated dirty workspace warnings, or routine process actions."
+  ];
   return [
-    "You are generating a compact Cadence dogfood operation plan for a hook-spawned checkpoint worker.",
+    `You are generating a compact Cadence dogfood operation plan for an agent-run ${input.mode} worker.`,
     "The model judges; the Cadence CLI validates and executes. Return JSON only. Do not call tools to mutate Cadence yourself.",
     "Preserve durable ticket purpose. Identify user intent, changed intent, corrections, decisions, rationale, implementation actions, verification, blockers, and useful notes.",
     "Do not include raw diffs, raw transcripts, terminal logs, tool streams, secrets, file contents, or model reasoning in server-bound fields.",
-    'Return this sparse JSON shape: {"summary":"short checkpoint summary","route":{"action":"current|noop|intake_create|intake_attach|switch_existing|needs_human","confidence":"low|medium|high","reason":"short reason","request":"natural language work request when intake is needed","targetTicketId":"optional existing ticket id"},"entries":[{"kind":"intent|decision|rationale|action|verification|blocker|correction|note","summary":"short entry summary","body":"safe Cadence work-log body","under":"optional: last, ticket-last, session-last, last-decision, last-correction, last-action, or entry UUID"}],"summaryUpdate":{"update":false,"value":null,"reason":"short reason"},"session":{"action":"keep|handoff|end|complete_ticket","summary":"optional handoff or completion summary","reason":"short reason"},"files":[{"path":"relative/path.ts","kind":"added|modified|deleted|renamed|unknown"}]}',
+    'Return this sparse JSON shape: {"summary":"short checkpoint summary","route":{"action":"current|noop|intake_create|intake_attach|switch_existing","confidence":"low|medium|high","reason":"short reason","request":"natural language work request when intake is needed","targetTicketId":"optional existing ticket id"},"entries":[{"kind":"intent|decision|rationale|action|verification|blocker|correction|note","summary":"short entry summary","body":"safe Cadence work-log body","under":"optional: last, ticket-last, session-last, last-decision, last-correction, last-action, or entry UUID"}],"summaryUpdate":{"update":false,"value":null,"reason":"short reason"},"session":{"action":"keep|handoff|end|complete_ticket","summary":"optional handoff or completion summary","reason":"short reason"},"files":[{"path":"relative/path.ts","kind":"added|modified|deleted|renamed|unknown"}]}',
     "Keep output sparse: omit summaryUpdate, session, and files unless needed. Use route.action noop with entries [] for filler, acknowledgements, or other turns with nothing durable to record.",
-    "Use route.action current for the same ticket. Use intake_create for clearly unrelated new work. Use intake_attach or switch_existing only when a specific existing ticket is clearly the right target. Use needs_human when routing is ambiguous.",
+    "Use route.action current for the same ticket. Use noop when routing is ambiguous or there is nothing durable to record. Use intake_create, intake_attach, or switch_existing only when recent work clearly belongs somewhere else; the CLI will delegate those actions to agent-run route.",
     "Set route.confidence high only when the recent user/assistant context makes the route and lifecycle action clear. Lifecycle mutations require high confidence.",
     "Use note only as a last-resort context kind. Prefer intent, decision, rationale, action, verification, correction, or blocker when those fit.",
     "Each entry body should be concise narrative, not a transcript. Keep each entry under 800 characters and avoid duplicating the same fact across entries.",
     "Set summaryUpdate.update true only when the durable current work summary is missing or misleading; otherwise omit summaryUpdate or leave update false.",
     "Use session.action complete_ticket only when the context indicates completion, merge, push/PR finalization, or explicit user completion intent. Use handoff/end only when the current session should close.",
+    ...modeInstructions,
     "",
     `Ticket: ${input.ticketId}`,
     input.sessionId ? `Session: ${input.sessionId}` : "",
     input.changesetId ? `ChangeSet: ${input.changesetId}` : "",
+    input.currentWorkSummary ? `Current Work Summary:
+${truncateText(input.currentWorkSummary, 1200)}` : "",
+    input.recentWorkLog ? `Recent high-signal Work Log entries:
+${truncateText(input.recentWorkLog, 3000)}` : "",
+    input.coverage ? `Prior coverage: ${JSON.stringify(input.coverage)}` : "",
     `Agent event: ${input.event.source}/${input.event.event}`,
     input.previousCheckpointSummary ? `Previous checkpoint summary: ${input.previousCheckpointSummary}` : "",
     recentTurnsText ? `Recent user/assistant turns (most recent 3, local checkpoint context only):
@@ -4008,6 +4087,297 @@ ${truncateText(input.changedFiles, 2000)}` : "Changed files: unavailable"
   ].filter(Boolean).join(`
 `);
 }
+function buildRoutePrompt(input) {
+  const recentTurns = checkpointRecentTurns(input.event);
+  const recentTurnsText = recentTurns.length ? formatCheckpointRecentTurns(recentTurns) : "";
+  const contextText = input.savedContext?.ticketId ? `Saved Cadence context: ticket ${input.savedContext.ticketId}${input.savedContext.sessionId ? `, session ${input.savedContext.sessionId}` : ""}${input.savedContext.changesetId ? `, ChangeSet ${input.savedContext.changesetId}` : ""}` : input.currentContext?.ticketId ? `No saved agent-session context. Current active Cadence context: ticket ${input.currentContext.ticketId}${input.currentContext.sessionId ? `, session ${input.currentContext.sessionId}` : ""}${input.currentContext.changesetId ? `, ChangeSet ${input.currentContext.changesetId}` : ""}` : "No saved agent-session context and no active Cadence context was found.";
+  return [
+    "You are generating a compact Cadence dogfood routing plan for an agent-run worker.",
+    "The model judges; the Cadence CLI validates and executes. Return JSON only. Do not call tools to mutate Cadence yourself.",
+    "Decide where this agent session belongs before checkpoint memory is written.",
+    "Do not include raw diffs, raw transcripts, terminal logs, tool streams, secrets, file contents, or model reasoning in server-bound fields.",
+    'Return this sparse JSON shape: {"summary":"short routing summary","route":{"action":"current|noop|intake_create|intake_attach|switch_existing","confidence":"low|medium|high","reason":"short reason","request":"natural language intake request when intake is needed","targetTicketId":"optional existing ticket id"},"entries":[{"kind":"intent|decision|rationale|action|verification|blocker|correction|note","summary":"short entry summary","body":"safe Cadence work-log body"}],"files":[{"path":"relative/path.ts","kind":"added|modified|deleted|renamed|unknown"}]}',
+    "Use noop for filler, acknowledgements, setup chatter, or anything not durable enough for Cadence.",
+    "Use current only when an existing Cadence context clearly fits the recent work.",
+    "Use intake_create for a clearly durable new task without a good existing ticket.",
+    "Use intake_attach or switch_existing only when a specific targetTicketId is clearly the correct ticket.",
+    "Set confidence high only when the route is clear. Low or medium confidence lifecycle actions will be ignored by the CLI.",
+    "Use note only as a last-resort context kind. Prefer intent for new routed work.",
+    "Each entry body should be concise narrative, not a transcript. Keep each entry under 800 characters.",
+    "",
+    `Route reason: ${input.reason ?? "manual"}`,
+    contextText,
+    `Agent event: ${input.event.source}/${input.event.event}`,
+    input.previousCheckpointSummary ? `Previous checkpoint summary: ${input.previousCheckpointSummary}` : "",
+    recentTurnsText ? `Recent user/assistant turns (most recent 3, local routing context only):
+${recentTurnsText}` : input.event.lastAssistantMessage ? `Last assistant message:
+${truncateText(input.event.lastAssistantMessage, 3000)}` : "Recent turns: unavailable",
+    input.gitStatus ? `Git status --short:
+${truncateText(input.gitStatus, 2000)}` : "Git status --short: clean or unavailable",
+    input.gitDiffStat ? `Git diff --stat origin/dev...:
+${truncateText(input.gitDiffStat, 2000)}` : "Git diff stat: unavailable",
+    input.changedFiles ? `Changed files:
+${truncateText(input.changedFiles, 2000)}` : "Changed files: unavailable"
+  ].filter(Boolean).join(`
+`);
+}
+function agentRunFingerprint(value) {
+  return stableHash(JSON.stringify(value));
+}
+function buildAgentRunFingerprints(input) {
+  return {
+    event: agentRunFingerprint({
+      source: input.event.source,
+      event: input.event.event,
+      agentSessionKey: input.event.agentSessionKey,
+      agentSessionId: input.event.agentSessionId,
+      threadId: input.event.threadId,
+      turnId: input.event.turnId,
+      lastAssistantMessage: input.event.lastAssistantMessage,
+      recentTurns: input.event.recentTurns,
+      payloadKeys: input.event.payloadKeys
+    }),
+    git: agentRunFingerprint({
+      status: input.gitStatus,
+      diffStat: input.gitDiffStat,
+      changedFiles: input.changedFiles
+    }),
+    cadenceContext: agentRunFingerprint({
+      ticketId: input.ticketId,
+      sessionId: input.sessionId,
+      changesetId: input.changesetId
+    }),
+    ...input.coverage?.hasDebt ? { coverageDebt: agentRunFingerprint(input.coverage) } : {}
+  };
+}
+function fingerprintsEqual(left, right) {
+  return Boolean(left && left.event === right.event && left.git === right.git && left.cadenceContext === right.cadenceContext && left.verification === right.verification && left.coverageDebt === right.coverageDebt);
+}
+function checkpointReasonBypassesFingerprintGate(reason) {
+  return reason === "manual" || reason === "idle" || reason === "ticket_switch" || reason === "closeout";
+}
+function entryText(entry) {
+  return `${entry.summary ?? ""}
+${entry.body}`.toLowerCase();
+}
+function entryReductionSummary(entry) {
+  return truncateText(entry.summary ?? checkpointEntrySummary(entry.body), 120);
+}
+function isRepeatedScopeNote(entry) {
+  const text = entryText(entry);
+  return entry.kind === "note" && (text.includes("dirty workspace") || text.includes("dirty files") || text.includes("unattributed"));
+}
+function isRepeatedNoVerificationNote(entry) {
+  const text = entryText(entry);
+  return entry.kind === "verification" && text.includes("no fresh") && (text.includes("test") || text.includes("verification"));
+}
+function isUnchangedIntent(entry) {
+  const text = entryText(entry);
+  return entry.kind === "intent" && (text.includes("remain") || text.includes("still")) && text.includes("active");
+}
+function isProcessOnlyAction(entry) {
+  if (entry.kind !== "action") {
+    return false;
+  }
+  const text = entryText(entry);
+  const processSignals = ["read ", "inspected", "looked at", "ran git status", "gathered context", "paused", "discussed", "answered"];
+  const reviewableSignals = [
+    "added",
+    "implemented",
+    "updated",
+    "changed",
+    "removed",
+    "refactored",
+    "fixed",
+    "moved",
+    "persisted",
+    "configured",
+    "wrote",
+    "split"
+  ];
+  return processSignals.some((signal) => text.includes(signal)) && !reviewableSignals.some((signal) => text.includes(signal));
+}
+function entryDedupeKey(entry) {
+  if (isRepeatedScopeNote(entry)) {
+    return "scope-note";
+  }
+  if (isRepeatedNoVerificationNote(entry)) {
+    return "no-verification";
+  }
+  if (isUnchangedIntent(entry)) {
+    return "unchanged-intent";
+  }
+  return `${entry.kind}:${entry.summary ?? checkpointEntrySummary(entry.body)}`.toLowerCase();
+}
+function mergeDecisionRationaleEntries(entries) {
+  const merged = [];
+  const records = [];
+  for (let index = 0;index < entries.length; index += 1) {
+    const entry = entries[index];
+    const next = entries[index + 1];
+    if (entry.kind === "decision" && next?.kind === "rationale") {
+      merged.push({
+        ...entry,
+        body: truncateText(`${entry.body}
+
+Rationale: ${next.body.replace(/^Rationale:\s*/i, "")}`, checkpointServerTextLimit)
+      });
+      records.push({
+        summary: entryReductionSummary(next),
+        reason: "merged_adjacent_decision_rationale"
+      });
+      index += 1;
+      continue;
+    }
+    merged.push(entry);
+  }
+  return { entries: merged, records };
+}
+function checkpointAllowsExtraEntries(entries) {
+  return entries.some((entry) => entry.kind === "blocker" || entry.kind === "verification" && /\b(fail|failed|failing|error|blocked)\b/i.test(entry.body));
+}
+function reduceCheckpointEntries(entries, mode) {
+  const dropped = [];
+  const seen = new Set;
+  const filtered = [];
+  for (const entry of entries) {
+    if (isProcessOnlyAction(entry)) {
+      dropped.push({ summary: entryReductionSummary(entry), reason: "process_only_action" });
+      continue;
+    }
+    const dedupeKey = entryDedupeKey(entry);
+    if (seen.has(dedupeKey)) {
+      dropped.push({ summary: entryReductionSummary(entry), reason: "duplicate_entry" });
+      continue;
+    }
+    seen.add(dedupeKey);
+    filtered.push(entry);
+  }
+  const merged = mergeDecisionRationaleEntries(filtered);
+  const maxEntries = mode === "closeout" ? 8 : checkpointAllowsExtraEntries(merged.entries) ? 4 : 3;
+  const capped = merged.entries.length > maxEntries;
+  const kept = capped ? merged.entries.slice(0, maxEntries) : merged.entries;
+  for (const entry of merged.entries.slice(maxEntries)) {
+    dropped.push({ summary: entryReductionSummary(entry), reason: "entry_budget" });
+  }
+  return {
+    entries: kept,
+    reduction: {
+      mode,
+      originalCount: entries.length,
+      keptCount: kept.length,
+      dropped,
+      merged: merged.records,
+      capped
+    }
+  };
+}
+function buildAgentRunCoverage(plan, mode) {
+  const entries = plan.entries;
+  const bodyText = [plan.summary ?? "", plan.session?.summary ?? "", ...entries.map((entry) => `${entry.summary ?? ""} ${entry.body}`)].join(`
+`).toLowerCase();
+  const outcome = Boolean(plan.summary || plan.session?.summary);
+  const implementation = entries.some((entry) => entry.kind === "action");
+  const decisions = entries.some((entry) => entry.kind === "decision" || entry.kind === "rationale");
+  const corrections = entries.some((entry) => entry.kind === "correction");
+  const verification = entries.some((entry) => entry.kind === "verification");
+  const blockers = entries.some((entry) => entry.kind === "blocker");
+  const scope = /\b(scope|attribut|dirty workspace|dirty files|unassigned|unattributed)\b/.test(bodyText);
+  const handoff = mode === "closeout" && Boolean(plan.session && plan.session.action !== "keep");
+  const hasDebt = mode === "closeout" && (!outcome || !implementation || !verification || !handoff);
+  return {
+    outcome,
+    implementation,
+    decisions,
+    corrections,
+    verification,
+    blockers,
+    scope,
+    handoff,
+    hasDebt
+  };
+}
+function applyCloseoutSessionDefaults(plan, sessionAction, completeTicket) {
+  const requestedAction = completeTicket ? "complete_ticket" : sessionAction;
+  const session = plan.session && (completeTicket || plan.session.action !== "complete_ticket") ? plan.session : {
+    action: requestedAction,
+    ...plan.summary ? { summary: plan.summary } : {},
+    reason: "Closeout defaults to ending or handing off the active session."
+  };
+  if (!completeTicket && session.action === "complete_ticket") {
+    return {
+      ...plan,
+      session: {
+        ...session,
+        action: sessionAction,
+        reason: "Ticket completion was not requested for this closeout."
+      }
+    };
+  }
+  return {
+    ...plan,
+    session
+  };
+}
+function parseCloseoutSessionAction(value) {
+  if (!value) {
+    return "handoff";
+  }
+  if (!closeoutSessionActions.includes(value)) {
+    throw new CliError("CLI_USAGE", "--session-action must be one of handoff, end, or keep.");
+  }
+  return value;
+}
+function checkpointModeForCommand(parsed) {
+  return parsed.command.name === "agent-run.closeout" ? "closeout" : "checkpoint";
+}
+function formatCloseoutWorkLogEvents(events) {
+  if (!Array.isArray(events)) {
+    return;
+  }
+  const entries = events.filter((event) => event && typeof event === "object").map((event) => {
+    const record = event;
+    const payload = record.payload && typeof record.payload === "object" && !Array.isArray(record.payload) ? record.payload : {};
+    const type = typeof record.type === "string" ? record.type : undefined;
+    const kind = typeof payload.entryKind === "string" ? payload.entryKind : undefined;
+    const summary = typeof payload.summary === "string" ? payload.summary : undefined;
+    const body = typeof payload.body === "string" ? payload.body : undefined;
+    if (type !== "ticket.work_log_appended" || !summary && !body) {
+      return;
+    }
+    return `- ${kind ?? "note"}: ${truncateText(summary ?? body ?? "", 180)}${body && summary ? ` \u2014 ${truncateText(body, 300)}` : ""}`;
+  }).filter((entry) => Boolean(entry)).slice(-12);
+  return entries.length ? entries.join(`
+`) : undefined;
+}
+async function readCloseoutPromptContext(input) {
+  let currentWorkSummary;
+  let recentWorkLog;
+  try {
+    const ticket = await input.client.tickets.get({
+      projectId: input.projectId,
+      ticketId: input.ticketId
+    });
+    if (ticket && typeof ticket === "object" && "currentSummary" in ticket && typeof ticket.currentSummary === "string") {
+      currentWorkSummary = ticket.currentSummary;
+    }
+  } catch {}
+  try {
+    const events = await input.client.events.list({
+      projectId: input.projectId,
+      filters: {
+        ticketId: input.ticketId,
+        ...input.sessionId ? { sessionId: input.sessionId } : {},
+        limit: 50
+      }
+    });
+    recentWorkLog = formatCloseoutWorkLogEvents(events);
+  } catch {}
+  return {
+    ...currentWorkSummary ? { currentWorkSummary } : {},
+    ...recentWorkLog ? { recentWorkLog } : {}
+  };
+}
 async function findRepoRoot(cwd) {
   const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
     cwd,
@@ -4246,6 +4616,8 @@ async function runAgentRunCommand(parsed, options) {
   switch (parsed.command.name) {
     case "agent-run.ingest-stop":
       return await runAgentRunIngestStop(parsed, options, config, meta);
+    case "agent-run.route":
+      return await runAgentRunRoute(parsed, options, config, meta);
     case "agent-run.checkpoint":
     case "agent-run.closeout":
       return await runAgentRunCheckpoint(parsed, options, config, meta);
@@ -4335,11 +4707,14 @@ async function runAgentRunIngestStop(parsed, options, config, meta) {
   const duplicateTurn = Boolean(normalized.turnId && existingSession?.lastObservedTurnId === normalized.turnId);
   const nextCount = (existingSession?.stopCount ?? 0) + (duplicateTurn ? 0 : 1);
   const recentTurns = mergeRecentAgentTurns(existingSession?.recentTurns, normalized.recentTurns);
-  let cadenceContext = existingSession?.cadenceContext;
-  try {
-    const client = await createClient(config, options);
-    cadenceContext = await readCurrentCadenceContext(client, projectId) ?? cadenceContext;
-  } catch {}
+  const savedCadenceContext = existingSession?.cadenceContext;
+  let cadenceContext = savedCadenceContext;
+  if (savedCadenceContext?.ticketId) {
+    try {
+      const client = await createClient(config, options);
+      cadenceContext = await readCurrentCadenceContext(client, projectId) ?? cadenceContext;
+    } catch {}
+  }
   const observedSession = {
     ...clearAgentSessionReason(existingSession ?? {
       source: normalized.source,
@@ -4364,6 +4739,124 @@ async function runAgentRunIngestStop(parsed, options, config, meta) {
       [normalized.agentSessionKey]: observedSession
     }
   };
+  if (duplicateTurn) {
+    await writeAgentLoopState(parsed, options, countedState);
+    const data2 = {
+      action: "updated",
+      reason: "duplicate_turn",
+      agentSessionKey: normalized.agentSessionKey,
+      stopCount: nextCount,
+      threshold
+    };
+    return {
+      stdout: parsed.flags.json ? formatJson(successEnvelope(data2, meta)) : `${JSON.stringify(data2, null, 2)}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  if (!savedCadenceContext?.ticketId) {
+    const eventFile2 = await writeAgentEventFile(parsed, options, normalized);
+    const lockPath2 = agentLoopLockPath(parsed, options, normalized.agentSessionKey);
+    const workerArgs2 = [
+      "agent-run",
+      "route",
+      "--agent-session-key",
+      normalized.agentSessionKey,
+      "--reason",
+      "missing_context",
+      "--event-file",
+      eventFile2,
+      "--lock",
+      lockPath2,
+      ...parsed.flags.project ? ["--project", parsed.flags.project] : [],
+      ...parsed.flags.server ? ["--server", parsed.flags.server] : []
+    ];
+    if (dryRun) {
+      await writeAgentLoopState(parsed, options, {
+        ...state,
+        sessions: {
+          ...state.sessions,
+          [normalized.agentSessionKey]: {
+            ...observedSession,
+            lastAction: "would_route",
+            lastEventFile: eventFile2
+          }
+        }
+      });
+      const data3 = {
+        action: "would_route",
+        agentSessionKey: normalized.agentSessionKey,
+        eventFile: eventFile2,
+        workerArgs: workerArgs2
+      };
+      return {
+        stdout: parsed.flags.json ? formatJson(successEnvelope(data3, meta)) : `${JSON.stringify(data3, null, 2)}
+`,
+        stderr: "",
+        exitCode: 0
+      };
+    }
+    const lock2 = await acquireAgentLoopLock(parsed, options, normalized.agentSessionKey);
+    if (!lock2.acquired) {
+      await writeAgentLoopState(parsed, options, {
+        ...state,
+        sessions: {
+          ...state.sessions,
+          [normalized.agentSessionKey]: {
+            ...observedSession,
+            lastAction: "skipped",
+            lastReason: "lock_held"
+          }
+        }
+      });
+      const data3 = {
+        action: "skipped",
+        reason: "lock_held",
+        lockPath: lock2.lockPath,
+        agentSessionKey: normalized.agentSessionKey
+      };
+      return {
+        stdout: parsed.flags.json ? formatJson(successEnvelope(data3, meta)) : `${JSON.stringify(data3, null, 2)}
+`,
+        stderr: "",
+        exitCode: 0
+      };
+    }
+    try {
+      await spawnAgentRunWorker(workerArgs2, options);
+    } catch (error) {
+      await releaseAgentLoopLock(lock2.lockPath);
+      throw error;
+    }
+    await writeAgentLoopState(parsed, options, {
+      ...state,
+      sessions: {
+        ...state.sessions,
+        [normalized.agentSessionKey]: {
+          ...observedSession,
+          stopCount: 0,
+          threshold: defaultCheckpointThresholdValue(),
+          lastAction: "route_spawned",
+          lastEventFile: eventFile2,
+          lastCheckpointAt: new Date().toISOString(),
+          lastCheckpointFingerprint: fingerprintForCheckpoint(normalized, options)
+        }
+      }
+    });
+    const data2 = {
+      action: "route_spawned",
+      agentSessionKey: normalized.agentSessionKey,
+      eventFile: eventFile2,
+      lockPath: lock2.lockPath
+    };
+    return {
+      stdout: parsed.flags.json ? formatJson(successEnvelope(data2, meta)) : `${JSON.stringify(data2, null, 2)}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
   if (nextCount < threshold) {
     await writeAgentLoopState(parsed, options, countedState);
     const data2 = {
@@ -4537,7 +5030,10 @@ async function runAgentRunIngestStop(parsed, options, config, meta) {
     exitCode: 0
   };
 }
-async function runAgentRunCheckpoint(parsed, options, config, meta) {
+function objectStringId(value) {
+  return value && typeof value === "object" && "id" in value && typeof value.id === "string" ? value.id : undefined;
+}
+async function runAgentRunRoute(parsed, options, config, meta) {
   const projectId = requireProjectId(config);
   const client = await createClient(config, options);
   const agentSessionKeyValue = requireOption(parsed, "agent-session-key");
@@ -4549,66 +5045,36 @@ async function runAgentRunCheckpoint(parsed, options, config, meta) {
     });
   }
   const savedContext = sessionState.cadenceContext;
-  const currentContext = parsed.options.ticket || savedContext?.ticketId ? undefined : await readCurrentCadenceContext(client, projectId);
-  const ticketId = parsed.options.ticket ?? savedContext?.ticketId ?? currentContext?.ticketId;
-  const sessionId = parsed.options.session ?? savedContext?.sessionId ?? currentContext?.sessionId;
-  const changesetId = parsed.options.changeset ?? savedContext?.changesetId ?? currentContext?.changesetId;
-  if (!ticketId) {
-    await writeAgentLoopState(parsed, options, {
-      ...state,
-      sessions: {
-        ...state.sessions,
-        [agentSessionKeyValue]: {
-          ...sessionState,
-          lastAction: "skipped",
-          lastReason: "no_active_ticket"
-        }
-      }
-    });
-    const data = {
-      action: "skipped",
-      reason: "no_active_ticket",
-      agentSessionKey: agentSessionKeyValue
-    };
-    return {
-      stdout: parsed.flags.json ? formatJson(successEnvelope(data, meta)) : `${JSON.stringify(data, null, 2)}
-`,
-      stderr: "",
-      exitCode: 0
-    };
-  }
+  const currentContext = savedContext?.ticketId ? undefined : await readCurrentCadenceContext(client, projectId);
   const eventFile = parsed.options["event-file"] ?? sessionState.lastEventFile;
   const event = eventFile ? tryParseJsonObject(await readFile(eventFile, "utf8"), eventFile) : synthesizeAgentEventFromSession(agentSessionKeyValue, sessionState, options);
-  const logKind = parseWorkLogEntryKind(parsed.options["log-kind"] ?? "note");
-  const updateSummary = parseBooleanOption(parsed.options["update-summary"], false);
-  const dryRun = parseBooleanOption(parsed.options["dry-run"], false);
-  const lockPath = parsed.options.lock;
   const checkpointSettings = await resolveCheckpointSettings(parsed, options);
   const gitStatus = gitOutput(["status", "--short"], options);
   const gitDiffStat = gitOutput(["diff", "--stat", "origin/dev..."], options);
   const changedFiles = gitOutput(["diff", "--name-only", "origin/dev..."], options);
-  const prompt = buildCheckpointPrompt({
+  const prompt = buildRoutePrompt({
     event,
-    ticketId,
-    ...sessionId ? { sessionId } : {},
-    ...changesetId ? { changesetId } : {},
+    ...parsed.options.reason ? { reason: parsed.options.reason } : {},
+    ...savedContext ? { savedContext } : {},
+    ...currentContext ? { currentContext } : {},
     gitStatus,
     gitDiffStat,
     changedFiles,
     ...sessionState.previousCheckpointSummary ? { previousCheckpointSummary: sessionState.previousCheckpointSummary } : {}
   });
   const promptTokenAccounting = buildCheckpointTokenAccounting(event, prompt, undefined);
+  const dryRun = parseBooleanOption(parsed.options["dry-run"], false);
+  const lockPath = parsed.options.lock;
   if (dryRun) {
     const auditFile = await writeAgentCheckpointAuditFile(parsed, options, {
       version: 1,
-      action: "would_checkpoint",
+      mode: "route",
+      action: "would_route",
       createdAt: new Date().toISOString(),
       localOnly: true,
-      localOnlyReason: "Raw hook context and checkpoint prompts stay on this machine and are not uploaded to Cadence.",
+      localOnlyReason: "Raw hook context and route prompts stay on this machine and are not uploaded to Cadence.",
       agentSessionKey: agentSessionKeyValue,
-      ticketId,
-      ...sessionId ? { sessionId } : {},
-      ...changesetId ? { changesetId } : {},
+      ...savedContext?.ticketId ? { ticketId: savedContext.ticketId } : currentContext?.ticketId ? { ticketId: currentContext.ticketId } : {},
       ...eventFile ? { eventFile } : {},
       event,
       prompt,
@@ -4617,13 +5083,10 @@ async function runAgentRunCheckpoint(parsed, options, config, meta) {
       cadenceWrites: []
     });
     const data = {
-      action: "would_checkpoint",
+      action: "would_route",
       prompt,
       auditFile,
-      ticketId,
-      agentSessionKey: agentSessionKeyValue,
-      ...sessionId ? { sessionId } : {},
-      ...changesetId ? { changesetId } : {}
+      agentSessionKey: agentSessionKeyValue
     };
     return {
       stdout: parsed.flags.json ? formatJson(successEnvelope(data, meta)) : `${JSON.stringify(data, null, 2)}
@@ -4658,21 +5121,37 @@ async function runAgentRunCheckpoint(parsed, options, config, meta) {
     const codexSessionTranscript = readCodexSessionTranscript(findCodexSessionFileCreatedAfter(options, codexStartedAtMs, codexCwd));
     const tokenAccounting = buildCheckpointTokenAccounting(event, prompt, codexSessionTranscript?.tokenUsage);
     if (codex.status !== 0 || codex.error) {
-      throw new CliError("AGENT_RUN_CHECKPOINT_FAILED", "Codex checkpoint generation failed.", {
+      throw new CliError("AGENT_RUN_ROUTE_FAILED", "Codex route generation failed.", {
         status: codex.status,
         stderr: truncateText(codex.stderr, 2000),
         error: codex.error?.message
       });
     }
-    let checkpoint = parseCheckpointPlanJson(codex.stdout, logKind);
-    let summary = checkpoint.summary ?? checkpoint.entries[0]?.summary ?? checkpoint.route.reason ?? "Agent run checkpoint";
-    let targetTicketId = ticketId;
-    let targetSessionId = sessionId;
-    let targetChangesetId = changesetId;
+    let routePlan = parseCheckpointPlanJson(codex.stdout, "intent");
+    const currentTicketId = savedContext?.ticketId ?? currentContext?.ticketId;
+    const currentSessionId = savedContext?.sessionId ?? currentContext?.sessionId;
+    const currentChangesetId = savedContext?.changesetId ?? currentContext?.changesetId;
+    if (routePlan.route.action === "needs_human") {
+      routePlan = safeAutomaticRoutePlan(routePlan, Boolean(currentTicketId), routePlan.route.reason ?? "Route was uncertain.");
+    } else if (checkpointRouteRequiresIntake(routePlan.route.action) && routePlan.route.confidence !== "high") {
+      routePlan = safeAutomaticRoutePlan(routePlan, Boolean(currentTicketId), "Automatic routing requires high confidence.");
+    } else if ((routePlan.route.action === "intake_attach" || routePlan.route.action === "switch_existing") && !routePlan.route.targetTicketId) {
+      routePlan = safeAutomaticRoutePlan(routePlan, Boolean(currentTicketId), "Automatic routing to existing work requires a target ticket id.");
+    } else if (routePlan.route.action === "current" && !currentTicketId) {
+      routePlan = checkpointPlanWithRoute(routePlan, {
+        action: "noop",
+        confidence: routePlan.route.confidence,
+        reason: routePlan.route.reason ?? "No current Cadence context exists."
+      });
+    }
     const cadenceWrites = [];
     const lifecycleOperations = [];
+    let targetTicketId = currentTicketId;
+    let targetSessionId = currentSessionId;
+    let targetChangesetId = currentChangesetId;
     let intakeResult;
     let selectedTicket;
+    let summary = routePlan.summary ?? routePlan.entries[0]?.summary ?? routePlan.route.reason ?? "Agent run route";
     const modelAudit = {
       provider: checkpointSettings.provider,
       command: codexCommand,
@@ -4684,68 +5163,72 @@ async function runAgentRunCheckpoint(parsed, options, config, meta) {
       ...codexSessionTranscript?.tokenUsage ? { tokenUsage: codexSessionTranscript.tokenUsage } : {},
       ...codexSessionTranscript ? { sessionTranscript: codexSessionTranscript } : {}
     };
-    const finishCheckpoint = async (action, reason) => {
+    const finishRoute = async (action, reason) => {
       const checkedAt = new Date().toISOString();
       const auditFile = await writeAgentCheckpointAuditFile(parsed, options, {
         version: 1,
+        mode: "route",
         action,
         createdAt: checkedAt,
         localOnly: true,
-        localOnlyReason: action === "noop" || action === "needs_human" ? "Raw hook context, checkpoint prompts, and model output stay on this machine; no Cadence writes were needed." : "Raw hook context, checkpoint prompts, and model output stay on this machine; Cadence receives only the structured writes listed here.",
+        localOnlyReason: action === "noop" || action === "current" ? "Raw hook context, route prompts, and model output stay on this machine; no Cadence writes were needed." : "Raw hook context, route prompts, and model output stay on this machine; Cadence receives only the structured writes listed here.",
         agentSessionKey: agentSessionKeyValue,
-        ticketId: targetTicketId,
+        ...targetTicketId ? { ticketId: targetTicketId } : {},
         ...targetSessionId ? { sessionId: targetSessionId } : {},
         ...targetChangesetId ? { changesetId: targetChangesetId } : {},
         ...eventFile ? { eventFile } : {},
         event,
         prompt,
         model: modelAudit,
-        checkpoint,
-        route: checkpoint.route,
-        ...intakeResult ? { intakeResult } : {},
-        ...selectedTicket ? { selectedTicket } : {},
+        checkpoint: routePlan,
+        route: routePlan.route,
+        intakeResult,
+        selectedTicket,
         lifecycleOperations,
         cadenceWrites,
         summary,
         ...reason ? { reason } : {},
-        entryCount: checkpoint.entries.length,
-        needsHuman: action === "needs_human"
+        entryCount: routePlan.entries.length
       });
+      const nextSessionState = {
+        ...sessionState,
+        stopCount: 0,
+        threshold: defaultCheckpointThresholdValue(),
+        previousCheckpointSummary: summary,
+        lastAction: action,
+        ...reason ? { lastReason: reason } : {},
+        ...eventFile ? { lastEventFile: eventFile } : {},
+        ...targetTicketId ? {
+          cadenceContext: {
+            ticketId: targetTicketId,
+            ...targetSessionId ? { sessionId: targetSessionId } : {},
+            ...targetChangesetId ? { changesetId: targetChangesetId } : {},
+            capturedAt: checkedAt
+          }
+        } : {},
+        lastCheckpointAt: checkedAt,
+        lastCheckpointMode: "checkpoint",
+        lastCheckpointAuditFile: auditFile
+      };
       await writeAgentLoopState(parsed, options, {
         ...state,
         sessions: {
           ...state.sessions,
-          [agentSessionKeyValue]: {
-            ...sessionState,
-            stopCount: 0,
-            threshold: defaultCheckpointThresholdValue(),
-            previousCheckpointSummary: summary,
-            lastAction: action,
-            ...reason ? { lastReason: reason } : {},
-            ...eventFile ? { lastEventFile: eventFile } : {},
-            cadenceContext: {
-              ticketId: targetTicketId,
-              ...targetSessionId ? { sessionId: targetSessionId } : {},
-              ...targetChangesetId ? { changesetId: targetChangesetId } : {},
-              capturedAt: checkedAt
-            },
-            lastCheckpointAt: checkedAt,
-            lastCheckpointAuditFile: auditFile
-          }
+          [agentSessionKeyValue]: nextSessionState
         }
       });
       const data = {
         action,
-        route: checkpoint.route,
+        route: routePlan.route,
         ...reason ? { reason } : {},
-        ticketId: targetTicketId,
+        ...targetTicketId ? { ticketId: targetTicketId } : {},
         summary,
-        entryCount: checkpoint.entries.length,
+        entryCount: routePlan.entries.length,
+        mode: "route",
         auditFile,
         agentSessionKey: agentSessionKeyValue,
         ...targetSessionId ? { sessionId: targetSessionId } : {},
-        ...targetChangesetId ? { changesetId: targetChangesetId } : {},
-        ...action === "needs_human" ? { needsHuman: true } : {}
+        ...targetChangesetId ? { changesetId: targetChangesetId } : {}
       };
       return {
         stdout: parsed.flags.json ? formatJson(successEnvelope(data, meta)) : `${JSON.stringify(data, null, 2)}
@@ -4754,17 +5237,14 @@ async function runAgentRunCheckpoint(parsed, options, config, meta) {
         exitCode: 0
       };
     };
-    if (checkpoint.session?.action === "complete_ticket" && !checkpointPlanCompletionAllowed(event, summary)) {
-      checkpoint = checkpointPlanNeedsHuman(checkpoint, "Completion requires explicit recent completion, push, PR, merge, clean branch, or verification intent.");
+    if (routePlan.route.action === "noop") {
+      return await finishRoute("noop", routePlan.route.reason ?? routePlan.summary ?? "Nothing durable to route.");
     }
-    if (checkpoint.route.action === "noop") {
-      return await finishCheckpoint("noop", checkpoint.route.reason ?? checkpoint.summary ?? "Nothing durable to record.");
+    if (routePlan.route.action === "current") {
+      return await finishRoute("current", routePlan.route.reason ?? "Kept current Cadence context.");
     }
-    if (checkpoint.route.action === "needs_human") {
-      return await finishCheckpoint("needs_human", checkpoint.route.reason ?? "Checkpoint routing needs human review.");
-    }
-    if (checkpointRouteRequiresIntake(checkpoint.route.action)) {
-      const intakeRequest = checkpoint.route.request ?? checkpointPlanDescription(checkpoint);
+    if (routePlanAllowsLifecycle(routePlan)) {
+      const intakeRequest = routePlan.route.request ?? checkpointPlanDescription(routePlan);
       intakeResult = await client.intake.create({
         projectId,
         intake: {
@@ -4773,34 +5253,33 @@ async function runAgentRunCheckpoint(parsed, options, config, meta) {
         }
       });
       lifecycleOperations.push(checkpointLifecycleOperation("intake.created", true, { request: intakeRequest, result: intakeResult }));
-      if (checkpointHasConflictingIntakeResult(intakeResult, checkpoint)) {
-        checkpoint = checkpointPlanNeedsHuman(checkpoint, "Intake returned conflicting duplicate, overlap, or completed-before candidates.");
-        return await finishCheckpoint("needs_human", checkpoint.route.reason);
+      if (checkpointHasConflictingIntakeResult(intakeResult, routePlan)) {
+        routePlan = safeAutomaticRoutePlan(routePlan, Boolean(currentTicketId), "Intake returned conflicting duplicate, overlap, or completed-before candidates.");
+        return await finishRoute(routePlan.route.action, routePlan.route.reason);
       }
-      if (checkpoint.route.action === "intake_create") {
+      if (routePlan.route.action === "intake_create") {
         selectedTicket = await client.tickets.create({
           projectId,
           ticket: {
-            title: checkpointPlanTitle(checkpoint),
-            description: checkpointPlanDescription(checkpoint),
-            fromIntakeId: typeof intakeResult === "object" && intakeResult && "id" in intakeResult ? String(intakeResult.id) : undefined,
+            title: checkpointPlanTitle(routePlan),
+            description: checkpointPlanDescription(routePlan),
+            fromIntakeId: objectStringId(intakeResult),
             ...commandMetadata()
           }
         });
         lifecycleOperations.push(checkpointLifecycleOperation("ticket.created", true, { ticket: selectedTicket }));
-        if (selectedTicket && typeof selectedTicket === "object" && "id" in selectedTicket) {
-          targetTicketId = String(selectedTicket.id);
-        }
+        targetTicketId = objectStringId(selectedTicket);
       } else {
-        if (!checkpoint.route.targetTicketId) {
-          checkpoint = checkpointPlanNeedsHuman(checkpoint, "Checkpoint route requires a target ticket id.");
-          return await finishCheckpoint("needs_human", checkpoint.route.reason);
+        const selectedTicketId = routePlan.route.targetTicketId;
+        if (!selectedTicketId) {
+          routePlan = safeAutomaticRoutePlan(routePlan, Boolean(currentTicketId), "Automatic routing to existing work requires a target ticket id.");
+          return await finishRoute(routePlan.route.action, routePlan.route.reason);
         }
-        targetTicketId = checkpoint.route.targetTicketId;
+        targetTicketId = selectedTicketId;
         selectedTicket = await client.tickets.get({ projectId, ticketId: targetTicketId });
         lifecycleOperations.push(checkpointLifecycleOperation("ticket.selected", true, { ticketId: targetTicketId, ticket: selectedTicket }));
         const selectedVersion = selectedTicket && typeof selectedTicket === "object" && typeof selectedTicket.projectionVersion === "number" ? selectedTicket.projectionVersion : undefined;
-        const intakeId = intakeResult && typeof intakeResult === "object" && "id" in intakeResult ? String(intakeResult.id) : undefined;
+        const intakeId = objectStringId(intakeResult);
         if (selectedVersion !== undefined && intakeId) {
           await client.tickets.attach({
             projectId,
@@ -4811,16 +5290,24 @@ async function runAgentRunCheckpoint(parsed, options, config, meta) {
           lifecycleOperations.push(checkpointLifecycleOperation("intake.attached", true, { ticketId: targetTicketId, intakeId }));
         }
       }
-      if (targetTicketId !== ticketId && targetSessionId) {
+      if (!targetTicketId) {
+        routePlan = checkpointPlanWithRoute(routePlan, {
+          action: currentTicketId ? "current" : "noop",
+          confidence: routePlan.route.confidence,
+          reason: "Automatic routing did not return a target ticket."
+        });
+        return await finishRoute(routePlan.route.action, routePlan.route.reason);
+      }
+      if (currentSessionId && currentTicketId && targetTicketId !== currentTicketId) {
         await client.sessions.end({
           projectId,
-          sessionId: targetSessionId,
+          sessionId: currentSessionId,
           session: {
-            summary: checkpoint.session?.summary ?? checkpoint.route.reason ?? summary,
+            summary: routePlan.route.reason ?? summary,
             ...commandMetadata()
           }
         });
-        lifecycleOperations.push(checkpointLifecycleOperation("session.ended", true, { sessionId: targetSessionId, reason: "ticket_switch" }));
+        lifecycleOperations.push(checkpointLifecycleOperation("session.ended", true, { sessionId: currentSessionId, reason: "ticket_switch" }));
         targetSessionId = undefined;
         targetChangesetId = undefined;
       }
@@ -4832,9 +5319,7 @@ async function runAgentRunCheckpoint(parsed, options, config, meta) {
         }
       });
       lifecycleOperations.push(checkpointLifecycleOperation("session.started", true, { ticketId: targetTicketId, session: startedSession }));
-      if (startedSession && typeof startedSession === "object" && "id" in startedSession) {
-        targetSessionId = String(startedSession.id);
-      }
+      targetSessionId = objectStringId(startedSession);
       if (targetSessionId) {
         const lease = await client.sessions.leases.create({
           projectId,
@@ -4842,7 +5327,6 @@ async function runAgentRunCheckpoint(parsed, options, config, meta) {
             ticketId: targetTicketId,
             sessionId: targetSessionId,
             expiresAt: leaseExpiresAt(defaultLeaseTtlSeconds),
-            replaceOwnActiveLease: true,
             ...commandMetadata()
           }
         });
@@ -4862,15 +5346,420 @@ async function runAgentRunCheckpoint(parsed, options, config, meta) {
             }
           });
           lifecycleOperations.push(checkpointLifecycleOperation("changeset.linked", true, { ticketId: targetTicketId, branchName, changeset }));
-          if (changeset && typeof changeset === "object" && "id" in changeset) {
-            targetChangesetId = String(changeset.id);
-          }
+          targetChangesetId = objectStringId(changeset);
         } catch (error) {
           lifecycleOperations.push(checkpointLifecycleOperation("changeset.linked", false, { error: error instanceof Error ? error.message : String(error) }));
         }
       }
+      const routeMetadata = checkpointWorkLogMetadata(checkpointSettings, "route", tokenAccounting);
+      for (const entry of routePlan.entries) {
+        const logEntry = {
+          entryKind: entry.kind,
+          body: entry.body,
+          summary: entry.summary ?? checkpointEntrySummary(entry.body),
+          ...targetSessionId ? { sessionId: targetSessionId } : {},
+          ...targetChangesetId ? { changesetId: targetChangesetId } : {},
+          metadata: routeMetadata,
+          ...commandMetadata()
+        };
+        await client.tickets.log({
+          projectId,
+          ticketId: targetTicketId,
+          entry: logEntry
+        });
+        cadenceWrites.push({
+          type: "ticket.work_log_appended",
+          success: true,
+          ticketId: targetTicketId,
+          entry: logEntry
+        });
+      }
+      if (routePlan.files.length && targetSessionId) {
+        const filesByKind = new Map;
+        for (const file of routePlan.files) {
+          filesByKind.set(file.kind, [...filesByKind.get(file.kind) ?? [], file.path]);
+        }
+        for (const [kind, paths] of filesByKind) {
+          const filesPayload = {
+            ...targetChangesetId ? { changesetId: targetChangesetId } : {},
+            files: paths.map((path) => ({
+              path,
+              changeKind: kind
+            })),
+            ...commandMetadata()
+          };
+          await client.sessions.files({
+            projectId,
+            sessionId: targetSessionId,
+            files: filesPayload
+          });
+          lifecycleOperations.push(checkpointLifecycleOperation("session.files_attached", true, { sessionId: targetSessionId, kind, files: paths }));
+        }
+      }
+      summary = routePlan.summary ?? routePlan.entries[0]?.summary ?? routePlan.route.reason ?? "Agent run routed";
+      return await finishRoute(routePlan.route.action === "intake_create" ? "routed" : "switched");
+    }
+    routePlan = safeAutomaticRoutePlan(routePlan, Boolean(currentTicketId), "Route did not request an executable automatic action.");
+    return await finishRoute(routePlan.route.action, routePlan.route.reason);
+  } finally {
+    await releaseAgentLoopLock(lockPath);
+  }
+}
+async function runAgentRunCheckpoint(parsed, options, config, meta) {
+  const projectId = requireProjectId(config);
+  const client = await createClient(config, options);
+  const agentSessionKeyValue = requireOption(parsed, "agent-session-key");
+  const state = await readAgentLoopState(parsed, options);
+  const sessionState = state.sessions[agentSessionKeyValue];
+  if (!sessionState) {
+    throw new CliError("AGENT_RUN_SESSION_NOT_FOUND", "No local agent-run session state exists for --agent-session-key.", {
+      agentSessionKey: agentSessionKeyValue
+    });
+  }
+  const savedContext = sessionState.cadenceContext;
+  const currentContext = parsed.options.ticket || savedContext?.ticketId ? undefined : await readCurrentCadenceContext(client, projectId);
+  const ticketId = parsed.options.ticket ?? savedContext?.ticketId ?? currentContext?.ticketId;
+  const sessionId = parsed.options.session ?? savedContext?.sessionId ?? currentContext?.sessionId;
+  const changesetId = parsed.options.changeset ?? savedContext?.changesetId ?? currentContext?.changesetId;
+  if (!ticketId) {
+    await writeAgentLoopState(parsed, options, {
+      ...state,
+      sessions: {
+        ...state.sessions,
+        [agentSessionKeyValue]: {
+          ...sessionState,
+          lastAction: "skipped",
+          lastReason: "no_active_ticket"
+        }
+      }
+    });
+    const data = {
+      action: "skipped",
+      reason: "no_active_ticket",
+      agentSessionKey: agentSessionKeyValue
+    };
+    return {
+      stdout: parsed.flags.json ? formatJson(successEnvelope(data, meta)) : `${JSON.stringify(data, null, 2)}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  const eventFile = parsed.options["event-file"] ?? sessionState.lastEventFile;
+  const event = eventFile ? tryParseJsonObject(await readFile(eventFile, "utf8"), eventFile) : synthesizeAgentEventFromSession(agentSessionKeyValue, sessionState, options);
+  const mode = checkpointModeForCommand(parsed);
+  const logKind = parseWorkLogEntryKind(parsed.options["log-kind"] ?? "note");
+  const updateSummary = parseBooleanOption(parsed.options["update-summary"], false);
+  const dryRun = parseBooleanOption(parsed.options["dry-run"], false);
+  const closeoutSessionAction = parseCloseoutSessionAction(parsed.options["session-action"]);
+  const completeTicket = parseBooleanOption(parsed.options["complete-ticket"], false);
+  const lockPath = parsed.options.lock;
+  const checkpointSettings = await resolveCheckpointSettings(parsed, options);
+  const gitStatus = gitOutput(["status", "--short"], options);
+  const gitDiffStat = gitOutput(["diff", "--stat", "origin/dev..."], options);
+  const changedFiles = gitOutput(["diff", "--name-only", "origin/dev..."], options);
+  const priorCoverage = sessionState.lastCheckpointCoverage;
+  const fingerprints = buildAgentRunFingerprints({
+    event,
+    ticketId,
+    ...sessionId ? { sessionId } : {},
+    ...changesetId ? { changesetId } : {},
+    gitStatus,
+    gitDiffStat,
+    changedFiles,
+    ...priorCoverage ? { coverage: priorCoverage } : {}
+  });
+  const closeoutContext = mode === "closeout" ? await readCloseoutPromptContext({
+    client,
+    projectId,
+    ticketId,
+    ...sessionId ? { sessionId } : {}
+  }) : {};
+  const prompt = buildCheckpointPrompt({
+    mode,
+    event,
+    ticketId,
+    ...sessionId ? { sessionId } : {},
+    ...changesetId ? { changesetId } : {},
+    gitStatus,
+    gitDiffStat,
+    changedFiles,
+    ...sessionState.previousCheckpointSummary ? { previousCheckpointSummary: sessionState.previousCheckpointSummary } : {},
+    ...priorCoverage ? { coverage: priorCoverage } : {},
+    ...closeoutContext
+  });
+  const promptTokenAccounting = buildCheckpointTokenAccounting(event, prompt, undefined);
+  if (mode === "checkpoint" && !dryRun && !priorCoverage?.hasDebt && fingerprintsEqual(sessionState.lastCheckpointFingerprints, fingerprints) && !checkpointReasonBypassesFingerprintGate(parsed.options.reason)) {
+    const checkedAt = new Date().toISOString();
+    const auditFile = await writeAgentCheckpointAuditFile(parsed, options, {
+      version: 1,
+      mode,
+      action: "skipped",
+      reason: "unchanged_fingerprints",
+      createdAt: checkedAt,
+      localOnly: true,
+      localOnlyReason: "Raw hook context and checkpoint prompts stay on this machine; unchanged fingerprints did not need a model call.",
+      agentSessionKey: agentSessionKeyValue,
+      ticketId,
+      ...sessionId ? { sessionId } : {},
+      ...changesetId ? { changesetId } : {},
+      ...eventFile ? { eventFile } : {},
+      event,
+      fingerprints,
+      cadenceWrites: []
+    });
+    await writeAgentLoopState(parsed, options, {
+      ...state,
+      sessions: {
+        ...state.sessions,
+        [agentSessionKeyValue]: {
+          ...sessionState,
+          stopCount: 0,
+          threshold: defaultCheckpointThresholdValue(),
+          lastAction: "skipped",
+          lastReason: "unchanged_fingerprints",
+          lastCheckpointAt: checkedAt,
+          lastCheckpointMode: mode,
+          lastCheckpointFingerprints: fingerprints,
+          lastCheckpointAuditFile: auditFile
+        }
+      }
+    });
+    const data = {
+      action: "skipped",
+      reason: "unchanged_fingerprints",
+      mode,
+      ticketId,
+      auditFile,
+      agentSessionKey: agentSessionKeyValue,
+      ...sessionId ? { sessionId } : {},
+      ...changesetId ? { changesetId } : {}
+    };
+    return {
+      stdout: parsed.flags.json ? formatJson(successEnvelope(data, meta)) : `${JSON.stringify(data, null, 2)}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  if (dryRun) {
+    const auditFile = await writeAgentCheckpointAuditFile(parsed, options, {
+      version: 1,
+      mode,
+      action: "would_checkpoint",
+      createdAt: new Date().toISOString(),
+      localOnly: true,
+      localOnlyReason: "Raw hook context and checkpoint prompts stay on this machine and are not uploaded to Cadence.",
+      agentSessionKey: agentSessionKeyValue,
+      ticketId,
+      ...sessionId ? { sessionId } : {},
+      ...changesetId ? { changesetId } : {},
+      ...eventFile ? { eventFile } : {},
+      event,
+      prompt,
+      fingerprints,
+      ...mode === "closeout" ? { coverage: priorCoverage ?? null } : {},
+      checkpointSettings,
+      tokenAccounting: promptTokenAccounting,
+      cadenceWrites: []
+    });
+    const data = {
+      action: "would_checkpoint",
+      prompt,
+      auditFile,
+      ticketId,
+      agentSessionKey: agentSessionKeyValue,
+      ...sessionId ? { sessionId } : {},
+      ...changesetId ? { changesetId } : {}
+    };
+    return {
+      stdout: parsed.flags.json ? formatJson(successEnvelope(data, meta)) : `${JSON.stringify(data, null, 2)}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  try {
+    const codexCommand = parsed.options["codex-command"] ?? "codex";
+    const codexStartedAtMs = Date.now();
+    const codexCwd = options.cwd ?? process.cwd();
+    const codexArgs = [
+      "exec",
+      ...checkpointSettings.model ? ["-m", checkpointSettings.model] : [],
+      "--disable",
+      "hooks",
+      "--sandbox",
+      "read-only",
+      "-C",
+      codexCwd,
+      prompt
+    ];
+    const codex = runLocalCommand(codexCommand, codexArgs, options, {
+      cwd: codexCwd,
+      env: {
+        [agentLoopSuppressEnv]: "1",
+        CADENCE_HOOK_SUPPRESS: "1"
+      },
+      timeoutMs: defaultCheckpointWorkerTimeoutMs
+    });
+    const codexSessionTranscript = readCodexSessionTranscript(findCodexSessionFileCreatedAfter(options, codexStartedAtMs, codexCwd));
+    const tokenAccounting = buildCheckpointTokenAccounting(event, prompt, codexSessionTranscript?.tokenUsage);
+    if (codex.status !== 0 || codex.error) {
+      throw new CliError("AGENT_RUN_CHECKPOINT_FAILED", "Codex checkpoint generation failed.", {
+        status: codex.status,
+        stderr: truncateText(codex.stderr, 2000),
+        error: codex.error?.message
+      });
+    }
+    let checkpoint = parseCheckpointPlanJson(codex.stdout, logKind);
+    if (mode === "closeout") {
+      checkpoint = applyCloseoutSessionDefaults(checkpoint, closeoutSessionAction, completeTicket);
+    }
+    const reductionResult = reduceCheckpointEntries(checkpoint.entries, mode);
+    checkpoint = {
+      ...checkpoint,
+      entries: reductionResult.entries
+    };
+    const coverage = buildAgentRunCoverage(checkpoint, mode);
+    let summary = checkpoint.summary ?? checkpoint.entries[0]?.summary ?? checkpoint.route.reason ?? "Agent run checkpoint";
+    let targetTicketId = ticketId;
+    let targetSessionId = sessionId;
+    let targetChangesetId = changesetId;
+    const cadenceWrites = [];
+    const lifecycleOperations = [];
+    let intakeResult;
+    let selectedTicket;
+    const modelAudit = {
+      provider: checkpointSettings.provider,
+      command: codexCommand,
+      ...checkpointSettings.model ? { model: checkpointSettings.model } : {},
+      status: codex.status,
+      stdout: codex.stdout.trim(),
+      stderr: truncateText(codex.stderr.trim(), 2000),
+      tokenAccounting,
+      ...codexSessionTranscript?.tokenUsage ? { tokenUsage: codexSessionTranscript.tokenUsage } : {},
+      ...codexSessionTranscript ? { sessionTranscript: codexSessionTranscript } : {}
+    };
+    const finishCheckpoint = async (action, reason) => {
+      const checkedAt = new Date().toISOString();
+      const auditFile = await writeAgentCheckpointAuditFile(parsed, options, {
+        version: 1,
+        action,
+        createdAt: checkedAt,
+        localOnly: true,
+        localOnlyReason: action === "noop" || action === "needs_human" || action === "reroute" ? "Raw hook context, checkpoint prompts, and model output stay on this machine; no Cadence writes were needed." : "Raw hook context, checkpoint prompts, and model output stay on this machine; Cadence receives only the structured writes listed here.",
+        agentSessionKey: agentSessionKeyValue,
+        ticketId: targetTicketId,
+        ...targetSessionId ? { sessionId: targetSessionId } : {},
+        ...targetChangesetId ? { changesetId: targetChangesetId } : {},
+        ...eventFile ? { eventFile } : {},
+        event,
+        prompt,
+        model: modelAudit,
+        checkpoint,
+        route: checkpoint.route,
+        mode,
+        fingerprints,
+        reduction: reductionResult.reduction,
+        ...mode === "closeout" ? { coverage } : {},
+        ...intakeResult ? { intakeResult } : {},
+        ...selectedTicket ? { selectedTicket } : {},
+        lifecycleOperations,
+        cadenceWrites,
+        summary,
+        ...reason ? { reason } : {},
+        entryCount: checkpoint.entries.length,
+        needsHuman: action === "needs_human"
+      });
+      await writeAgentLoopState(parsed, options, {
+        ...state,
+        sessions: {
+          ...state.sessions,
+          [agentSessionKeyValue]: {
+            ...sessionState,
+            stopCount: 0,
+            threshold: defaultCheckpointThresholdValue(),
+            previousCheckpointSummary: summary,
+            lastAction: action,
+            ...reason ? { lastReason: reason } : {},
+            ...eventFile ? { lastEventFile: eventFile } : {},
+            cadenceContext: {
+              ticketId: targetTicketId,
+              ...targetSessionId ? { sessionId: targetSessionId } : {},
+              ...targetChangesetId ? { changesetId: targetChangesetId } : {},
+              capturedAt: checkedAt
+            },
+            lastCheckpointAt: checkedAt,
+            lastCheckpointMode: mode,
+            lastCheckpointFingerprints: fingerprints,
+            lastCheckpointCoverage: coverage,
+            lastCheckpointAuditFile: auditFile
+          }
+        }
+      });
+      const data = {
+        action,
+        route: checkpoint.route,
+        ...reason ? { reason } : {},
+        ticketId: targetTicketId,
+        summary,
+        entryCount: checkpoint.entries.length,
+        mode,
+        auditFile,
+        agentSessionKey: agentSessionKeyValue,
+        ...targetSessionId ? { sessionId: targetSessionId } : {},
+        ...targetChangesetId ? { changesetId: targetChangesetId } : {},
+        ...action === "needs_human" ? { needsHuman: true } : {}
+      };
+      return {
+        stdout: parsed.flags.json ? formatJson(successEnvelope(data, meta)) : `${JSON.stringify(data, null, 2)}
+`,
+        stderr: "",
+        exitCode: 0
+      };
+    };
+    if (checkpoint.session?.action === "complete_ticket" && mode === "closeout" && !completeTicket) {
+      checkpoint = checkpointPlanNeedsHuman(checkpoint, "Closeout ticket completion requires --complete-ticket true.");
+    }
+    if (checkpoint.session?.action === "complete_ticket" && !checkpointPlanCompletionAllowed(event, summary)) {
+      checkpoint = checkpointPlanNeedsHuman(checkpoint, "Completion requires explicit recent completion, push, PR, merge, clean branch, or verification intent.");
+    }
+    if (checkpoint.route.action === "noop") {
+      return await finishCheckpoint("noop", checkpoint.route.reason ?? checkpoint.summary ?? "Nothing durable to record.");
+    }
+    if (checkpoint.route.action === "needs_human") {
+      checkpoint = checkpointPlanWithRoute(checkpoint, {
+        action: "noop",
+        confidence: checkpoint.route.confidence,
+        reason: checkpoint.route.reason ?? "Checkpoint routing was uncertain."
+      });
+      return await finishCheckpoint("noop", checkpoint.route.reason);
+    }
+    if (checkpointRouteRequiresIntake(checkpoint.route.action)) {
+      if (checkpoint.route.confidence !== "high") {
+        checkpoint = checkpointPlanWithRoute(checkpoint, {
+          action: "noop",
+          confidence: checkpoint.route.confidence,
+          reason: "Checkpoint reroute requires high confidence."
+        });
+        return await finishCheckpoint("noop", checkpoint.route.reason);
+      }
+      const routeArgs = [
+        "agent-run",
+        "route",
+        "--agent-session-key",
+        agentSessionKeyValue,
+        "--reason",
+        "checkpoint_reroute",
+        ...eventFile ? ["--event-file", eventFile] : [],
+        ...parsed.flags.project ? ["--project", parsed.flags.project] : [],
+        ...parsed.flags.server ? ["--server", parsed.flags.server] : []
+      ];
+      const rerouteResult = await finishCheckpoint("reroute", checkpoint.route.reason ?? "Checkpoint delegated routing to agent-run route.");
+      await spawnAgentRunWorker(routeArgs, options);
+      return rerouteResult;
     }
-    const checkpointMetadata = checkpointWorkLogMetadata(checkpointSettings, tokenAccounting);
+    const checkpointMetadata = checkpointWorkLogMetadata(checkpointSettings, mode, tokenAccounting);
     for (const entry of checkpoint.entries) {
       const logEntry = {
         entryKind: entry.kind,
@@ -5033,26 +5922,17 @@ async function runAgentRunSweep(parsed, options, config, meta) {
     lastObservedAt: session.lastObservedAt
   }));
   if (!dryRun) {
-    const needsFallbackContext = staleSessions.some((staleSession) => !state.sessions[staleSession.agentSessionKey]?.cadenceContext);
-    let fallbackContext;
-    if (needsFallbackContext && config.projectId) {
-      try {
-        const client = await createClient(config, options);
-        fallbackContext = await readCurrentCadenceContext(client, config.projectId);
-      } catch {}
-    }
     let nextState = state;
     for (const staleSession of staleSessions) {
       const existingSession = nextState.sessions[staleSession.agentSessionKey];
-      const cadenceContext = existingSession?.cadenceContext ?? fallbackContext;
-      if (existingSession && cadenceContext) {
+      const hasContext = Boolean(existingSession?.cadenceContext?.ticketId);
+      if (existingSession) {
         nextState = {
           ...nextState,
           sessions: {
             ...nextState.sessions,
             [staleSession.agentSessionKey]: {
               ...existingSession,
-              cadenceContext,
               lastAction: "sweep_spawned"
             }
           }
@@ -5061,11 +5941,11 @@ async function runAgentRunSweep(parsed, options, config, meta) {
       }
       await spawnAgentRunCheckpoint([
         "agent-run",
-        "checkpoint",
+        hasContext ? "checkpoint" : "route",
         "--agent-session-key",
         staleSession.agentSessionKey,
         "--reason",
-        "idle",
+        hasContext ? "idle" : "missing_context",
         "--lock",
         agentLoopLockPath(parsed, options, staleSession.agentSessionKey),
         ...parsed.flags.project ? ["--project", parsed.flags.project] : [],
@@ -5733,7 +6613,7 @@ async function runCli(argv, options = {}) {
     if (parsed.command.name === "projects.list") {
       return await runProjectCommand(parsed, options);
     }
-    if (parsed.command.name === "agent-run.ingest-stop" || parsed.command.name === "agent-run.checkpoint" || parsed.command.name === "agent-run.closeout" || parsed.command.name === "agent-run.sweep" || parsed.command.name === "agent-run.doctor") {
+    if (parsed.command.name === "agent-run.ingest-stop" || parsed.command.name === "agent-run.route" || parsed.command.name === "agent-run.checkpoint" || parsed.command.name === "agent-run.closeout" || parsed.command.name === "agent-run.sweep" || parsed.command.name === "agent-run.doctor") {
       return await runAgentRunCommand(parsed, options);
     }
     if (parsed.command.name === "hooks.install" || parsed.command.name === "hooks.doctor") {