[clintecker]

Problem

Second of three PRs for #732. With PR 1's pause plumbing in place, nothing yet pauses a human gate, and a library caller has no way to answer one. Running from an agent's shell, CI or a script still means stdin, --auto-approve, --autopilot or a webhook.

Fix

• handlers.PausingInterviewer. Records exactly what each gate asked and pauses the run with pipeline.NewPausedGateError. The record (pipeline.PausedGate) holds:

  • the Ask* arguments as passed;
  • the full prompt;
  • the scope path;
  • interview questions, including context;
  • a fingerprint (GateFingerprint) and a random nonce.

  Alternatively it returns an in-memory PendingAnswer once, to the gate with the same node, scope and fingerprint. If the question changed, the answer is dropped and the gate pauses again with a note.

• Engine. Stores the records on Checkpoint.PausedGates (secure state dir, authoritative) and Checkpoint.PriorUsage. It mirrors them to <run dir>/gate.json (0600, symlink refused, atomic, never read back) and puts the gate on gate_paused. Records clear when the paused node completes; a run start with no waiting gate removes a stale mirror.

• Per-gate context. handlers.WithGateInfo / GateInfoFrom carry the gate's identity, full prompt, ScopePath and branch index on every Ask*Context call. Subgraph and manager_loop children run under pipeline.WithSubgraphScope, and branch contexts get internal _branch_scope / _branch_index keys.

• Pause mode inside a subgraph or manager_loop child fails closed (routable OutcomeFail). A paused gate's gate_resolved carries resolution: "paused" and no error.

• Parallel. Every waiting branch gate is recorded, lowest branch first. A billing pause outranks the gates and carries no gate records.

• Resume of a gate-paused run. No context compaction (the question must re-render identically), and the budget baseline is seeded from PriorUsage, so caps span every answer.

• Library.

  • Config.GateMode (pause requires ArtifactDir; console; lowest priority).
  • tracker.Answer, ValidateAnswer, PendingGates, WaitingRuns.
  • Result.PausedGate / RunSummary.PausedGate.
  • Per-run lock: pipeline.AcquireRunLock, taken by every ResumeRunID run, stale locks replaced. Answer re-checks the nonce under the lock.

• Wire. gate_resolution / gate_fingerprint on the activity log and NDJSON; GateQuestion.context.

• Docs. embedding.md, transport-boundary.md, handlers/human.md (pause mode, plus the not-tamper-proof residual), engine.md (pausing), api-stability.md, site transport page, CHANGELOG.

• Size-ratchet moves. interviewer_callback.go, parallel_events.go, parallel_pause.go, tracker_resume.go; terminal results moved to terminal_emit.go. The baseline only shrinks.

Verification

• New tests, each watched failing first (the run-lock test was checked with a mutation instead):
  • fingerprint, checkpoint record, mirror, stale-mirror removal, clearing on completion, gate_paused detail;
  • scope and GateInfo on context, including inside parallel branches;
  • PausingInterviewer in every mode: apply-once, changed question, other scope, interview answers and cancel;
  • handler pause event and the subgraph fail-closed path;
  • parallel merge and billing precedence;
  • resume without compaction (RF1), plain resume re-pauses / interactive answer clears (RF2), budget across answers;
  • the ValidateAnswer table (incl. " Approve ", RF3), GateMode precedence, Answer round trip / not waiting / two gates / planted files ignored / nonce changed;
  • WaitingRuns, run lock (concurrent + stale + released after a canceled answer, RF4).
• go test ./... -short green; API surface and wire envelope goldens updated; activity schema regenerated; pre-commit gates green.

PR 1 (#733) is merged; rebased onto main.

Part of #732

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	⚠️ Failed 2026-10-20T22:47:02.468840Z	0e73409	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 25 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: b8ac3da6-4044-4b8a-8a82-faec56ec575f

📥 Commits

Reviewing files that changed from the base of the PR and between 17d4d6e and ec0347e.

⛔ Files ignored due to path filters: 1

• scripts/gen/activitylog/schema.go is excluded by !**/gen/**

📒 Files selected for processing: 56

• CHANGELOG.md
• docs/api-stability.md
• docs/architecture/embedding.md
• docs/architecture/engine.md
• docs/architecture/handlers/human.md
• docs/architecture/transport-boundary.md
• pipeline/budget.go
• pipeline/checkpoint.go
• pipeline/engine.go
• pipeline/engine_options.go
• pipeline/engine_resume_paused.go
• pipeline/engine_resume_paused_gate_test.go
• pipeline/engine_run.go
• pipeline/engine_run_identity.go
• pipeline/events_gate.go
• pipeline/events_jsonl_entry.go
• pipeline/events_jsonl_gate.go
• pipeline/handlers/human.go
• pipeline/handlers/human_gate_aware.go
• pipeline/handlers/human_gate_ctx_test.go
• pipeline/handlers/human_gate_events.go
• pipeline/handlers/human_gate_pause.go
• pipeline/handlers/interviewer_callback.go
• pipeline/handlers/interviewer_pausing.go
• pipeline/handlers/interviewer_pausing_test.go
• pipeline/handlers/manager_loop.go
• pipeline/handlers/parallel.go
• pipeline/handlers/parallel_branch_test.go
• pipeline/handlers/parallel_pause.go
• pipeline/handlers/pause_resume_test.go
• pipeline/pause.go
• pipeline/paused_gate.go
• pipeline/paused_gate_answer.go
• pipeline/paused_gate_test.go
• pipeline/run_lock.go
• pipeline/run_lock_test.go
• pipeline/run_lock_unix.go
• pipeline/run_lock_windows.go
• pipeline/scope.go
• pipeline/scope_test.go
• pipeline/subgraph.go
• pipeline/terminal_emit.go
• scripts/complexity/baseline.txt
• site/content/transport.html
• testdata/api_surface.golden
• tracker.go
• tracker_activity_entry_gen.go
• tracker_activity_raw_gen.go
• tracker_answer.go
• tracker_answer_test.go
• tracker_audit.go
• tracker_events.go
• tracker_events_payload.go
• tracker_interviewer.go
• tracker_resume.go
• tracker_wireshape_test.go

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}