instar 1.3.520 → 1.3.522

package/upgrades/side-effects/orphaned-work-sentinel.md

@@ -0,0 +1,40 @@
+# Side-effects review — OrphanedWorkSentinel (silent-uncommitted-death backstop)
+
+## 1. What changed
+
+A new dark, dev-gated, signal-only monitoring sentinel that detects agent worktrees with uncommitted work whose owning session is dead + settled, records them durably, and raises ONE deduped agent-health attention item. Optional off-by-default non-destructive preservation patch.
+
+- `src/monitoring/OrphanedWorkSentinel.ts` — class + pure classifier + config.
+- `src/monitoring/orphanedWorkGit.ts` — git/fs-backed deps (reuses `agentWorktreeGit` helpers).
+- Config type (`src/core/types.ts`), default with `enabled` OMITTED (`src/config/ConfigDefaults.ts`).
+- Dev-gate registration (`src/core/devGatedFeatures.ts`).
+- Server wiring (`src/commands/server.ts`), route ctx + `GET /orphaned-work` (`src/server/AgentServer.ts`, `src/server/routes.ts`).
+- Route classification in `src/server/CapabilityIndex.ts` (INTERNAL — observability the agent reads).
+- 3-tier tests: unit (classifier + real-git deps), integration (route), e2e (feature alive).
+
+## 2. Blast radius
+
+Read-only on the fleet (dark; route 503s). On a dev agent: a background timer runs one git/lsof scan per `scanIntervalMs` (default 10 min) over the agent's `.worktrees/`, records to `state/orphaned-work.jsonl`, and may raise ONE agent-health attention item per stranded worktree episode (deduped on path+content-signature; the agent-health lane routes to the calm "🩺 Agent Health" topic — never a per-item topic flood).
+
+## 3. Destructive actions
+
+None by default. The only mutation is the optional `preserveWork` sub-flag (off for everyone): it writes a patch FILE under the state dir from `git diff HEAD` (read-only) + the untracked file list. It never touches the worktree, its index, or any ref, and never deletes anything.
+
+## 4. Reversibility
+
+Fully reversible: it ships dark; disabling the dev-gate (or `enabled: false`) stops it. No data migration, no schema change. The durable jsonl + patch files are additive and bounded.
+
+## 5. Failure modes
+
+- `lsof`/git read failure → empty/clean signal → SKIP (never a false orphan). Recording/attention are best-effort (wrapped) and never throw the scan pass. Server wiring is wrapped in try/catch (non-fatal). Episode dedupe prevents re-alert spam; `maxFlagsPerPass` bounds blast radius.
+
+## 6. Operator-surface quality
+
+N/A — this change touches NO operator surface (no dashboard renderer/markup, no approval/grant/secret form). The only user-facing output is a plain-language agent-health attention item, authored in plain English ("a build died here with uncommitted changes — open the worktree to finish it, or discard"). No raw internals are surfaced to the user.
+
+## 7. Standards
+
+- Dev-agent dark-gate: `enabled` OMITTED + registered in `DEV_GATED_FEATURES` (lint + wiring test green).
+- Migration Parity: default added to `ConfigDefaults.ts` → `applyDefaults` propagates to existing agents automatically.
+- Testing Integrity: all 3 tiers + real-git wiring-integrity test.
+- Capability discoverability: route prefix classified INTERNAL.

package/upgrades/1.3.520.md

@@ -1,50 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- assembled-by: assemble-next-md -->
-<!-- bump: minor -->
-
-## What Changed
-
-Two cohesive changes (topic 22367, CMT-1434):
-
-1. **Mandates dashboard tab redesign.** The Mandates card now leads with the Grant
-   form as its primary, always-open block; Revoke is demoted to a quiet, collapsed
-   control beneath it. Raw JSON bounds, agent fingerprints, and scope slugs are
-   replaced with a plain-language summary sentence; identifiers survive only on a
-   muted "For support" line. Existing grants read as plain English ("Adam Admin can
-   deploy to production until 9:37 PM — authorized by you"), and the decision-audit
-   table stacks into labelled rows at phone width so the reason column is never
-   truncated. Renderer + markup + CSS only — the mandate API, payloads, and
-   PIN-never-retained discipline are unchanged. Ships via `dashboard/` static
-   serving, so it reaches every agent through the normal update path.
-
-2. **New constitutional standard: Operator-Surface Quality** (sibling to
-   Mobile-Complete Operator Actions) in `docs/STANDARDS-REGISTRY.md`. Where
-   Mobile-Complete asks "can the operator do this from a phone?", this asks "is it
-   actually good when they do?" — lead with the primary action, zero raw internals,
-   de-emphasized destructive actions, plain language, phone-width layout. It lands
-   with teeth: a new operator-surface-quality question in the instar-dev
-   side-effects review template, and a pre-commit gate
-   (`scripts/instar-dev-precommit.js`) that blocks any commit touching an operator
-   surface unless the review answers it. The standard names that gate, so the
-   Standards-Enforcement-Coverage audit classifies it as an enforced gate.
-
-## What to Tell Your User
-
-- **A cleaner Mandates screen on your phone**: "I gave the Mandates tab a real
-  overhaul. The action you actually came to do — granting someone permission — is
-  now front and centre, the risky Revoke button is tucked quietly out of the way,
-  and the screen reads in plain English instead of raw data. The history list also
-  finally fits your phone without cutting off the reason column."
-- **A new quality bar for everything you touch**: "I also turned this into a
-  standing rule for myself: any screen you use to approve or decide something has to
-  be genuinely good to use on your phone, not just technically reachable. I added an
-  automatic check that holds me to it whenever I build one of those screens."
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Redesigned Mandates tab (humanized, mobile-first) | Open the Mandates tab in the dashboard |
-| Operator-Surface Quality standard | docs/STANDARDS-REGISTRY.md (constitution) |
-| Operator-surface-quality pre-commit gate | automatic during instar-dev work |