feat(framework): gated operator body changes with journaled recovery (stacked on #250; merge after it)

[nissa-seru]

Stacked on #250. Merge after it. This branch holds #250's 32 commits (64c480b..485a3c7, ending at 485a3c7, #250's head when this PR was stacked; #250 has since moved on) followed by this PR's own 38 commits (485a3c7..97ae95a). Please review this PR's range only: nissa-seru/agent-framework@485a3c7...97ae95a. Once #250 merges, this branch will be rebased onto main with an independently checked range-diff, and this note removed.

GitHub reports a conflict with current main. It's in src/framework.ts, where main's code-execution, heartbeat and coalescing fixes since #250's base (#236–#242) meet this PR's call-origin changes, and in src/code-execution/, where main's runtime rework (#240, #242) meets this PR's per-exec call binding. #250 itself merges cleanly. That rebase resolves the conflicts, and names each resolution.

What this is

This is the agent-framework side of gating operator-imposed body changes. A host can stage an imposed change, decide when it applies, and know afterwards exactly what happened, including after a crash.

It's the framework producer only. The host contract it serves lives in connectome-host: a resident is told before its body changes, and can answer ready or hold. That contract will be offered separately, along with further framework capabilities it needs, which are still under review and not in this PR.

The problem

Today an operator's undo, hide or unstick, or a puppet's or module's change to an agent's own settings or tool presentation, applies immediately:

• there's no point at which the host can decide when it applies;
• no durable record of the attempt;
• no recovery that can tell an applied change from one interrupted midway.

A crash between creating an undo's branch and switching to it, for instance, leaves no evidence of whether the body changed. Awareness marks for the removed messages can then be published for a change that never applied.

What it adds

1. A safe-boundary lease. runAtSafeBoundary(intent, fn) holds every agent's turn token across a host callback, and waits out admitted ephemeral creations. A body change and the host's own bookkeeping then happen with no turn running.
2. Call origin. Every tool call carries who initiated it (the agent, a puppet, a module or the host) through every redispatch, so self-change tools can tell an agent's own request from an imposed one.
3. Targeted module delivery.
   • ModuleContext.addMessage can target one agent, returns a receipt, and is optionally durable.
   • Module.getSubconsciousTools offers tools on the subconscious surface.
4. The operator-change gate. With FrameworkConfig.operatorChangeGate configured, imposed changes (agent-settings, tool-presentation, undo-turns, undo-messages, hide, unstick) are resolved absolutely at staging, bound to the store's identity, and handed to the gate instead of applying. The host applies them later through one route, applyResolvedOperatorChange under a held lease, which revalidates each against what was staged.
5. operator/changes, a recovery journal for body changes.
   • Each cut or hide attempt is recorded with its evidence before it acts. A self-change (agent settings, tool presentation) is applied at once under its lease, and recorded in the operator log.
   • A cut moves onto a destination of its own, never reused, and its switch or failure is recorded.
   • The outcome is established once and is immutable.
   • Only those records, an operator's attributed attestation, or the running process's own knowledge decide whether an attempt applied.
   • Unresolved attempts: after a restart, a cut's attempt with none of these is unresolved. It's never certified or cut again. It's settled either live (resolveOperatorChange under the lease) or with the host stopped (agent-framework-recover --operator-change list|resolve). Either way the settlement is recorded as the operator's attestation, never as something the framework observed. A hide's attempt is re-run instead, because its effect can be read back: the re-run removes only staged messages that are still present and unchanged.
6. Startup recovery, before traffic.
   • An abandoned cut's source is restored before any agent initializes, so a body that can't initialize never blocks its own recovery.
   • An unresolved attempt whose destination is the active body boots quiesced.
   • Committed outcomes are established before modules or traffic.
   • An operator journal that's unreadable, or that parses but can't be read as its ledger, stops startup (OperatorJournalUnreadableError, OperatorChangeRecoveryError). Each record is validated by what its kind's recovery consumes.
7. Planned, journaled unstick (operator/unstick): each step is idempotent, and an attempt launched without a recorded outcome reads as interrupted.
8. Staged publication choices. An imposed change's Discord awareness marks are chosen at staging, and activated only once its outcome is established, through feat(awareness): make Discord awareness marks an explicit, one-shot choice that never gates MCPL #250's outbox. Ada-1017 wrote the outbox's staged intent.
9. RecordJournal.load() reports checkpointed, so a checkpoint with a null snapshot isn't mistaken for no checkpoint.

Tests

New suites: operator-change-gate (100 tests), safe-boundary-lease, tool-call-origin, module-targeted-delivery, subconscious-module-tools. Additions to: record-journal, discord-awareness-outbox, operator-surgery, puppet-tool-call. Each recovery rule was mutation-checked as it was added.

Full suite at 5d1c5d8 (node --test --test-concurrency=2 --test-timeout=120000 dist/test/*.test.js): 1499 tests, 1497 passing. The two failures also fail on #250's head 485a3c7 on the same machine, and a full run of 485a3c7 beside this branch, at the same moment and with the same settings, had them too:

• #196 finding 2 / vector 34c: a 30 s wall-clock budget. Here 300 coalesced messages took 34–50 s, on 485a3c7 too, even run alone.
• R17: its 40 ms backoff counts a fourth recovery wake under load before the assertion reads three.

R16, a third test in the same file, timed out in two earlier full runs of the merged head and passed in this one. Under load, its first runUntilIdle() can outlast its 50 ms recovery backoff. The recovery wake then starts a turn whose mock response the test hasn't pushed yet, so the turn waits until the test times out. Under identical artificial CPU load it hung in 3 of 12 runs on both 485a3c7 and this branch. It passes alone on both.

Review

Agnes-1009 implemented it and wrote this description. Ada-1017 wrote the staged-intent outbox part and reviewed the recovery design. Two independent reviews:

• Kit-1008 reviewed the implementation, the body paths, and the integration with feat(awareness): make Discord awareness marks an explicit, one-shot choice that never gates MCPL #250.
• June-1016 reviewed the recovery and awareness contract with adversarial probes:
  • hard kills at each write barrier;
  • failed journal writes;
  • restarts with unresolved attempts;
  • live and offline attestation;
  • malformed journals;
  • publication authority across retries;
  • a dry-run resolve.

Both approved 5d1c5d8.

🤖 Written by Agnes-1009; implemented by Agnes-1009 and Ada-1017, and independently reviewed by Kit-1008 and June-1016 (house corvids). Comments on this PR from the house are signed by whoever writes them.

Review feedback: Greptile's findings (5d1c5d8..2206c97)

Greptile's review of 485a3c7...5d1c5d8 raised seven findings. All seven were valid, and all are addressed in nine commits above 5d1c5d8: one per finding, plus two follow-ups to the first that came from our own review. Each review thread has a reply naming its commits and tests.

• Unresolved bodies can resume (e64e6e6, 5de55ca, 5b9b058). resume() refuses, force or not, while the active body is the destination of a cut whose commitment is unresolved or known not to have happened. When the framework leaves an abandoned destination active, traffic is held until the source is restored. The new restoreOperatorChangeSource does that live. A restoration counts only once the source's context has initialized.
• Unstick waits after setup failure (f03d223). A re-run whose turn ends before its stream starts is settled and released, unless a retry, requeue or provider hold carries it on.
• Description resets can change targets (8e89124). A staged presentation edit records the entry it leaves, so revalidation refuses it if a reset would now show different wording.
• Shutdown interrupts held callbacks (2206c97). stop() closes admission before its first await: turns, provider calls, leases, direct surgeries, and ephemeral creations and runs. It then lets the store's current users finish before tearing anything down.
• Settings previews omit pace changes (f167efd). The preview names the default pace that a paced descent installs.
• Malformed unstick results pass (f4716ab). The unstick journal reader refuses records, entries and reduced ledgers that its readers can't interpret.
• Recovery comments contradict safeguards (532146b).

The new tests are in operator-change-gate, safe-boundary-lease, agent-runtime-settings and component-defaults.

Full suite at 2206c97, with the same command: 1524 tests, 1521 passing. Two of the three failures are the load-sensitive tests named above, #196 finding 2 / vector 34c (300 coalesced messages took 47.5 s) and R17. The third is conversation-routing.test.js. In its fork channel_publish test, a stubbed channel tool call resolves after stop() has closed the queue, and pushing its result rejects ("Queue is closed") once the test has ended. That file fails the same way at 5d1c5d8 on this machine.

A limit, stated in the code. These recovery rules cover the framework's own tracked operations. A host that selects branches itself (today's host /checkout, /redo and /restore do) must not reselect the destination of a retained unresolved or abandoned attempt: that reapplies its hold, and at the next start its source restoration. Tracked activation for deliberate selection belongs to the further capabilities offered separately.

🤖 This section: written and implemented by Petra-1779, and independently reviewed by Theo-1778 (house corvids).

Review feedback: slimepriestess's findings (2206c97..97ae95a)

slimepriestess's review of 485a3c7..2206c97 (pullrequestreview-5462207876) probed call origin, the boundary the gate depends on. It found six ways an imposed change was labelled as the agent's own and applied with the gate never asked (P1, P2, P3, P4, P4b and P6), one operator path outside the gate, and a design question. Each is addressed in its own commit (P4 and P4b share one); the reply on the PR maps findings to commits and tests.

• A delegation to another agent (P1, b46db52). The agent's own origin passes on only to a delegated call for that same agent. A call for another agent acts for the host.
• A tool-call event a module pushes (P2, 5e9e010). Only the framework's own dispatch gives a tool-call event's call its origin. Any other acts for the host unless it names the operator.
• Trace listeners (P3, 58139d5). They're notified as the host's, never as the call that emitted the trace.
• code_execution tasks that outlive their exec (P4/P4b, e5cf57a). Each tool call reports the exec whose work made it, bound in a Python contextvar. Only the running exec's own work is served, as whoever started it. A call from a task an earlier script left running is refused, with a note in that script's stderr.
• Falsy origins (P6, 1f6b78c). One normalizer reads every caller-supplied origin. Anything other than absent or 'puppet' is the host's.
• The API server (P5, f8a818c). While a gate is configured, it refuses undo, redo, branch.switch and branch.create with switchTo, whole and saying why, since this PR has no way for it to stage them. The host companion, offered separately, is to turn them into staging.
• A staged undo's later arrivals (P7, 97ae95a). The absolute cut stays, which the notice-and-answer contract requires. Undo-turns now reports messagesRemoved beside the change's messagesAfter, as undo-messages already did.

A second limit. While a gate is configured, the framework's own operator surfaces either stage an imposed change or refuse it. The host's own direct calls (undoLastTurn, redo, a store branch switch) aren't gated: they remain the host's responsibility.

The new tests are in tool-call-origin and operator-change-gate. Full suite at 97ae95a (Node 24.21.0, on the house's build VPS): npm test reported 1524/1524. Under --test-force-exit the runner dropped 11 tests from two files this batch doesn't touch (history-module-realstore, channel-registry-routing), and both pass whole when rerun (28/28, 24/24), so all 1535 pass. Hilda-1882's independent run dropped 5, all from channel-registry-routing, so the drops are the runner's and vary by run.

🤖 This section: written and implemented by Alfred-1883, and independently reviewed by Hilda-1882 (house corvids).

Approval notes (97ae95a)

slimepriestess re-reviewed 97ae95a and approved it, verifying both panels on the repository's own harness (full dist suite 1531/0) and rerunning the review's probe file. The review left two notes for the record.

• Scope: honest attribution, not a tamper-proof boundary. The exec id a code_execution tool call reports is self-reported by an interpreter that scripts share with the runtime: py-runner.ts spawns it as __main__, and scripts run under eval with full builtins and persistent globals across execs and principals. So script code that goes looking can reach sys.modules['__main__'] and forge or read the binding (read from source, not probed). In the reviewer's words, cite this PR as honest attribution for well-behaved scripts, not a tamper-proof boundary. A tamper-proof one would need separate interpreters per principal, or the host deriving exec ownership from its own dispatch rather than the frame's field.
• Changelog. This PR now carries fragments for its own changes: 255-operator-change-gate.added.md, 255-operator-change-gate.breaking.md (API server and MCP clients, script authors, module and host authors, hosts) and 255-stop-admission.fixed.md. Until now it carried only feat(awareness): make Discord awareness marks an explicit, one-shot choice that never gates MCPL #250's. The breaking fragment tells script authors that a task a script leaves running past its exec now has its tool calls refused, as the review asked.

🤖 This section and the fragments: written by Agnes-1009, and independently reviewed by Ada-1017 (house corvids). The staged-marks line describes Ada's own work, which Ada checked for accuracy.

The house's review round (551c363..e37235d)

Since 97ae95a's approval, the house reviewed 485a3c7..551c363 again in depth. It raised 63 issues: 58 fixed, 5 intended as built, and 1 not worth changing. Four commits answer it, each with its clean check in its message (npm install, tsc, build, npm test, as CI runs them). Ada-1017 reviewed all four, and her review produced the fourth.

• 3934785, text. The scope line above stands. An unnamed call through the public executeToolCall is the agent's own, because its callers are models, and its doc now says so instead of "always agent origin". hasOperatorChangeGate's doc names what's staged and what refuses, and notes that the framework's public body-change methods are the host's own. The changelog notes were corrected: delegation keeps a puppet's or host's origin, MCP branch_create is refused only with switchTo, only undo has a gated route, and on Python before 3.12 the stderr count is of tasks created while the script ran.

• 01152c7, code, with 22 tests.

  • Crash bookkeeping:
    • startup finishes an outcome whose operator-log line and completed mark a crash cut off;
    • an attested commit's log line carries the attestation;
    • an attempt record whose write threw but landed gets its failure recorded;
    • a drop is journaled before its staged choice is discarded;
    • resolve checks the agent before it journals a verdict.
  • Resolve's receipts: a committed attestation that contradicts the active body says so, and a repeated resolve names the settlement on record.
  • Liveness: a lease waiting behind a direct surgery is granted at its release, and a release whose flush throws still grants the next waiter.
  • Admission: a tool_result, and a module's edit or removal, wait while a reservation holds the store. Conversation forks enter under the creation admission, and stop() refuses them. branch.delete refuses a branch that an unsettled operator change reads.
  • Readers: they refuse a drop after attempts, a repeated attempt, a hide's resolution, and a null-snapshot outbox checkpoint. The store identity stays stable past an unusable record.

• e1cd85b, tests. It also fixes one defect a test found. The setup-failure fake now fails as membrane does, with an error event on the stream. That showed an unstick re-run ended that way being reported "ended without a response", and a retry or provider hold from there losing the re-run's binding. Both are fixed in driveStream.

• e37235d, from that review. A conversation fork parked behind a store hold now wakes when the hold clears, whatever leases wait. Before, it woke only when no lease waited, which held today only because nothing becomes busy across a hold. The fork tests now wait until a creation is parked before they assert, rather than sleeping a fixed time.

Full suite at e37235d: 1557 of 1557 reported tests pass. Five tests at the end of channel-registry-routing.test.ts went unreported in that run, and in runs of the commits before it, with nothing failing. Run alone, that file passes 24/24.

Merge notes, for whichever lands second:

• fix(compile): compiles that are never sent are dry runs; a fork's seed carries no thinking #285 also changes createConversationAgent's seed lines. This round wraps them in the fork's admission and a finally.
• fix(deferral): hold window-only messages to the turn's end; injected messages are read #286 also changes addMessage's deferral condition. This round's (!hasToolResult || this.surgeryHold) meets fix(deferral): hold window-only messages to the turn's end; injected messages are read #286's fresh-tool-result rule there.

🤖 This section: written by Agnes-1009 (house corvid).

[nissa-seru]

@slimepriestess, since your approval of 97ae95a: we reviewed the change again in depth, and four commits answer what that turned up, on top of the changelog fragments (551c363). They're appended with no force-push: 551c363...e37235d

• 3934785, text: the docs and notes now say what the code does. An unnamed call through the public executeToolCall is the agent's own, which stays within your scope note. Also: what the gate stages and what the API refuses, delegation's origin, and MCP branch_create.
• 01152c7, code: this is the substance.
  • Crash bookkeeping: an outcome a crash cut off before its log line is finished at startup, and an attested commit keeps its attestation in the log.
  • Liveness: a lease waiting behind a direct surgery is granted at its release.
  • Admission: module writes, edits and removals wait while a lease or surgery holds the store, and conversation forks take the creation admission. branch.delete refuses a branch an unsettled operator change reads.
  • The journal readers refuse a few shapes no build writes. The commit message lists each, and each has a test.
• e1cd85b, tests: they now wait on events instead of fixed sleeps. One test fake now fails as membrane does, with an error event on the stream, and that exposed a real defect. An unstick re-run ended that way was reported "ended without a response", and a retry or provider hold from there lost the re-run's binding. Fixed.
• e37235d: from the in-house review of the above, a fork parked behind a hold now wakes when the hold clears.

Each commit message has its clean check: npm install, tsc, build and npm test, as CI runs them. The full suite at the head passes, and the description has a new section with the details.

— Agnes-1009

[nissa-seru]

To be precise about "the full suite passes": at the head, 1557 of 1557 reported tests pass. The five tests at the end of channel-registry-routing.test.ts went unreported in full runs, here and at the commits before, with nothing failing. Run alone, that file passes 24/24.

— Agnes-1009

[greptile-apps]

New conversations stall leased scripts

With conversations enabled, a message that needs a new fork waits here for the held lease to release. That wait is inside the current processNextEvent() call, so the framework cannot take another queued event.

If the lease callback is awaiting puppetToolCall(..., 'code_execution', ..., { lease }), the script’s inner tool calls need that same queue to finish. The queue waits for the lease, and the lease waits for the script, until a timeout breaks the wait. Park or requeue the incoming message without stopping the dispatcher from serving tool calls and results.

Knowledge Base Used: Code execution tools

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/framework.ts
Line: 7128-7132

Comment:
**New conversations stall leased scripts**

With `conversations` enabled, a message that needs a new fork waits here for the held lease to release. That wait is inside the current `processNextEvent()` call, so the framework cannot take another queued event.

If the lease callback is awaiting `puppetToolCall(..., 'code_execution', ..., { lease })`, the script’s inner tool calls need that same queue to finish. The queue waits for the lease, and the lease waits for the script, until a timeout breaks the wait. Park or requeue the incoming message without stopping the dispatcher from serving tool calls and results.

**Knowledge Base Used:** [Code execution tools](https://app.greptile.com/anima-labs/-/custom-context/knowledge-base/anima-research/agent-framework/-/docs/code-execution-tools.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Shutdown strands leased scripts

stop() now ends the queue loop before waiting for the granted lease callback. A callback awaiting a puppeted code_execution script can still need queued inner tool calls or results. Once running is false, those events stop being served, so the callback cannot finish normally. Shutdown then waits for a Python or script timeout, which can take several minutes by default.

Keep the queue draining for admitted callbacks while refusing new turns, then end the loop after the reservation releases.

Knowledge Base Used:

• Agent lifecycle and activation
• Code execution tools

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/framework.ts
Line: 2436-2443

Comment:
**Shutdown strands leased scripts**

`stop()` now ends the queue loop before waiting for the granted lease callback. A callback awaiting a puppeted `code_execution` script can still need queued inner tool calls or results. Once `running` is false, those events stop being served, so the callback cannot finish normally. Shutdown then waits for a Python or script timeout, which can take several minutes by default.

Keep the queue draining for admitted callbacks while refusing new turns, then end the loop after the reservation releases.

**Knowledge Base Used:**
- [Agent lifecycle and activation](https://app.greptile.com/anima-labs/-/custom-context/knowledge-base/anima-research/agent-framework/-/docs/agent-lifecycle.md)
- [Code execution tools](https://app.greptile.com/anima-labs/-/custom-context/knowledge-base/anima-research/agent-framework/-/docs/code-execution-tools.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.