instar 1.3.1337 → 1.3.1339

package/upgrades/a2a-relay-unknown-sender-trust.eli16.md

@@ -0,0 +1,21 @@
+# A first message is not a grant of trust (ELI16)
+
+Agents talk to each other through a shared relay on the internet. Normally a message is locked so only the receiver can read it, and before the receiver acts on it, a checkpoint looks the sender up in its trust list. A sender that is not on the list may only "ping" to see if anyone is there.
+
+There is a second kind of message: one the receiver cannot unlock, because it does not have the sender's keys yet. These arrive as plain text. They skipped the checkpoint completely. Every one of them was treated as coming from a known, trusted-enough agent. The receiver sent an automatic "got it" reply, put the message in its inbox, and could start a working session with full tools to answer it. Worse, that first message quietly wrote the sender onto the trust list as "verified", so from then on it was trusted on every route.
+
+The relay does prove one thing: the sender really holds the key that matches its name tag. It does not prove who the sender is, and nobody ever decided to trust it. That is the hole this change closes.
+
+With the change switched on, a plain-text message is judged by the trust list the same way a locked message is. A sender that is not on the list gets nothing: no "got it" reply, no inbox entry, no session, and it is not written onto the list. Its automatic "got it" replies to messages we sent still count, so peers we write to do not look unreachable. A sender that is on the list is handled at the level the list actually holds for it. Passwords and other secrets are never accepted this way, because secrets must always travel locked.
+
+One detail turned out to matter. The checkpoint lets a stranger's "ping" through, expecting it to be answered on the spot. But the code after the checkpoint does not answer pings on the spot; it treats them like any message and can start a session. So on this route a stranger's ping is dropped too. The same gap on the locked route is recorded for its own fix.
+
+It starts in watch-only mode, on development agents only. In watch-only mode every message is delivered exactly as before, and each one that would have been dropped is written to the log and counted on the agent's private health page. Strangers who write during this time are still added to the list as before, but they are marked as "only a first contact", and that mark is saved, so it survives a restart. When watch-only mode is switched off, a marked entry counts as no trust at all, on both routes, until someone actually grants that agent trust.
+
+Agents already on the list before this change are left alone. On the development computer both existing entries were created by exactly this hole; deciding which of them are real is the operator's call, made from the counts.
+
+**What ships now.** On for development agents, watch-only. Off for everyone else.
+
+**What needs deciding later.** After two days of counts, grant trust to the real peers and switch watch-only mode off on the development agent. Turning it on for everyone needs an easier way to grant trust than one peer at a time.
+
+**Status.** Built under the operator's standing approval of 2026-10-08.

package/upgrades/side-effects/a2a-relay-unknown-sender-trust.md

