instar 1.3.255 → 1.3.256

package/upgrades/1.3.256.md

@@ -0,0 +1,92 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The `dangerous-command-guard.sh` PreToolUse hook blocks risky git commands,
+including `git push --force` and `git push -f`. Because the match is a
+case-insensitive substring, the SAFE variant `git push --force-with-lease` also
+matched `git push --force` and got blocked — even though force-with-lease to one's
+OWN feature/PR branch is the normal, expected way to update an amended/rebased
+branch (it refuses to overwrite work the local clone hasn't seen, so it can't
+silently clobber a collaborator).
+
+This adds a narrow carve-out: `git push --force-with-lease` is allowed ONLY when it
+does not explicitly target a protected branch (`main`/`master`/`develop`/`release*`).
+Everything else stays exactly as strict — plain `--force`/`-f` (no lease), any
+force-push to a protected branch, and all other risky patterns (`git reset --hard`,
+`git clean -fd`, DB-destruction) remain blocked. The fix is applied to both
+canonical deploy sources (`PostUpdateMigrator.getDangerousCommandGuard()` for
+existing agents, always-overwritten on migration; and the `src/commands/init.ts`
+inline copy for fresh init).
+
+Fixed a Threadline continuity bug where a known peer's reply could be
+false-isolated to a fresh cold-spawn thread, breaking agent-to-agent
+conversation memory.
+
+When a caller addressed a peer with the `name:fpPrefix` disambiguation syntax
+(e.g. `Dawn-Workstation:8c7928aa`), `/threadline/relay-send` resolved the peer's
+full fingerprint for routing but `captureOrigin` stored the raw composite string
+as the conversation's `remoteAgent`. The inbound anti-hijack guard
+(`ThreadlineRouter`) compares a reply's bare `senderFingerprint` (often with an
+empty `senderName`) against the stored owner; a composite never equals a bare
+fingerprint, so the guard treated the legitimate reply as a possible hijack and
+shunted it into a new empty thread.
+
+The fix stores the **resolved full fingerprint** as `remoteAgent` (and keeps the
+typed label only as `remoteAgentDisplayName`), so the reply matches and resumes.
+This mirrors `telegramBridge.mirrorOutbound`, which already stored the resolved
+fingerprint as the owner. The anti-hijack guard is unchanged and not weakened: we
+only store the full fingerprint the server itself resolved for routing — never a
+guessed value and never a spoofable short prefix — so an impostor with a
+different fingerprint is still isolated.
+
+## What to Tell Your User
+
+Nothing proactive required — this is an internal developer-experience fix to the
+safety guard. If a dev session previously got blocked trying to safely update its
+own pull-request branch, that false alarm is gone; force-pushing to shared
+branches like main is still blocked.
+
+Agent-to-agent conversations that were addressed using the name-plus-shortcode
+syntax now stay coherent across replies instead of occasionally restarting from
+scratch as if the other agent had become a stranger. Nothing to turn on, and no
+conversation history is lost.
+
+## Summary of New Capabilities
+
+None user-facing — a safety-hook false-positive fix. Agents resolving their own PRs
+(rebase/amend → safe force-with-lease push to a feature branch) are no longer
+incorrectly blocked, with no loss of protection against genuinely-risky force-pushes.
+
+| Capability | How to Use |
+|-----------|-----------|
+| Coherent replies for name:shortcode-addressed peers | Automatic. When you message a peer by the name-plus-fingerprint-prefix form, the conversation owner is now recorded as the peer's full resolved fingerprint, so their reply resumes the same thread instead of cold-spawning. |
+
+## Evidence
+
+- **Reproduction:** Codey, mid-cycle on its own PR branch, ran a
+  `--force-with-lease` push to update an amended commit and was blocked by the
+  guard (framework-issue `52fa8663`, "force-push-guard-blocks-own-pr-amend").
+  Reproduced again live this session: a Telegram status message that merely
+  *quoted* the command string was itself blocked by the deployed hook.
+- **Before:** `--force-with-lease` to a feature branch → BLOCKED (exit 2), matching
+  the `git push --force` substring pattern.
+- **After:** `--force-with-lease` to a non-protected branch → ALLOWED; plain
+  `--force`/`-f`, force-to-`main`, and all other risky patterns → still BLOCKED.
+- **Tests:** `tests/unit/dangerous-command-guard-force-with-lease.test.ts` — 10
+  tests, both content (carve-out present in both writers) and behavioral (runs the
+  actually-rendered migrator hook: ALLOW own/feature branch + no-branch + protected-
+  word-substring; BLOCK plain force, `-f`, force-to-main/master, and an unrelated
+  `git reset --hard`). All pass. The existing
+  `dangerous-command-guard-gh-pr-merge-gate.test.ts` suite re-run green (no
+  regression). `tsc --noEmit` clean.
+
+Reproduced live as the 2026-06-04 Dawn cold-spawn incident (a reply isolated with
+`unverified sender 8c7928aa9f04… owned by Dawn-Workstation; isolating`). New unit
+test reproduces that exact log line for the composite-owner case and proves the
+full-fingerprint-owner case resumes; new integration test asserts
+`/threadline/relay-send` stores the resolved fingerprint. tsc clean; 56 related
+tests green.

