instar 1.3.725 → 1.3.727

package/upgrades/1.3.727.md

@@ -0,0 +1,143 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`AgentWorktreeReaper.start()` scheduled ONLY a 24h `setInterval` — no initial
+pass. Agent servers restart far more often than daily (auto-updates, sleep/wake
+supervisor bounces), so the interval timer reset on every restart and an
+**enabled + armed** reaper never ran a single pass. Measured live on 2026-07-02:
+86 worktrees / 25GB accumulated on a machine with `enabled: true, dryRun: false`
+and `lastPassAt: 0` — the feature was on and structurally inert (root cause of
+that day's fseventsd/reboot resource incident).
+
+The fix:
+
+- New `initialPassDelayMs` config (default 15 min; `<= 0` disables — the exact
+  legacy behavior as a no-release rollback lever) on
+  `monitoring.agentWorktreeReaper`.
+- `start()` now schedules a ONE-TIME initial pass after that delay (unref'd
+  timer, cleared by `stop()`), then the unchanged 24h cadence. The delay keeps
+  the pass off the busy post-boot window.
+- The pass runs through the same `reap()` as always: same KEEP gates (in-use /
+  dirty / unmerged / detached), same dry-run gating, same `maxReapsPerPass`
+  blast-radius cap, same per-path reclaim-failure breaker. Nothing about WHAT
+  may be deleted changed — only WHEN passes run.
+- `GET /worktrees/agent-reaper` snapshot additively reports
+  `initialPassPending`.
+- CLAUDE.md template + PostUpdateMigrator addendum so deployed agents learn the
+  new behavior (idempotent, content-sniffed on `initialPassDelayMs`).
+
+Fixes the roadmap-0.3 blocker found in the Slack permission-gate false-positive
+review (`docs/audits/slack-permission-fp-review-2026-07.md`, row 29): after the
+2026-07-01 silent-loss registry rebuild, the Slack live-test scenario cast could no
+longer resolve, so every Slack sender — including the workspace owner — resolved as an
+unregistered guest. Root cause: the gate derives roles from the production user registry
+(`users.json`), the rebuild removed the five Slack test-cast principals, and the
+fixture-identity guard (correctly) refuses to let test identities back into the
+production registry.
+
+The fix is a SEPARATE, test-workspace-scoped principal source rather than a registry
+edit:
+
+- **New `TestWorkspacePrincipalSource` + `ChainedUserLookup`** (`src/permissions/`).
+  The gate's `SlackPrincipalResolver` now reads production-registry-FIRST, then the
+  cast as a fallback. A production-registered user can never be shadowed or
+  role-escalated by a cast entry.
+- **Config-carried cast** — `permissionGate.testCast` in the Slack messaging config
+  (`{ testWorkspace, workspaceId, principals[] }`). It lives beside the workspace
+  tokens, so a `users.json` rebuild can never silently drop it again.
+- **Code-enforced workspace scoping** — the cast resolves ONLY while the adapter's
+  VERIFIED connected team id (captured from Slack's own `auth.test` at start, exposed
+  via `SlackAdapter.getConnectedTeamId()`) EXACTLY equals `workspaceId`. Any other
+  workspace → the source is structurally invisible (production behavior byte-identical
+  to no cast). An unlisted uid in the test workspace → today's unregistered-guest default.
+- **Partition invariant** — every cast `slackUserId` must match the SAME fixture-marker
+  matcher (`users/testIdentityMarkers.ts`) the production guard uses to refuse fixtures;
+  a non-fixture id is refused at load. One identity, two disjoint homes.
+- **Fail-closed self-declaration** — the block must set `testWorkspace: true`; without
+  it the whole cast is ignored (zero principals, one loud log line, no production
+  effect). A cast can never be activated by accident.
+- **Authority scope (KYP)** — the source feeds permission-gate role resolution ONLY. It
+  takes no state dir and has no write surface, so it cannot create user-registry
+  entries, cannot feed operator binding, and cannot affect message authorization /
+  sender validation.
+
+The runbook (`docs/specs/SLACK-ORG-TEST-WORKSPACE-RUNBOOK.md`) is patched: the old
+"seed the cast in users.json" step is replaced with the `testCast` config block plus a
+re-provision checklist so a registry rebuild can't silently lose principal resolution
+again. Dark by default — nothing activates without an explicit `testCast` block.
+
+## What to Tell Your User
+
+<!-- audience: user, maturity: stable -->
+
+If you switched on the stale-worktree auto-cleaner, it now genuinely runs: one
+cleaning pass about 15 minutes after each server start, then daily as designed.
+Previously a quirk meant frequent server restarts kept pushing its first run
+into the future forever, so leftover work folders could quietly pile up into
+tens of gigabytes even with the cleaner enabled. Its safety rules are untouched:
+it still only removes folders whose work is fully merged and saved, still does
+dry-run first, and it stays entirely off unless you enabled it.
+
+- **Slack permission demo is more robust**: the test harness that proves the Slack
+  "who's allowed to do what" feature now keeps its demo cast in a safe place that a
+  routine cleanup of your real people-list can't wipe out. This is behind-the-scenes
+  test infrastructure — nothing changes in how I work for you day to day, and the
+  pretend demo roles are locked to the throwaway test workspace so they can never leak
+  into a real one.
+
+## Summary of New Capabilities
+
+- The stale-worktree reaper actually fires on real deployments: a one-time
+  cleaning pass ~15 minutes after boot (tunable/disableable via
+  `monitoring.agentWorktreeReaper.initialPassDelayMs`), unchanged daily cadence
+  thereafter, and `initialPassPending` visibility on the existing report route.
+
+| Capability | How to Use |
+|-----------|-----------|
+| Test-workspace-scoped Slack principal cast | Add a `testCast` block (with `testWorkspace: true`, `workspaceId`, `principals`) under the Slack `permissionGate` config — dark unless configured |
+
+## Evidence
+
+- `tests/unit/agent-worktree-reaper.test.ts`: 47/47 green — 7 new tests (initial
+  pass fires exactly once at the configured delay and before the interval;
+  respects dry-run; disabled reaper sets no timers; `<= 0` restores
+  interval-only; `stop()` cancels the pending pass; 24h cadence unchanged after
+  the initial pass; snapshot reports `initialPassPending` honestly).
+- Live incident data (2026-07-02, topic 30379): reaper enabled+armed with 25
+  reap-eligible worktrees and `lastPassAt: 0`; server uptime history shows no
+  24h-continuous window for weeks.
+
+Root cause is a live datapoint captured in `docs/audits/slack-permission-fp-review-2026-07.md`:
+row 29 (2026-07-02 18:15:19, the only organic decision row) shows the workspace OWNER
+seat's Slack UID resolving as `role: guest, registered: false` — the same UID that
+resolved as `role: owner, registered: true` in every June scenario row, because the
+2026-07-01 rebuild removed the cast from `users.json`.
+
+The fix is verified by `tests/unit/slack-test-workspace-principal-source.test.ts` (22
+tests, all passing), which exercises BOTH sides of every boundary:
+
+- matching workspace + listed uid → registered role; matching workspace + unlisted uid
+  → guest.
+- non-matching workspace + listed uid → source invisible, and the resolved principal is
+  asserted EQUAL to the no-cast baseline (the scoping proof that roles can't leak into a
+  production workspace).
+- missing `testWorkspace: true` → source disabled, zero seats, loud log line, and
+  byte-identical to no cast.
+- non-fixture uid refused at load; cast cap enforced; production-registry-first
+  precedence; a throwing source skipped.
+- authority-scope assertions: the source exposes only the read contract (no
+  write/registry/operator methods) and takes no state dir.
+
+`tests/integration/slack-testcast-principal-pipeline.test.ts` (5 tests, all passing)
+additionally drives the EXACT server.ts composition through the real inbound chokepoint
+(`SlackAdapter._handleMessage`) and asserts the durable decision-ledger rows: the owner
+seat resolves `owner, registered:true` through the live path (the row-29 regression),
+the same seat is an unregistered guest when connected to any other workspace or before
+`auth.test` verifies the connection, an unlisted uid stays a guest, and a production
+record beats the cast for the same uid.
+
+`npx tsc --noEmit` exits 0.

package/upgrades/side-effects/reaper-initial-pass.md

@@ -0,0 +1,103 @@
+# Side-Effects Review — AgentWorktreeReaper one-time initial pass (reaper-never-fires fix)
+
+**Version / slug:** `reaper-initial-pass`
+**Date:** `2026-07-02`
+**Author:** `Instar Agent (echo)`
+**Second-pass reviewer:** `echo reviewer subagent (independent read)`
+
+## Summary of the change
+
+`AgentWorktreeReaper.start()` scheduled ONLY a 24h `setInterval` with no initial pass. Real agent servers restart far more often than daily (updates, sleep/wake supervisor bounces), so the interval reset forever and an **enabled + armed** reaper never ran a single pass — measured on 2026-07-02 as 86 worktrees / 25GB accumulated on a machine with `enabled: true, dryRun: false` (the fseventsd/reboot incident's root cause). The fix adds a one-time initial pass `initialPassDelayMs` (default 15 min) after `start()`, keeping the 24h cadence unchanged. Files: `src/monitoring/AgentWorktreeReaper.ts` (config field + initial `setTimeout`, unref'd, cleared by `stop()`, `initialPassPending` in `snapshot()`), `src/core/types.ts` + `src/config/ConfigDefaults.ts` (config plumbing), `src/core/PostUpdateMigrator.ts` (CLAUDE.md awareness bullet for fresh + already-installed sections), `tests/unit/agent-worktree-reaper.test.ts` (7 new tests).
+
+## Decision-point inventory
+
+- `AgentWorktreeReaper.evaluate()` (keep/reap classifier) — **pass-through** — untouched; all safety gates (in-use / dirty / unmerged / detached → KEEP) unchanged.
+- `AgentWorktreeReaper.start()` scheduling — **modify** — adds WHEN a pass runs (one initial pass), never WHAT a pass may delete.
+- `killsEnabled` (enabled && !dryRun) — **pass-through** — the initial pass runs through the same `reap()` with the same dry-run/enabled gating and the same `maxReapsPerPass` blast-radius cap and per-path failure breaker.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. (Nothing new is rejected; the classifier is untouched.)
+
+---
+
+## 2. Under-block
+
+The inverse risk (over-DELETE) is the relevant frame for a deleter: the initial pass cannot delete anything the interval pass wouldn't — same `reap()`, same gates, same cap. Residual miss: an agent whose server restarts more often than every `initialPassDelayMs` (15 min) still never completes a pass; that pathological restart-loop case is out of scope here (the crash-loop itself is the incident to fix) and the pass is cheap enough that a partial-uptime server still benefits on the next calm boot.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Right layer: the defect is purely in the component's own scheduling, so the fix lives in the component's `start()`. Alternatives considered and rejected: a scheduler job wrapping the reaper (duplicates an existing component lifecycle for no gain); persisting `lastPassAt` across restarts and firing when overdue (more state, more failure modes — the 15-min delayed pass achieves the same outcome stateless).
+
+---
+
+## 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.
+
+The change adds no authority and no detector. The reaper's existing (deliberately conservative, fail-closed) classifier keeps sole authority over deletions; this change only makes the already-shipped schedule actually execute. Dry-run/enabled defaults are unchanged (ships OFF + dry-run).
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** none — no other component schedules reaper passes.
+- **Double-fire:** initial pass and interval pass could theoretically overlap on a pathologically slow pass; `reap()` already has a `running` re-entrancy guard (returns empty, does not queue). Confirmed in code and covered by existing tests.
+- **Races:** the initial pass lands ~15 min after boot — after the busy post-boot window, and any worktree in use at that moment is kept by the `isInUse` gate (lock or live process cwd). A concurrently-created fresh worktree is kept by `isInUse`/dirty/unmerged gates exactly as during an interval pass.
+- **Feedback loops:** none — reaping does not feed anything that schedules reaping.
+
+---
+
+## 6. External surfaces
+
+- Other agents on the same machine: each agent's server reaps only its own `.worktrees/` estate (worktreesDir-bounded) — unchanged.
+- Install base: behavior change is that an agent with the reaper ENABLED will now actually reclaim merged+clean+idle worktrees within ~15 min of boot instead of never. The feature still ships OFF + dry-run by default, so fleet agents see no change until an operator opts in.
+- External systems: the initial pass may trigger the existing one-per-sweep `gh` merged-PR call ~15 min after boot (same call the interval pass makes; fail-safe to cherry-only).
+- Persistent state: none added; `initialPassPending` is in-memory observability on the existing snapshot route.
+- **Operator surface (Mobile-Complete Operator Actions):** no operator-facing actions added — config-only tuning, and the existing `GET /worktrees/agent-reaper` report is unchanged in shape (one additive field).
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator surface — not applicable (no dashboard/approval/form files touched; one additive JSON field on an existing observability route).
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN.** A worktree estate is a per-machine filesystem artifact; each machine's reaper reclaims only its own disk. No user-facing notices are emitted (housekeeping events go to the existing reaper event listeners/logs), no durable state is held that could strand on topic transfer, and no URLs are generated. The pool-wide "how much disk is reclaimable across machines?" question remains answerable per-machine via the existing route (a merged view is a separate feature, not regressed here).
+
+---
+
+## 8. Rollback cost
+
+Pure code change. Config kill-switch without a release: `{"monitoring": {"agentWorktreeReaper": {"initialPassDelayMs": 0}}}` restores exact legacy scheduling (interval-only). Full rollback: revert the PR, ship next patch. No persistent state, no migrations, no user-visible regression during the rollback window (the feature ships dark; worst case is returning to "reaper never fires", which is the status quo ante).
+
+---
+
+## Conclusion
+
+The review confirms this is a scheduling-only fix to a real, measured never-fires defect, with the deletion authority, safety gates, blast-radius cap, failure breaker, and OFF+dry-run defaults all untouched. The one design question the review surfaced — could the initial pass fire during a busy/fragile boot window — is addressed by the 15-min delay, the unref'd timer (never holds the process open), the `running` re-entrancy guard, and the existing in-use/dirty KEEP gates. Clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** echo reviewer subagent (independent audit, 2026-07-02)
+**Independent read of the artifact: concur**
+
+Concur with the review. Verified against the real diff: (a) the initial pass invokes the identical `reap()` — same KEEP gates, same `killsEnabled` dry-run gate, same `maxReapsPerPass` cap, same per-path breaker, so it cannot delete anything the interval pass could not; (b) the `running` re-entrancy guard returns empty without queuing; (c) double-`start()` is blocked by the `this.timer` guard, `stop()` clears both timers, the fired callback self-clears so `snapshot()` stays honest, and production has exactly one `start()` callsite; (d) the migrator addendum is idempotent via the `initialPassDelayMs` content-sniff, the anchor matches deployed CLAUDE.md byte-for-byte (verified against a live deployment), and anchor drift degrades to an append — no corruption path; (e) `initialPassPending` is additive and backward-compatible at the single `res.json(snapshot())` consumer; (f) config plumbing delivers `initialPassDelayMs` from `.instar/config.json` with no server.ts change, and `0` genuinely restores interval-only scheduling. Reproduced the test evidence: 47/47 green.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/agent-worktree-reaper.test.ts` — 47/47 green (7 new: initial-pass timing, dry-run respected, disabled → no timers, `<=0` rollback lever, stop() cancels, 24h cadence unchanged, snapshot honesty).
+- Live incident data: 2026-07-02 topic 30379 — reaper `enabled:true, dryRun:false, lastPassAt:0` with 25 reap-eligible worktrees sitting unreclaimed; server uptime histories show restarts always < 24h apart.

package/upgrades/side-effects/slack-test-workspace-principal-source.md

@@ -0,0 +1,227 @@
+# Side-Effects Review — Slack test-workspace-scoped principal source
+
+**Version / slug:** `slack-test-workspace-principal-source`
+**Date:** `2026-07-02`
+**Author:** `echo`
+**Second-pass reviewer:** `echo (independent second pass)`
+
+## Summary of the change
+
+Adds a sanctioned, workspace-scoped principal source for the Slack permission gate's
+role resolution, so the live-test scenario cast can resolve WITHOUT being seeded into
+the production user registry (`users.json`). Files touched:
+`src/permissions/TestWorkspacePrincipalSource.ts` (new: `TestWorkspacePrincipalSource`
++ `ChainedUserLookup`), `src/permissions/index.ts` (export), `src/messaging/slack/types.ts`
+(`permissionGate.testCast` config shape incl. the `testWorkspace` marker),
+`src/messaging/slack/SlackAdapter.ts` (capture + expose the VERIFIED connected team id
+from `auth.test`), `src/commands/server.ts` (wire production-registry-first chained
+resolution + fail-closed on the missing marker), the runbook
+(`docs/specs/SLACK-ORG-TEST-WORKSPACE-RUNBOOK.md`), and the unit test suite. The single
+decision point it interacts with is the gate's **principal role resolution** — it FEEDS
+that lookup as a fallback data source; it adds no new block/allow authority.
+
+## Decision-point inventory
+
+- `SlackPrincipalResolver` role resolution (`src/permissions/SlackPrincipalResolver.ts`) — **pass-through / feed** — the resolver now reads from a `ChainedUserLookup` (production registry first, then the test cast) instead of the bare production lookup. The resolver's own logic (registered vs guest, role derivation) is unchanged.
+- `TestWorkspacePrincipalSource.resolveFromSlackUserId` — **add** — a read-only lookup that answers ONLY for the verified test workspace and ONLY for fixture-marker ids; every uncertainty resolves null (fail-closed to the resolver's existing unregistered-guest default).
+- The permission gate's allow/refuse decision — **pass-through** — unchanged; it consumes the resolved principal exactly as before.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No new block/allow surface — the source only resolves an id to a role (or null); the
+gate still owns every allow/refuse decision. The only "rejection" it performs is at
+LOAD time (refusing to admit a cast entry): a non-fixture id, an invalid role, a
+duplicate, or an over-cap entry is dropped from the cast. Those refusals cannot
+over-block a real user, because a refused cast entry simply falls through to production
+resolution (which is the authoritative path anyway). A production-registered user is
+never affected — the production lookup is consulted first and wins.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+The source is deliberately narrow, so the "misses" are by design: it does not itself
+enforce anything (observe-only gate is unchanged), and it does not attempt to detect a
+misconfigured `workspaceId` (a `workspaceId` that never matches the connected team id
+just means the cast stays permanently inert — the safe direction, surfaced by the boot
+log's `admitted/refused` counts and the runbook's re-provision checklist). It also does
+not cover a cast id that a future edit removes from the fixture-marker list — such an id
+would then be refused at load (`not-a-fixture-identity`), which is loud, not silent.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes — it is a low-level, in-memory DATA SOURCE (a `UserLookup` implementation) that feeds
+the existing higher-level `SlackPrincipalResolver`, which in turn feeds the gate. It does
+NOT re-implement role derivation (that stays in `deriveRole`), does NOT re-implement the
+allow/refuse policy (that stays in `SlackPermissionGate`), and does NOT duplicate the
+fixture-identity matcher (it reuses the single `matchesTestIdentityToken` the production
+guard uses — one matcher, never two lists). The workspace-scope check is the one piece of
+new logic, and it lives at exactly the layer that knows the verified connection (a supplier
+reading `SlackAdapter.getConnectedTeamId()`).
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change produces a signal (a resolved role, or null) consumed by an existing smart gate; it holds no block/allow authority.
+
+The source answers "what role, if any, does this id play in the sanctioned test
+workspace?" and nothing more. It never blocks, never sends, never mutates. The
+authoritative allow/refuse decision remains entirely with `SlackPermissionGate`. The
+one gate-shaped decision it makes — "should I answer for this id at all?" — is a
+structural OWNERSHIP check (verified connected team id EXACTLY equals the configured
+workspace id), not a brittle content heuristic, and it fails CLOSED (null) on every
+uncertainty. That is the signal-vs-authority-compliant shape: a cheap structural check
+that only ever WITHHOLDS an answer, never grants an escalation.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** production resolution is consulted FIRST in the chain, so the cast can
+  never shadow a genuinely registered user. The reverse (cast shadowed by production) is
+  intended — a production record always wins. Verified by the `ChainedUserLookup`
+  precedence test.
+- **Double-fire:** none — a single resolution per inbound message; `ChainedUserLookup`
+  returns at the first non-null source.
+- **Races:** none — the cast is built once at wiring time and is immutable thereafter;
+  `resolveFromSlackUserId` is a pure map read behind the scope gate. No shared mutable
+  state, no concurrent writers.
+- **Feedback loops:** none — the source is read-only and does not record or learn.
+- **Fixture-identity guard:** complementary, not conflicting. The production guard refuses
+  fixtures INTO `users.json`; this source admits ONLY fixtures. Same matcher, disjoint
+  homes — an identity lives in exactly one store.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- Other agents on the same machine? No — the source is per-Slack-adapter, in-memory.
+- Other users of the install base? No — dark by default; nothing loads unless a Slack
+  config adds a `testCast` block with `testWorkspace: true`. On a plain install the whole
+  path is inert.
+- External systems? Reads one additional field (`team_id`) from the EXISTING `auth.test`
+  response the adapter already calls at startup. No new Slack API call, no contract change
+  (both changed adapter files carry a `CONTRACT-EVIDENCE: EXEMPT` marker with the reason).
+- Persistent state? None — the source writes nothing (no state dir, no fs handle). It
+  cannot create/modify `users.json`, operator bindings, or any file. This is the load-
+  bearing authority-scope property (KYP): the cast feeds role resolution ONLY.
+- Operator surface (Mobile-Complete Operator Actions)? No operator-facing actions — this is
+  test-harness wiring configured in `.instar/config.json`, not a runtime operator action.
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator surface — not applicable. This change touches no dashboard renderer, approval
+page, or grant/revoke/secret-drop form.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN.** A Slack adapter is bound to one workspace and runs on the
+machine serving that Slack connection; the `testCast` config and the verified connected
+team id are properties of THAT machine's live Slack socket. There is no cross-machine
+state to replicate: the cast is read-only config-derived data, not learned/durable state,
+so it neither strands on topic transfer nor needs a pool-wide merged read. It emits no
+user-facing notices (no one-voice concern) and generates no URLs. If the same live-test
+Slack adapter is ever run on two machines, each independently derives the same cast from
+the same config and each independently verifies its own connected team id — no divergence
+is possible because the input is static config plus a per-machine verified connection.
+
+---
+
+## 8. Rollback cost
+
+**Pure code + config change — revert and ship a patch.** No persistent state is created,
+so there is no data migration and no agent-state repair. Because the feature is dark by
+default (nothing activates without an explicit `testCast` block), a rollback has zero
+user-visible surface on any normal install. Removing the `testCast` block from the one
+live-test config (or setting `enforce`/`observeOnly` off) instantly reverts to
+production-registry-only resolution with no restart-order hazards beyond the normal
+"restart to pick up config" rule.
+
+---
+
+## Conclusion
+
+The review produced one substantive design fix during the build: the in-flight code
+lacked the required `testWorkspace: true` self-declaration marker (requirement 3). It was
+added as a fail-closed gate that lives IN the source constructor (not only at the wiring
+site), so the "ignored + one loud log line, no production impact" guarantee holds for
+every caller — Structure over Willpower. The scoping proof (why roles can't leak into a
+production workspace) is the load-bearing property and is covered on both sides by tests:
+matching-workspace resolves the cast; non-matching-workspace is byte-identical to having
+no cast at all. The change is a signal-producing data source with no new authority, dark
+by default, and is clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** echo (independent second pass — the change touches the word "gate")
+**Independent read of the artifact: concur**
+
+Independently re-derived the three safety properties and confirmed each is covered on both
+sides in `tests/unit/slack-test-workspace-principal-source.test.ts`: (1) scope — matching
+team + listed id resolves the role, non-matching team is invisible AND byte-identical to
+the no-cast baseline; (2) partition — a non-fixture id is refused at load and the cap
+bounds the source so it can't become a shadow registry; (3) opt-in — a missing
+`testWorkspace` marker disables the whole source, loudly, and is byte-identical to no cast.
+Also confirmed the authority-scope assertions: the source exposes only the `UserLookup`
+read contract (no write/registry/operator methods) and takes no state dir, so it
+structurally cannot write `users.json` or feed operator binding / sender validation. One
+concern considered and dismissed: the scope check uses the adapter's connected team id
+rather than a per-message `team_id` — but a Slack adapter is bound to exactly one workspace
+(one bot token), so the verified connected team id IS authoritative for every inbound
+message and is strictly stronger than trusting an envelope field. Concur with the review's
+conclusion: clear to ship.
+
+**Second-pass reviewer (dedicated subagent, 2026-07-02): CONCUR.** Independently
+re-verified in code (not from this artifact): (a) no blocking authority — resolution
+returns a record or null only, the gate keeps every allow/refuse; (b) fail-closed on
+disabled/throw/unverified/mismatch; (c) zero changes under `src/users/` (`git diff`),
+production fixture-identity guard fully intact; (d) production-first chain order at the
+wiring site; (e) no fs/write surface, unreachable from sender auth (`isAuthorized` runs
+BEFORE the observer and never consults a `UserLookup`); (f) both test suites re-run green;
+(g) no-`testCast` installs byte-identical (absent/invalid/disabled block leaves the bare
+production lookup; the whole wiring sits in try/catch degrading to production-only). Two
+non-blocking notes, both addressed in this build: the Tier-2 integration suite is staged
+with the commit, and `workspaceId` is now stored TRIMMED (a padded config value can no
+longer yield a permanently-inert cast; covered by a new unit test).
+
+---
+
+## Evidence pointers
+
+- `tests/unit/slack-test-workspace-principal-source.test.ts` — 23 tests, all passing (both
+  sides of scope, marker, partition, chain precedence, wiring, authority-scope, trim).
+- `tests/integration/slack-testcast-principal-pipeline.test.ts` — 5 tests, all passing
+  (Tier 2: the EXACT server.ts composition driven through the real inbound chokepoint
+  `SlackAdapter._handleMessage`, asserted against the durable decision ledger — the
+  row-29 owner-resolves-owner proof, the cross-workspace invisibility proof, fail-closed
+  pre-verification, unlisted-uid guest default, and production-precedence-beats-cast).
+  Tier 3 (E2E route liveness) is not applicable: the feature adds no HTTP routes, and its
+  only wiring site (`server.ts` Slack messaging block) requires live Slack credentials.
+- `npx tsc --noEmit` — exit 0.
+- Root-cause datapoint: `docs/audits/slack-permission-fp-review-2026-07.md` row 29 (the
+  owner seat resolving `guest, registered:false` after the 2026-07-01 registry rebuild).