instar 1.3.43 → 1.3.45

package/upgrades/side-effects/cross-machine-seamlessness-exactly-once-ingress.md

@@ -0,0 +1,73 @@
+# Side-Effects Review — Cross-Machine Seamlessness: exactly-once ingress gate (D, no-duplicate half)
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §8 G3a (converged, approved)
+
+Wires the MessageProcessingLedger into the live Telegram message path so a redelivered /
+handoff-window-replayed inbound event is recognized and NOT answered twice. This is the
+no-DUPLICATE-reply half of G3a. It ships DARK behind `multiMachine.exactlyOnceIngress`
+(default false): when off, the message path is byte-for-byte unchanged.
+
+## What changed
+- `src/messaging/ingressDedup.ts` — NEW. `decideIngress(ledger, dedupeKey, opts)` → process | drop
+  (records received → claims processing under the lease epoch; drops already-replied or
+  in-flight-not-stuck; re-claims a fenced-holder's stuck entry). `commitInboundReply(...)` →
+  reply_committed + cursor_advanced with the deterministic idempotency key. `dedupeKeyFor(...)`.
+- `src/server/routes.ts` — INBOUND gate in `/internal/telegram-forward`, placed AFTER the
+  sentinel intercept (emergency-stop/pause must never be deduped) and BEFORE routing: on a
+  drop, returns `{ok:true,deduped:true}` without routing. OUTBOUND commit in
+  `/telegram/reply/:topicId` after a successful `sendToTopic`: commits the topic's current
+  inbound dedupeKey (skipped for proxy/system sends). Both FAIL-OPEN. Added `messageLedger` +
+  `currentInboundByTopic` to RouteContext.
+- `src/server/AgentServer.ts` — `messageLedger?` + `currentInboundByTopic?` options → routeCtx.
+- `src/commands/server.ts` — constructs the ledger + per-topic map ONLY when
+  `seamlessness.exactlyOnceIngress` (fail-open if open() throws → gate stays dark).
+- `src/core/seamlessnessConfig.ts` + `src/core/types.ts` — `exactlyOnceIngress` flag (default false).
+- `src/core/MultiMachineCoordinator.ts` — `getLeaseEpoch()` accessor (the ledger's fencing token).
+
+## Over-block / under-block
+- UNDER-block (the dangerous direction = a real message silently dropped): mitigated three ways.
+  (1) The gate ONLY drops when the ledger shows the SAME dedupeKey already reply_committed/
+  cursor_advanced, or processing-and-not-stuck — never a first-seen event. Proven both sides in
+  ingress-dedup.test.ts + the integration test. (2) FAIL-OPEN: any ledger throw routes normally
+  (tested). (3) Ships DARK (flag default false) — zero behavior change until a live test-as-self
+  flips it on.
+- OVER-block: a genuine NEW message is always `first-seen` → process. The dedupeKey is
+  `telegram:<topic>:<messageId>`, unique per user message, so two distinct messages never collide.
+- dedupeKey uses Telegram `message_id` (already on the forward, stable across redeliveries and
+  across machines). The spec names `update_id`; message_id is the functional v1 key (gate falls
+  back to it). update_id threading is a tracked refinement. <!-- tracked: topic-13481 -->
+
+## Signal vs authority
+- decideIngress returns a decision; the route is the single authority that drops/routes. The
+  ledger is durable record + fencing, not a gate of its own.
+
+## Interactions
+- Placed after the sentinel intercept so "stop everything" is never deduped (wiring-integrity
+  test asserts gate index is between classify and onTopicMessage).
+- Outbound commit skipped for `isProxy` sends (PresenceProxy etc. are not replies to a user
+  inbound) so it never falsely commits an unrelated topic.
+- `currentInboundByTopic` is best-effort association (last claimed inbound per topic). Concurrent
+  inbounds for one topic before the first reply → the earlier one stays processing (eventually
+  reclaimable / replayed). Acceptable for v1, behind the flag.
+
+## NOT in this increment (tracked, topic-13481)
+- **No-LOSS-on-crash replay** (re-inject un-committed entries on restart) — the other G3a half.
+  Without it, this increment is a strict IMPROVEMENT (adds dedup, no regression: a crash after
+  inject-before-reply loses the reply exactly as today). Next increment.
+- Cross-machine `applyRemoteReplyMarker` propagation (tunnel+git) — the lease already ensures one
+  forwarder, so cross-machine double-handle is already prevented; this hardens the failover window.
+- CONTINUATION resume verification (D3); update_id dedupeKey (vs message_id).
+
+## Rollback cost
+- Low. Flag default-off ⇒ inert in production. Revert = drop the gate block + commit block + the
+  ledger construction; no migration, no persisted schema beyond the opt-in SQLite file. The route
+  returns to identical behavior when `messageLedger` is null.
+
+## Tests
+- `tests/unit/ingress-dedup.test.ts` (8) — decision both sides: first-seen, in-flight drop,
+  already-replied drop, stuck re-claim, within-window no-reclaim; commit idempotent + deterministic key.
+- `tests/integration/exactly-once-ingress.test.ts` (5) — gate through the REAL route + REAL ledger:
+  dark routes both, first routes + claims, in-flight dup dropped, already-replied dup dropped,
+  fail-open; + wiring-integrity (gate between sentinel and routing).
+- `tests/e2e/exactly-once-ingress-e2e.test.ts` (1) — gate ALIVE in a real booted AgentServer:
+  already-replied redelivery → 200 + deduped over real HTTP, not routed.

package/upgrades/side-effects/cross-machine-seamlessness-handoff-ack-yield.md

@@ -0,0 +1,82 @@
+# Side-Effects Review — Cross-Machine Seamlessness: handoff ack/yield wire
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §8 G3d/G3e (converged, approved)
+
+Third piece of the wire-transport increment. The point-to-point ack/yield channel
+the two machines use to negotiate a verified, lease-safe planned handoff.
+
+## What changed
+- `src/core/HandoffWireTransport.ts` — NEW. Symmetric transport, used per-role:
+  - OUTGOING: `awaitAck(timeoutMs)` (resolves when the incoming POSTs its ack via
+    recordAck; null on timeout, timer unref'd), `sendYield()` (POST the explicit
+    yield to the incoming).
+  - INCOMING: `sendAck(ack)` (POST the "caught up" echo to the outgoing),
+    `onYield(cb)`/`recordYield()` (the yield route triggers the incoming's lease CAS).
+  All POSTs ride the authenticated channel (signRequest). Injected fetch/clock.
+- `src/server/machineRoutes.ts` — NEW routes `POST /api/handoff/ack` and
+  `POST /api/handoff/yield` (both authMiddleware). `/ack` validates the echo shape
+  (tailSeq + ingressPosition + threadHistoryHash) and delivers it via `onHandoffAck`;
+  `/yield` delivers via `onHandoffYield`. Both return 503 when the callback is
+  absent (honest — consistent with the live-tail receiver), never a silent ok.
+- `src/server/AgentServer.ts` — NEW `handoffWireTransport?` option
+  (`{ recordAck, recordYield }`, mirrors `leaseTransport`). When present, the mount
+  wires `onHandoffAck → transport.recordAck` and `onHandoffYield → transport.recordYield`;
+  absent → the routes stay 503. This is what flips the routes from dangling handlers
+  to LIVE on a mesh machine.
+- `src/commands/server.ts` — instantiate ONE `HandoffWireTransport` in the fenced-lease
+  block (gated on `coordinator.enabled && isGitRepo && gitBackupEnabled`), with a 1:1
+  `peer()` resolver (first reachable non-self machine; null for a solo agent → sends are
+  reachable no-ops) and a monotonic `nextSequence`. Passed straight into AgentServer
+  options. A single-machine mesh behaves exactly as before (no peer → no sends).
+
+## Over-block / under-block
+- The yield is the SOLE trigger for the incoming's lease CAS (the design closes the
+  two-holders-same-epoch window). A dropped/missing yield → the incoming simply never
+  acquires → the outgoing stays awake (safe under-action, no double-leader).
+- `awaitAck` supersedes any stale pending wait and always resolves (ack or null) — it
+  cannot wedge the HandoffSentinel.
+- recordAck with no pending wait, recordYield with no handler, and no-peer sends are all
+  safe no-ops / false returns (tested).
+
+## Signal vs authority
+- The transport carries no authority — it moves the ack and the yield. The DECISION to
+  yield (verified ack + passing validation) lives in HandoffSentinel (§8 G3e), which is
+  the next integrating step that constructs these ops; the lease CAS itself is the
+  authority. This transport only delivers the negotiated signals.
+
+## Interactions
+- Reuses signRequest/machineAuthMiddleware (the same authenticated machine channel as
+  /api/lease and /api/live-tail). 1:1 with the single peer (resolved by the caller).
+- Consumes `HandoffAck`/`IngressPosition` from HandoffSentinel/types (already shipped).
+- **Done here:** the transport is now instantiated in server.ts and bolted into the
+  live route mount via the AgentServer option — both routes are LIVE on a mesh machine
+  (e2e-proven through the real booted server). The transport carries the ack/yield; with
+  no handler registered yet, recordAck-with-no-pending and recordYield-with-no-handler are
+  safe no-ops (logged, 200 at the route).
+- **Next piece (next increment):** construct the OUTGOING HandoffSentinel (drives flush →
+  awaitAck-on-this-transport → verify → sendYield → demoteSelf) and the INCOMING
+  HandoffReceiver (buildAck from buffer+ingress+threadHash; `onYield` registers the
+  receiver's lease-CAS via `recordYield`), plus the `inProgress` race guard so the
+  reaper/scheduler don't act mid-handoff. <!-- tracked: topic-13481 -->
+
+## Rollback cost
+- Low. Two additive routes + one new standalone class + one optional AgentServer option +
+  one gated server.ts instantiation. Reverting removes them with no behavior change to a
+  solo agent (the transport is a reachable no-op with no peer) and only disables the
+  not-yet-orchestrated ack/yield channel on a mesh.
+
+## Tests
+- `tests/unit/HandoffWireTransport.test.ts` (7): awaitAck resolves on recordAck, awaitAck
+  times out → null, sendYield/sendAck POST to the right endpoints with signed headers,
+  onYield handler fires, no-peer → false, recordAck-with-no-pending safe no-op. tsc clean.
+- `tests/integration/machine-routes.test.ts` (+6, route surface): a valid signed ack is
+  delivered to `onHandoffAck` with the authenticated machine id; a malformed echo (missing
+  ingressPosition/threadHistoryHash) → 400 and the callback never fires; an unauthenticated
+  ack/yield → 401; a valid signed yield is delivered to `onHandoffYield` with the machine id;
+  and — the honest-503 contract — a route set built WITHOUT the callbacks returns 503 for
+  both ack and yield (never a silent ok). Full machine-routes suite green (20/20), tsc clean.
+- `tests/e2e/multi-machine-http.test.ts` (+3, feature-is-alive): two AgentServers boot for
+  real; a signed ack POSTed from machine B over HTTP resolves machine A's pending
+  `awaitAck` with the echoed tailSeq/hash; a signed yield fires A's registered yield
+  handler; an unsigned ack → 401 and a malformed echo → 400. This is the Tier-3 proof that
+  the routes are ALIVE through the production AgentServer mount, not silently 503. (12/12)

package/upgrades/side-effects/cross-machine-seamlessness-handoff-begin.md

@@ -0,0 +1,48 @@
+# Side-Effects Review — Cross-Machine Seamlessness: handoff begin signal
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §8 G3d (converged, approved)
+
+The begin signal the spec's planned-handoff protocol needs but left implicit: the
+point-to-point message by which the OUTGOING machine opens a handoff and hands the
+INCOMING machine the flush manifest it must echo. Symmetric with the ack/yield routes
+already shipped (commit 5fc5a1008). This increment lands the ROUTE SURFACE only; the
+incoming HandoffReceiver that consumes it and the outgoing HandoffSentinel that POSTs it
+are the next sub-increments (C-receiver, C2 — tracked in docs/SEAMLESSNESS-WIRING-PLAN.md).
+
+## What changed
+- `src/server/machineRoutes.ts` — NEW route `POST /api/handoff/begin` (authMiddleware).
+  Validates the manifest shape (tailSeq:number + ingressPosition + threadHistoryHash:string;
+  topic is carried for the incoming's hash recomputation) and delivers it via `onHandoffBegin`.
+  Returns 400 on a malformed manifest, 401 unauthenticated, and 503 when the callback is
+  absent (honest not-wired — never a silent ok).
+- `src/server/AgentServer.ts` — NEW `onHandoffBegin?` option forwarded into the route mount.
+  Absent → the begin route 503s. server.ts will bind it (C-receiver) to store the manifest
+  and drive HandoffReceiver.onBeginHandoff.
+
+## Over-block / under-block
+- The begin route carries no authority — it only delivers a manifest to the incoming. The
+  incoming still attempts NO lease action on begin (it only builds + sends its ack); the lease
+  CAS happens solely on the later explicit yield. So a spurious/forged begin (rejected anyway
+  by machineAuth) cannot move the lease.
+- Manifest validation is shape-only here; the semantic echo-verification (does the incoming's
+  ack match what the outgoing flushed?) is the HandoffSentinel's job (§8 G3e), unchanged.
+
+## Signal vs authority
+- Pure transport/signal. No role mutation, no lease mutation. The authority (yield → CAS)
+  is untouched.
+
+## Interactions
+- Same authenticated machine channel (signRequest/machineAuthMiddleware) as
+  /api/lease, /api/live-tail, /api/handoff/{ack,yield}. 1:1 with the single peer.
+- Consumes nothing new; produces a delivered manifest for the (next-increment) receiver.
+
+## Rollback cost
+- Minimal. One additive route + one optional option. Reverting removes them with no behavior
+  change (the route 503s today since server.ts does not yet supply the callback).
+
+## Tests
+- `tests/integration/machine-routes.test.ts` (+3): a valid signed begin → onHandoffBegin with
+  the manifest + machine id; a malformed manifest → 400 (callback never fires); unauthenticated
+  → 401; plus the unwired route → 503 (extended the honest-503 case). 23/23.
+- `tests/e2e/multi-machine-http.test.ts` (+1, feature-is-alive): a signed begin POSTed from
+  machine B reaches machine A's onHandoffBegin through the real booted server. 13/13. tsc clean.

package/upgrades/side-effects/cross-machine-seamlessness-handoff-boot-wiring.md

@@ -0,0 +1,68 @@
+# Side-Effects Review — Cross-Machine Seamlessness: handoff sentinel boot-wiring + operator trigger (C2b/C3)
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §8 G3e (converged, approved)
+
+Bolts the outgoing planned-handoff conductor (HandoffSentinel, built + unit-tested as a
+factory in the prior increment) into the live server boot, and exposes the explicit
+operator/test trigger. The protocol pieces (lease, live-tail, ack/yield/begin wire, receiver)
+were already wired in earlier increments; this closes the outgoing-side gap so a planned
+handoff can actually be initiated and run end-to-end. C2b (boot wiring + trigger route) and C3
+(two-server e2e) land together because the trigger route touches `src/server/`, which the
+e2e-pairing gate requires to ship with a `tests/e2e/*.test.ts`.
+
+## What changed
+- `src/core/handoffSentinelBootWiring.ts` — NEW. `createHandoffSentinelBootWiring(deps)` binds
+  the sentinel to the live components (Telegram adapter, coordinator, LiveTailSource, wire
+  transport) and owns the active-topic selection (`pickActiveTopic` — most-recently-active
+  topic; getTopicHistory is chronological so the last entry is newest). Extracted from server.ts
+  so the boot glue is a tested unit, mirroring `handoffReceiverWiring`.
+- `src/server/handoffInitiateRoutes.ts` — NEW. `POST /handoff/initiate` (bearer-authed, mounted
+  after the global auth middleware) → runs the sentinel to a terminal outcome; `failed`→500,
+  `handed-off`/`aborted-stay-awake`→200, both carry `{outcome,inProgress}`. `GET /handoff/status`
+  exposes `inProgress`. Unwired (solo / multi-machine off) → honest 503, never a silent ok.
+- `src/server/AgentServer.ts` — added `onHandoffInitiate?` + `handoffInProgress?` options;
+  imports + mounts `createHandoffInitiateRoutes` after the usher routes.
+- `src/commands/server.ts` — inside the live-tail block (where `liveTailSource` is in scope,
+  additionally gated on `handoffWireTransport`), constructs the boot wiring and exposes
+  `handoffInitiate` + `handoffSentinelInProgress` to the AgentServer constructor.
+
+## Over-block / under-block
+- The lease is NEVER yielded unless the incoming's echo verifies (HandoffSentinel.ackMatches)
+  AND validation passes — unchanged from the sentinel's own guarantee. The two-server e2e proves
+  it over real HTTP: a caught-up standby hands off (B acquires, A demotes); a stale standby
+  (divergent history → hash mismatch) makes A abort and stay awake with ZERO yield and B never
+  acquiring. No two-holders window.
+- The trigger is explicit-only. There is deliberately no sleep/wake auto-trigger:
+  SleepWakeDetector emits only a `wake` event (verified), so there is no pre-sleep hook for v1.
+  An automatic trigger is a tracked follow-on, NOT silently half-built here.
+- Unwired → 503 (honest), proven by the e2e against a server with no `onHandoffInitiate`.
+
+## Signal vs authority
+- The route only pulls the trigger and surfaces the outcome. The DECISION to yield lives in
+  HandoffSentinel; the lease CAS authority is the incoming coordinator's, fired solely by the
+  explicit yield. The boot wiring supplies ops; it holds no authority of its own.
+
+## Interactions
+- Reuses the exact factories server.ts already boots (`createHandoffSentinelWiring`,
+  `hashTopicHistory`) so outgoing-flush and incoming-echo hash identical bytes.
+- `handoffInProgress` / `HandoffSentinel.inProgress` race guard: there is currently NO
+  `holdsLease`-style gate in the scheduler or reaper to wire it into, so it is exposed
+  (AgentServer option + `GET /handoff/status`) for future consumers rather than threaded into a
+  nonexistent gate — wiring into a gate that doesn't exist would be scope creep. <!-- tracked: topic-13481 -->
+- The trigger route is bearer-authed via the existing global `authMiddleware`; no new auth
+  surface. The machine-to-machine begin/ack/yield routes (signed) are unchanged.
+
+## Rollback cost
+- Low. Two new standalone modules + two AgentServer options + one boot block. Reverting the
+  boot block + the route mount fully disables the trigger; the protocol primitives (already on
+  main from #419 + earlier wire increments) are untouched. No migration, no persisted state, no
+  schema. The route 503s by construction when the option is absent, so a partial revert
+  degrades safely.
+
+## Tests
+- `tests/unit/handoff-sentinel-boot-wiring.test.ts` (6) — wiring-integrity: non-null sentinel;
+  full happy `initiate()` delegates pushTick→sendBegin→awaitAck→sendYield→demote in order (not a
+  no-op); abort-on-echo-mismatch never yields/demotes; `pickActiveTopic` on all three branches.
+- `tests/e2e/planned-handoff-e2e.test.ts` (4) — two real booted AgentServers with real peer
+  resolvers: caught-up handoff (handed-off + B acquires with A's id + A demotes), stale-standby
+  abort (no yield, A keeps lease), route alive (200 outcome), route 503 when unwired.

package/upgrades/side-effects/cross-machine-seamlessness-handoff-receiver-wiring.md

@@ -0,0 +1,52 @@
+# Side-Effects Review — Cross-Machine Seamlessness: incoming handoff receiver wiring
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §8 G3d/G3e (converged, approved)
+
+Wires the INCOMING side of the planned handoff into the live server: the begin route
+now drives a real HandoffReceiver that builds + sends the caught-up ack, and the yield
+route now drives the lease CAS. Closes the gap where HandoffReceiver was a tested class
+with no production caller (spec §10 mandates it be constructed in startup, not dead code).
+
+## What changed
+- `src/core/handoffReceiverWiring.ts` — NEW. `createHandoffReceiverWiring(deps)` composes a
+  HandoffReceiver with ops bound to injected deps (sendAck, acquireLeaseOnConsent,
+  getTopicHistory) and returns `{ receiver, onBegin, yieldHandler }`. Extracted as a unit
+  (not inline in server.ts) per the Testing Integrity Standard so the DI wiring is testable.
+  Also exports `hashTopicHistory(getTopicHistory, topic)` — the canonical thread-history hash
+  the OUTGOING flush must reuse so the echo verifies. The hash uses the SAME content
+  formatting as LiveTailSource (`[ts] text\n`).
+- `src/commands/server.ts` — in the mesh/git block, when a handoffWireTransport + telegram +
+  coordinator exist, build the wiring, register `transport.onYield(wiring.yieldHandler)`, and
+  pass `wiring.onBegin` as the AgentServer `onHandoffBegin`. Gated on coordinator.enabled; a
+  solo/non-mesh agent constructs nothing.
+
+## Over-block / under-block
+- The lease CAS (`acquireLeaseOnConsent`) is invoked ONLY by the yield handler, and the
+  HandoffReceiver ignores a yield unless it is in `ack_sent` (a handoff is genuinely underway).
+  A bare/forged yield with no prior begin → no CAS (tested). The ack never moves the lease.
+- buildAck RECOMPUTES the hash from this machine's own synced history — it never echoes the
+  manifest's own hash. A not-caught-up standby therefore produces a non-matching echo, and the
+  outgoing's verify (HandoffSentinel.ackMatches) refuses to yield (tested: caught-up matches,
+  stale differs).
+- Manifest absent at buildAck time → throws → receiver goes `failed`, no ack sent (safe).
+
+## Signal vs authority
+- The wiring carries signals (manifest in, ack out) and triggers the consent-gated CAS, which
+  is the coordinator's authority. The wiring itself mutates no role/registry state.
+
+## Interactions
+- Reuses telegram.getTopicHistory (same call LiveTailSource uses for the tail content),
+  coordinator.acquireLeaseOnConsent (already shipped), and the HandoffWireTransport (sendAck /
+  onYield). The OUTGOING HandoffSentinel (next increment C2) POSTs the begin + drives the
+  flush and must reuse `hashTopicHistory` for the echo to verify. <!-- tracked: topic-13481 -->
+
+## Rollback cost
+- Low. One new standalone module + a gated wiring block. Reverting leaves the begin/ack/yield
+  routes 503 (no callback supplied) — exactly the prior state, no behavior change to a solo agent.
+
+## Tests
+- `tests/unit/handoff-receiver-wiring.test.ts` (3): begin → caught-up ack echoes tailSeq +
+  ingressPosition + a hash matching the outgoing's (caught-up) ; a stale local history yields a
+  NON-matching hash (so the echo won't verify) ; a yield with no handoff is ignored, and a yield
+  after a begin drives acquireLeaseOnConsent with the begin originator's machine id, reaching
+  `acquired`. tsc clean.

package/upgrades/side-effects/cross-machine-seamlessness-handoff-receiver.md

@@ -0,0 +1,46 @@
+# Side-Effects Review — Cross-Machine Seamlessness: HandoffReceiver (incoming side)
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §8 G3d/G3e (converged, approved)
+
+The INCOMING-machine half of the planned handoff — the counterpart to the
+outgoing-only HandoffSentinel. Completes the two-sided handoff protocol at the
+component level (both sides now exist + tested; only server wiring remains).
+
+## What changed
+- `src/core/HandoffReceiver.ts` — NEW, standalone state machine:
+  idle → catching_up → ack_sent → acquired | failed.
+  - onBeginHandoff(): builds the caught-up ack (tailSeq + ingressPosition +
+    threadHistoryHash), sends it to the outgoing machine. Build/send failure → failed.
+  - onYield(): acquires the lease via the consented path — but ONLY while a handoff
+    is genuinely in progress (state ack_sent). A stray yield is ignored.
+  All I/O (buildAck/sendAck/acquireOnYield) injected → unit-testable, channel-agnostic.
+
+## Over-block / under-block
+- Acting on yield ONLY in ack_sent is a deliberate over-guard: a stray/replayed yield
+  with no handoff underway is ignored (and the lease's own consent guard already refuses
+  a yield from a non-holder — defense in depth).
+- A failed consent acquire leaves the machine STANDBY (failed state), never a partial/
+  ambiguous role — pairs with the outgoing's "stay awake on no verified handoff", so a
+  broken handoff degrades to "no change", never to two-leaders or no-leader.
+
+## Signal vs authority
+- No authority of its own — it sequences signals (ack out, yield in) and delegates the
+  authority mutation to coordinator.acquireLeaseOnConsent (which is itself guarded). The
+  DECISION to yield lives on the outgoing (HandoffSentinel).
+
+## Interactions
+- Pairs with HandoffSentinel (outgoing), HandoffWireTransport (sendAck/onYield delivery),
+  LiveTailBuffer (tailSeq for the ack), and coordinator.acquireLeaseOnConsent (the acquire).
+- **Next (final integration):** server.ts constructs both HandoffSentinel + HandoffReceiver,
+  binds their ops to the live transports/coordinator/telegram, wires the routes live
+  (onHandoffAck→sentinel.recordAck via HandoffWireTransport; onHandoffYield→receiver.onYield;
+  a begin-handoff signal→receiver.onBeginHandoff), adds the handoff trigger + the live-tail
+  streaming cadence + the content provider, and ships the boots-the-server e2e test.
+
+## Rollback cost
+- Minimal — one new standalone file, unreferenced by the live path until the integration step.
+
+## Tests
+- `tests/unit/HandoffReceiver.test.ts` (6): begin→build+send ack; ack-not-accepted → failed;
+  buildAck-throws → failed; yield-after-ack → acquired; stray-yield-ignored; failed-acquire
+  → standby. tsc clean.

package/upgrades/side-effects/cross-machine-seamlessness-handoff-sentinel-wiring.md

@@ -0,0 +1,47 @@
+# Side-Effects Review — Cross-Machine Seamlessness: outgoing handoff sentinel wiring
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §8 G3e (converged, approved)
+
+The OUTGOING-machine orchestration logic for a planned handoff, as a tested unit: drive the
+live tail → POST begin → await + verify the ack → validate → yield → demote. Counterpart to
+the incoming receiver wiring (commit 79e9bf23f). This increment lands the LOGIC + its
+transport primitive; bolting the sentinel into server.ts boot + the operator/test trigger
+route + the two-server e2e are the next sub-increment (C2b/C3, tracked in the wiring plan).
+
+## What changed
+- `src/core/HandoffWireTransport.ts` — NEW `sendBegin(manifest)` → POST /api/handoff/begin to
+  the peer. Symmetric with the existing sendAck/sendYield; rides the same signed channel.
+- `src/core/handoffSentinelWiring.ts` — NEW `createHandoffSentinelWiring(deps)` composes a real
+  HandoffSentinel with ops bound to injected deps: flush (pushTick the live tail, build the
+  manifest with `hashTopicHistory` reused from the receiver wiring so the echo verifies, POST
+  begin), awaitAck, validate (default deterministic — ackMatches is the substantive gate; Haiku
+  Tier-1 is the spec's tracked upgrade), sendYield, demoteSelf. Returns `{ sentinel, initiate }`.
+
+## Over-block / under-block
+- The lease is NEVER yielded unless the ack echo verifies (HandoffSentinel.ackMatches) AND
+  validate passes — proven by tests: a mismatched echo, an absent ack, a failed validation, and
+  an unreachable-peer begin all return `aborted-stay-awake`/`failed` with ZERO sendYield and
+  ZERO demoteSelf calls. The outgoing simply stays awake. No two-holders window.
+- flush throws if the begin POST is not accepted (no reachable peer / rejected) → the sentinel
+  reports `failed` before any ack wait — it never proceeds to yield on a peer it can't reach.
+
+## Signal vs authority
+- The wiring supplies ops only. The DECISION to yield lives in HandoffSentinel (verify + validate
+  gate); the lease CAS authority is the incoming coordinator's, triggered solely by the yield.
+
+## Interactions
+- Reuses hashTopicHistory (handoffReceiverWiring) so outgoing-flush and incoming-echo hash the
+  SAME bytes → the caught-up check is meaningful. Consumes HandoffWireTransport (sendBegin/
+  awaitAck/sendYield) + telegram ingress/history + coordinator.demoteToStandby (all shipped).
+- NOT yet constructed in server.ts boot; no trigger route yet → no runtime behavior change.
+  Bolting in + the trigger + the e2e are C2b/C3. <!-- tracked: topic-13481 -->
+
+## Rollback cost
+- Minimal. Two new standalone additions (one method + one module). No boot wiring yet, so a
+  revert is a pure no-op on the running pipeline.
+
+## Tests
+- `tests/unit/handoff-sentinel-wiring.test.ts` (5): verified+validated ack → flush+yield+demote+
+  handed-off ; mismatched echo → abort, no yield ; no ack → abort, no yield ; failed validate →
+  abort, no yield ; unreachable-peer begin → failed, no yield. tsc clean; HandoffWireTransport
+  unit suite still green (7).

package/upgrades/side-effects/cross-machine-seamlessness-lease-wire.md

@@ -0,0 +1,46 @@
+# Side-Effects Review — Cross-Machine Seamlessness: lease wire transport (§6)
+
+**Spec:** CROSS-MACHINE-SEAMLESSNESS-SPEC.md §6 ("the low-latency authoritative copy of the lease travels over the tunnel"). First piece of the wire-transport increment (live-tail-flush + handoff-ack transport follow).
+
+## What changed
+- `src/core/HttpLeaseTransport.ts` (new) — implements LeaseTransport over the
+  existing authenticated machine channel (signRequest + machineAuth). broadcast()
+  POSTs the signed lease to each peer's /api/lease; observed() returns the
+  freshest received lease + per-holder nonce map; isReachable() reflects recent
+  broadcast success; recordObserved() ingests a peer lease (highest-epoch wins,
+  nonce watermark advances, replays dropped).
+- `src/server/machineRoutes.ts` — new auth-verified POST /api/lease receiver
+  (lease holder must match the authenticated machine) → ctx.onLeaseReceived.
+- `src/server/AgentServer.ts` — new optional `leaseTransport` option; wires
+  onLeaseReceived → leaseTransport.recordObserved.
+- `src/commands/server.ts` — constructs HttpLeaseTransport, passes it as the
+  LeaseCoordinator's `tunnel`, and into AgentServer.
+
+## Over/under-block, safety
+- SINGLE-MACHINE SAFE: with no peers, broadcast() is a reachable no-op and
+  isReachable() stays true, so the lease behaves EXACTLY as git-only (Echo and
+  all single-machine agents are unaffected — no behavior change).
+- Multi-machine: the lease now also travels over the wire (RTT-bounded
+  acquisition) and renewal requires reaching a medium (tunnel OR git) — the
+  spec's split-authority guard. FencedLease.acceptTunnelLease re-verifies the
+  Ed25519 signature + git-epoch floor + nonce before trusting a wire lease, so a
+  forged/replayed/below-floor broadcast is rejected regardless of the endpoint.
+
+## Signal vs authority / interactions
+- The endpoint is signature-gated (machineAuth) AND holder-must-match-auth; the
+  transport is a fast COPY, never the authority (git CAS + FencedLease fencing
+  remain authoritative; max(tunnel,git) never drops below the git floor).
+- recordObserved keeps only the highest-epoch lease + advances the nonce
+  watermark → an at-least-once wire redelivery cannot regress the view.
+
+## Rollback cost
+- Low. leaseTransport is optional; removing the server.ts wiring reverts the
+  LeaseCoordinator to git-only (the prior, tested behavior). The endpoint is
+  inert without onLeaseReceived. New module unreferenced if unwired.
+
+## Tests
+- tests/unit/HttpLeaseTransport.test.ts (6): broadcast reachability, single-machine
+  no-op, observed recording, nonce watermark + replay drop, highest-epoch wins,
+  reachability window. LeaseCoordinator + FencedLease suites still green (35 total).
+- Live two-machine wire behavior is exercised by the real-hardware gate (the
+  over-Telegram test increment).

package/upgrades/side-effects/cross-machine-seamlessness-livetail-source.md

@@ -0,0 +1,50 @@
+# Side-Effects Review — Cross-Machine Seamlessness: LiveTailSource (holder flush producer)
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §8 G3b (converged, approved)
+
+Fourth piece of the wire-transport increment. The holder-side producer that drives
+the live-tail SENDER (HttpLiveTailTransport.broadcast) — the missing primitive that
+makes the encrypted stream actually fire, and that the handoff flush() builds its
+manifest from.
+
+## What changed
+- `src/core/LiveTailSource.ts` — NEW, standalone. Per-topic delta accounting: tracks
+  the content already streamed to the standby and emits only the NEW suffix as a
+  monotonic-sequence flush (the standby's LiveTailBuffer APPENDS contiguous flushes,
+  so the source must send deltas, not the full tail). Drivers: pushTick() (cadence,
+  keeps the standby fresh to liveTailMaxStalenessMs) and flushTopic/flushAll (handoff,
+  returns per-topic seqs for the manifest). currentSeq() exposes the high-water for
+  the manifest. Content provider + transport injected → channel-agnostic + testable.
+
+## Over-block / under-block
+- A failed broadcast does NOT advance the streamed/seq state, so the same delta retries
+  on the next tick (the buffer dedups on seq, so a retry is harmless). This is the
+  correct under-action: never mark content delivered that the standby didn't ack.
+- No new content → no flush, no seq bump — duplicate ticks can't inflate the standby's
+  sequence or push empty flushes.
+- Content divergence (history rewrite/compaction shrinks or changes the prefix) → resend
+  the full content as a fresh delta, rather than send a broken suffix.
+
+## Signal vs authority
+- Pure producer — no authority. It decides only WHAT content is new; it does not decide
+  who leads or who may send (the lease/FencedOutbox do). It is gated upstream: the wiring
+  step only runs the cadence/handoff flush on the machine that holds the lease.
+
+## Interactions
+- Drives HttpLiveTailTransport.broadcast (already shipped, redacts+encrypts). The
+  correctness test feeds the source's deltas through a REAL LiveTailBuffer and asserts
+  the original conversation is reconstructed exactly — the delta model and the buffer's
+  append model are proven consistent.
+- **Next piece (same increment):** the integrating commit wires LiveTailSource into the
+  server (content provider = recent topic messages; cadence timer on the holder; handoff
+  flush() = flushAll() + manifest from currentSeq), takes the handoff routes live, binds
+  HandoffSentinel ops, and adds the boots-the-server e2e test.
+
+## Rollback cost
+- Minimal — one new standalone file, unreferenced by the live path until the wiring step.
+
+## Tests
+- `tests/unit/LiveTailSource.test.ts` (6): first-flush-full / subsequent-delta, no-new-
+  content no-op, divergence resends full, failed-broadcast-does-not-advance (retry-safe),
+  **deltas reconstruct the original tail through a real LiveTailBuffer**, flushAll covers
+  all topics. tsc clean.

package/upgrades/side-effects/cross-machine-seamlessness-livetail-streaming.md

@@ -0,0 +1,50 @@
+# Side-Effects Review — Cross-Machine Seamlessness: live-tail streaming wired live
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §8 G3b (converged, approved)
+
+Makes the encrypted live-tail stream END-TO-END LIVE: the holder now actually pushes
+the conversation tail to the standby on a cadence (the receiver has been live since the
+live-tail-wire commit). First true integration into the running server.
+
+## What changed
+- `src/messaging/TelegramAdapter.ts` — NEW `getKnownTopicIds(): number[]` accessor
+  (keys of topicToSession) — the set of live conversations to stream.
+- `src/commands/server.ts`:
+  - In the lease block, constructs the holder-side `HttpLiveTailTransport` (sender) —
+    peers resolved from the registry, each peer's X25519 key via
+    `idMgr.getEncryptionPublicKeyPem` → SPKI-DER base64; content encrypted via encryptForSync.
+  - Before AgentServer construction, constructs `LiveTailSource` (content provider =
+    `telegram.getTopicHistory(topic, 500)` formatted append-only; active topics =
+    `telegram.getKnownTopicIds()`) and a cadence `setInterval(liveTailPushRateMs)` that
+    calls `pushTick()` — GATED on `coordinator.holdsLease()` so ONLY the awake machine
+    streams (mirrors scheduler/sentinel gating). Timer unref'd. Only when
+    `liveTailTransport: 'tunnel'` + coordinator enabled + telegram present.
+
+## Over-block / under-block
+- Holder-gated: a standby that does not hold the lease never streams (no double-push).
+- Solo agent / no peers: the sender's broadcast is a reachable no-op — zero behavior change
+  for single-machine installs (the dominant case). `liveTailTransport: 'git'` skips it entirely.
+- Window-shift caveat: getTopicHistory is a bounded recent window (500), so a conversation
+  exceeding it triggers a one-off full resend (LiveTailSource divergence path) — the standby
+  buffer dedups by seq + caps by bytes, so this is correct, just occasionally redundant.
+  Documented; a growing/append-only provider is a tracked tuning follow-on. <!-- tracked: ACT-156 -->
+
+## Signal vs authority
+- The cadence timer reads authority (coordinator.holdsLease()) to decide whether to stream;
+  it does not mutate authority. The sender carries redacted+encrypted content only.
+
+## Interactions
+- Sender (HttpLiveTailTransport) + LiveTailSource + the already-live receiver
+  (/api/live-tail → decrypt → LiveTailBuffer) now form the complete one-directional stream.
+- The handoff flush() (next commit) will reuse this same LiveTailSource for its manifest.
+
+## Rollback cost
+- Low. The accessor is additive; the streaming block is guarded and unref'd. Reverting removes
+  the block + accessor with no effect on single-machine installs.
+
+## Tests
+- Components already unit-tested: HttpLiveTailTransport (6), LiveTailSource (6, incl. the
+  reconstruct-through-LiveTailBuffer correctness proof), live-tail-receive-roundtrip (3).
+  101 seamlessness unit tests green; tsc clean. The true holder→standby streaming is
+  exercised by the two-machine hardware test-as-self (task 8) — a single-machine e2e cannot
+  drive a no-peer no-op sender.

package/upgrades/side-effects/cross-machine-seamlessness-livetail-wire.md

@@ -0,0 +1,65 @@
+# Side-Effects Review — Cross-Machine Seamlessness: live-tail wire (receiver) + transport
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §8 G3b/G3c (converged, approved)
+
+Second piece of the wire-transport increment (after the lease wire transport). Stands
+up the encrypted holder→standby live-tail channel: the SENDER transport class and the
+RECEIVER end-to-end (route → decrypt → sequence-deduped buffer, fully live).
+
+## What changed
+- `src/core/HttpLiveTailTransport.ts` — NEW. Holder-side sender: redacts content
+  (liveTailRedaction) BEFORE anything leaves the machine, encrypts per-peer with the v3
+  machine scheme (encryptForSync: ephemeral X25519 + AES-256-GCM, forward-secret per
+  flush), and POSTs to each standby's `/api/live-tail` over the authenticated machine
+  channel (signRequest). No peers → reachable no-op (solo agent unaffected). Injected
+  fetch/encryptor/clock for testability.
+- `src/server/machineRoutes.ts` — NEW route `POST /api/live-tail` (authMiddleware) +
+  `onLiveTailReceived` ctx callback. Validates the flush shape, rejects an unverifiable
+  peer at the auth boundary BEFORE any content is accepted (§8 G3c), hands the encrypted
+  flush to the server-lifecycle decryptor, returns 400 on decrypt/verify failure (logged
+  to SecurityLog as `live_tail_rejected`).
+- `src/server/AgentServer.ts` — NEW `liveTailReceiver` option, passed through to the
+  machine-routes context as `onLiveTailReceived`.
+- `src/commands/server.ts` — constructs the standby-side `LiveTailBuffer` + the decrypt
+  receiver closure (decrypts with THIS machine's X25519 private key, then sequence-deduped
+  applyFlush), wired only when `liveTailTransport: 'tunnel'`. The holder-side sender
+  (HttpLiveTailTransport.broadcast) is constructed/driven by the flush producer in the
+  NEXT increment piece (inbound-dispatch + handoff) — the class ships unit-tested here.
+
+## Over-block / under-block
+- The receiver REJECTS (400) any flush it cannot decrypt/verify — intended over-block; a
+  forged or wrong-key flush must never enter the context window. Replay/duplicate seqs are
+  dropped by LiveTailBuffer (no double-append corrupting history).
+- Redaction is conservative/high-precision (false positives acceptable per §8 G3c); ordinary
+  prose is left intact (tested).
+- Solo / no-peer: the sender is a no-op and the receiver simply never fires — identical to a
+  disabled mesh. `liveTailTransport: 'git'` skips the tunnel receiver entirely.
+
+## Signal vs authority
+- The transport carries no authority — it does not decide who is leader or who may send;
+  it only moves (redacted, encrypted) context. The FencedOutbox/lease (separate) hold send
+  authority. The receiver's only judgment is cryptographic (auth tag + machine-auth), not policy.
+
+## Interactions
+- Reuses the established v3 machine path: `signRequest`/`machineAuthMiddleware` (mutual auth),
+  `encryptForSync`/`decryptFromSync` (the same scheme as secret sync), and `MachineIdentity`'s
+  dedicated X25519 encryption keys — no new crypto invented.
+- Feeds `LiveTailBuffer` (already shipped), whose sequence-dedup is the context-integrity guard.
+- **Tracked follow-on (not this commit):** carry-by-reference for large tool output (§8 G3b) —
+  depends on the durable encrypted work-ledger reference mechanism not yet built; redaction
+  (the actual security requirement) is fully in place. <!-- tracked: ACT-156 -->
+- **Next piece (same increment):** the holder flush producer drives `broadcast()` from the live
+  message path; the handoff-ack transport + HandoffSentinel live-wiring consume the buffer.
+
+## Rollback cost
+- Minimal. The route is additive (unknown route → 404 previously); the option is optional;
+  the sender class is unreferenced by the live path until the next piece. Reverting removes
+  the new file + the four additive edits.
+
+## Tests
+- `tests/unit/HttpLiveTailTransport.test.ts` (6): no-peer no-op, signed POST to /api/live-tail,
+  **redaction-before-encryption** (no secret leaves in the clear — security-negative), per-peer
+  encryption, unreachable-on-all-error, non-ok-not-reachable.
+- `tests/unit/live-tail-receive-roundtrip.test.ts` (3): encrypt→decrypt→apply round-trip,
+  replayed-seq dropped (no double-append), **non-recipient cannot decrypt** (security-negative).
+- Full seamlessness suite green (76 unit tests across 9 files); tsc clean.