package/upgrades/side-effects/force-with-lease-own-branch.md

@@ -0,0 +1,103 @@
+# Side-Effects Review — dangerous-command-guard allows force-with-lease to own branch
+
+**Version / slug:** `force-with-lease-own-branch`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `required (safety-hook relaxation)`
+
+## Summary of the change
+
+The `dangerous-command-guard.sh` PreToolUse hook blocks risky git commands. Its
+risky-pattern list includes `"git push --force"` and `"git push -f"`. Because the
+match is a case-insensitive substring, `git push --force-with-lease` ALSO matches
+`git push --force` and gets blocked — even though `--force-with-lease` is the
+*safe* force-push (it refuses to overwrite work the local clone hasn't seen).
+
+This is a recurring friction: a dev session resolving its OWN PR (rebase/amend →
+push) needs `--force-with-lease` to its feature/PR branch, and the guard blocks
+it. Codey hit it mid-cycle (framework-issue `52fa8663`).
+
+The fix adds a narrow carve-out BEFORE the risky-pattern loop:
+
+```
+FORCE_WITH_LEASE_OWN_BRANCH=0
+if <command contains "git push ... --force-with-lease">; then
+  if <command explicitly names a protected branch: main|master|develop|release*>; then
+    FORCE_WITH_LEASE_OWN_BRANCH=0   # keep blocking
+  else
+    FORCE_WITH_LEASE_OWN_BRANCH=1   # allow the safe case
+  fi
+fi
+```
+
+Inside the loop, when `FORCE_WITH_LEASE_OWN_BRANCH=1` and the matched pattern is a
+force-push pattern, the loop `continue`s (skips the block). All OTHER risky
+patterns (`git reset --hard`, `git clean -fd`, DB-destruction, plain `--force`)
+are untouched.
+
+The change is applied identically to BOTH canonical deploy sources —
+`PostUpdateMigrator.getDangerousCommandGuard()` (existing agents, always-overwrite
+on every migration) and the inline copy in `src/commands/init.ts` (fresh init) —
+plus the vestigial reference copy at `src/templates/hooks/dangerous-command-guard.sh`
+(not on any runtime deploy path, kept consistent to avoid a future stale-source trap).
+
+## Decision-point inventory
+
+One decision point, two conditions:
+1. **Is it force-with-lease?** `git +push[^|;&]*--force-with-lease` (the safe variant).
+   If not present → no carve-out, normal blocking applies.
+2. **Does it explicitly target a protected branch?** A standalone `main`/`master`/
+   `develop`/`release*` token (word-boundary anchored: preceded by space/`:`/`/`/start,
+   followed by space/`:`/end). If yes → keep blocking. If no → allow.
+
+## 1. Over-block (what does this still block that it should?)
+
+- **Plain `git push --force` / `git push -f`** (no `--force-with-lease`): still
+  blocked — `FORCE_WITH_LEASE_OWN_BRANCH` stays 0, the force pattern matches, no
+  carve-out. ✅ (test: "BLOCKS plain git push --force", "BLOCKS git push -f")
+- **`--force-with-lease` to an explicit protected branch** (`... origin main`,
+  `... master`): still blocked — the protected-token regex sets the flag back to 0.
+  ✅ (tests: "BLOCKS force-with-lease that explicitly targets main/master")
+- **Every non-force risky pattern** (`git reset --hard`, `git clean -fd`, DROP/
+  TRUNCATE/DELETE, `rm -rf .`): untouched — the carve-out only `continue`s for
+  patterns matching `git push (--force|-f)`. ✅ (test: "still BLOCKS git reset --hard")
+
+## 2. Under-block (what does it now allow that it didn't?)
+
+ONLY `git push --force-with-lease` to a NON-protected branch (the agent's own
+feature/PR branch). This is genuinely safe:
+- `--force-with-lease` will not clobber commits the local ref hasn't observed (it
+  fails loudly if the remote moved underneath you), so it cannot silently destroy
+  a collaborator's work the way bare `--force` can.
+- A feature/PR branch is not shared history; force-updating it after a rebase/amend
+  is the normal, expected workflow.
+
+**Residual edge — `git push --force-with-lease` while checked out ON main with no
+branch named** (the command string contains no protected token, so the flag is 1).
+This is double-protected and not a real risk:
+1. Instar agents work in feature-branch worktrees per the Worktree Convention —
+   they are never checked out on main.
+2. `main` carries remote branch protection on the canonical repo, which rejects
+   any force-push regardless of what the local guard allows.
+The local guard is defense-in-depth, not the only line; this edge requires
+defeating BOTH the convention and remote branch protection.
+
+## 3. Blast radius
+
+- `src/core/PostUpdateMigrator.ts` (`getDangerousCommandGuard()`) — redeploys the
+  hook to every agent on next migration (always-overwrite path, line ~1832). No
+  new migration method required: the existing always-overwrite is the delivery.
+- `src/commands/init.ts` — fresh-init copy.
+- `src/templates/hooks/dangerous-command-guard.sh` — vestigial reference, kept in sync.
+- `tests/unit/dangerous-command-guard-force-with-lease.test.ts` — new (10 tests).
+- No API, schema, config, or behavior change beyond the one guard decision.
+- The pre-existing gh-pr-merge gate and coherence-gate blocks in the same hook are
+  untouched (regression test `dangerous-command-guard-gh-pr-merge-gate.test.ts`
+  re-run green).
+
+## 4. Reversibility
+
+Fully reversible: revert the carve-out block in the three sources; the next
+migration redeploys the prior hook. No state, no persisted format, no migration
+flag. Verified: `tsc --noEmit` clean; 10/10 new tests pass; the existing guard
+test suite stays green.

