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

README.md

@@ -161,15 +161,23 @@ agent-framework-recover \
 
 The specified Discord message is the last message the agent will still see;
 everything after it is left on the old branch. The command scans in bounded
-windows, never compiles message content, activates
-the new Chronicle branch, and writes only Discord `{serverId, channelId,
-messageId}` metadata to
-`<store>/recovery/discord-awareness-outbox.json`. When the host and that
-agent's `discord-mcpl` bot reconnect, each addressable discarded message is
-marked with 💤. Delivery state is recorded per message: retryable failures
-remain queued, permanent deleted/inaccessible-message failures remain in the
-audit ledger without blocking later markers. Portal and other non-Discord
-records are ignored.
+windows, never compiles message content, and activates the new Chronicle
+branch. By default the recovery is local to the resident: nothing is posted to
+Discord. To let the people involved see that the agent no longer has their
+messages, choose awareness marks explicitly with `--marks addressed` (removed
+messages that mentioned or replied to the bot, and DMs) or `--marks all`
+(every removed Discord message). The output counts what will be marked and
+what stays unmarked, and `--dry-run` shows exactly which addresses each choice
+covers. Only `{serverId, channelId, messageId}` metadata is written, to the
+awareness journal kept in the store itself, and the marks are delivered when
+the host and that agent's `discord-mcpl` bot next connect (see
+[Live surgery and Discord awareness marks](#live-surgery-and-discord-awareness-marks)).
+If the branch is made but the marks can't be recorded, the output's `markers`
+says so and the branch stands. Like a live surgery, the recovery (with its
+marks choice and receipt) is recorded in the store's operator log,
+`operator-actions.jsonl`, with the OS account that ran it; so is each
+`--awareness` cancel, retract and release. A dry run records nothing.
+Portal and other non-Discord records are ignored.
 
 When the safe point is an assistant/tool-side record rather than a Discord
 message, use its exact ContextManager message ID:
@@ -202,7 +210,7 @@ agent-framework-recover \
 `--suppress-range <first>..<last>` suppresses the inclusive context interval
 between two Discord messages, including intervening agent/tool entries. These
 removals exist only on the recovery branch; the source branch remains intact.
-Suppressed Discord messages are queued for the same 💤 awareness marker.
+Suppressed Discord messages follow the same `--marks` choice.
 Selections that split a sharded body group or a tool-use/tool-result exchange
 are rejected. The suppression plan is journaled before the branch switch; if
 the recovery process is interrupted between interval removals, framework
@@ -212,17 +220,10 @@ For old stores whose messages lack `metadata.serverId`, supply
 normal agent host must be stopped while this command has the Chronicle store
 open.
 
-The marker sidecar is a retained operation ledger, not a delete-on-success
-queue. Switching back to the source branch queues removal of the bot's marker;
-returning to the recovery branch queues it again. Initial MCPL events remain
-buffered until the ledger has been reconciled. Startup, reconnect, runtime
-list-change, and online undo use one framework-global generation: every MCPL
-data plane waits while all control planes remain live for registration and
-marker service. Awareness marker calls also have a mandatory deadline that is
-independent of `requestTimeoutMs` (including when that value is `0`); configure
-it with `discordAwarenessDeadlineMs` (default 10000ms, clamped to 50..60000ms).
-Configure the online marker with `discordAwarenessEmoji`; the offline CLI
-accepts `--emoji`.
+With the host stopped, the same command inspects and controls the awareness
+journal: `--awareness list`, `--awareness cancel <batch|retract-request>`,
+`--awareness retract <batch|all>` and `--awareness release <batch>` behave as
+the live controls described below.
 
 ### MCPL (MCP Live)
 
@@ -324,6 +325,99 @@ servers granted `allowHostCommands`. The HTTP host verbs accept an optional
 shared secret (`ApiServerConfig.adminToken`, sent as `x-admin-token`) for
 deployments that front the port with a proxy.
 
+### Live surgery and Discord awareness marks
+
+`rollbackToMessage(agent, { messageId })` forks the agent's context at a
+message and switches to the fork; `suppressMessages(agent, { messageIds })`
+forks at the head and removes the chosen messages on the fork. The source
+branch stays intact either way. Removing Discord messages from an agent's
+context is local to that agent unless the operator also chooses to mark them:
+
+```typescript
+const preview = framework.previewSurgeryMarks('cairn', { rollbackTo: messageId });
+// preview.scopes.addressed / .all: count, per-channel counts and refs
+const result = await framework.rollbackToMessage('cairn', {
+  messageId,
+  marks: { scope: 'addressed', refs: preview.scopes.addressed.refs },
+});
+// result.markers: { status: 'none' | 'queued' | 'not-scheduled' | 'unresolved', ... }
+```
+
+- **`marks`** is `'none'` (the default), or `{ scope: 'addressed' | 'all', refs? }`.
+  `addressed` covers messages tagged `chat:addressed` (mentions, replies to
+  the bot, DMs). Passing a preview's `refs` binds the choice to exactly that
+  set: messages that arrive before the surgery applies are removed locally but
+  never marked. The choice is recorded in the operator log.
+- **The surgery returns once marks are scheduled**, never after Discord has
+  accepted them. `result.markers` says whether they were scheduled (`queued`
+  with a count and batch id), not chosen or not in scope (`none`), not to be
+  delivered because recording the batch failed after the body change and it
+  was retired or never recorded (`not-scheduled`), or `unresolved` (neither
+  activation nor retirement could be recorded, or the journal could not be
+  read back to say whether the batch was; it names a batch that may still be
+  delivered). Every receipt also counts the removed messages left unmarked.
+  Marker bookkeeping never fails or undoes an applied rollback or
+  suppression.
+- **Delivery runs in the background** and never holds MCPL traffic or turns.
+  A route that is not connected keeps its work queued until it connects.
+  Each reaction call has a mandatory deadline independent of
+  `requestTimeoutMs` (including `0`): `discordAwarenessDeadlineMs` (default
+  10000ms, clamped to 50..60000ms). The emoji is `discordAwarenessEmoji`
+  (offline: `--emoji`).
+- **Marks are one-shot.** Switching branches, undo/redo and restarts never add
+  or remove a mark. The journal is an append-only history of requests and
+  their attempts, kept as typed records in the Chronicle store: it survives
+  rollbacks, branch deletion and a killed process, and lives with its store.
+  Each request is written ahead of its dispatch, and a dispatch is admitted
+  from the journal as it is at that moment, so a cancel takes effect even
+  while an earlier request is on the wire. A request written and never
+  answered is recorded as `unknown`, and a later confirmation of a different
+  attempt never resolves it. Between opposite requests for one reaction,
+  the later *authorization* wins, whenever each request was created: a
+  surgery's adds carry the moment of its marks choice, even when activation
+  comes later, so a retract made in between prevails; a release is a new
+  act. A record that certifies a body change (an activation, a completed
+  suppression, a retirement, or the batch a hide or turn undo records after
+  its change) is written only after that change is synced.
+  A batch whose surgery was interrupted before its branch switch was
+  recorded is held at startup until an operator releases it; an interrupted
+  suppression's redactions are resumed whenever its branch is active at
+  startup, whatever its marks' state.
+- **Operator controls,** each recorded in the operator log:
+  - `listDiscordAwareness()` lists batches and retract requests;
+  - `cancelDiscordAwareness(batch | retractRequest)` stops all further sends
+    and retries of a batch's marks or a retract's removals, and never removes
+    or undoes anything. Its receipt counts requests in flight or unknown,
+    including earlier attempts later answered, any of which may still land;
+  - `retractDiscordAwareness(batch | 'all')` queues removal of this bot's
+    reaction, through each address's configured MCPL route, for every message
+    of the batch (or of every batch not retired by its own surgery, prepared,
+    held or active, and every message an imported ledger recorded), whatever
+    history says: removing an absent reaction does nothing. As the latest
+    authorization for those messages, it stops adds that haven't ended and
+    any an earlier choice would request later; cancelling it never revives
+    them. Its receipt discloses earlier requests whose outcome is unknown and
+    imported history that leaves outcomes unrecorded;
+  - `releaseDiscordAwareness(batch)` queues a held batch.
+- **Over `host/command`** (servers granted `allowHostCommands`): `undo` (by
+  messages or by turns) and `hide` take `marks: 'none' | 'addressed' | 'all'`
+  (default `none`; any other value is refused) and return `markers`. Each
+  holds the store like every surgery, so it is refused while any agent
+  sharing the store is mid-turn. The `marks` verb takes `action: 'list'
+  | 'cancel' | 'retract' | 'release'` with a `target` (a batch id; for cancel
+  also a retract request id; for retract also `all`).
+
+A pre-journal awareness ledger (`discord-awareness-outbox.json` under the
+store, or `discordAwarenessOutboxPath`) is imported once on first use and the
+file renamed `.migrated-v2`. What it recorded about each message is kept as
+evidence (attempt count; the last action and the outcome its error field
+establishes; the old writer's delivery status, labelled as the
+reconciliation state it was; and how many attempt outcomes it leaves
+unrecorded), never as a claim about what is on Discord,
+and an imported `active` suppression is not taken as proof that its body
+completed: startup verifies and resumes its intervals on its branch. Its
+undelivered work is held for an explicit release.
+
 ## Observability
 
 Subscribe to trace events for logging, UI updates, or debugging:

changelog.d/255-operator-change-gate.added.md

@@ -0,0 +1,10 @@
+- **An operator-change gate for imposed body changes** (#255). With `FrameworkConfig.operatorChangeGate`, the framework's own operator mutations are resolved to an absolute change and handed to the host's gate, which stages it and answers with a receipt: accepted and queued, not applied. They are a `host/command` undo (by turns or by messages), hide or unstick, and an operator's or module's mutating `agent_settings` or tool-presentation call. The host applies a staged change only through `applyResolvedOperatorChange`, under a held safe-boundary lease. Without a gate, every operator path behaves as before, except that `resume()` refuses while a cut a gated run left unresolved or abandoned holds the active body (see Breaking).
+  - Each cut and hide attempt is journaled in the store (`operator/changes`) before it acts, and recovery settles it from that record: a cut whose outcome can't be told waits for an operator's verdict, and a hide, whose effect can be read back, is re-run. An unstick keeps its own journal (`operator/unstick`). `getOperatorChangeRecord` reads a change's record, `resolveOperatorChange` settles an attempt whose outcome can't be told (or `agent-framework-recover`, offline), and `restoreOperatorChangeSource` restores the source of a cut that didn't commit.
+  - An unstick is a planned, journaled operation: it sheds the newest exchanges a step at a time until a re-run responds.
+  - An applied undo-turns receipt reports what its cut removed (`messagesRemoved`), and a resolved undo, by turns or by messages, records how many messages followed the cut when it was staged (`messagesAfter`).
+  - `previewSurgeryMarks` returns the store and branch it previewed (`context: {storeId, branch}`), and `getStoreIdentity()` names the store, so a host can bind a staged surgery to where it was previewed.
+  - A staged change's Discord awareness marks can be chosen at staging (`prepare({ id, staged: true, … })`), and are activated by the change once its body change is established.
+- **`runAtSafeBoundary(opts, fn)`** holds a store reservation across a host callback, with no turn running, for work that must not interleave with one (#255).
+- **A tool call carries who initiated it** through every redispatch: the agent itself, the operator (through a puppet call), or the host. So a gate can tell an imposed change from the agent's own (#255).
+- **`ModuleContext.addMessage` delivery options** (#255): a targeted, receipted delivery, optionally made durable before its receipt says so.
+- **`Module.getSubconsciousTools()`** offers a module's tools on the subconscious's surface (#255).

changelog.d/255-operator-change-gate.breaking.md

@@ -0,0 +1,9 @@
+- **API server and MCP clients:** while an operator-change gate is configured, the API server refuses `undo`, `redo`, `branch.switch` and `branch.create` with `switchTo` whole, saying why, since it can't stage them (#255). The MCP server's `branch_switch`, and its `branch_create` with `switchTo`, are refused the same way; a `branch_create` without `switchTo` still works. An undo can be staged instead, through the host's gated `host/command` undo; redo and branch switching have no gated route, so under a gate they're refused. Without a gate, nothing changes. Gate or not, `branch.delete` refuses a branch that an operator change not yet settled names as its attempt's source or destination, since its recovery reads that branch.
+- **Script authors (`code_execution`):** a script's tool call is served only while the exec that made it is running, as whoever started that exec (#255).
+  - A task a script leaves running past its exec has its later tool calls refused: its standing ended with its exec. They used to run, unrecorded, as the agent's own. A foreground script's result notes in its stderr how many of the tasks it started were still running when it ended (on Python before 3.12, the tasks created while it ran, which can include ones a leftover task from an earlier exec started).
+  - A call sent from a thread the script started (as with `run_coroutine_threadsafe`) is refused as untraceable.
+- **Module and host authors:** a caller-named origin is normalized (#255). Anything other than absent or `'puppet'` acts for the host, never as the agent's own. Likewise:
+  - a tool-call event that anything other than the framework's own dispatch queues (a module or the host) acts for the host, unless it names the operator;
+  - trace listeners are notified as the host's;
+  - an agent's own call delegating to another agent acts for the host; a puppet's or the host's call keeps its origin through a delegation.
+- **Hosts:** `resume()` refuses, force or not, while the active body is the destination of an unresolved or abandoned cut, until it's resolved or its source restored (#255).

changelog.d/255-stop-admission.fixed.md

@@ -0,0 +1 @@
+- `stop()` closes admission before its first await: no lease, direct surgery, ephemeral agent or conversation fork enters the store once it has begun. Before tearing anything down it waits for the holder of a store reservation and for agents and conversation forks still being created; live agent streams are cancelled, as before (#255).

changelog.d/fix-surgery-marks-receipt.fixed.md

@@ -0,0 +1,14 @@
+- Live `rollbackToMessage` and `suppressMessages` (and message-granular
+  `host/command` undo, which rides on rollback) return once the body change
+  has landed, with a marker-scheduling receipt, instead of after every 💤
+  reaction has been delivered. Previously the store stayed reserved, and the
+  operator got no answer, for the whole serial drain. At the reported pace
+  of about one reaction per second, 918 queued marks would take roughly 15
+  minutes; the household's client timed out after 60 seconds. Delivery now
+  continues in the background. The result's new `markers` field (`none` |
+  `queued` | `not-scheduled` | `unresolved`) says whether marks were scheduled, never
+  that Discord accepted them. If the ledger write after the switch fails, the
+  rollback that already applied is no longer reported as failed: the batch is
+  retired (`not-scheduled`), or, if even that write fails, the result says
+  the batch may still be delivered (`unresolved`). A suppression whose
+  redactions all committed is no longer undone by that failure.

changelog.d/mcpl-reconnect-registration.fixed.md

@@ -0,0 +1,10 @@
+- An MCPL server that reconnects now has its channel registration accepted.
+  A reconnect resets the server's grant, and its traffic used to reach
+  admission before the host's new §5.3 policy Request was answered: a
+  `channels/register` sent right after initialize, as chat bridges do, was
+  refused (-32002) and never replayed, so the route's incoming messages
+  stayed unknown channels until the server registered again. A reconnect
+  now holds control traffic as well as data until the new grant is
+  established, as initial connect already did, both for a connection that
+  was open and for one whose first connect had failed, and even when
+  startup or a quiesce resume opens every connection meanwhile.

changelog.d/mcpl-request-outcome.added.md

@@ -0,0 +1,10 @@
+- **`McplRequestError`: why an MCPL request produced no result.** A request
+  to an MCPL server that fails now rejects with `McplRequestError` (exported),
+  whose `outcome` says which of three things happened: `not-sent` (refused
+  before anything was written: the connection was already closed),
+  `error-response` (the server answered with a JSON-RPC error; `code` and the
+  error's `data` are kept), or `no-response` (the request was handed to the
+  transport and no answer came back: a timeout, or the connection closed
+  while awaiting; it may or may not have reached the server). Only
+  `not-sent` proves the server never saw the request. Messages are unchanged,
+  and it is still an `Error`, so existing handling keeps working.

changelog.d/surgery-marks-controls.added.md

@@ -0,0 +1,34 @@
+- Operator controls for awareness marks:
+  - `previewSurgeryMarks(agent, { rollbackTo } | { suppress })` shows what a
+    surgery would remove and which messages each scope would mark, per
+    channel.
+  - `listDiscordAwareness()` lists the journal's batches and retract
+    requests.
+  - `cancelDiscordAwareness(batch | retractRequest)` stops all further sends
+    and retries of a batch's marks, or of a retract's removals, and never
+    removes or undoes anything. Its receipt counts requests in flight or
+    unknown, including earlier attempts later answered, which may still land.
+  - `retractDiscordAwareness(batch | 'all')` queues removal of this bot's
+    reaction, through each message's configured MCPL route, for every
+    selected message, whatever history says. As the latest authorization
+    for those messages, it stops adds that haven't ended and any an earlier
+    choice would request later (a prepared surgery's activation), and
+    cancelling it never revives them. Its receipt discloses requests whose
+    outcome is unknown and imported history that leaves outcomes
+    unrecorded.
+  - `releaseDiscordAwareness(batch)` queues a held batch.
+
+  Each control is recorded in the operator log. The same controls are
+  available as the `host/command` `marks` verb (`action: list | cancel |
+  retract | release`, `target`) and, with the host stopped, as
+  `agent-framework-recover --awareness list|cancel|retract|release`.
+- A turn-based `host/command` `undo` that undoes a turn records one
+  `undo-turns` entry in the operator log: the requested turns, the marks
+  choice (`none` included) and the receipt, beside the per-turn `undo-turn`
+  entries.
+- `agent-framework-recover` records its acts in the store's operator log
+  (`<store>/operator-actions.jsonl`), done or refused, with the OS account
+  that ran it: each `--awareness` cancel, retract and release, and each
+  recovery with its marks choice and receipt (kind `recovery`). A list, and
+  a recovery's dry run, record nothing. `--dry-run` with `--awareness` is
+  refused: a control has no preview.