[Meganeuridae]

Problem

A Python await currently holds the model-facing tool call open until the whole script exits. The runner also accepts overlapping cold starts, and an outstanding tool response from a killed interpreter can satisfy a replacement interpreter's reused call ID. Background wake requests can exceed the configured rate/cap when concurrent and falsely acknowledge a context delivery failure.

Changes

• Reserve startup before awaiting readiness; make startup cancellation settle promptly; bind tool replies and wake acknowledgements to their originating interpreter/execution; preserve sub-second tool timeouts.
• Separate script execution from bounded observation. A persistent agent's foreground calls return a running script_id after 10 seconds by default (wait_ms, maximum 60 seconds); action=wait retrieves or rejoins the same run. Ephemeral agents wait for the script to end, since they cannot receive a completion notice. Persistent Python state stays serial and busy responses identify the active run.
• on_timeout=end_turn arms completion delivery before returning an end-turn result. An active observer consumes completion directly; otherwise a yielded execution sends a bounded completion notice and wake. A result a notice announced stays retrievable until the agent retrieves it (at most 20 per owner); other settled results, the five most recent. An inner end-turn ends only a turn still waiting on its script.
• Preserve independent background interpreters and existing silent-clean-exit watcher behavior. Serialize explicit wakes, acknowledge delivery failures honestly, and scope inner-tool end-turn effects to their originating execution.
• Host quiesce (Quiesce/maintenance mode: pause main thread + MCPLs, run maintenance through the live compression machinery #122) keeps its guarantee: the drain waits for foreground scripts that outlived their turn and abandon stops them; host status adds foregroundScripts. Background watchers stay exempt.
• Add releaseCodeExecutionWait(agentName, scriptId?) for the host's admin-only command. This resolves observations through the normal tool-result boundary without killing Python. It is not an agent tool and is not exposed on the generic framework socket API.

The agent-facing description keeps its original guidance and adds the waiting behavior; docs/code-execution-lifecycle.md describes the exact behavior and the further design work. A breaking-change fragment calls out the new foreground return contract.

Tests

Current head (merged with main at e45c1a1, which includes #203):

• Build passes; npm test: 1138 pass / 0 fail / 4 skipped (1142 total).
• Focused code-execution, ScriptRun and quiesce tests: 98 pass / 0 fail.
• Each review fix and each previously untested changelog fix has a regression test that fails when the fix is reverted (14 reverts, 14 failures).
• Real terminal-sessions acceptance against this branch: 7/7. Paired host check with connectome-host#130 (recipe limits reach the tool, untrusted release refused, admin release keeps Python running, completion wakes once): 4/4.

Original submission: baseline 8b612f5 786 pass; branch 802 pass; three regressions replayed red against the original source.

Not verified / limits

No live provider, resident deployment, host restart recovery, or cross-platform run was performed. Scripts/results remain process-local. Cancelling Python does not cancel an already dispatched inner tool. A wake_agent queued behind a live turn is acknowledged once queued; a store rejection when it is later flushed is logged and dropped, as for every deferred write. Durable outcomes, paged journals, and delivery receipts are explicitly deferred in the design note.

Companion PRs

Companion: anima-research/connectome-host#130. It adds admin-only /release-wait [script_id] and recipe validation. Publish/install a framework release containing this primitive before expecting that command to work; the companion fails explicitly on older framework versions. No merge, package publication, dependency rollout, or deployment is included here.

Generated with OpenAI Codex.

Review fixes: 🤖 Generated with Claude Code

[slimepriestess]

Reviewed head 7130ac8, and as a trial merge onto main@67991cf (0.18.0). Second read by Opus 5.5 in a separate session; the ephemeral finding and the test-gap list are its catches, re-verified here.

Verdict: CHANGES REQUESTED. For primary agents the mechanism is right and the ordering in ScriptRun holds up. Three things stand in the way: ephemerals lose results and are told they won't, four of the changelog's fixes have no test that goes red on revert, and the branch doesn't typecheck against current main.

Blocking

1. Ephemerals are promised a wake they can't receive, and their script is killed when they believe it. An ephemeral's foreground call yields after 10s with the note "Still running. Completion will notify you"; the tool description says the same. When the ephemeral's run ends, the finally in runEphemeralToCompletion calls disposeAgentScripts, which sets cancelled and so suppresses the completion notice in settleCodeExecution. An ephemeral that ends its turn on that note never sees its output. Before this PR a 30s script in an ephemeral blocked and returned. The PR already knows ephemerals can't be woken, which is why on_timeout=end_turn is refused for them (runCodeExecution); the default path breaks the same promise silently. No test touches ephemerals on the foreground path. Fix is either blocking semantics for ephemerals (observe until the script deadline) or an honest note ("you must keep waiting; this execution ends with your run") plus a test for whichever you pick.

2. Four fixes in the changelog have no revert-goes-red test. Reverting any of these leaves the suite green:

   • Inner-tool endTurn scoped to its execution ("keep deferred end-turn effects scoped"). Background runners now pass no onEndTurn, so a background inner endTurn is dropped instead of landing on an unrelated foreground result. Only the pre-existing foreground case at test/code-execution.test.ts:508 touches endTurn.
   • abortAgentScript aborting only an observed run ("unrelated later stream failures leave yielded work alone"). Nothing exercises a stream error against an observed run, or against a yielded one. Item 4 below depends on this behavior, so it needs the test.
   • Stale wake_ack after interpreter replacement. The test at :299 covers tool_result; the wake branch has the same guard and no test.
   • wakeAbort cutting a rate-floor wait short when the run ends.

3. Doesn't typecheck on main. getHostModeStatus (src/framework.ts:2741 on main, from #122) reads this.backgroundScripts, which this PR renames. Git merges everything but the first import line cleanly, then tsc fails with TS2551 on that property. [...this.codeExecutionScripts.values()].filter(r => r.status === 'running').length fixes it; see item 4 for what the field should mean now.

For antra to rule

4. Yielded foreground runs change a guarantee of #122's quiesce. Before: a foreground script held a turn token, so drain waited for it and abandon killed it. Now: drained: true can be reported while model-authored foreground work is mid-flight (up to scriptTimeoutMs, 600s by default), and abandon no longer stops it, because abortAgentScript skips a run nobody is observing. Background daemons were already exempt by design; this extends the exemption to work that came out of a turn. Either abandon also aborts yielded foreground runs, or the quiesce doc says drained is not quiet. Whichever way, the status field should count both modes and probably stop being called backgroundScripts.

5. The code_execution description is rewritten, and the guidance flips. tool-definition.ts drops the header comment antra wrote on 7/31 explaining that the tool's name, input shape and description deliberately track Anthropic's server-side programmatic tool calling so models' trained priors transfer. The new text replaces "call tools directly when a single call answers the question" with "choose direct calls or code as useful, including for a single call," drops the sanitized-name example, and drops the "arm a wake rule as backup" caution. It also never says that a detached foreground run still dies at scriptTimeoutMs, so an agent will start a 30-minute job in the foreground and get a DIED wake at ten minutes. The lifecycle sentences need adding, no question. The rest is a decision about how residents are steered, riding inside a lifecycle PR.

Notes

6. A deferred inner-tool endTurn from a yielded run is applied to whichever later wait retrieves the result: the agent wakes on completion, calls wait, and the retrieval ends its turn. Defensible; say so in the doc, or clear the flag on yield.
7. Script wakes are now system: true, so isConversationalInjection returns false for them: a wake no longer clears explicit-send suppression and never influences routing. Reads right for completion notices, less obviously right for wake_agent(payload), which is the script speaking to its owner. Intentional?
8. ScriptRun drops the old belt-and-suspenders catch. With the new py-runner the completion can't reject by construction (the ensureChild chain settles its own failures), so this is defense in depth, not a bug. If it ever did reject, the record would sit at running with the context reporting busy; cancel recovers it.
9. injectScriptWake's return value is ignored inside settleCodeExecution, so a completion whose notice fails to land is lost to an agent that already ended its turn. The doc admits this under limits; fine for now, worth a line in the notice-failure log at least.

Verified

• runtime-py.ts on main already emits exec_id on tool_call and wake, so the new "reply must match the pending execution" filter is live-correct, not a silent drop.
• wait_ms: integer 0–60000, default codeExecution.foregroundWaitMs then 10_000; end_turn refused for ephemerals and unregistered agents.
• Busy foreground context returns the running id. cancel of a yielded run calls PyRunner.abort(), which reclaims the interpreter (the runner object survives, the Python child and its globals don't); the next run gets a fresh child. The test at :727 prints a literal, so it doesn't actually show freshness; asserting a prior global is gone would.
• Startup reserve: pending is set before the first await; abort and dispose during startup settle; late tool_result from a replaced interpreter is dropped (tests).
• Wake serialization under asyncio.gather respects floor and cap; delivery failure surfaces in Python as RuntimeError (tests).
• Completion path: addMessage(..., { forAgent }) plus a pendingRequests entry with reason script:wake; parked during quiesce, admitted otherwise; not an EventGate event, so "bypasses ambient gating" is accurate. "Queued even if it arrives during turn teardown" is read, not tested: the release tests sleep 0.4s, so completion lands after teardown.
• ScriptRun ordering: result set, waiters finished, onComplete run synchronously in the same .then; the observer's continuation runs after, so record.status is final when read. A timer firing before completion arms one notice; completion before the timer delivers to the observer; no path gives both.
• Head: script-run + code-execution tests 42/42. Trial merge with item 3 patched: 974 tests, 970 pass, 0 fail, 4 skipped (workspace-mount re-attach cases, platform-gated, unrelated).
• Companion connectome-host#130: calls releaseCodeExecutionWait behind a feature check, gates /release-wait on operator authority, and validates foregroundWaitMs as an integer ≤ 60000. Not reviewed beyond that.

For the #architecture thread: the ten seconds isn't hardcoded. Default 10_000, recipe codeExecution.foregroundWaitMs (host main already forwards the block whole), per-call wait_ms up to 60_000.

[greptile-apps]

Confidence Score: 3/5

[Critical risk] Restructures code execution lifecycle and observation model.

The PR is not ready to merge until late inner-tool end-turn effects and deferred wake acknowledgments are correctly scoped and delivered.

Findings

1.  Late end-turn affects another turn ▶
2.  Deferred wake acknowledged too early ▶
3.  Invalid default blocks script management ▶
4.  Completion notice promises evicted result ▶

Fix with agent prompt

### Issue 1
src/framework.ts:8200-8201
When a foreground script outlasts its observation budget and later calls an inner tool such as `skip_reply`, that tool sets `record.endTurn` after the original tool result has returned. A later `action=wait`, even after the script finishes, consumes the flag and ends that unrelated turn prematurely.

### Issue 2
src/framework.ts:8488
When `wake_agent()` fires during an active turn, the envelope is deferred rather than stored, but this path immediately acknowledges delivery to Python. If the later flush fails, it discards the envelope while the queued wake can still start inference, so the agent never receives the payload Python was told it delivered.

### Issue 3
src/framework.ts:8095-8098
If the host sets `foregroundWaitMs` outside 0–60000, validation rejects every `code_execution` call without an explicit `wait_ms`. That includes `action=list`, `action=cancel`, and immediate background starts, none of which needs a foreground observation budget. An invalid default therefore prevents agents from managing existing scripts.

### Issue 4
src/framework.ts:8442
The notice tells the agent to retrieve the result by `script_id`, but if five other executions settle before the agent acts on the queued wake, this result is evicted. `action=wait` then returns `no script`, leaving a foreground script’s full output unavailable beyond the notice’s short tail.

---

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

Summary

This PR separates Python script execution from bounded tool-call observation and adds retained results, waits, completion wakes, and an operator wait-release method. It also tightens interpreter startup, reply correlation, and background wake handling.

• The new lifecycle has two turn/delivery boundary failures that need correction.
• Configuration validation and result-eviction messaging need smaller follow-up fixes.

_{Reviews (1) · Last reviewed commit: "fix(code-execution): separate script lif..."}

[greptile-apps]

Late end-turn affects another turn When a foreground script outlasts its observation budget and later calls an inner tool such as skip_reply, that tool sets record.endTurn after the original tool result has returned. A later action=wait, even after the script finishes, consumes the flag and ends that unrelated turn prematurely.

Prompt To Fix With AI

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

Comment:
**Late end-turn affects another turn** When a foreground script outlasts its observation budget and later calls an inner tool such as `skip_reply`, that tool sets `record.endTurn` after the original tool result has returned. A later `action=wait`, even after the script finishes, consumes the flag and ends that unrelated turn prematurely.

---

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

[greptile-apps]

Deferred wake acknowledged too early When wake_agent() fires during an active turn, the envelope is deferred rather than stored, but this path immediately acknowledges delivery to Python. If the later flush fails, it discards the envelope while the queued wake can still start inference, so the agent never receives the payload Python was told it delivered.

Prompt To Fix With AI

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

Comment:
**Deferred wake acknowledged too early** When `wake_agent()` fires during an active turn, the envelope is deferred rather than stored, but this path immediately acknowledges delivery to Python. If the later flush fails, it discards the envelope while the queued wake can still start inference, so the agent never receives the payload Python was told it delivered.

---

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

[greptile-apps]

Invalid default blocks script management If the host sets foregroundWaitMs outside 0–60000, validation rejects every code_execution call without an explicit wait_ms. That includes action=list, action=cancel, and immediate background starts, none of which needs a foreground observation budget. An invalid default therefore prevents agents from managing existing scripts.

Prompt To Fix With AI

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

Comment:
**Invalid default blocks script management** If the host sets `foregroundWaitMs` outside 0–60000, validation rejects every `code_execution` call without an explicit `wait_ms`. That includes `action=list`, `action=cancel`, and immediate background starts, none of which needs a foreground observation budget. An invalid default therefore prevents agents from managing existing scripts.

---

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

[greptile-apps]

Completion notice promises evicted result The notice tells the agent to retrieve the result by script_id, but if five other executions settle before the agent acts on the queued wake, this result is evicted. action=wait then returns no script, leaving a foreground script’s full output unavailable beyond the notice’s short tail.

Prompt To Fix With AI

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

Comment:
**Completion notice promises evicted result** The notice tells the agent to retrieve the result by `script_id`, but if five other executions settle before the agent acts on the queued wake, this result is evicted. `action=wait` then returns `no script`, leaving a foreground script’s full output unavailable beyond the notice’s short tail.

---

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

[Meganeuridae]

Updated to 39f474c: merged current main (including #203's per-call time_limit_ms), then addressed both reviews. Full suite 1138 pass / 0 fail / 4 skipped. Every fix below has a test, and each test was checked by reverting its fix and seeing it fail (14 reverts, 14 failures).

Greptile

1. Late end-turn affects another turn. Fixed. An inner end-turn now ends only a turn still waiting on the script (record.run.observing). Once the call has returned running, a late request is dropped instead of ending whichever later wait retrieves the result. Test: an inner end-turn ends only a turn that is still waiting on the script.
2. Deferred wake acknowledged too early. Contract made explicit, not changed. A wake queued behind the agent's live turn is acknowledged once it is in the deferred queue: the same queue and guarantee every other writer gets, including module events and message.send. Holding the script until the turn's next boundary would stall watchers. It would also make an agent that observes its own background script with wait_ms always time out, because the wake can't land until that observation returns. What remains is a queued write the store rejects at flush, which the framework logs and drops for every writer. The design note said "only after context delivery", which overstated this; it now states what happens. A per-message delivery receipt is in the note's next steps and would serve every writer, not only scripts.
3. Invalid default blocks script management. Fixed. codeExecution.foregroundWaitMs is validated in validateCodeExecutionConfig when the framework is created. Per call, only an explicit wait_ms is checked, so configuration can no longer block list or cancel. Test: an out-of-range foregroundWaitMs is refused when the framework is created.
4. Completion notice promises evicted result. Fixed. A result announced by a completion notice is kept until the agent retrieves it, at most 20 per agent so an agent that never retrieves can't grow memory. Other settled results keep the five-deep rule. The notice now says "kept until you retrieve it", and an evicted id's error says it is no longer retained. Test: a result announced by a completion notice is kept until retrieved.

@slimepriestess

1. Ephemerals. I chose blocking semantics. An ephemeral's foreground call always waits for its script to end (bounded by the script's time limit), whatever wait_ms says, so it is never promised a wake. Test: an ephemeral agent waits for its script to finish instead of being promised a wake.
2. Revert-red tests for the four fixes, all added:
   • background inner end-turn: a background script's inner end-turn never ends a foreground call
   • observed-only abortAgentScript: a failed turn stops the script it is waiting on, never one it already left running
   • stale wake_ack: does not deliver a late wake acknowledgement to a replacement interpreter
   • wakeAbort: a pending rate-limited wake is released when its script ends
3. Typecheck on main. Fixed in the merge. getHostModeStatus counts running background interpreters.
4. Quiesce. Keeps Quiesce/maintenance mode: pause main thread + MCPLs, run maintenance through the live compression machinery #122's guarantee. drained is false while any foreground script runs, including one whose call already returned. The drain waits for those scripts, and abandon stops them; the owner gets the completion notice at resume. Background watchers stay exempt. backgroundScripts is unchanged, and status adds foregroundScripts. Test: quiesce drains scripts that outlived their turn; abandon stops them and spares watchers.
5. Description. The header comment and the original description are restored verbatim. That includes "call tools directly when a single call answers the question", the sanitized-name examples and the wake-rule caution. Only the waiting sentences and the retention sentence are added. feat(code-execution): per-call time limit (time_limit_ms) #203's time-limit sentence already says a script is stopped at its limit, even after the call returns.
6. Resolved by Greptile 1.
7. Completion notices stay system. wake_agent(payload) messages are conversational again, as on main, since that is the script speaking to its agent. Both are asserted in tests.
8. The rejection guard is back in ScriptRun: a rejected completion settles as a failed result. It uses a single then(ok, fail), so completion ordering is unchanged. Test added.
9. A completion notice that can't be delivered is now logged with its script id.

The cancel test now also asserts that a prior global is gone after cancelling.

@antra-tess: items 4, 5 and 7 were yours to rule on. In each case I kept the old behaviour, and any of them can be changed.

#181 is separate and not included here.

[nissa-seru]

@Meganeuridae #608 replaced the Python code_execution runner with JavaScript in a QuickJS isolate; if makes sense, it may be cleanest for us to close this PR and open a separate one if similar issues remain in the JS-based runner.