package/upgrades/side-effects/threadline-canonicalize-peer-address.md

@@ -0,0 +1,93 @@
+# Side-Effects Review — Canonicalize peer address to full fingerprint on send
+
+**Version / slug:** `threadline-canonicalize-peer-address`
+**Date:** `2026-06-04`
+**Author:** `Echo (instar dev agent)`
+**Tier:** `1 (targeted bug fix to existing route + tests; no new surface, no schema change)`
+**Second-pass reviewer:** `recommended — SHARED Threadline security code (Dawn runs it too). PR is opened for Dawn's review before merge; NOT self-merged.`
+
+## Summary of the change
+
+`/threadline/relay-send` resolves a peer's **full fingerprint** for routing
+(`resolvedId` on the relay path; `localTarget.fingerprint` on the local path),
+but `captureOrigin` stored the raw caller-supplied target (which may be a
+`name:fpPrefix` composite like `Dawn-Workstation:8c7928aa`) as the conversation's
+`remoteAgent`. The inbound anti-hijack guard (`ThreadlineRouter`) compares a
+reply's `senderFingerprint` (the bare full fingerprint, often with empty
+`senderName`) against the stored `remoteAgent`; a composite/display string never
+equals a bare fingerprint, so a known peer's reply was false-isolated to a fresh
+cold-spawn thread — breaking A2A continuity (the "one coherent individual"
+property). Observed live as the 2026-06-04 Dawn cold-spawn incident.
+
+Fix: `captureOrigin(effThreadId, canonicalRemoteAgent, displayName?)` now stores
+the **resolved full fingerprint** as `remoteAgent` and keeps the raw target only
+as `remoteAgentDisplayName`. The two call-sites pass the already-resolved
+fingerprint (relay: `resolvedId`; local: `localTarget.fingerprint ||
+publicKey.slice(0,32) || name`). Mirrors `telegramBridge.mirrorOutbound`, which
+already stored `{ remoteAgent: resolvedId, remoteAgentName: targetAgent }`.
+
+Files: `src/server/routes.ts` (captureOrigin signature + 2 call-sites),
+`tests/unit/ThreadlineRouter-anti-hijack.test.ts` (+2 guard tests),
+`tests/integration/threadline/relay-send-canonical-remoteagent.test.ts` (new).
+
+## 1. Over-block / weakening
+
+Does it weaken the guard? No. We only ever store the **full** fingerprint the
+server itself resolved for routing — never a guessed value and never an
+8-char prefix (prefix-matching would be a ~32-bit, grind-able hijack vector and
+is explicitly NOT used). An impostor presenting a different fingerprint still
+fails `peer === inboundFp` and is still isolated (proved by the retained
+"isolates an unverified sender" test + the new composite-isolation test). The
+change strictly *adds* correct matches for a genuinely-resolved peer; it removes
+no isolation.
+
+## 2. Under-block
+
+Does it miss a case it should catch? No new bypass: the stored owner is now a
+stronger identity (full fingerprint) than before (a spoofable display string).
+Existing threads already persisted with a composite owner are NOT retroactively
+rewritten — this is a forward fix at the write path; the one historically-broken
+thread is a one-off. The deeper R2 question (relay inbound `trust.kind` is
+hardcoded `plaintext-tofu`, so a verified peer is never crypto-exempted) is
+intentionally OUT OF SCOPE here and left for security-design review.
+
+## 3. Level-of-abstraction fit
+
+The canonicalization lives at the send/record boundary (`captureOrigin`), the
+same place that already owns the resolved-fingerprint vs display-name split for
+the Telegram mirror. The guard is untouched (no change to ThreadlineRouter).
+
+## 4. Signal vs authority compliance
+
+No gate/authority change. `remoteAgentDisplayName` preserves the human-facing
+label for all display strings (`captureOriginOnSend` already falls back to
+`remoteAgentDisplayName ?? remoteAgent`).
+
+## 5. Interactions
+
+- The anti-hijack guard now matches a known peer's bare-fingerprint reply
+  (`peer === inboundFp`) and resumes instead of cold-spawning.
+- `appendCanonicalOutboxEntry` and `mirrorOutbound` already used `resolvedId`;
+  this aligns `captureOrigin` with them (consistency, not a new direction).
+- `captureOrigin` only fires when `originTopicId` is set (origin capture);
+  topic-less sends are unaffected (their owner is written by the inbound handler
+  as `message.from.agent = senderFingerprint`, already a full fingerprint).
+
+## 6. External surfaces
+
+No new HTTP route, no config, no template/CLAUDE.md change, no persisted-format
+change (the `remoteAgent` field already existed; only the VALUE stored is now the
+canonical fingerprint). Nothing to migrate.
+
+## 7. Rollback cost
+
+Low — revert one function signature + two call-sites + two test files. No
+data-format change; existing records are untouched.
+
+## Conclusion
+
+Low-risk, strictly non-weakening, additive correctness fix at the send/record
+boundary that closes the composite-address false-isolation (the Dawn cold-spawn
+incident). Guard unchanged; impostors still isolated; only genuinely-resolved
+peers now resume. Shipped behind a PR for Dawn's review (shared security code);
+the deeper R2 trust-propagation question is logged separately, not touched here.

