supipowers 1.5.3 → 2.0.1

package/src/ultraplan/runtime/hook-bridge.ts

@@ -0,0 +1,486 @@
+import type { Platform } from "../../platform/types.js";
+import { systemPromptText } from "../../platform/system-prompt.js";
+import type {
+  UltraPlanCursor,
+  UltraPlanHookEventName,
+  UltraPlanHookObservation,
+  UltraPlanLaunchContext,
+  UltraPlanMutationPlan,
+  UltraPlanRuntimeTracker,
+  UltraPlanStorageResult,
+} from "../../types.js";
+import { LAUNCH_CONTEXT_METADATA_KEY, recoverLaunchContextFromEvent } from "./launch-context.js";
+import { normalizeHookEvent, type NormalizeHookEventInput } from "./normalize.js";
+import {
+  loadTracker as loadTrackerDefault,
+  saveTrackerAtomic as saveTrackerAtomicDefault,
+} from "./tracker-storage.js";
+import { reduce as reduceDefault, type ReducerState } from "./reducer.js";
+import {
+  repairOnSessionShutdown as repairOnSessionShutdownDefault,
+  repairOnSessionStart as repairOnSessionStartDefault,
+  type RepairPlan,
+} from "./repair.js";
+import {
+  resolveSessionMigration as resolveSessionMigrationDefault,
+  type MigrationOutcome,
+} from "./migration.js";
+import {
+  listActiveUltraPlanExecutions,
+  readActiveUltraPlanExecutionForSession as readRegistryActiveExecutionForSession,
+  type ActiveUltraPlanExecution,
+} from "./active-execution.js";
+import { applyUltraPlanMutation } from "./apply-mutation.js";
+
+/**
+ * Slice-2 hook bridge.
+ *
+ * This is the only UltraPlan module that `src/context-mode/hooks.ts` imports. It wires platform
+ * hook events into the runtime pipeline (normalize \u2192 reduce \u2192 apply) without performing any
+ * business decisions itself. Every runtime unit is injected so the bridge is fully testable in
+ * isolation and so the context-mode hook layer stays generic.
+ */
+
+export interface UltraPlanSessionContext {
+  sessionId: string;
+  cwd: string;
+}
+
+export interface UltraPlanHookBridgeDeps {
+  /** Resolves the currently-focused UltraPlan session for a given platform hook context. */
+  resolveActiveSession(ctx: unknown): UltraPlanSessionContext | null;
+
+  normalize(input: NormalizeHookEventInput): UltraPlanHookObservation;
+
+  loadTracker(paths: Platform["paths"], cwd: string, sessionId: string): UltraPlanStorageResult<UltraPlanRuntimeTracker>;
+  saveTrackerAtomic(
+    paths: Platform["paths"],
+    cwd: string,
+    sessionId: string,
+    tracker: UltraPlanRuntimeTracker,
+  ): UltraPlanStorageResult<string>;
+
+  reduce(state: ReducerState, action: Parameters<typeof reduceDefault>[1]): UltraPlanMutationPlan;
+
+  /** Single I/O funnel that applies a mutation plan in the required durability order. */
+  applyMutationPlan(input: ApplyMutationPlanInput): void;
+
+  repairOnSessionStart(state: { tracker: UltraPlanRuntimeTracker; manifest: null }, nowIso: string): RepairPlan;
+  repairOnSessionShutdown(state: { tracker: UltraPlanRuntimeTracker; manifest: null }, nowIso: string): RepairPlan;
+
+  resolveSessionMigration(input: {
+    paths: Platform["paths"];
+    cwd: string;
+    sessionId: string;
+    nowIso: string;
+  }): MigrationOutcome;
+}
+
+export interface ApplyMutationPlanInput {
+  platform: Platform;
+  cwd: string;
+  sessionId: string;
+  observation: UltraPlanHookObservation;
+  mutationPlan: UltraPlanMutationPlan;
+}
+
+/**
+ * Register the UltraPlan hook bridge on a platform. The six UltraPlan-relevant hooks are wired to
+ * the runtime pipeline; when `resolveActiveSession` returns null the handlers are no-ops.
+ */
+export function registerUltraPlanHookBridge(
+  platform: Platform,
+  overrides: Partial<UltraPlanHookBridgeDeps> = {},
+): void {
+  const deps: UltraPlanHookBridgeDeps = {
+    resolveActiveSession: overrides.resolveActiveSession ?? defaultResolveActiveSession,
+    normalize: overrides.normalize ?? normalizeHookEvent,
+    loadTracker: overrides.loadTracker ?? loadTrackerDefault,
+    saveTrackerAtomic: overrides.saveTrackerAtomic ?? saveTrackerAtomicDefault,
+    reduce: overrides.reduce ?? reduceDefault,
+    applyMutationPlan: overrides.applyMutationPlan ?? applyMutationPlanDefault,
+    repairOnSessionStart: overrides.repairOnSessionStart ?? repairOnSessionStartDefault,
+    repairOnSessionShutdown: overrides.repairOnSessionShutdown ?? repairOnSessionShutdownDefault,
+    resolveSessionMigration: overrides.resolveSessionMigration ?? resolveSessionMigrationDefault,
+  };
+
+  const sessionStart = (rawEvent: unknown, ctx?: unknown) =>
+    handleSessionStart(platform, deps, rawEvent, ctx);
+  const beforeAgentStart = (rawEvent: unknown, ctx?: unknown) =>
+    handleAttemptEvent(platform, deps, "before_agent_start", rawEvent, ctx);
+  const toolCall = (rawEvent: unknown, ctx?: unknown) =>
+    handleAttemptEvent(platform, deps, "tool_call", rawEvent, ctx);
+  const toolResult = (rawEvent: unknown, ctx?: unknown) =>
+    handleAttemptEvent(platform, deps, "tool_result", rawEvent, ctx);
+  const agentEnd = (rawEvent: unknown, ctx?: unknown) =>
+    handleAttemptEvent(platform, deps, "agent_end", rawEvent, ctx);
+  const sessionShutdown = (rawEvent: unknown, ctx?: unknown) =>
+    handleSessionShutdown(platform, deps, rawEvent, ctx);
+
+  platform.on("session_start", sessionStart);
+  platform.on("before_agent_start", beforeAgentStart);
+  platform.on("tool_call", toolCall);
+  platform.on("tool_result", toolResult);
+  platform.on("agent_end", agentEnd);
+  platform.on("session_shutdown", sessionShutdown);
+}
+
+// ---------------------------------------------------------------------------
+// Hook handlers
+// ---------------------------------------------------------------------------
+
+function handleSessionStart(
+  platform: Platform,
+  deps: UltraPlanHookBridgeDeps,
+  rawEvent: unknown,
+  ctx: unknown,
+): void {
+  const session = resolveSessionContext(deps, platform, "session_start", rawEvent, ctx);
+  if (!session) return;
+
+  const nowIso = new Date().toISOString();
+
+  // Migration check runs before any tracker work so a partial global directory can be repaired.
+  deps.resolveSessionMigration({ paths: platform.paths, cwd: session.cwd, sessionId: session.sessionId, nowIso });
+
+  const tracker = loadTrackerOrEmpty(deps, platform, session);
+  const repair = deps.repairOnSessionStart({ tracker, manifest: null }, nowIso);
+  void repair; // Slice-2 bridge applies repair actions inside the reducer flow below.
+
+
+  const observation = deps.normalize({
+    hookEvent: "session_start",
+    sessionId: session.sessionId,
+    nowIso,
+    metadata: extractMetadata(rawEvent, ctx),
+    prompt: extractPrompt(rawEvent, ctx),
+    persistedActiveAttempt: tracker.activeAttempt,
+    payload: toRecord(rawEvent),
+  });
+
+  const plan = deps.reduce({ tracker, cursor: tracker.activeAttempt?.cursorSnapshot ?? null }, {
+    kind: "session_started",
+    observation,
+    nowIso,
+  });
+  deps.applyMutationPlan({ platform, cwd: session.cwd, sessionId: session.sessionId, observation, mutationPlan: plan });
+}
+
+function handleAttemptEvent(
+  platform: Platform,
+  deps: UltraPlanHookBridgeDeps,
+  hookEvent: UltraPlanHookEventName,
+  rawEvent: unknown,
+  ctx: unknown,
+): void {
+  const session = resolveSessionContext(deps, platform, hookEvent, rawEvent, ctx);
+  if (!session) return;
+
+  const nowIso = new Date().toISOString();
+  const tracker = loadTrackerOrEmpty(deps, platform, session);
+  const activeExecution = resolveActiveUltraPlanExecutionForEvent(session, rawEvent, ctx);
+  const observation = deps.normalize({
+    hookEvent,
+    sessionId: session.sessionId,
+    nowIso,
+    metadata: extractMetadata(rawEvent, ctx),
+    prompt: extractPrompt(rawEvent, ctx),
+    persistedActiveAttempt: tracker.activeAttempt,
+    payload: extractPayload(rawEvent),
+    targetHint: extractTargetHint(rawEvent, ctx),
+    fallbackTargetHint: buildFallbackTargetHint(activeExecution),
+  });
+
+  const cursor: UltraPlanCursor | null = tracker.activeAttempt?.cursorSnapshot ?? null;
+
+  const plan = deps.reduce({ tracker, cursor }, reducerActionForEvent(hookEvent, observation, nowIso));
+  deps.applyMutationPlan({ platform, cwd: session.cwd, sessionId: session.sessionId, observation, mutationPlan: plan });
+}
+
+function handleSessionShutdown(
+  platform: Platform,
+  deps: UltraPlanHookBridgeDeps,
+  rawEvent: unknown,
+  ctx: unknown,
+): void {
+  const session = resolveSessionContext(deps, platform, "session_shutdown", rawEvent, ctx);
+  if (!session) return;
+
+  const nowIso = new Date().toISOString();
+  const tracker = loadTrackerOrEmpty(deps, platform, session);
+  const repair = deps.repairOnSessionShutdown({ tracker, manifest: null }, nowIso);
+  void repair; // passed into the reducer via repair_applied actions in Slice-5 expansion.
+
+
+  const observation = deps.normalize({
+    hookEvent: "session_shutdown",
+    sessionId: session.sessionId,
+    nowIso,
+    metadata: extractMetadata(rawEvent, ctx),
+    prompt: extractPrompt(rawEvent, ctx),
+    persistedActiveAttempt: tracker.activeAttempt,
+    payload: toRecord(rawEvent),
+  });
+
+  const plan = deps.reduce({ tracker, cursor: tracker.activeAttempt?.cursorSnapshot ?? null }, {
+    kind: "session_shutdown",
+    observation,
+    nowIso,
+  });
+  deps.applyMutationPlan({ platform, cwd: session.cwd, sessionId: session.sessionId, observation, mutationPlan: plan });
+}
+
+// ---------------------------------------------------------------------------
+// Default resolvers
+// ---------------------------------------------------------------------------
+
+function defaultResolveActiveSession(_ctx: unknown): UltraPlanSessionContext | null {
+  return null;
+}
+
+function applyMutationPlanDefault(input: ApplyMutationPlanInput): void {
+  applyUltraPlanMutation(input);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function loadTrackerOrEmpty(
+  deps: UltraPlanHookBridgeDeps,
+  platform: Platform,
+  session: UltraPlanSessionContext,
+): UltraPlanRuntimeTracker {
+  const result = deps.loadTracker(platform.paths, session.cwd, session.sessionId);
+  if (result.ok) return result.value;
+  return {
+    version: 1,
+    sessionId: session.sessionId,
+    activeAttempt: null,
+    finalizedAttempts: [],
+    appliedFingerprints: [],
+    pendingMutation: null,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function resolveSessionContext(
+  deps: UltraPlanHookBridgeDeps,
+  platform: Platform,
+  hookEvent: UltraPlanHookEventName,
+  rawEvent: unknown,
+  ctx: unknown,
+): UltraPlanSessionContext | null {
+  const explicit = deps.resolveActiveSession(ctx);
+  if (explicit) {
+    return explicit;
+  }
+
+  return resolveFallbackSessionContext(deps, platform, hookEvent, rawEvent, ctx);
+}
+
+function resolveFallbackSessionContext(
+  deps: UltraPlanHookBridgeDeps,
+  platform: Platform,
+  hookEvent: UltraPlanHookEventName,
+  rawEvent: unknown,
+  ctx: unknown,
+ ): UltraPlanSessionContext | null {
+  if (hookEvent === "session_start") {
+    return null;
+  }
+
+  const launchContext = recoverLaunchContextFromEvent({
+    metadata: extractMetadata(rawEvent, ctx),
+    prompt: extractPrompt(rawEvent, ctx),
+    persistedActiveAttempt: null,
+  });
+
+  if (launchContext) {
+    const activeExecution = readActiveUltraPlanExecutionForLaunchContext(launchContext);
+    return activeExecution ? { sessionId: activeExecution.sessionId, cwd: activeExecution.cwd } : null;
+  }
+
+  if (hookEvent === "before_agent_start") {
+    return null;
+  }
+
+  const activeExecution = readUniqueActiveUltraPlanExecutionForCwd(extractCwd(rawEvent, ctx));
+  if (!activeExecution) {
+    return null;
+  }
+
+  const tracker = deps.loadTracker(platform.paths, activeExecution.cwd, activeExecution.sessionId);
+  if (!tracker.ok || !tracker.value.activeAttempt) {
+    return null;
+  }
+
+  if (!sameLaunchContext(tracker.value.activeAttempt.launchContext, activeExecution.launchContext)) {
+    return null;
+  }
+
+  return { sessionId: activeExecution.sessionId, cwd: activeExecution.cwd };
+}
+
+function readActiveUltraPlanExecutionForSession(
+  session: UltraPlanSessionContext,
+ ): ActiveUltraPlanExecution | null {
+  return readRegistryActiveExecutionForSession(session.sessionId, session.cwd);
+}
+
+function readActiveUltraPlanExecutionForLaunchContext(
+  launchContext: UltraPlanLaunchContext,
+ ): ActiveUltraPlanExecution | null {
+  const matches = listActiveUltraPlanExecutions().filter((execution) => sameLaunchContext(launchContext, execution.launchContext));
+  return matches.length === 1 ? matches[0]! : null;
+}
+
+function readUniqueActiveUltraPlanExecutionForCwd(cwd: string | null): ActiveUltraPlanExecution | null {
+  if (!cwd) {
+    return null;
+  }
+
+  const matches = listActiveUltraPlanExecutions().filter((execution) => execution.cwd === cwd);
+  return matches.length === 1 ? matches[0]! : null;
+}
+
+function resolveActiveUltraPlanExecutionForEvent(
+  session: UltraPlanSessionContext,
+  rawEvent: unknown,
+  ctx: unknown,
+ ): ActiveUltraPlanExecution | null {
+  const launchContext = recoverLaunchContextFromEvent({
+    metadata: extractMetadata(rawEvent, ctx),
+    prompt: extractPrompt(rawEvent, ctx),
+    persistedActiveAttempt: null,
+  });
+  if (launchContext) {
+    const activeExecution = readActiveUltraPlanExecutionForLaunchContext(launchContext);
+    if (activeExecution?.sessionId === session.sessionId && activeExecution.cwd === session.cwd) {
+      return activeExecution;
+    }
+  }
+
+  return readActiveUltraPlanExecutionForSession(session);
+}
+
+function sameLaunchContext(left: UltraPlanLaunchContext, right: UltraPlanLaunchContext): boolean {
+  return left.attemptId === right.attemptId && left.attemptKey === right.attemptKey;
+}
+
+function extractCwd(rawEvent: unknown, ctx: unknown): string | null {
+  const rawCwd = asRecord(rawEvent)?.cwd;
+  if (typeof rawCwd === "string" && rawCwd.length > 0) {
+    return rawCwd;
+  }
+
+  const ctxCwd = asRecord(ctx)?.cwd;
+  return typeof ctxCwd === "string" && ctxCwd.length > 0 ? ctxCwd : null;
+}
+
+
+function extractTargetHint(
+  rawEvent: unknown,
+  ctx: unknown,
+): NormalizeHookEventInput["targetHint"] | undefined {
+  const rawHint = asRecord(rawEvent)?.targetHint;
+  if (rawHint && typeof rawHint === "object" && !Array.isArray(rawHint)) {
+    return rawHint as NormalizeHookEventInput["targetHint"];
+  }
+  const ctxHint = asRecord(ctx)?.targetHint;
+  if (ctxHint && typeof ctxHint === "object" && !Array.isArray(ctxHint)) {
+    return ctxHint as NormalizeHookEventInput["targetHint"];
+  }
+  return undefined;
+}
+
+function buildFallbackTargetHint(activeExecution: ActiveUltraPlanExecution | null): NormalizeHookEventInput["fallbackTargetHint"] {
+  if (!activeExecution) {
+    return undefined;
+  }
+
+  return {
+    targetType: activeExecution.target.targetType,
+    stack: activeExecution.target.stack,
+    domainId: activeExecution.target.domainId,
+    level: activeExecution.target.level,
+    scenarioId: activeExecution.target.scenarioId,
+    phase: activeExecution.target.phase,
+    resolvedSlot: activeExecution.target.requiredSlot,
+    actorKind: "slot",
+    sourceAgent: "sub-agent",
+  };
+}
+
+function extractPayload(rawEvent: unknown): Record<string, unknown> {
+  const payload = toRecord(rawEvent);
+  const signalPayload = asRecord(asRecord(rawEvent)?.details)?.payload;
+  if (!signalPayload) {
+    return payload;
+  }
+
+  return {
+    ...payload,
+    payload: signalPayload,
+    summary: typeof payload.summary === "string" ? payload.summary : payload.payloadSummary,
+  };
+}
+
+function reducerActionForEvent(
+  hookEvent: UltraPlanHookEventName,
+  observation: UltraPlanHookObservation,
+  nowIso: string,
+): Parameters<typeof reduceDefault>[1] {
+  switch (hookEvent) {
+    case "before_agent_start": {
+      // The bridge extracts a launch context (or fails correlation at normalization time).
+      // When correlation failed, pass an attempt_started action anyway so the reducer emits a
+      // blocker plan; the observation's correlationFailure carries the reason.
+      const launchContext = {
+        attemptId: observation.attemptId ?? "unknown",
+        attemptKey: observation.attemptKey ?? "unknown",
+        sourceAgent: observation.sourceAgent,
+        launchedAt: observation.occurredAt,
+      };
+      return { kind: "attempt_started", observation, launchContext };
+    }
+    case "tool_call":
+    case "tool_result":
+      return { kind: "observation_staged", observation };
+    case "agent_end":
+      return { kind: "attempt_finalized", observation, nowIso };
+    default:
+      return { kind: "observation_staged", observation };
+  }
+}
+
+function extractMetadata(rawEvent: unknown, ctx: unknown): Record<string, unknown> | null {
+  const rawMeta = asRecord(rawEvent)?.metadata as Record<string, unknown> | undefined;
+  const ctxMeta = asRecord(ctx)?.metadata as Record<string, unknown> | undefined;
+  if (rawMeta && ctxMeta) return { ...ctxMeta, ...rawMeta };
+  return rawMeta ?? ctxMeta ?? null;
+}
+
+function extractPrompt(rawEvent: unknown, ctx: unknown): string | null {
+  const rawPrompt = asRecord(rawEvent)?.prompt;
+  if (typeof rawPrompt === "string") return rawPrompt;
+  const rawSystemPrompt = systemPromptText(asRecord(rawEvent)?.systemPrompt);
+  if (rawSystemPrompt.length > 0) return rawSystemPrompt;
+  const ctxPrompt = asRecord(ctx)?.prompt;
+  if (typeof ctxPrompt === "string") return ctxPrompt;
+  return null;
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  return asRecord(value) ?? {};
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return null;
+}
+
+// Re-export useful carrier bits for hosts that need them.
+export { LAUNCH_CONTEXT_METADATA_KEY, recoverLaunchContextFromEvent };

package/src/ultraplan/runtime/launch-context.ts

@@ -0,0 +1,207 @@
+import { randomUUID } from "node:crypto";
+import {
+  ULTRAPLAN_AGENT_SLOT_NAMES,
+  ULTRAPLAN_CURSOR_TARGETS,
+  ULTRAPLAN_EXECUTION_PHASES,
+  ULTRAPLAN_LEVELS,
+  ULTRAPLAN_STACKS,
+} from "../contracts.js";
+import type {
+  UltraPlanAttemptRecord,
+  UltraPlanLaunchContext,
+  UltraPlanSourceAgent,
+} from "../../types.js";
+import { isUltraPlanLaunchContext } from "../contracts.js";
+import type { UltraPlanTargetHint } from "./normalize.js";
+
+/**
+ * Slice-2 cross-hook correlation carrier.
+ *
+ * The runtime spec §cross-hook carrier requires that every slot-backed launch embed a launch
+ * context into both structured metadata and the prompt/assignment text so later hooks can recover
+ * the attempt identity even when the platform drops one carrier. This module owns minting,
+ * injecting, and recovering those carriers. It is pure — no I/O.
+ */
+
+/** The metadata key the bridge uses to carry a structured launch context through platform hooks. */
+export const LAUNCH_CONTEXT_METADATA_KEY = "ultraplanLaunchContext" as const;
+/** Prompt marker line form: `ULTRAPLAN_LAUNCH_CONTEXT=<json>`. */
+export const LAUNCH_CONTEXT_PROMPT_MARKER = "ULTRAPLAN_LAUNCH_CONTEXT" as const;
+/** Structured metadata key for the execution target hint carried alongside launch context. */
+export const TARGET_HINT_METADATA_KEY = "ultraplanTargetHint" as const;
+/** Prompt marker line form: `ULTRAPLAN_TARGET_HINT=<json>`. */
+export const TARGET_HINT_PROMPT_MARKER = "ULTRAPLAN_TARGET_HINT" as const;
+
+export interface MintLaunchContextInput {
+  attemptKey: string;
+  sourceAgent: UltraPlanSourceAgent;
+  nowIso: string;
+  /**
+   * When set, the minted launch context inherits the parent attempt's `attemptId` and
+   * `attemptKey`. Slice 2 uses this so a nested sub-agent shares its parent's attempt identity
+   * instead of minting a child attempt. Retries do NOT pass `inheritFrom` — they mint a fresh id.
+   */
+  inheritFrom?: UltraPlanLaunchContext | null;
+}
+
+export function mintLaunchContext(input: MintLaunchContextInput): UltraPlanLaunchContext {
+  const { attemptKey, sourceAgent, nowIso, inheritFrom } = input;
+
+  if (inheritFrom && isUltraPlanLaunchContext(inheritFrom)) {
+    return {
+      attemptId: inheritFrom.attemptId,
+      attemptKey: inheritFrom.attemptKey,
+      sourceAgent,
+      launchedAt: nowIso,
+    };
+  }
+
+  return {
+    attemptId: randomUUID(),
+    attemptKey,
+    sourceAgent,
+    launchedAt: nowIso,
+  };
+}
+
+/**
+ * Inject the exact `ULTRAPLAN_LAUNCH_CONTEXT=<json>` line into a prompt/assignment string.
+ *
+ * Idempotent: if the prompt already contains a marker line for a context with the same payload,
+ * a second injection does not duplicate it. Different payloads replace the prior marker so the
+ * latest intent wins.
+ */
+export function injectLaunchContextIntoPrompt(prompt: string, ctx: UltraPlanLaunchContext): string {
+  return injectJsonCarrierIntoPrompt(prompt, LAUNCH_CONTEXT_PROMPT_MARKER, ctx);
+}
+
+/**
+ * Inject the exact `ULTRAPLAN_TARGET_HINT=<json>` line into a prompt/assignment string.
+ * Mirrors the launch-context carrier semantics so later hooks can recover the execution target
+ * even when platform metadata is dropped.
+ */
+export function injectTargetHintIntoPrompt(prompt: string, hint: UltraPlanTargetHint): string {
+  return injectJsonCarrierIntoPrompt(prompt, TARGET_HINT_PROMPT_MARKER, hint);
+}
+
+export interface RecoverLaunchContextInput {
+  /** Structured platform metadata carried alongside the event. May be null. */
+  metadata: Record<string, unknown> | null | undefined;
+  /** Raw prompt / assignment / system prompt text that may carry the marker line. May be null. */
+  prompt: string | null | undefined;
+  /** The currently-persisted active attempt from the tracker, used as a last-resort. May be null. */
+  persistedActiveAttempt: UltraPlanAttemptRecord | null | undefined;
+}
+
+/****
+ * Recover a launch context from the available carriers.
+ *
+ * Priority (spec §cross-hook carrier, line 464):
+ * 1. Structured metadata under the `ultraplanLaunchContext` key.
+ * 2. `ULTRAPLAN_LAUNCH_CONTEXT=<json>` line inside the prompt/assignment text.
+ * 3. The persisted active attempt record's own launch context, as a last-resort consistency check.
+ * 4. Otherwise return null; the normalization layer surfaces this as a correlation failure.
+ */
+export function recoverLaunchContextFromEvent(input: RecoverLaunchContextInput): UltraPlanLaunchContext | null {
+  const fromMetadata = readMetadataCarrier(input.metadata);
+  if (fromMetadata) return fromMetadata;
+
+  const fromPrompt = recoverLaunchContextFromPrompt(input.prompt);
+  if (fromPrompt) return fromPrompt;
+
+  if (input.persistedActiveAttempt && isUltraPlanLaunchContext(input.persistedActiveAttempt.launchContext)) {
+    return input.persistedActiveAttempt.launchContext;
+  }
+  return null;
+}
+
+export function recoverLaunchContextFromPrompt(prompt: string | null | undefined): UltraPlanLaunchContext | null {
+  const candidate = readJsonPromptCarrier(prompt, LAUNCH_CONTEXT_PROMPT_MARKER);
+  return isUltraPlanLaunchContext(candidate) ? candidate : null;
+}
+
+export function recoverTargetHintFromPrompt(prompt: string | null | undefined): UltraPlanTargetHint | null {
+  const candidate = readJsonPromptCarrier(prompt, TARGET_HINT_PROMPT_MARKER);
+  return isUltraPlanTargetHint(candidate) ? candidate : null;
+}
+
+// --- internal helpers ------------------------------------------------------
+
+function readMetadataCarrier(metadata: RecoverLaunchContextInput["metadata"]): UltraPlanLaunchContext | null {
+  if (!metadata || typeof metadata !== "object") return null;
+  const candidate = (metadata as Record<string, unknown>)[LAUNCH_CONTEXT_METADATA_KEY];
+  return isUltraPlanLaunchContext(candidate) ? candidate : null;
+}
+
+function injectJsonCarrierIntoPrompt(prompt: string, marker: string, payload: unknown): string {
+  const line = buildMarkerLine(marker, payload);
+  if (prompt.includes(line)) {
+    return prompt;
+  }
+
+  const existingLineRegex = new RegExp(`^${escapeRegExp(marker)}=.*$`, "m");
+  if (existingLineRegex.test(prompt)) {
+    return prompt.replace(existingLineRegex, line);
+  }
+
+  const separator = prompt.endsWith("\n") || prompt.length === 0 ? "" : "\n";
+  return `${prompt}${separator}\n${line}`;
+}
+
+function readJsonPromptCarrier(prompt: string | null | undefined, marker: string): unknown {
+  if (typeof prompt !== "string" || prompt.length === 0) return null;
+  const prefix = `${marker}=`;
+  for (const line of prompt.split(/\r?\n/)) {
+    if (!line.startsWith(prefix)) continue;
+    try {
+      return JSON.parse(line.slice(prefix.length));
+    } catch {
+      // Ignore malformed JSON and continue scanning for a valid marker.
+    }
+  }
+
+  return null;
+}
+
+function buildMarkerLine(marker: string, payload: unknown): string {
+  return `${marker}=${JSON.stringify(payload)}`;
+}
+
+function isUltraPlanTargetHint(value: unknown): value is UltraPlanTargetHint {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+
+  const candidate = value as Record<string, unknown>;
+  return isOptionalEnum(candidate.targetType, ULTRAPLAN_CURSOR_TARGETS)
+    && isOptionalNullableEnum(candidate.stack, ULTRAPLAN_STACKS)
+    && isOptionalNullableString(candidate.domainId)
+    && isOptionalNullableEnum(candidate.level, ULTRAPLAN_LEVELS)
+    && isOptionalNullableString(candidate.scenarioId)
+    && isOptionalEnum(candidate.phase, ULTRAPLAN_EXECUTION_PHASES)
+    && isOptionalNullableEnum(candidate.resolvedSlot, ULTRAPLAN_AGENT_SLOT_NAMES)
+    && isOptionalEnum(candidate.actorKind, ["slot"] as const)
+    && isOptionalEnum(candidate.sourceAgent, ["sub-agent"] as const);
+}
+
+function isOptionalEnum<TValue extends string>(
+  value: unknown,
+  allowed: readonly TValue[],
+): value is TValue | undefined {
+  return value === undefined || (typeof value === "string" && allowed.includes(value as TValue));
+}
+
+function isOptionalNullableEnum<TValue extends string>(
+  value: unknown,
+  allowed: readonly TValue[],
+): value is TValue | null | undefined {
+  return value === null || isOptionalEnum(value, allowed);
+}
+
+function isOptionalNullableString(value: unknown): value is string | null | undefined {
+  return value === undefined || value === null || (typeof value === "string" && value.length > 0);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}