@@ -0,0 +1,129 @@
+# Side-Effects Review — A2A relay unknown-sender trust
+
+**Version / slug:** `a2a-relay-unknown-sender-trust`
+**Date:** `2026-10-09`
+**Author:** `echo`
+**Second-pass reviewer:** `independent reviewer subagent (see below)`
+
+Spec: docs/specs/a2a-relay-unknown-sender-trust.md (three cross-model rounds, one internal reviewer, conformance gate; approved under the operator's standing approval of 2026-10-08 14:49). Tracking action ACT-066.
+
+## Summary of the change
+
+The relay client raises `unknown-sender` for a message whose sender's keys this agent does not hold. `ThreadlineBootstrap`'s handler skipped `InboundMessageGate`, emitted `gate-passed` at `verified` (reason `relay-authenticated`) and recorded the interaction, which created a fingerprint profile at `verified` / `setup-default`. The handler now calls `handleRelayUnknownSender` (new pure module `src/threadline/relayUnknownSenderTrust.ts`) after the existing payload-size check.
+
+- off (`enabled` omitted on a non-development agent, or `false`): today's handling, byte for byte.
+- dry-run (default when on): today's delivery and profile write; the verdict is counted and a would-refuse logged. A profile created by this path is created already marked `relayFirstContact: true`.
+- enforcing (`dryRun: false`): a refused message is dropped before `gate-passed`; an allowed one is emitted at the held level (reason `probe` for a profiled sender's ping/health). Interaction recorded only for an existing profile.
+
+Verdict: held level from the trust manager; a marked, still-`setup-default` profile counts as none; `ack` passes at every level; `credential-share` never; an `untrusted` sender passes nothing else (no probes); otherwise the gate's `getAllowedOperationsByFingerprint` table.
+
+`AgentTrustManager`: optional live `newFingerprintProfileLevel` (only lowers to `untrusted`, throw-safe) and `onFingerprintProfileCreated`; `getOrCreateProfileByFingerprint` takes `createOpts.relayFirstContact`; while enforcing, `getTrustLevelByFingerprint` / `getAllowedOperationsByFingerprint` read a marked, still-`setup-default` profile as `untrusted`. `server.ts` supplies the live mode reader. `routes.ts` authed `/health` carries mode + counters + `unmarkedSetupDefaultProfiles`. `ThreadlineConfig.relayUnknownSenderTrust` type; `DEV_GATED_FEATURES` `a2aRelayUnknownSenderTrust`; CLAUDE.md template + `migrateClaudeMd` section (framework-shadowed). The unknown-sender message content no longer carries a `type: undefined` key.
+
+## Decision-point inventory
+
+- Pass or drop an unknown-sender relay message by sender trust — **add** — invariant: the trust manager's level table (with the ack / credential / untrusted-probe differences stated in the spec); enforced only with `dryRun: false`.
+- Trust level handed to the `gate-passed` consumer from this path — **modify** — `verified` today; when enforcing, the held level.
+- Level of a new fingerprint profile — **modify** — `verified` today; `untrusted` while enforcing.
+- Gate's fingerprint trust reads — **modify** — a marked, still-`setup-default` profile reads `untrusted` while enforcing. Unmarked profiles unchanged.
+- `InboundMessageGate` logic — **pass-through** — not changed.
+
+---
+
+## 1. Over-block
+
+Only when enforcing (deliberate operator setting):
+
+- A real peer that has no trust profile, or only a watch-only first-contact profile, is dropped until the operator grants it trust. That is the intended change; the rollout reads `wouldRefuse` first and grants real peers (ACT-069).
+- An untrusted sender's `ping`/`health` is dropped (the gate would pass it). It is a stranger's probe; nothing answers probes inline today.
+- A `verified` sender asking for an operation above its level (e.g. `task-request`) is dropped, as the gate drops it.
+- A plaintext `credential-share` is dropped at every level.
+- A throwing lookup while enforcing drops the message (fail closed).
+- A new fingerprint profile created by any path while enforcing (including the gate's credential dry-run branch) starts `untrusted`; an operator grant still lands.
+
+Off and dry-run drop nothing.
+
+## 2. Under-block
+
+- Unmarked `setup-default` profiles keep `verified`: those written before this change, while the check was off, or (in dry-run) by other creators such as the gate's own interaction record and the pairing paths. All are counted in `unmarkedSetupDefaultProfiles` on `/health` for the operator to decide.
+- Rate limits and replay protection of the gate are not applied on this path (as today).
+- A mode read failure is treated as off.
+- The MCP stdio process's trust manager can overwrite server-side state (pre-existing, ACT-052).
+- The end-to-end path still routes an untrusted sender's probe to a session (pre-existing, ACT-056 filed 2026-10-09).
+
+## 3. Level-of-abstraction fit
+
+The authority stays `AgentTrustManager`; the module only reads its level and table. The drop happens at the one point where the unknown-sender path hands messages onward (`gate-passed`), mirroring the gate. The profile default lives in the manager because it is the only creator of profiles.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [ ] No — this change has no block/allow surface.
+- [x] Yes — but the logic is not brittle pattern-matching: a deterministic lookup in the trust manager's enumerable level-to-operation table, the same invariant the relay gate already holds.
+- [ ] ⚠️ Yes, with brittle logic.
+
+No content is judged. In its default (dry-run) form it blocks nothing and only produces a log line and counters.
+
+## 4b. Judgment-point check
+
+No new heuristic at a competing-signals point. The one judgment — when to leave dry-run — is the operator's (`## Decision points touched`, ACT-069).
+
+## 5. Interactions
+
+- **Ack stage:** acks pass at every level and are consumed by `runRelayAckStage` before routing; our own auto-ack is sent only to non-`untrusted` senders, so a dropped or untrusted sender gets none.
+- **Inbound-id ledger:** reason `relay-authenticated` keeps the `relay-unknown-sender` ingress; `probe` skips the ledger, as for the gate.
+- **Local-route trust (sibling):** a same-machine sender refused on the local route falls back to the relay; while this check enforces, a no-profile sender is now dropped there too, closing the gap the sibling spec recorded.
+- **Gate:** while enforcing, its fingerprint reads honour the first-contact mark, so the two relay paths agree.
+- **Double-fire / races:** none. Synchronous, single-threaded; one log line per verdict.
+
+## 6. External surfaces
+
+- Other agents: when enforcing, strangers' relay messages go unanswered (no ack), as gate blocks already do.
+- Install base: none by default (dark on the fleet).
+- Persistent state: an optional `relayFirstContact` field on trust profiles (older versions ignore it).
+- Authed `/health`: new `threadline.relayUnknownSenderTrust` block; not on the unauthenticated `/health` (tested).
+
+## 6b. Operator-surface quality
+
+No new operator surface; granting trust uses the existing `threadline_trust` / dashboard paths.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN** (`physical-credential-locality`): unknown-sender messages arrive only on the machine holding the relay connection (one per agent identity), and are judged against that machine's trust manager. The first-contact mark lives on the profile it qualifies and can only remove a grant, so losing it on a move cannot add one. Counters per machine. No notices, no URLs.
+
+## 8. Rollback cost
+
+- Live: `threadline.relayUnknownSenderTrust.enabled: false` (read per message) restores today; `dryRun: true` stops dropping.
+- Profiles created `untrusted` while enforcing stay so; grant with `threadline_trust`. Marked profiles revert to ordinary `verified` reads once the check is off.
+- Code revert: pure patch, no data migration.
+
+## Conclusion
+
+Review changed the design in five ways (probes dropped; durable first-contact mark replacing an in-memory set; mark written atomically with the profile; credential-share refused; unmarked-profile count on `/health`). Clear to ship dev-gated in dry-run. Enforcement on the development agent is decided from the evidence on ACT-069.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** independent reviewer subagent (read-only; given the code and this artifact)
+**Independent read of the artifact: concur**
+
+Concur. Off and dry-run delivery are unchanged (the profile hook returns `verified` unless enforcing; `isUngrantedFirstContact` applies only while enforcing; the dropped `type: undefined` key was already omitted by `JSON.stringify` and every reader uses `content.type`). Enforcing leaks nothing: an unprofiled or marked sender resolves `untrusted`, everything but `ack` is dropped before `gate-passed`, the ack is consumed by the ack stage before auto-ack, inbox and routing, our auto-ack requires a non-`untrusted` level, and the gate's fingerprint reads apply the same mark. Signal-vs-authority holds (deterministic table lookup, no content judged, dry-run default).
+
+One imprecision raised and fixed: section 2 now says unmarked `setup-default` profiles can also be written in dry-run by other creators (the gate's interaction record, the pairing paths), all counted on `/health`.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/a2a-relay-unknown-sender-trust.test.ts` — 32 tests.
+- `tests/integration/threadline/a2a-relay-unknown-sender-trust.test.ts` — 4 tests.
+- `tests/e2e/threadline/a2a-relay-unknown-sender-trust-alive.test.ts` — 3 tests, real relay.
+- Risk check, development machine, 2026-10-09: two fingerprint profiles, both `verified` / `setup-default` (created by this path).
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+No self-triggered controller — not applicable. The check runs only inside an inbound relay message and fires no restart, spawn, notify or retry.

package/upgrades/side-effects/sessions-refresh-prebind.md

@@ -0,0 +1,113 @@
+# Side-Effects Review — POST /sessions/refresh answers target refusals before the 202 (EVO-025)
+
+**Version / slug:** `sessions-refresh-prebind`
+**Date:** `2026-09-24`
+**Author:** `Echo`
+**Second-pass reviewer:** `independent reviewer subagent (required: session lifecycle)`
+
+## Summary of the change
+
+`POST /sessions/refresh` returned 202 "Refresh scheduled" and only 500ms later called `SessionRefresh.refreshSession()`; target refusals (`not_telegram_bound`, `session_not_found`, `refresh_in_progress`, `rate_limited`, `slack_respawner_unwired`) reached only `console.warn`. A caller passing a display name ("Jev") instead of the tmux name ("echo-jev") was told the restart was scheduled when it was refused. The detect phase of `refreshSession()` is extracted verbatim into a private `resolveTarget()`; a new read-only `precheckRefusal(sessionName)` runs `resolveTarget()` plus the in-flight check plus a non-recording rate-limit check. The route calls it before the existing busy precheck and answers a refusal synchronously (409 with `{code, error}`; 429 for `rate_limited`). The `not_telegram_bound` and `session_not_found` messages gain a display-name hint naming the matching running session's `tmuxSession`. Files: `src/core/SessionRefresh.ts`, `src/server/routes.ts`, `tests/unit/SessionRefresh.test.ts`, `tests/unit/sessions-refresh-route.test.ts`.
+
+## Decision-point inventory
+
+- `POST /sessions/refresh` admission — modify — target refusals are now answered pre-202 instead of post-202 in the log.
+- `SessionRefresh.refreshSession` detect phase — pass-through — same checks, same order, same refusal codes (the not_telegram_bound / session_not_found messages gain the display-name hint, which also reaches the post-202 log line); moved into `resolveTarget()` and shared.
+- `SessionRefresh.precheckRefusal` — add — read-only early answer; never kills, records, or respawns.
+
+---
+
+## 1. Over-block
+
+The early check refuses only when `refreshSession()` itself would refuse with the same code at that moment, using the same lookups. A binding that is registered in the ≤500ms between the precheck and the scheduled call used to succeed and is now refused (the caller can retry immediately); this window is negligible and the caller now learns the result. No legitimate request that would have been refreshed is refused for any other reason. The work gate is not duplicated here (it has its own precheck), so `force:true` behaviour is unchanged.
+
+---
+
+## 2. Under-block
+
+A refusal that arises only after the 202 (binding removed or the session exiting in the 500ms window, a work-gate verdict change, a respawner failure) is still reported only in the log — `refreshSession()` re-runs every check authoritatively, so this is a reporting gap, not a safety gap. The self-refresh case (the caller is the session being killed) still needs the 202-before-kill ordering and keeps it.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layer: the orchestrator owns the lookup logic and exposes it once; the route only translates a refusal to an HTTP status. No lookup is re-implemented in the route (unlike `restart-all`, which inlines the Telegram lookup). The display-name hint lives in the orchestrator next to the state lookup it depends on.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no new block/allow surface.
+
+The refusals are the orchestrator's existing deterministic refusals (binding existence, session existence, in-flight, rate cap) — structural invariants, not judgment. The change moves when the caller hears them; it grants no new authority and removes none. The display-name case is deliberately a hint, never a remap.
+
+---
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No new static heuristic at a competing-signals decision point. The checks are enumerable invariants (is there a binding, is there a running session with this tmux name, is a refresh in flight, is the fixed rate cap reached).
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** the new precheck runs before the busy precheck. For an unbound name the caller now gets 409 `not_telegram_bound` instead of a busy verdict — correct, since the refresh could not run anyway. Likewise a session that is both busy and out of rate budget now gets 429 `rate_limited` where it used to get 409 `session-busy`; both are correct refusals. The busy precheck and post-202 authoritative path are unchanged.
+- **Double-fire:** none — the precheck performs no action.
+- **Races:** `precheckRefusal` reads `inFlight` and the rate window without writing (the rate check's opportunistic prune of expired timestamps is idempotent and already happens on every refresh). Test proves repeated prechecks consume no budget.
+- **Feedback loops:** the loop-guarded mcp-autorefresh hook POSTs this route fire-and-forget; a 409 is simply logged by curl, no retry loop. Internal callers (ContextWedgeSentinel, quota swap, restart-all) call `refreshSession()` directly and are unaffected.
+
+---
+
+## 6. External surfaces
+
+- The HTTP response for a refused target changes from 202 to 409/429 with `{code, error}`. This is the intended fix; the documented usage already says to pass the tmux name. No in-repo caller depends on a 202 for a refused name (grep of src, scripts, templates).
+- No persistent state, no external systems, no notices.
+- Operator surface: no operator-facing actions added.
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator surface — not applicable.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Machine-local by design: a refresh acts on a tmux session on the machine serving the request, and the orchestrator's in-flight set and rate window are already per-process. No notices, no durable state, no URLs.
+
+---
+
+## 8. Rollback cost
+
+Pure code change — revert and ship a patch. No persistent state, no migration, no agent state repair. During a rollback window callers would again receive 202 for refused names (the prior behaviour).
+
+---
+
+## Conclusion
+
+Small correctness fix: the route now tells callers the truth about target refusals it previously hid in the log. The detect phase was extracted without behaviour change (the existing SessionRefresh, Slack-arm, route, integration and e2e swap-continuity suites pass unchanged apart from the route mock gaining the new method). GET /sessions already exposes the binding as `platform`/`platformId`; the stored `topicId` field is left as-is rather than redefined. Second-pass reviewer concurred; clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** independent general-purpose reviewer subagent (read-only, same worktree)
+**Independent read of the artifact: concur**
+
+Concur: the extraction is behaviour-preserving, `precheckRefusal` is non-mutating (the rate-window prune only drops already-expired timestamps), the self-refresh 202 still precedes the kill, and the suites plus `tsc` pass. Two artifact corrections raised and applied: messages (not only codes) gain the display-name hint, and busy + rate-exhausted now answers 429 instead of 409 session-busy.
+
+---
+
+## Evidence pointers
+
+- `npx vitest run tests/unit/SessionRefresh.test.ts tests/unit/sessions-refresh-route.test.ts tests/unit/sessionRefresh-slack.test.ts tests/integration/swap-continuity-antithrash-routes.test.ts tests/e2e/swap-continuity-antithrash-lifecycle.test.ts` → 5 files, 74 tests passed.
+- `tsc --noEmit` clean.
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect — not applicable. (Route response-ordering bug in server source; not a prompt/hook/config/skill/standards defect, and not a self-triggered controller.)