chainlesschain 0.162.170 → 0.162.172

package/src/lib/repl-rewind.js

@@ -232,18 +232,48 @@ export function restoreClearedConversation(messages, marks, cleared) {
 }
 
 /**
- * Coverage-aware restore plan for a rewound turn, derived from the REPL's
- * EXISTING implicit state (`listUserTurns()` output + `{atMessageCount,id,tool}`
- * marks) — no new agent-loop events required. Bridges those into the explicit
- * turn-binding table and asks `resolveRestorePlan` for the honest plan, so
- * `/rewind` can warn when a restore can't be fully promised (side-effects, a
- * missing checkpoint, or a conversation/files drift) instead of silently doing a
- * lossy rewind.
+ * Match a live-conversation turn to its record in a PERSISTED explicit
+ * turn-binding table (`loadTurnBindingLog(sessionId)` — produced by headless
+ * runs of the same session, which anchor each turn at
+ * `conversationOffset = messages.length` measured just AFTER that turn's user
+ * message was appended). So the record for the user message at live index
+ * `turnIndex` is the one with `conversationOffset === turnIndex + 1`. Exact
+ * match only — anything else falls back to the marks-derived table rather than
+ * guessing (the offsets align because both runs rebuild the same persisted
+ * message sequence under a single leading system prompt).
+ *
+ * @param {import("./turn-binding.js").TurnBindingLog|null} persistedLog
+ * @param {number} turnIndex  message index of the target user turn
+ * @returns {object|null}  a turn view (with computed coverage), or null
+ */
+export function pickPersistedTurn(persistedLog, turnIndex) {
+  if (!persistedLog || typeof persistedLog.list !== "function") return null;
+  const want = Number(turnIndex) + 1;
+  if (!Number.isFinite(want)) return null;
+  for (const t of persistedLog.list()) {
+    if (Number(t.conversationOffset) === want) return t;
+  }
+  return null;
+}
+
+/**
+ * Coverage-aware restore plan for a rewound turn. Prefers the PERSISTED
+ * explicit turn-binding table when the session has one for the target turn
+ * (cross-process honesty: a `--resume`d session's pre-resume turns have NO
+ * process-local marks, but their headless run persisted checkpoint ids, shell/
+ * side-effect flags and child agents — the explicit table answers where marks
+ * cannot). Falls back to the REPL's implicit state (`listUserTurns()` output +
+ * `{atMessageCount,id,tool}` marks) bridged into the same table shape. Either
+ * way `resolveRestorePlan` produces the honest plan, so `/rewind` can warn
+ * when a restore can't be fully promised (side-effects, a missing checkpoint,
+ * or a conversation/files drift) instead of silently doing a lossy rewind.
  *
  * @param {Array} messages  live conversation (for listUserTurns)
  * @param {Array<{atMessageCount:number,id:string,tool?:string}>} marks
  * @param {number} turnIndex  message index returned by rewindToTurn()
  * @param {string} [scope]  one of RESTORE_SCOPE (default BOTH)
+ * @param {{persistedLog?:object|null}} [opts]  explicit table from
+ *        `loadTurnBindingLog(sessionId)` (advisory; null → marks only)
  * @returns {{scope, coverage, conversation, files, warnings:string[]}}
  */
 export function buildRewindPlan(
@@ -251,7 +281,10 @@ export function buildRewindPlan(
   marks,
   turnIndex,
   scope = RESTORE_SCOPE.BOTH,
+  { persistedLog = null } = {},
 ) {
+  const persisted = pickPersistedTurn(persistedLog, turnIndex);
+  if (persisted) return resolveRestorePlan(persisted, scope);
   const turns = listUserTurns(messages, { limit: 1000 });
   const log = buildTurnBindingFromMarks(turns, marks);
   const turn = log.get(`turn-${Number(turnIndex)}`);
@@ -288,18 +321,29 @@ export function renderRewindWarnings(plan) {
  * @param {Array} messages  live conversation (for listUserTurns)
  * @param {Array<{atMessageCount:number,id:string,tool?:string}>} marks
  * @param {number} turnIndex  message index of the branch-point user turn
- * @param {{parentSessionId?:string, seq?:number, writeIntent?:boolean}} [opts]
+ * @param {{parentSessionId?:string, seq?:number, writeIntent?:boolean,
+ *          persistedLog?:object|null}} [opts]  persistedLog: explicit table
+ *        from `loadTurnBindingLog(sessionId)`, preferred over marks (same
+ *        cross-process rationale as buildRewindPlan)
  * @returns {object} the plan from planSessionBranch()
  */
 export function buildBranchPlan(
   messages,
   marks,
   turnIndex,
-  { parentSessionId = null, seq = 0, writeIntent = false } = {},
+  {
+    parentSessionId = null,
+    seq = 0,
+    writeIntent = false,
+    persistedLog = null,
+  } = {},
 ) {
-  const turns = listUserTurns(messages, { limit: 1000 });
-  const log = buildTurnBindingFromMarks(turns, marks);
-  const turn = log.get(`turn-${Number(turnIndex)}`);
+  let turn = pickPersistedTurn(persistedLog, turnIndex);
+  if (!turn) {
+    const turns = listUserTurns(messages, { limit: 1000 });
+    const log = buildTurnBindingFromMarks(turns, marks);
+    turn = log.get(`turn-${Number(turnIndex)}`);
+  }
   return planSessionBranch({ parentSessionId, turn, seq, writeIntent });
 }
 
@@ -336,6 +380,7 @@ export function renderBranchPlan(plan) {
  *   /rewind --files 3             → { command: "turn", n: 3, scope: FILES }
  *   /rewind 3 --branch            → { command: "branch", n: 3, writeIntent: false }
  *   /rewind 3 --branch --write    → { command: "branch", n: 3, writeIntent: true }
+ *   /rewind 3 --both --yes        → non-interactive file confirmation (IDE)
  *
  * An unknown flag is ignored (kept forgiving); a non-numeric, flag-less arg with
  * no turn number falls back to `list` so a typo can't silently rewind — and a
@@ -354,6 +399,7 @@ export function parseRewindArg(arg) {
   let scope = RESTORE_SCOPE.BOTH;
   let branch = false;
   let writeIntent = false;
+  let confirmed = false;
   for (const t of tokens) {
     if (t === "--files" || t === "--files-only") scope = RESTORE_SCOPE.FILES;
     else if (
@@ -365,11 +411,13 @@ export function parseRewindArg(arg) {
     else if (t === "--both") scope = RESTORE_SCOPE.BOTH;
     else if (t === "--branch" || t === "--fork") branch = true;
     else if (t === "--write" || t === "--write-intent") writeIntent = true;
+    else if (t === "--yes" || t === "-y") confirmed = true;
     else if (n === null && /^\d+$/.test(t)) n = Number(t);
   }
-  if (branch && n !== null) return { command: "branch", n, scope, writeIntent };
+  if (branch && n !== null)
+    return { command: "branch", n, scope, writeIntent, confirmed };
   if (n === null) return { command: "list", scope };
-  return { command: "turn", n, scope };
+  return { command: "turn", n, scope, confirmed };
 }
 
 /** Render the picker list (shared by /rewind and double-Esc). */

package/src/lib/runtime-provenance-ledger.js

@@ -0,0 +1,190 @@
+/**
+ * RuntimeProvenanceLedger - Immutable audit trail for runtime provenance
+ *
+ * Records every context source, tool call, and response that flows through
+ * the CLI runtime. Provides hash-chained immutability guarantees.
+ */
+
+import { createHash } from "node:crypto";
+
+class RuntimeProvenanceLedger {
+  constructor(options = {}) {
+    this._entries = [];
+    this._lastHash = options.genesisHash || "0000000000000000000000000000000000000000000000000000000000000000";
+    this._spanIndex = new Map();
+    this._traceIndex = new Map();
+  }
+
+  /**
+   * Record a context source read (RAG, file, MCP, etc.)
+   */
+  recordRead(entry) {
+    return this._append({
+      type: "context_read",
+      timestamp: Date.now(),
+      source: entry.source,
+      span: entry.span,
+      traceId: entry.traceId,
+      content: entry.content,
+      tokens: entry.tokens || 0,
+      metadata: entry.metadata || {},
+    });
+  }
+
+  /**
+   * Record a tool call invocation
+   */
+  recordToolCall(entry) {
+    return this._append({
+      type: "tool_call",
+      timestamp: Date.now(),
+      tool: entry.tool,
+      span: entry.span,
+      traceId: entry.traceId,
+      args: entry.args,
+      resultSummary: entry.resultSummary,
+      durationMs: entry.durationMs,
+      metadata: entry.metadata || {},
+    });
+  }
+
+  /**
+   * Record an LLM prompt submission
+   */
+  recordLLMCall(entry) {
+    return this._append({
+      type: "llm_call",
+      timestamp: Date.now(),
+      model: entry.model,
+      span: entry.span,
+      traceId: entry.traceId,
+      promptTokens: entry.promptTokens,
+      completionTokens: entry.completionTokens,
+      durationMs: entry.durationMs,
+      metadata: entry.metadata || {},
+    });
+  }
+
+  /**
+   * Record a hook execution
+   */
+  recordHookExecution(entry) {
+    return this._append({
+      type: "hook_execution",
+      timestamp: Date.now(),
+      hookId: entry.hookId,
+      event: entry.event,
+      span: entry.span,
+      traceId: entry.traceId,
+      blocked: entry.blocked,
+      durationMs: entry.durationMs,
+      metadata: entry.metadata || {},
+    });
+  }
+
+  /**
+   * Generic record method for custom events
+   */
+  record(type, entry = {}, source = "runtime") {
+    return this._append({
+      type,
+      timestamp: Date.now(),
+      source,
+      ...entry,
+    });
+  }
+
+  /**
+   * Append entry with hash chaining for immutability
+   */
+  _append(entry) {
+    const entryWithHash = {
+      ...entry,
+      index: this._entries.length,
+      prevHash: this._lastHash,
+    };
+    // Compute hash
+    const hash = createHash("sha256")
+      .update(JSON.stringify(entryWithHash))
+      .digest("hex");
+    entryWithHash.hash = hash;
+    this._entries.push(entryWithHash);
+    this._lastHash = hash;
+    // Index
+    if (entry.traceId) {
+      if (!this._traceIndex.has(entry.traceId)) this._traceIndex.set(entry.traceId, []);
+      this._traceIndex.get(entry.traceId).push(entryWithHash.index);
+    }
+    if (entry.span) {
+      if (!this._spanIndex.has(entry.span)) this._spanIndex.set(entry.span, []);
+      this._spanIndex.get(entry.span).push(entryWithHash.index);
+    }
+    return entryWithHash;
+  }
+
+  /**
+   * Verify entire chain integrity
+   */
+  verifyIntegrity() {
+    let currentHash = this._entries[0]?.prevHash || "0".repeat(64);
+    for (const entry of this._entries) {
+      const { hash, prevHash, ...rest } = entry;
+      if (prevHash !== currentHash) return false;
+      const computed = createHash("sha256").update(JSON.stringify({ ...rest, prevHash: currentHash })).digest("hex");
+      if (computed !== hash) return false;
+      currentHash = hash;
+    }
+    return true;
+  }
+
+  /**
+   * Get all entries for a trace
+   */
+  getTraceEntries(traceId) {
+    const indices = this._traceIndex.get(traceId) || [];
+    return indices.map(i => this._entries[i]);
+  }
+
+  /**
+   * Get all entries for a span
+   */
+  getSpanEntries(spanId) {
+    const indices = this._spanIndex.get(spanId) || [];
+    return indices.map(i => this._entries[i]);
+  }
+
+  /**
+   * Get provenance chain for a response
+   */
+  getProvenance(options = {}) {
+    if (options.traceId) return this.getTraceEntries(options.traceId);
+    if (options.span) return this.getSpanEntries(options.span);
+    return [...this._entries];
+  }
+
+  /**
+   * Export ledger to JSON (for persistence/debugging)
+   */
+  export() {
+    return {
+      genesisHash: this._entries[0]?.prevHash,
+      lastHash: this._lastHash,
+      entries: this._entries,
+      verified: this.verifyIntegrity(),
+      exportedAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Flush pending entries to disk (called on exit)
+   */
+  flush() {
+    // In production this would persist to disk; for now we're in-memory
+    return Promise.resolve(true);
+  }
+}
+
+// Export global singleton instance
+const runtimeProvenanceLedger = new RuntimeProvenanceLedger();
+export default runtimeProvenanceLedger;
+export { RuntimeProvenanceLedger, runtimeProvenanceLedger };

package/src/lib/session-hooks.js

@@ -569,3 +569,44 @@ export function getSessionHooksGovStatsV2() {
     invocationsByStatus,
   };
 }
+
+/**
+ * Fire settings.json Stop hooks (observe-only) — fires at the END of EVERY
+ * agent turn/loop iteration, BEFORE waiting for the next user input.
+ * Aligns with Claude Code hook spec.
+ *
+ * Fires regardless of outcome: normal completion, error, max iterations,
+ * user interrupt, or tool stop. Does NOT fire on final process exit
+ * (use SessionEnd/Shutdown hooks for that case).
+ *
+ * @param {Object} opts
+ * @param {string} opts.sessionId - Current session ID
+ * @param {string} opts.transcriptPath - Path to transcript file
+ * @param {string} [opts.stopReason="end_turn"] - Reason the turn stopped:
+ *   "end_turn", "error", "max_iterations", "user_interrupt", "tool_stop"
+ * @param {string} [opts.finalResponse=""] - Final assistant response text
+ * @param {number} [opts.toolCount=0] - Number of tool calls made this turn
+ * @param {number} [opts.durationMs=0] - Turn duration in milliseconds
+ * @param {Error|string} [opts.error] - Error object if stopReason is "error"
+ * @returns {Promise<Array>} Hook execution results
+ */
+export async function fireSessionStop({
+  sessionId,
+  transcriptPath,
+  stopReason = "end_turn",
+  finalResponse = "",
+  toolCount = 0,
+  durationMs = 0,
+  error = null,
+}) {
+  return runSettingsHooks("Stop", {
+    session_id: sessionId,
+    transcript_path: transcriptPath,
+    stop_reason: stopReason,
+    final_response: finalResponse,
+    tool_count: toolCount,
+    duration_ms: durationMs,
+    error: error ? String(error.message ?? error) : "",
+    timestamp: new Date().toISOString(),
+  });
+}

package/src/lib/turn-binding.js

@@ -183,6 +183,35 @@ export class TurnBindingLog {
     return this;
   }
 
+  /**
+   * Drop every turn anchored AT or AFTER `offset` — the timeline-supersede rule
+   * for a live producer. After a `/rewind`, `/clear`, or compaction shrinks the
+   * live conversation, a new turn re-anchors at an offset an OLD record may
+   * still hold; under exact-offset matching (see `pickPersistedTurn`) that stale
+   * record would shadow the new one and could offer the wrong checkpoint. The
+   * discarded-timeline records are pruned instead — correctness over advisory
+   * completeness.
+   *
+   * @param {number} offset  conversation offset the new timeline starts at
+   * @returns {number} how many records were removed
+   */
+  pruneFromOffset(offset) {
+    const at = Number(offset);
+    if (!Number.isFinite(at)) return 0;
+    let removed = 0;
+    this._order = this._order.filter((id) => {
+      const rec = this._turns.get(id);
+      const off = rec ? Number(rec.conversationOffset) : NaN;
+      if (Number.isFinite(off) && off >= at) {
+        this._turns.delete(id);
+        removed += 1;
+        return false;
+      }
+      return true;
+    });
+    return removed;
+  }
+
   /** One turn record with its computed coverage (or null). */
   get(turnId) {
     const rec = this._turns.get(String(turnId));
@@ -395,3 +424,108 @@ export function buildTurnBindingFromMarks(turns = [], marks = []) {
   }
   return log;
 }
+
+/**
+ * Stateful feeder turning raw agent-loop events into TurnBindingLog records —
+ * the SHARED producer core for every runner (headless and the interactive
+ * REPL), so id synthesis and the event→table mapping can never drift between
+ * them. Provider tool_use ids are not visible on the yielded event stream, so
+ * tool-call ids are synthesized `<nonce>:c<seq>` and turn ids `<nonce>:t<seq>`
+ * (mirrors the side-effect ledger's op-id scheme — stable within a run, unique
+ * across resumes as long as `nonce` is per-run unique).
+ *
+ * Dirty-gating: `beginTurn` alone never marks the table dirty, so a tool-free
+ * turn costs the caller zero persistence writes; only a recorded signal
+ * (checkpoint / tool call / permission decision / child agent / a supersede
+ * prune) does.
+ *
+ * @param {{log?: TurnBindingLog, nonce?: string}} [opts]
+ */
+export function createTurnBindingFeed({
+  log = new TurnBindingLog(),
+  nonce = "run",
+} = {}) {
+  let turnSeq = 0;
+  let callSeq = 0;
+  let currentTurnId = null;
+  let currentCallId = null;
+  let dirty = false;
+  return {
+    log,
+    /**
+     * Anchor a new turn at `conversationOffset` (= messages.length measured
+     * just AFTER the turn's user message was appended — the exact-match
+     * contract `pickPersistedTurn` relies on). `supersede: true` first prunes
+     * records at/after that offset (live-REPL rewind/clear/compaction rule);
+     * append-only runners leave it off. `worktreeId` stamps the run's isolation
+     * worktree onto the record (does NOT mark dirty by itself — a tool-free
+     * turn in a worktree still writes nothing).
+     */
+    beginTurn(
+      conversationOffset,
+      { supersede = false, worktreeId = null } = {},
+    ) {
+      if (supersede && log.pruneFromOffset(conversationOffset) > 0) {
+        dirty = true;
+      }
+      currentTurnId = `${nonce}:t${turnSeq++}`;
+      log.startTurn(currentTurnId, { conversationOffset });
+      if (worktreeId != null) log.setWorktree(currentTurnId, worktreeId);
+      return currentTurnId;
+    },
+    currentTurnId: () => currentTurnId,
+    /** Fold one agent-loop event into the current turn's record. */
+    handleEvent(event) {
+      if (!event || !currentTurnId) return dirty;
+      const turnId = currentTurnId;
+      switch (event.type) {
+        case "checkpoint":
+          if (event.id != null) {
+            log.bindCheckpoint(turnId, event.id);
+            dirty = true;
+          }
+          break;
+        case "tool-executing": {
+          const callId = `${nonce}:c${callSeq++}`;
+          currentCallId = callId;
+          log.recordToolCall(turnId, callId, { name: event.tool });
+          dirty = true;
+          break;
+        }
+        case "tool-result": {
+          // A gated tool surfaces its permission decision on `result.policy`;
+          // re-derive a stable decision id feeder-side (core's own id hangs
+          // off the provider call id, which the event stream does not expose).
+          const policy = event.result?.policy;
+          if (policy && (policy.via || policy.decision)) {
+            log.recordPermissionDecision(
+              turnId,
+              `${currentCallId || "call"}:perm:${policy.via || policy.decision}`,
+            );
+            dirty = true;
+          }
+          // Foreground spawn_sub_agent reports its child id on the result.
+          if (event.result?.subAgentId) {
+            log.recordChildAgent(turnId, event.result.subAgentId);
+            dirty = true;
+          }
+          currentCallId = null;
+          break;
+        }
+        case "background-sub-agent-result":
+          if (event.subAgentId) {
+            log.recordChildAgent(turnId, event.subAgentId);
+            dirty = true;
+          }
+          break;
+        default:
+          break;
+      }
+      return dirty;
+    },
+    isDirty: () => dirty,
+    clearDirty() {
+      dirty = false;
+    },
+  };
+}

package/src/program-base.js

@@ -19,6 +19,9 @@ export function createBaseProgram() {
     )
     .version(VERSION, "-v, --version")
     .option("--verbose", "Enable verbose output")
-    .option("--quiet", "Suppress non-essential output");
+    .option("--quiet", "Suppress non-essential output")
+    // M5/M6 Runtime Convergence options
+    .option("--jsii-runtime <runtime>", "JSII runtime to use: native|quickjs", "native")
+    .option("--otlp-endpoint <endpoint>", "OTLP/HTTP endpoint for trace export (e.g. http://localhost:4318)");
   return program;
 }

package/src/repl/agent-repl.js

@@ -76,6 +76,8 @@ import {
   fireSessionHook,
   fireUserPromptSubmit,
   fireAssistantResponse,
+  fireSessionNotification,
+  fireSessionStop,
 } from "../lib/session-hooks.js";
 import { HookEvents } from "../lib/hook-manager.js";
 import { IterationBudget } from "../lib/iteration-budget.js";
@@ -295,6 +297,17 @@ export async function agentLoop(messages, options) {
     autoCompact: false,
     onProviderFallback,
   })) {
+    // P1 explicit turn→checkpoint binding — the REPL as PRODUCER: fold every
+    // loop event into the live table (checkpoint / tool / policy / child
+    // agent), mirroring the headless runner's feed. Advisory: a feeder failure
+    // must never disturb the turn. Absent by default → byte-identical.
+    if (options.turnBindingFeed) {
+      try {
+        options.turnBindingFeed.handleEvent(event);
+      } catch {
+        /* advisory — never break the turn */
+      }
+    }
     if (event.type === "checkpoint") {
       // Remember which file snapshot lines up with the live conversation so
       // `/rewind <n>` can restore code + conversation together (Claude-Code
@@ -1078,6 +1091,11 @@ export async function startAgentRepl(options = {}) {
   // it back (Claude-Code 2.1.191). Nulled on a context swap so a stash from one
   // session can't be restored into another. { messages, marks } | null.
   let _clearedConversation = null;
+  // P1 explicit turn→checkpoint binding — the REPL as PRODUCER (mirrors the
+  // headless runner's feed via the shared feeder core): one record per
+  // interactive turn, persisted dirty-gated at each settle. Lazily created on
+  // the first prompt turn of a persistable (JSONL) session; advisory only.
+  let _turnBindingProducer = null;
   // Apply --output-style or the settings.json `outputStyle` default at startup.
   try {
     const { resolveOutputStyle } = await import("../lib/output-styles.js");
@@ -3120,6 +3138,7 @@ export async function startAgentRepl(options = {}) {
           buildBranchPlan,
           renderBranchPlan,
           parseRewindArg,
+          pickPersistedTurn,
           RESTORE_SCOPE,
         } = await import("../lib/repl-rewind.js");
         const arg = trimmed.slice("/rewind".length).trim();
@@ -3127,6 +3146,24 @@ export async function startAgentRepl(options = {}) {
         // --files / --both). Claude-Code parity: a rewind can restore the
         // conversation only, the files only, or both.
         const parsed = parseRewindArg(arg);
+        // P1 turn/checkpoint binding: load the session's PERSISTED explicit
+        // turn-binding table (headless runs of this session feed it). A
+        // --resume'd session's pre-resume turns have no process-local marks —
+        // the explicit table is the only source of their checkpoint ids and
+        // side-effect coverage. Best-effort advisory: never blocks /rewind.
+        let _persistedBinding = null;
+        if (
+          sessionId &&
+          (parsed.command === "turn" || parsed.command === "branch")
+        ) {
+          try {
+            const { loadTurnBindingLog } =
+              await import("../lib/turn-binding-store.js");
+            _persistedBinding = loadTurnBindingLog(sessionId);
+          } catch {
+            /* marks-only fallback */
+          }
+        }
         if (parsed.command === "clear") {
           // Restore the conversation stashed by /clear (Claude-Code 2.1.191).
           const r = restoreClearedConversation(
@@ -3173,6 +3210,7 @@ export async function startAgentRepl(options = {}) {
               {
                 parentSessionId: sessionId,
                 writeIntent: parsed.writeIntent,
+                persistedLog: _persistedBinding,
               },
             );
             if (!plan || !plan.branchSessionId) {
@@ -3277,6 +3315,7 @@ export async function startAgentRepl(options = {}) {
                 _checkpointMarks,
                 turnIndex,
                 scope,
+                { persistedLog: _persistedBinding },
               );
               for (const line of renderRewindWarnings(plan))
                 logger.log(chalk.yellow(line));
@@ -3286,11 +3325,21 @@ export async function startAgentRepl(options = {}) {
             // 3) File restore (skipped for conversation-only). Match the turn to
             // the snapshot taken just before it first mutated the tree, then
             // offer to roll the working tree back to it (undoable — the restore
-            // takes its own safety checkpoint first). Prune dropped-turn marks
-            // only when the conversation was actually truncated.
-            const cp = restoreFiles
+            // takes its own safety checkpoint first). Process-local marks win;
+            // a --resume'd turn with no marks falls back to the checkpoint id
+            // the PERSISTED binding table recorded for it (same checkpoint
+            // store, so cross-process file rewind actually works — restore
+            // still fails soft if the snapshot is gone). Prune dropped-turn
+            // marks only when the conversation was actually truncated.
+            let cp = restoreFiles
               ? pickCheckpointForTurn(_checkpointMarks, turnIndex)
               : null;
+            if (!cp && restoreFiles) {
+              const persisted = pickPersistedTurn(_persistedBinding, turnIndex);
+              if (persisted?.fileCheckpointId) {
+                cp = { id: persisted.fileCheckpointId, fromPersisted: true };
+              }
+            }
             if (rewindConversation)
               pruneMarksAfter(_checkpointMarks, turnIndex);
             if (cp) {
@@ -5159,6 +5208,25 @@ export async function startAgentRepl(options = {}) {
     const _userMsg = { role: "user", content: _userMessageContent };
     messages.push(_userMsg);
 
+    // P1 turn→checkpoint binding: anchor this turn in the explicit table at
+    // `conversationOffset = messages.length` measured just AFTER the user
+    // message was appended (the exact-match contract pickPersistedTurn relies
+    // on — same anchor as the headless runner). Only JSONL sessions can
+    // persist the table; the producer supersedes stale records from a
+    // discarded timeline (post-/rewind, /clear, compaction) itself.
+    if (sessionId && useJsonl) {
+      try {
+        if (!_turnBindingProducer) {
+          const { createReplTurnBindingProducer } =
+            await import("./repl-turn-binding.js");
+          _turnBindingProducer = createReplTurnBindingProducer({ sessionId });
+        }
+        _turnBindingProducer?.beginTurn(messages.length);
+      } catch {
+        /* advisory — never disturb the turn */
+      }
+    }
+
     // Slot-filling: detect intent and fill missing parameters interactively
     try {
       const { CLISlotFiller } = await import("../lib/slot-filler.js");
@@ -5368,6 +5436,9 @@ export async function startAgentRepl(options = {}) {
         autoCheckpoint,
         checkpointSession: sessionId,
         checkpointMarks: _checkpointMarks,
+        // Explicit turn-binding producer (null unless a JSONL session): the
+        // wrapper folds every loop event into the live table.
+        turnBindingFeed: _turnBindingProducer,
         denialLog: _recentDenials,
         persistRecentDenials: true,
         permissionMode: _sessionTier,
@@ -5589,6 +5660,9 @@ export async function startAgentRepl(options = {}) {
           // Non-critical
         }
       }
+      // Persist the explicit turn-binding table for this settled turn
+      // (dirty-gated: a tool-free Q&A turn writes nothing; never throws).
+      _turnBindingProducer?.persistIfDirty();
       // Auto-compact when context grows too large
       if (
         feature("PROMPT_COMPRESSOR") &&