instar 1.3.138 → 1.3.140

package/upgrades/1.3.140.md

@@ -0,0 +1,47 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Multi-machine: a standby machine can now actually receive a transferred session.**
+When you run one agent across two machines, the machines agree on which one is "in
+charge" via a lease (a who-is-the-captain token). Cross-machine commands — like
+moving a conversation to the other machine — are only accepted from the recognized
+captain. A live two-machine test surfaced that the standby machine had no idea who
+the captain was, so it refused every hand-off. Root cause: the code that runs the
+captain-tracking system was bundled with git backup, and on machines where git
+backup is blocked or off (including an agent whose home is the instar source tree),
+the whole system silently never started. This change runs the captain-tracking
+system over the machines' existing secure connection whenever multi-machine is on,
+independent of git — so a standby learns the captain and accepts the hand-off. A
+second, latent bug (the standby discarding the captain's announcements due to an
+over-strict duplicate check) is fixed too. Single-machine agents are unaffected.
+
+## What to Tell Your User
+
+If you run on one machine, nothing changes. If you run one agent across two
+machines, moving a conversation to the other machine now works end to end —
+previously the second machine would quietly refuse the hand-off because it never
+learned which machine was in charge. Nothing to configure.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Git-less lease coordination | Automatic. A machine with no git medium (a credential-less standby, or an agent home that is the instar source tree) now coordinates the lease over the existing HTTP channel and learns the holder, so cross-machine transfer is authorized. No configuration. |
+
+## Evidence
+
+- New `LocalLeaseStore` (git-less lease store) unit tests:
+  `tests/unit/LocalLeaseStore.test.ts` (5 cases — strict-advance CAS, durable
+  persistence across instances, refresh/supersede, corrupt-file self-heal).
+- Regression: `tests/unit/StandbyLeaseObservation.test.ts` (3 cases — a git-less
+  standby resolves the holder from a real HttpLeaseTransport broadcast; the holder
+  acquires + broadcasts). This is the gap the mocked suites missed.
+- Existing `LeaseCoordinator` (16), `FencedLease` (21), `HttpLeaseTransport` (6)
+  suites stay green — no replay-semantic regression. `server` (17) + `middleware`
+  (27) green — boot wiring unaffected. `tsc --noEmit` + repo lint clean.
+- Live Tier-3: re-run the two-machine "move this to the other machine" transfer
+  after deploy; the standby accepts the forwarded message and serves the session.
+- Side-effects: `upgrades/side-effects/standby-lease-holder-sync.md`.

package/upgrades/side-effects/source-tree-guard-reaper-readtier.md