package/upgrades/threadline-canonicalize-peer-address.eli16.md

@@ -0,0 +1,58 @@
+# ELI16 — Store a peer's real fingerprint as the conversation owner
+
+## The problem, in plain English
+
+When one agent messages another over Threadline, you can address the other
+agent by a friendly "name plus a short code" label — for example
+`Dawn-Workstation:8c7928aa`. The `8c7928aa` part is just the first 8 characters
+of the other agent's long cryptographic fingerprint, used to tell apart two
+agents that happen to share a name.
+
+Here's the bug. When I sent the first message, my server looked up the *full*
+fingerprint (`8c7928aa9f04fbda947172a2f9b2d81a`) so it could actually route and
+encrypt the message to the right agent — but then, when it wrote down "who owns
+this conversation," it saved the raw label I typed (`Dawn-Workstation:8c7928aa`)
+instead of that resolved full fingerprint.
+
+That mattered because of a security guard. Threadline has an anti-hijack check:
+when a reply comes in claiming to belong to an existing conversation, the guard
+asks "is the sender actually the agent who owns this thread?" A genuine reply
+arrives carrying the sender's *full* fingerprint (and often no display name at
+all). The guard compared the stored owner (`Dawn-Workstation:8c7928aa`, a label)
+against the reply's bare full fingerprint (`8c7928aa9f04…`), saw they were not
+equal, and concluded the reply might be an impostor. So it shunted my friend's
+perfectly legitimate reply into a brand-new, empty conversation — and the thread
+lost all its memory. It felt like the other agent had become a stranger
+mid-conversation. This is the "fragmented identity" incoherence: a known peer's
+own replies being treated as someone else's.
+
+## The fix
+
+The server *already* resolves the peer's full fingerprint when it sends the
+message (it has to, in order to route and encrypt). The fix is simply: store
+*that* resolved full fingerprint as the conversation's owner, and keep the label
+I typed only as a separate, human-friendly display name. Now when the reply
+comes back carrying the full fingerprint, it matches the stored owner exactly,
+the guard says "yes, this is the same agent," and the conversation continues
+normally instead of cold-starting.
+
+This follows a pattern the code already uses elsewhere: the Telegram mirror for
+outbound messages already stored the resolved fingerprint as the owner and the
+typed name as the display name. Only the "capture origin" write had been using
+the raw label. We brought it in line.
+
+## Why it's safe
+
+The guard is not weakened at all. We never guess, and we never trust a short
+8-character prefix as proof of identity (that would be too easy to fake). We
+only store the *full* fingerprint that the server itself resolved for routing.
+An impostor presenting a *different* fingerprint still fails the match and still
+gets isolated — exactly as before. The only thing that changes is that a real,
+known peer's reply now correctly resumes its own conversation instead of being
+mistaken for a stranger.
+
+## What you'd notice
+
+Almost nothing — that's the point. Agent-to-agent conversations that were
+addressed with the `name:shortcode` syntax will simply stay coherent across
+replies instead of occasionally restarting as if from scratch.