@mgiles/perk 3.1.0 → 3.3.0

package/extension/session/lifecycle.ts

@@ -0,0 +1,644 @@
+// The session identity lifecycle (contracts.md §8.2/§8.3) as named, Pi-free session
+// operations: decide what `session_start` should do (claim / fork / adopt / mint / keep) and
+// perform the workflow-state establishment for the decided arm — the ONE combined claim entry
+// with establish-before-consume, the derived fork/adopt identities, the warm mint, and the
+// deliberate keep-arm non-write (reload-generation reconstruction IS the LWW rebuild; no
+// version backfill) — then the two-phase startup facts around the gate: `sessionStartToolScope`
+// (pure; the mode/stage slice the gate syncs from BEFORE any fallible read) and
+// `resolveSessionStartFacts` (post-gate; the lazy launched-stage linkage reconciliation plus the
+// implementation-capture and feedback-receiver inputs), with `sessionTreeFacts` as the
+// navigation twin over the already-rebuilt selected-branch state.
+//
+// Pi-free by construction (importDirectionGuard Rule D): effects arrive through narrow
+// injection points — `SessionStateStore` (the workflow-state slice: rebuild + plain append +
+// the strict verified append), `SessionIdentityPorts` (handoff read/consume, run-scratch
+// isolation, the run-id mint, the §8.3 version stamp), and `SessionStartFactReads` (the handoff
+// + checkout plan-ref reads the post-gate facts may touch). `index.ts` binds the production
+// values, orders the Pi effects, and renders the outcome's per-arm problems/warnings with today's
+// exact report scopes; the strict appends keep reporting through
+// `appendWorkflowStateClassified`'s own loudness channel (the report slice rides
+// `SessionArtifactCtx`, re-exported via `substrate/sessionData.ts` — this module never imports
+// `surfaces/`, `pi/`, or the feedback receiver).
+//
+// ONE handoff authority: every handoff/run-id read — the claim arm's, `decideClaim`'s
+// env-child probe, `resolveRunStage`'s stage lookup, and `deriveForkRunId`'s sibling scan —
+// flows through the injected reads (`SessionIdentityReads`, the read slice of
+// `SessionIdentityPorts`), so the lifecycle is genuinely independent of the cache backing and
+// the fakes never touch disk. The decision logic is byte-identical to its
+// `substrate/workflowState.ts` ancestry.
+
+import type { Handoff, PlanRef } from "../substrate/cache.ts";
+import { type Registry, stageConsumesPlanRef } from "../substrate/registry.ts";
+import type { SessionArtifactCtx } from "../substrate/sessionData.ts";
+import {
+  type AppendWorkflowStateOpts,
+  appendWorkflowStateClassified,
+  branchOf,
+  type ClassifiedAppend,
+  type EntrySink,
+  planRefsEqual,
+  rebuildWorkflowState,
+  WORKFLOW_STATE_TYPE,
+  type WorkflowState,
+} from "../substrate/workflowState.ts";
+
+/**
+ * The exterior reads the lifecycle's decision tier needs — the read slice of
+ * `SessionIdentityPorts` (production bound to `substrate/cache.ts` by `index.ts`; the test
+ * suites bind fakes).
+ */
+export interface SessionIdentityReads {
+  /** The cold-launch handoff blob for `runId`, or null (missing/unreadable). */
+  readHandoff(runId: string): Handoff | null;
+  /** The existing run ids under `scratch/runs/` (the fork/adopt sibling-derivation scan). */
+  listRunIds(): string[];
+}
+
+/**
+ * Derive a fork-child run_id: `<parent>.<n>` where `n` is the max existing sibling + 1
+ * (over the `scratch/runs/` scan), else 1.
+ */
+export function deriveForkRunId(parentRunId: string, runIds: Iterable<string>): string {
+  const prefix = `${parentRunId}.`;
+  let max = 0;
+  for (const id of runIds) {
+    if (!id.startsWith(prefix)) continue;
+    const segment = id.slice(prefix.length).split(".")[0] ?? "";
+    const n = Number.parseInt(segment, 10);
+    if (Number.isInteger(n) && n > max) max = n;
+  }
+  return `${parentRunId}.${max + 1}`;
+}
+
+export type ClaimDecision =
+  | { action: "keep"; source: "session"; state: WorkflowState }
+  | {
+      action: "fork";
+      source: "fork";
+      childRunId: string;
+      parentRunId: string;
+      state: WorkflowState;
+    }
+  | { action: "claim"; source: "env"; runId: string }
+  | {
+      action: "adopt";
+      source: "env-child";
+      childRunId: string;
+      parentRunId: string;
+      /** Inherited from the parent's handoff so read-only gating survives into the child. */
+      mode?: string;
+    }
+  | { action: "none"; source: "none"; state: WorkflowState };
+
+/**
+ * The registry stage id the launched run is acting on, read from its handoff blob, or null.
+ * Only `claim` (cold) and `keep` (reload) sessions have a settled run whose handoff records a
+ * `stage` — a kept session re-reads its run's handoff on every reload, so a consuming stage's
+ * checkout binding is re-read there too; `fork`, `adopt`, and `none` carry no launched stage (an
+ * adopted env-child must never impersonate the launched stage; LWW restores fork/none state
+ * instead). The stage gates whether `session_start` reconciles `cache.plan-ref` into
+ * `active_plan_ref`.
+ */
+export function resolveRunStage(
+  decision: ClaimDecision,
+  reads: Pick<SessionIdentityReads, "readHandoff">,
+): string | null {
+  const runId =
+    decision.action === "claim"
+      ? decision.runId
+      : decision.action === "keep"
+        ? decision.state.run_id
+        : null;
+  if (runId === undefined || runId === null) return null;
+  const stage = reads.readHandoff(runId)?.stage;
+  return typeof stage === "string" && stage !== "" ? stage : null;
+}
+
+/**
+ * Decide what `session_start` should do, from the rebuilt state + the current session handle
+ * + the launch env. Reload vs fork is distinguished by the `run_id ↔ pi_session_id` mapping
+ * (NOT `event.reason`, which is "startup" for a headless `pi --fork`): if the branch already
+ * carries a `run_id` whose recorded `pi_session_id` differs from the current session, the id
+ * was inherited across a fork → derive a child; if it matches (or is absent), it's a reload.
+ * An env-inherited run id whose handoff was already CONSUMED by a different session is a
+ * spawned child, not the launched session → `adopt` (derive a sibling id, inherit `mode`).
+ */
+export function decideClaim(args: {
+  state: WorkflowState;
+  currentSessionId: string | null;
+  envRunId: string | null;
+  reads: SessionIdentityReads;
+}): ClaimDecision {
+  const { state, currentSessionId, envRunId, reads } = args;
+  if (state.run_id !== undefined) {
+    if (state.pi_session_id === undefined || state.pi_session_id === currentSessionId) {
+      return { action: "keep", source: "session", state };
+    }
+    const childRunId = deriveForkRunId(state.run_id, reads.listRunIds());
+    return { action: "fork", source: "fork", childRunId, parentRunId: state.run_id, state };
+  }
+  if (envRunId !== null && envRunId !== "") {
+    // Env-child detection (contracts §8.2): subagent children are spawned as separate `pi`
+    // processes with the parent's env, so they arrive here carrying the parent's PERK_RUN_ID.
+    // A handoff already consumed by a DIFFERENT (or unrecorded) session belongs to someone else:
+    // adopt a derived `<run_id>.<n>` child identity instead of re-claiming — never re-consume the
+    // handoff, never capture pointers, never impersonate the launched stage. The parent's `mode`
+    // is inherited so read-only gating survives into exploration children. Everything else —
+    // absent/corrupt/mismatched handoff (the loud unclaimed error), unconsumed (the normal cold
+    // claim), or consumed by THIS session (idempotent re-claim after lost branch state) — stays
+    // the claim arm.
+    const handoff = reads.readHandoff(envRunId);
+    if (
+      handoff !== null &&
+      handoff.run_id === envRunId &&
+      handoff.consumed === true &&
+      handoff.pi_session_id !== currentSessionId
+    ) {
+      return {
+        action: "adopt",
+        source: "env-child",
+        childRunId: deriveForkRunId(envRunId, reads.listRunIds()),
+        parentRunId: envRunId,
+        mode: handoff.mode,
+      };
+    }
+    return { action: "claim", source: "env", runId: envRunId };
+  }
+  return { action: "none", source: "none", state };
+}
+
+// --------------------------------------------------------------- the identity establishment
+
+/**
+ * The narrow workflow-state store port: the LWW rebuild, the plain (honest-tier, no read-back)
+ * append the fork/adopt arms use, and the strict verified append. ONE port serves both the
+ * identity lifecycle (which verifies `run_id`) and the session engine
+ * (`session/workflowSession.ts`, which verifies each change's own field) — hence the generic
+ * verified append.
+ */
+export interface SessionStateStore {
+  rebuild(): WorkflowState;
+  append(data: WorkflowState): void;
+  appendVerified<K extends keyof WorkflowState>(opts: AppendWorkflowStateOpts<K>): ClassifiedAppend;
+}
+
+/**
+ * The production `SessionStateStore` over the live branch: `EntrySink` appends,
+ * `rebuildWorkflowState` over the branch, and `appendWorkflowStateClassified` for the strict
+ * tier (its report() path stays the loudness channel for read-back failures).
+ */
+export function branchSessionStateStore(
+  sink: EntrySink,
+  source: SessionArtifactCtx,
+): SessionStateStore {
+  return {
+    rebuild: () => rebuildWorkflowState(branchOf(source)),
+    append: (data) => sink.appendEntry(WORKFLOW_STATE_TYPE, data),
+    appendVerified: (opts) => appendWorkflowStateClassified(sink, source, opts),
+  };
+}
+
+/** The exterior effects the lifecycle needs — production bound in `index.ts`, fakes in tests. */
+export interface SessionIdentityPorts extends SessionIdentityReads {
+  /** Mark the handoff consumed (establish-before-consume: called only after a verified claim). */
+  markHandoffConsumed(runId: string, opts: { piSessionId?: string }): void;
+  /** Isolate the derived child's run scratch root (a throw is tolerated — warned, not fatal). */
+  ensureRunScratch(runId: string): void;
+  /** Mint a fresh run_id for the warm identity-less arm. */
+  mintRunId(): string;
+  /**
+   * The §8.3 exact-vintage stamp recorded by every identity-establishing arm
+   * (claim/fork/adopt/mint); undefined (the perkVersion() failure sentinel) drops the key on
+   * serialize and leaves the session on the timestamp-estimate arm.
+   */
+  versionStamp: string | undefined;
+}
+
+/** Which lifecycle arm settled (the failed claim/mint arms both read `unclaimed`). */
+export type SessionIdentityArm = "claimed" | "kept" | "forked" | "adopted" | "minted" | "unclaimed";
+
+/**
+ * What `session_start` consumes downstream: the settled arm, the resolved state the byte-
+ * identical derivations run over (`scopeStage`, `implStage`, the sentinel source —
+ * `arm === "minted" ? "mint" : decision.source`), the decision itself, and the per-arm
+ * problems/warnings the caller renders with today's exact report scopes ("workflow-state
+ * linkage error" `{alsoLog: true}`; "run scratch" warnings).
+ *
+ * A discriminated union on `arm`, correlating each settled arm with exactly the decision that
+ * can produce it: an impossible pair (e.g. `forked` carrying a claim decision) does not
+ * compile, and narrowing on `arm` proves the decision's fields. `unclaimed` is the shared
+ * failure arm of the two strict-append paths — a failed cold claim (`action: "claim"`) or a
+ * failed mint (`action: "none"`); the correlated decision says which.
+ */
+export type EstablishIdentityOutcome = {
+  resolved: WorkflowState;
+  /** Caller-rendered with scope "workflow-state linkage error" (`{alsoLog: true}`). */
+  problems: string[];
+  /** Caller-rendered with scope "run scratch" (`{alsoLog: true}`). */
+  warnings: string[];
+} & (
+  | { arm: "claimed"; decision: Extract<ClaimDecision, { action: "claim" }> }
+  | { arm: "kept"; decision: Extract<ClaimDecision, { action: "keep" }> }
+  | { arm: "forked"; decision: Extract<ClaimDecision, { action: "fork" }> }
+  | { arm: "adopted"; decision: Extract<ClaimDecision, { action: "adopt" }> }
+  | { arm: "minted"; decision: Extract<ClaimDecision, { action: "none" }> }
+  | { arm: "unclaimed"; decision: Extract<ClaimDecision, { action: "claim" | "none" }> }
+);
+
+/** Reflect a captured restriction without participating in identity or handoff authority. */
+export function reflectSessionReadOnlyFloor(
+  store: SessionStateStore,
+  outcome: EstablishIdentityOutcome,
+): { outcome: EstablishIdentityOutcome; unexpectedFailure: boolean } {
+  if (outcome.arm === "unclaimed" || outcome.resolved.mode === "read-only") {
+    return { outcome, unexpectedFailure: false };
+  }
+  let appended: ClassifiedAppend;
+  try {
+    appended = store.appendVerified({
+      data: { mode: "read-only" },
+      field: "mode",
+      expected: "read-only",
+      scope: "child restriction",
+      failure:
+        "could not persist child read-only restriction; in-memory restriction remains active",
+    });
+  } catch {
+    // The Pi edge reports this escaped-contract failure once and continues startup with the floor.
+    return { outcome, unexpectedFailure: true };
+  }
+  return {
+    outcome:
+      appended.status === "applied"
+        ? { ...outcome, resolved: { ...outcome.resolved, mode: "read-only" } }
+        : outcome,
+    unexpectedFailure: false,
+  };
+}
+
+/** The refinement stage id (registry vocabulary; the admission check keys on it). */
+const REFINE_STAGE_ID = "objective-refine";
+
+/** The top-level handoff keys the plan-graph doors use as planning-link / plan-ref inputs. */
+const PLANNING_LINK_KEYS = [
+  "objective_id",
+  "node_id",
+  "adopt_from",
+  "supersedes",
+  "gist_scope",
+  "consumed_learn",
+] as const;
+
+/**
+ * Which planning-link / plan-ref input (if any) an `objective-refine` handoff carries at the
+ * top level — `null` for every non-refinement handoff and for a clean refinement one. A key is
+ * "carried" when present and not null/undefined (an empty `consumed_learn` list is clean).
+ */
+export function refinementHandoffContamination(handoff: Handoff): string | null {
+  if (handoff.stage !== REFINE_STAGE_ID) return null;
+  const carried = PLANNING_LINK_KEYS.filter((key) => {
+    const value = handoff[key];
+    if (value === undefined || value === null) return false;
+    if (Array.isArray(value)) return value.length > 0;
+    return true;
+  });
+  return carried.length === 0 ? null : carried.join(", ");
+}
+
+/**
+ * Establish the session's run identity — the four `session_start` arms as one named operation:
+ *
+ * - **claim** (cold): read the handoff via the port (missing/mismatched ⇒ `unclaimed` with the
+ *   loud problem; never falls through to mint) → build the ONE combined entry (`run_id`,
+ *   `pi_session_id`, `mode`, the `perk_version` stamp, `stage`, and the `objective_node_claim`
+ *   carrier when the handoff's `objective_id`/`node_id` are both non-blank strings) → ONE
+ *   strict append verified on `run_id` → only on verified success, consume the handoff
+ *   (establish-before-consume: a failed read-back ⇒ `unclaimed`, NOT consumed).
+ * - **fork** / **adopt**: isolate the derived child's scratch (a throw is a warning; identity
+ *   still settles) → the derived-identity append — plain appends (honest tier, no read-back).
+ *   Fork inherits the parent's `mode` and NO `stage` (LWW carries the parent's); adopt takes
+ *   `mode` from the handoff and never impersonates stage or claim (and never re-consumes).
+ * - **mint** (`none`): mint a run_id → strict append verified on `run_id`; a failed read-back
+ *   leaves the session unidentified (`unclaimed` — re-mints next `session_start`).
+ * - **keep** (reload): NO append — reload-generation reconstruction IS the LWW rebuild, and the
+ *   deliberate no-version-backfill non-write is preserved.
+ */
+export function establishSessionIdentity(
+  store: SessionStateStore,
+  ports: SessionIdentityPorts,
+  input: { currentSessionId: string | null; envRunId: string | null },
+): EstablishIdentityOutcome {
+  const problems: string[] = [];
+  const warnings: string[] = [];
+  const currentSessionId = input.currentSessionId;
+  const decision = decideClaim({
+    state: store.rebuild(),
+    currentSessionId,
+    envRunId: input.envRunId,
+    reads: ports,
+  });
+  const stamp = ports.versionStamp;
+
+  if (decision.action === "claim") {
+    // Cold claim — establish before consume (strict).
+    const handoff = ports.readHandoff(decision.runId);
+    if (handoff === null || handoff.run_id !== decision.runId) {
+      problems.push(`handoff missing or mismatched for run ${decision.runId}`);
+      return { arm: "unclaimed", resolved: {}, decision, problems, warnings };
+    }
+    // Refinement admission (contracts.md §8.67): the isolated `objective-refine` stage must
+    // never arrive carrying a planning link or plan-ref input — those top-level keys are what
+    // the claim arm below (and the plan-save recovery paths) read as a planning claim /
+    // adoption. A contaminated refinement handoff is REFUSED before any claim is recorded and
+    // is NOT consumed (the door that wrote it is the defect; nothing here rebinds or clears).
+    // Ordinary objective-plan handoffs (which legitimately carry objective_id/node_id) are
+    // untouched.
+    const contamination = refinementHandoffContamination(handoff);
+    if (contamination !== null) {
+      problems.push(
+        `refusing the objective-refine handoff for run ${decision.runId}: it carries ${contamination} (a planning link/plan-ref input a refinement session never accepts)`,
+      );
+      return { arm: "unclaimed", resolved: {}, decision, problems, warnings };
+    }
+    // The objective-plan cold door's handoff_extra carries the node link
+    // (objective_id/node_id): persist it as the objective_node_claim so the implement-here
+    // exits are structurally suppressed in COLD objective-plan sessions too (the warm
+    // `objective_node` tool records the claim; a cold factory session never calls it — the
+    // door marked the node before launch). Blank/absent ids persist nothing; the claim
+    // clears on a successful node-linked save exactly as the warm-recorded one does.
+    const handoffObjective = handoff.objective_id;
+    const handoffNode = handoff.node_id;
+    const nodeClaim =
+      typeof handoffObjective === "string" &&
+      handoffObjective.trim() !== "" &&
+      typeof handoffNode === "string" &&
+      handoffNode.trim() !== ""
+        ? { objective: handoffObjective, node: handoffNode }
+        : undefined;
+    const data: WorkflowState = {
+      run_id: decision.runId,
+      pi_session_id: currentSessionId ?? undefined,
+      mode: handoff.mode,
+      perk_version: stamp,
+      // Record the launched stage so the interior can tell e.g. objective-author from plan
+      // (both are read-only) and inject the right authoring context.
+      stage: handoff.stage,
+      ...(nodeClaim !== undefined ? { objective_node_claim: nodeClaim } : {}),
+    };
+    const appended = store.appendVerified({
+      data,
+      field: "run_id",
+      expected: decision.runId,
+      scope: "workflow-state linkage error",
+      failure: `read-back failed for run ${decision.runId}`,
+    });
+    if (appended.status !== "applied") {
+      // do NOT consume — the strict-append seam already reported the failure loudly.
+      return { arm: "unclaimed", resolved: {}, decision, problems, warnings };
+    }
+    ports.markHandoffConsumed(decision.runId, { piSessionId: currentSessionId ?? undefined });
+    return { arm: "claimed", resolved: data, decision, problems, warnings };
+  }
+
+  if (decision.action === "fork" || decision.action === "adopt") {
+    // Inherited/adopted run identity → isolate the child's scratch. A static redirect or
+    // filesystem failure is loud but does not prevent the derived workflow identity from
+    // settling; later eligible turns retry through the agent-scratch resolver. The adopt arm
+    // mirrors fork minus everything that belongs to the launched session (contracts §8.2):
+    // never re-consume the handoff, no `stage` (no stage impersonation), no claim.
+    try {
+      ports.ensureRunScratch(decision.childRunId);
+    } catch (error) {
+      const kind = decision.action === "fork" ? "fork" : "adopted";
+      warnings.push(
+        `could not create ${kind} run root for ${decision.childRunId}: ${String(error)}`,
+      );
+    }
+    const data: WorkflowState = {
+      run_id: decision.childRunId,
+      pi_session_id: currentSessionId ?? undefined,
+      predecessor: decision.parentRunId,
+      mode: decision.action === "fork" ? decision.state.mode : decision.mode,
+      perk_version: stamp,
+    };
+    store.append(data);
+    if (decision.action === "fork") {
+      return { arm: "forked", resolved: data, decision, problems, warnings };
+    }
+    return { arm: "adopted", resolved: data, decision, problems, warnings };
+  }
+
+  if (decision.action === "none") {
+    // A warm session with no identity mints its own run_id so per-run state (the session data
+    // dir) can key off it. No disk artifacts — dirs are the accessor's job; provenance is
+    // recorded separately. A failed cold claim above never falls here (claim stays a loud
+    // unclaimed error).
+    const runId = ports.mintRunId();
+    const data: WorkflowState = {
+      run_id: runId,
+      pi_session_id: currentSessionId ?? undefined,
+      perk_version: stamp,
+    };
+    const appended = store.appendVerified({
+      data,
+      field: "run_id",
+      expected: runId,
+      scope: "workflow-state linkage error",
+      failure: `read-back failed for minted run ${runId}`,
+    });
+    if (appended.status === "applied") {
+      return {
+        arm: "minted",
+        resolved: { ...decision.state, ...data },
+        decision,
+        problems,
+        warnings,
+      };
+    }
+    // Loud-but-non-fatal (the seam reported): the session stays unidentified and re-mints on
+    // the next session_start.
+    return { arm: "unclaimed", resolved: decision.state, decision, problems, warnings };
+  }
+
+  // keep (reload): NO append — reload-generation reconstruction IS the LWW rebuild; the
+  // deliberate no-version-backfill non-write is preserved (§8.3: an LWW backfill would
+  // mis-stamp an old session with today's version).
+  return { arm: "kept", resolved: decision.state, decision, problems, warnings };
+}
+
+// ------------------------------------------------------------- the two-phase startup facts
+
+/**
+ * PHASE 1 (before the gate) — the tool-scope slice `gating.syncFromState` consumes, derived
+ * PURELY from the established identity: no store, handoff, registry, or checkout read can sit
+ * between identity establishment and gate synchronization (a read failure must never leave the
+ * gate unsynced). Mode is exactly the resolved mode (after optional floor reflection). The scope
+ * stage is the workflow-state `stage` key (§8.40): claim → the handoff-recorded stage just
+ * appended; keep/none → the branch-LWW stage; fork INHERITS the parent's stage (a forked
+ * implement session is an implement session); adopt NEVER impersonates (a subagent child's
+ * fresh branch carries no stage, so `session_tree` agrees). A failed claim leaves `resolved`
+ * empty → no stage → unscoped (stage scoping is fail-open). No stage validation or
+ * normalization — an unknown stage id passes through as-is.
+ */
+export function sessionStartToolScope(
+  identity: EstablishIdentityOutcome,
+): Pick<WorkflowState, "mode" | "stage"> {
+  const { resolved, decision } = identity;
+  const stage =
+    decision.action === "adopt"
+      ? undefined
+      : (resolved.stage ?? (decision.action === "fork" ? decision.state.stage : undefined));
+  return { mode: resolved.mode, stage };
+}
+
+/**
+ * The exterior reads the post-gate facts may touch — the handoff (the launched-stage authority
+ * for claim/keep) and the checkout `cache.plan-ref` (read ONLY on the consuming arm). Production
+ * binds both cwd-bound in `index.ts`; the suites bind recording fakes.
+ */
+export interface SessionStartFactReads extends Pick<SessionIdentityReads, "readHandoff"> {
+  /** The worktree's `cache.plan-ref` selector, or null (missing/unreadable). */
+  readPlanRef(): PlanRef | null;
+}
+
+/**
+ * The receiver-shaped feedback inputs both startup and navigation derive. Deliberately a local,
+ * inferred structural shape (no shared vocabulary with `hunkFeedback/receiver.ts`): the
+ * `index.ts` call site adds Pi's run `mode` and the receiver's own `ReceiverSyncArgs` accepts
+ * the result structurally. Eligibility stays receiver-owned (its fresh checkout read included).
+ */
+interface SessionFeedbackFacts {
+  stage: string | null;
+  adopted: boolean;
+  runId: string | null;
+  piSessionId: string | null;
+  activePlanRef: PlanRef | null;
+}
+
+/**
+ * PHASE 2 (after the gate and the claimed-only refinement import) — the lazy linkage
+ * reconciliation plus the derived capture/feedback inputs. `resolved` is the same
+ * `WorkflowState`-shaped diagnostic startup always produced (the T3 sentinel's material) —
+ * lifecycle-local, not a feature-facing snapshot.
+ */
+export interface SessionStartFacts {
+  resolved: WorkflowState;
+  /** Present only for an identified implement session (launched or fork-inherited stage). */
+  implementationCapture: { runId: string; parentSessionId: string | null } | null;
+  feedback: SessionFeedbackFacts;
+}
+
+/**
+ * The post-gate startup facts. Operation order (each step's port is the only one it touches):
+ *
+ * 1. Rebuild the live linked `active_plan_ref` ONCE (the store), before any handoff read.
+ * 2. Resolve the launched stage through the handoff reader — claim/keep only (`resolveRunStage`);
+ *    fork/adopt/none never read a stage handoff here.
+ * 3. Registry admission: only a non-null launched stage can consume the checkout ref
+ *    (`stageConsumesPlanRef`); a null registry stays PERMISSIVE when a stage is present (to
+ *    preserve implement linkage); an unknown stage in an available registry does not consume.
+ * 4. On the consuming arm ONLY, read the checkout `cache.plan-ref`: same `(provider, pr_id)`
+ *    keeps the existing linked object without appending; a different ref performs ONE strict
+ *    verified append (`active_plan_ref`, `planRefsEqual`, the "workflow-state linkage error"
+ *    scope) and folds the new ref in ONLY on `applied` — a rejected/unverified append leaves
+ *    `resolved` exactly as it arrived (a kept session keeps its LWW ref; a fresh claim keeps
+ *    none — never flattened, never rebuilt again to manufacture a fallback); no cached ref
+ *    preserves a non-null linked ref. A non-consuming (or absent) launched stage preserves a
+ *    non-null linked ref WITHOUT reading the checkout — the root selector must not leak in.
+ * 5. The implementation stage is the launched stage, with only a fork falling back to its
+ *    parent's LWW stage; `implementationCapture` exists only for a truthy run id on
+ *    `stage === "implement"` (parent provenance comes only from the fork decision).
+ * 6. `feedback` carries the implementation stage, the decision's adoption, the resolved
+ *    run/ref, and startup's CURRENT Pi session handle (never an inherited branch handle).
+ *
+ * A throwing store/read propagates to the caller (Pi's hook error boundary) — unreadability is
+ * never turned into confirmed absence, and no later effect runs from guessed facts.
+ */
+export function resolveSessionStartFacts(
+  store: SessionStateStore,
+  reads: SessionStartFactReads,
+  input: {
+    identity: EstablishIdentityOutcome;
+    /** The already-loaded registry (null when it failed to load) — never a loader. */
+    registry: Registry | null;
+    currentSessionId: string | null;
+  },
+): SessionStartFacts {
+  const { identity, registry, currentSessionId } = input;
+  const decision = identity.decision;
+  let resolved: WorkflowState = identity.resolved;
+
+  const linked = store.rebuild().active_plan_ref ?? null;
+  const launchedStage = resolveRunStage(decision, reads);
+  const consumesPlanRef =
+    launchedStage !== null && (registry === null || stageConsumesPlanRef(registry, launchedStage));
+  if (consumesPlanRef) {
+    const cachedRef = reads.readPlanRef();
+    if (cachedRef !== null) {
+      if (planRefsEqual(linked, cachedRef)) {
+        resolved = { ...resolved, active_plan_ref: linked };
+      } else {
+        const appended = store.appendVerified({
+          data: { active_plan_ref: cachedRef },
+          field: "active_plan_ref",
+          expected: cachedRef,
+          scope: "workflow-state linkage error",
+          failure: `plan-ref read-back failed for ${cachedRef.provider}:${cachedRef.pr_id}`,
+          equals: planRefsEqual,
+        });
+        if (appended.status === "applied") resolved = { ...resolved, active_plan_ref: cachedRef };
+      }
+    } else if (linked !== null) {
+      resolved = { ...resolved, active_plan_ref: linked };
+    }
+  } else if (linked !== null) {
+    resolved = { ...resolved, active_plan_ref: linked };
+  }
+
+  const implementationStage =
+    launchedStage ?? (decision.action === "fork" ? (decision.state.stage ?? null) : null);
+  const implementationCapture =
+    resolved.run_id && implementationStage === "implement"
+      ? {
+          runId: resolved.run_id,
+          parentSessionId:
+            decision.action === "fork" ? (decision.state.pi_session_id ?? null) : null,
+        }
+      : null;
+
+  return {
+    resolved,
+    implementationCapture,
+    feedback: {
+      stage: implementationStage,
+      adopted: decision.action === "adopt",
+      runId: resolved.run_id ?? null,
+      piSessionId: currentSessionId,
+      activePlanRef: resolved.active_plan_ref ?? null,
+    },
+  };
+}
+
+/**
+ * The navigation twin (`session_tree`), PURE over the ONE already-rebuilt selected-branch state:
+ * tool scope is the branch's per-field-LWW mode/stage (the §8.40 key); feedback uses the
+ * branch's stage/run/ref AND ITS OWN recorded session id (not startup's current-handle
+ * override) with `adopted: false` — an env-adopted child's fresh branch carries no stage, so the
+ * stage gate alone keeps it receiver-ineligible. No handoff/checkout read, claim, linkage, or
+ * implementation capture happens on navigation (a deliberate asymmetry with startup).
+ */
+export function sessionTreeFacts(state: WorkflowState): {
+  toolScope: Pick<WorkflowState, "mode" | "stage">;
+  feedback: SessionFeedbackFacts;
+} {
+  return {
+    toolScope: { mode: state.mode, stage: state.stage },
+    feedback: {
+      stage: state.stage ?? null,
+      adopted: false,
+      runId: state.run_id ?? null,
+      piSessionId: state.pi_session_id ?? null,
+      activePlanRef: state.active_plan_ref ?? null,
+    },
+  };
+}