@@ -0,0 +1,132 @@
+# Side-Effects Review — SourceTreeGuard read-tier + worktree-remove for the AgentWorktreeReaper
+
+**Version / slug:** `source-tree-guard-reaper-readtier`
+**Date:** `2026-05-31`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (single-author safety-guard fix; review is exhaustive below)`
+
+## Summary of the change
+
+The AgentWorktreeReaper (v1.3.133) runs inside the instar server, whose working
+directory IS a checkout of the instar source tree. Every git call it makes was
+blocked by the SourceTreeGuard, so it reported 0 reclaimable in production. This
+change makes three precise, shape-checked widenings in `src/core/SafeGitExecutor.ts`
+— add `cherry` to `READONLY_GIT_VERBS`; add `status` + `cherry` to
+`SOURCE_TREE_READ_TIER_VERBS`; extend the worktree-manager source-tree allowlist
+(`isAllowedWorktreeManagerSubcommand`) to permit `worktree list` and non-forced
+`worktree remove` alongside `add`/`prune` — and passes the corresponding bypass
+flags from the reaper's git wrapper (`src/monitoring/agentWorktreeGit.ts`). It
+interacts with one decision point: the SourceTreeGuard source-tree bypass.
+
+## Decision-point inventory
+
+- `SafeGitExecutor.isSourceTreeCheckBypassed` (via `SOURCE_TREE_READ_TIER_VERBS`) — modify — add two pure-read verbs (`status`, `cherry`) to the read-tier allowlist.
+- `SafeGitExecutor.isAllowedWorktreeManagerSubcommand` (renamed from `isWorktreeManagerMutation`) — modify — add `list` + non-forced `remove` to the worktree-manager allowlist; explicitly deny `--force`/`-f`.
+- `SafeGitExecutor.readSync` verb classification (via `READONLY_GIT_VERBS`) — modify — recognize `cherry` as read-only (root cause of the silent failure).
+- `agentWorktreeGit.ts` `defaultReadGit` / `removeWorktree` — modify — pass the bypass flags.
+
+---
+
+## 1. Over-block
+
+After the change the guard is slightly *more* permissive, not less, so over-block
+risk is unchanged for everyone except the reaper. The one thing that could be
+called "over-block" is intentional: `worktree remove --force` against the source
+tree is still rejected even with `sourceTreeWorktreeManagerOk`. That is by design —
+the forced form is the only one that can delete a dirty worktree, and the reaper
+never needs it. No legitimate caller is newly rejected.
+
+---
+
+## 2. Under-block
+
+The relevant question for a guard-*widening* is "does this newly ALLOW something
+dangerous?" The widenings are: two pure reads (`status`, `cherry` — cannot mutate)
+and `worktree remove` without `--force` (which git itself refuses to run against a
+dirty/locked worktree). The residual under-block surface: a caller holding
+`sourceTreeWorktreeManagerOk` could now run `worktree remove` (non-forced) against
+the source tree. That flag is opt-in per call and currently set only by
+`instar worktree create` and this reaper; the non-forced form is self-protecting
+(refuses dirty/locked), so even a misuse cannot delete uncommitted work. `--force`
+stays blocked, which closes the only data-loss path.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layer. These are pure reads plus one narrowly-shaped, self-protecting
+mutation, expressed as additions to existing closed allowlists (the established
+pattern for `fetch`/`rev-parse`/`add`/`prune`). The reaper continues to USE the
+`SafeGitExecutor` primitive rather than re-implementing git access, and the
+merged/clean/in-use reasoning stays in the reaper classifier — this change only
+unblocks the reads/remove it already wanted to make.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface over messages or user-facing
+  actions. It widens an internal git safety allowlist for one internal consumer.
+
+The SourceTreeGuard does hold blocking authority, but its logic here is a closed,
+shape-checked allowlist (not brittle heuristic), and the change makes it recognize
+two harmless reads and one self-protecting mutation. No new blocking authority is
+introduced; the reaper itself remains signal-only (dark + dry-run by default).
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** none. The bypass check runs in the same place it always has
+  (`isSourceTreeCheckBypassed` inside `readSync`/`execSync`); we add entries to its
+  allowlists, we don't reorder checks. `readSync` still rejects destructive shapes
+  before the source-tree check, so the read-path widening cannot enable a mutation.
+- **Double-fire:** none. The reaper is the only new consumer; the immediate manual
+  reclaim used direct shell `git` (not via SafeGitExecutor) and is unaffected.
+- **Races:** the reaper's `worktree remove` and a concurrent session inside the same
+  worktree — covered by the reaper's existing not-in-use gate (lock file + live
+  process cwd) AND by git's own non-forced refusal if the worktree is locked. Two
+  layers.
+- **Feedback loops:** none.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** the guard widening is per-call opt-in via
+  flags only this reaper and `instar worktree create` set, so other code paths are
+  unchanged. The reaper ships dark + dry-run, so no agent's worktrees are touched
+  until explicitly enabled.
+- **Install base:** pure source change, no config/migration/agent-installed files —
+  every agent picks it up on the normal update; behavior is identical until the
+  reaper is enabled.
+- **External systems:** none.
+- **Persistent state:** none added. When enabled, the reaper removes worktree
+  *checkouts* (disk) but never branches/commits — the work is preserved in the
+  branch ref and in main.
+- **Timing:** none we don't control.
+
+---
+
+## 7. Rollback cost
+
+- **Hot-fix release:** revert the one commit, ship as the next patch. The reaper
+  reverts to reporting 0 (blocked); no functional regression elsewhere.
+- **Data migration:** none — no persistent state introduced.
+- **Agent state repair:** none — no agent needs notification or reset.
+- **User visibility:** none — the reaper is dark by default, so no user sees a
+  change during a rollback window.
+
+---
+
+## Conclusion
+
+This review confirmed the change is a tightly-scoped guard widening: two pure reads
+and one self-protecting mutation, with the only data-loss path (`worktree remove
+--force`) explicitly kept blocked. The review reinforced the decision to deny
+`--force` in the allowlist (not just rely on the reaper never passing it) and to
+add a real-git integration test against a promoted source tree — the test the
+original fake-git suite lacked, which is why the reaper shipped non-functional.
+Clear to ship; verify live via `GET /worktrees/agent-reaper` reporting non-zero.

package/upgrades/side-effects/standby-lease-holder-sync.md

@@ -0,0 +1,70 @@
+# Side-Effects Review — Standby lease-holder propagation
+
+**Version / slug:** `standby-lease-holder-sync`
+**Date:** `2026-05-31`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Decouple cross-machine lease coordination from git. The lease coordinator +
+`HttpLeaseTransport` (and the handoff / reply-marker / live-tail transports) now
+run whenever `coordinator.enabled && coordinator.identity`, instead of being
+nested inside a single `try` gated on `gitBackupEnabled` whose first statement
+(`new GitSyncManager`) throws on an instar-source-tree home (SourceTreeGuard) and
+discarded everything. Git-sync is now an internal best-effort optional; when no
+git medium exists the lease uses a new `LocalLeaseStore` (local-file backed) and
+the HTTP transport carries cross-machine propagation. Also fixes a self-rejection
+in `LeaseCoordinator.effectiveView` (it passed the transport's self-inclusive
+nonce watermark to `acceptTunnelLease`, rejecting the very lease it validated).
+
+## Decision-point inventory
+
+1. **`gitSyncRef` defined vs undefined** → `GitLeaseStore` vs `LocalLeaseStore`.
+2. **`effectiveView` tunnel-fold** → accept the observed lease iff sig + git-floor
+   + epoch-newer pass (nonce floor now excludes the lease's own holder).
+
+## 1. Over-block
+
+**What legitimate inputs does this reject?** None added. The lease coordinator now
+runs in MORE cases (git-less machines) than before, not fewer. `acceptTunnelLease`
+still rejects forged/below-floor/older-nonce leases (signature + git-floor +
+replay checks all run); excluding the observed lease's own holder from the nonce
+floor does not weaken this — the transport's `recordObserved` already dropped
+replays on receive, and a forged lease is still caught by the signature check
+before it is ever folded.
+
+## 2. Under-block
+
+**What does this still miss?** A git-less mesh inherits the tunnel's coordination
+(RTT-bounded acquisition + observe-before-acquire), not git's shared CAS — so its
+split-brain guarantees are exactly the documented tunnel-path guarantees, no
+stronger. This matches the spec non-goal. In the current 1-awake/1-standby
+topology the standby never acquires, so there is no acquisition contention to
+resolve. When git IS available, `GitLeaseStore` (shared CAS) is still used.
+
+## 3. Blast radius
+
+- New file `LocalLeaseStore.ts` is only constructed when `gitSyncRef` is undefined
+  (no git medium). On any git-backed agent the behavior is byte-identical to today
+  (`GitLeaseStore` path unchanged).
+- The `effectiveView` change runs for ALL lease-coordinator users (git and
+  git-less). It only RELAXES a redundant nonce self-check; existing
+  `LeaseCoordinator`/`FencedLease`/`HttpLeaseTransport` unit suites (51 tests
+  across these + the new ones) stay green, confirming no replay-semantic
+  regression.
+- The server.ts restructure moves the lease/handoff/live-tail setup out of the
+  git-gated `try`. A failure in lease setup is still caught (now with a
+  "Lease/transport setup" message) so a single-machine agent is unaffected.
+
+## 4. Rollback
+
+Pure code (no migration, no config default, no schema). Rollback = revert the PR;
+`lease-local.json` becomes inert (no reader). No data is mutated or deleted.
+
+## 5. Failure modes
+
+- `LocalLeaseStore` persist fails (disk) → logged, in-memory view still serves;
+  cross-machine propagation continues over the tunnel. Never blocks boot.
+- Git medium unavailable → caught, lease falls back to LocalLeaseStore. This is
+  the intended path, not an error.