chainlesschain 0.162.170 → 0.162.171

package/src/lib/interaction-adapter.js

@@ -187,7 +187,7 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
     });
   }
 
-  _ask(questionType, question, extra = {}) {
+  _ask(questionType, question, extra = {}, options = {}) {
     return this._request(
       {
         type: "question",
@@ -195,7 +195,12 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
         question,
         ...extra,
       },
-      { kind: "question" },
+      {
+        kind: "question",
+        // Approval binding pass-through: a permission-gate producer supplies
+        // it; plain questions never carry one (message stays byte-identical).
+        ...(options.binding ? { binding: options.binding } : {}),
+      },
     );
   }
 
@@ -207,10 +212,26 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
     return this._ask("select", question, { choices });
   }
 
+  /**
+   * @param {string} question
+   * @param {boolean|object} [defaultVal] — boolean (legacy, byte-identical) or
+   *   an options object `{ default, binding, ...extra }`: `binding` rides out
+   *   on the request so the client must echo it back on approve (verified in
+   *   _resolvePending, mismatched approve → deny); any other keys merge into
+   *   the question message (e.g. structured `approval` context for UIs).
+   */
   async askConfirm(question, defaultVal = true) {
-    const answer = await this._ask("confirm", question, {
-      default: defaultVal,
-    });
+    const opts =
+      defaultVal !== null && typeof defaultVal === "object"
+        ? defaultVal
+        : { default: defaultVal };
+    const { binding = null, default: dflt = true, ...extra } = opts;
+    const answer = await this._ask(
+      "confirm",
+      question,
+      { default: dflt, ...extra },
+      binding ? { binding } : {},
+    );
     // Normalize to boolean
     if (typeof answer === "boolean") return answer;
     return answer === "true" || answer === "yes" || answer === "y";

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/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/repl/agent-repl.js

@@ -295,6 +295,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 +1089,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 +3136,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 +3144,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 +3208,7 @@ export async function startAgentRepl(options = {}) {
               {
                 parentSessionId: sessionId,
                 writeIntent: parsed.writeIntent,
+                persistedLog: _persistedBinding,
               },
             );
             if (!plan || !plan.branchSessionId) {
@@ -3277,6 +3313,7 @@ export async function startAgentRepl(options = {}) {
                 _checkpointMarks,
                 turnIndex,
                 scope,
+                { persistedLog: _persistedBinding },
               );
               for (const line of renderRewindWarnings(plan))
                 logger.log(chalk.yellow(line));
@@ -3286,11 +3323,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 +5206,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 +5434,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 +5658,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") &&

package/src/repl/repl-turn-binding.js

@@ -0,0 +1,91 @@
+/**
+ * REPL turn-binding PRODUCER — closes the incremental-gap 仍欠 item "REPL 自身
+ * 作为显式表生产者（交互 turn 实时喂+持久化，镜像 headless 接线；现 REPL 只消费）".
+ *
+ * Wraps the SHARED feeder core ([[turn-binding.js]] `createTurnBindingFeed` —
+ * the exact mapping the headless runner uses, so the two producers can never
+ * drift) with the three REPL-specific concerns:
+ *
+ *   1. Rehydrate: the first turn loads the session's persisted table
+ *      (`loadTurnBindingLog`) so an interactive continuation of a headless (or
+ *      earlier REPL) run APPENDS to the existing table instead of clobbering it.
+ *   2. Timeline supersede: the live REPL can shrink its conversation
+ *      (`/rewind`, `/clear`, auto-compaction), so each new turn prunes records
+ *      anchored at/after its own offset — under `pickPersistedTurn`'s
+ *      exact-offset matching a stale record from the discarded timeline would
+ *      otherwise shadow the new turn and could offer the wrong checkpoint.
+ *   3. Per-settle persistence: dirty-gated `persistTurnBinding` after each turn
+ *      (a tool-free Q&A turn writes nothing), best-effort — the producer is
+ *      advisory and must NEVER disturb the turn itself, so every method
+ *      swallows its own failures.
+ *
+ * I/O goes through `_deps` so tests drive the producer hermetically.
+ */
+
+import { createTurnBindingFeed } from "../lib/turn-binding.js";
+import {
+  loadTurnBindingLog,
+  persistTurnBinding,
+} from "../lib/turn-binding-store.js";
+
+// Injected so tests can seed the persisted table / capture snapshots without
+// touching the real sessions directory.
+export const _deps = {
+  loadTurnBindingLog,
+  persistTurnBinding,
+  now: () => Date.now(),
+};
+
+/**
+ * @param {{sessionId?: string, nonce?: string}} [opts]
+ * @returns {object|null}  null when the session cannot persist (no sessionId)
+ */
+export function createReplTurnBindingProducer({ sessionId, nonce } = {}) {
+  if (!sessionId) return null;
+  // Per-process nonce (mirrors the headless runner's per-run nonce): restored
+  // turn ids keep their original nonce, new ids can't collide across resumes.
+  const runNonce = nonce || String(_deps.now());
+  let feed = null;
+  return {
+    /**
+     * Anchor a new interactive turn. Call just AFTER the user message was
+     * appended, with `conversationOffset = messages.length` — the exact-match
+     * contract `pickPersistedTurn` relies on.
+     */
+    beginTurn(conversationOffset) {
+      try {
+        if (!feed) {
+          feed = createTurnBindingFeed({
+            log: _deps.loadTurnBindingLog(sessionId),
+            nonce: runNonce,
+          });
+        }
+        return feed.beginTurn(conversationOffset, { supersede: true });
+      } catch {
+        return null; // advisory — never disturb the turn
+      }
+    },
+    /** Fold one agent-loop event into the current turn (fed by agentLoop). */
+    handleEvent(event) {
+      if (!feed) return false;
+      try {
+        return feed.handleEvent(event);
+      } catch {
+        return false;
+      }
+    },
+    /** Persist the table after a settled turn (dirty-gated, best-effort). */
+    persistIfDirty() {
+      if (!feed || !feed.isDirty()) return false;
+      try {
+        const ok = _deps.persistTurnBinding(sessionId, feed.log);
+        if (ok) feed.clearDirty();
+        return ok;
+      } catch {
+        return false;
+      }
+    },
+    /** The live table (for tests / future in-process consumers). */
+    log: () => (feed ? feed.log : null),
+  };
+}

package/src/runtime/headless-runner.js

@@ -57,6 +57,8 @@ import {
   classifyToolSideEffect,
 } from "../lib/side-effect-ledger.js";
 import { SIDE_EFFECT_LEDGER_EVENT } from "../lib/side-effect-ledger-store.js";
+import { TurnBindingLog, createTurnBindingFeed } from "../lib/turn-binding.js";
+import { TURN_BINDING_EVENT } from "../lib/turn-binding-store.js";
 import { operationIdempotencyKey } from "../lib/idempotency.js";
 import { expandFileRefsAsync } from "./file-ref-expander.js";
 import { composeSystemPrompt } from "./system-prompt.js";
@@ -730,6 +732,50 @@ export async function runAgentHeadless(options = {}, deps = {}) {
       // best-effort — never fail the run over ledger persistence
     }
   };
+  // P1 explicit turn→checkpoint binding: feed the TurnBindingLog in real time
+  // off the yielded agent-loop events (checkpoint / tool / policy / child-agent)
+  // and persist the table as a hash-chained `turn_checkpoint_binding` session
+  // event at each turn boundary. Provider tool_use ids are not runner-visible,
+  // so tool-call ids are synthesized `<nonce>:c<seq>` (mirrors the side-effect
+  // ledger's op-id scheme — stable within a run, unique across resumes).
+  // rebuildMessages ignores this event type, so it never pollutes model
+  // context. Only writes when a turn actually recorded something, and only for
+  // persisted runs — a tool-free Q&A or ephemeral run stays byte-identical.
+  let turnBindingLog = new TurnBindingLog();
+  if (persist) {
+    try {
+      const events = store.readEvents(sessionId) || [];
+      for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if (
+          e &&
+          e.type === TURN_BINDING_EVENT &&
+          e.data &&
+          Array.isArray(e.data.turns)
+        ) {
+          turnBindingLog = TurnBindingLog.fromJSON(e.data);
+          break;
+        }
+      }
+    } catch {
+      // fresh log — best effort
+    }
+  }
+  // Event→table folding + id synthesis live in the SHARED feeder core
+  // (createTurnBindingFeed) so the interactive REPL producer can never drift
+  // from this runner's mapping. No feed at all for non-persisted runs.
+  const turnBindingFeed = persist
+    ? createTurnBindingFeed({ log: turnBindingLog, nonce: sideEffectRunNonce })
+    : null;
+  const persistTurnBindingLog = () => {
+    if (!turnBindingFeed || !turnBindingFeed.isDirty()) return;
+    try {
+      store.appendEvent(sessionId, TURN_BINDING_EVENT, turnBindingLog.toJSON());
+      turnBindingFeed.clearDirty();
+    } catch {
+      // best-effort — never fail the run over binding persistence
+    }
+  };
   if (persist) {
     try {
       const events = store.readEvents(sessionId) || [];
@@ -1703,7 +1749,17 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   try {
     // eslint-disable-next-line no-constant-condition
     while (true) {
+      // P1 turn→checkpoint binding: one drain of the loop = one turn. Anchor
+      // the conversation offset before the model sees the new user turn. A
+      // `--worktree` run stamps its isolation worktree (branch name, threaded
+      // from the command layer) onto each turn record.
+      if (turnBindingFeed) {
+        turnBindingFeed.beginTurn(messages.length, {
+          worktreeId: options.worktreeId ?? null,
+        });
+      }
       for await (const event of runLoop(messages, loopOptions)) {
+        if (turnBindingFeed) turnBindingFeed.handleEvent(event);
         switch (event.type) {
           case "checkpoint": {
             if (isText)
@@ -1876,6 +1932,9 @@ export async function runAgentHeadless(options = {}, deps = {}) {
         // call is made (break out of the for-await, not just the switch).
         if (stopForCost) break;
       }
+      // P1 turn→checkpoint binding: the turn settled — persist the explicit
+      // table (latest snapshot wins on load; no-op when nothing was recorded).
+      persistTurnBindingLog();
       // ── auto-rewake re-drive (opt-in via --auto-rewake) ─────────────────
       // Under auto-rewake, settle the async Stop hooks after EVERY turn (so the
       // final turn's background check still runs). If an asyncRewake check