instar 1.3.435 → 1.3.437

package/upgrades/1.3.437.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Every Instar agent now receives the **developer-skill toolkit** — the skills Instar uses to develop itself: `spec-converge`, `instar-dev`, `systematic-debugging`, `smart-web-fetch`, `knowledge-base`, `instar-scheduler`, `agent-memory`, `agent-identity`, `instar-identity`, `credential-leak-detector`.
+
+These skills were git-tracked under `skills/` but **no code installed them**, and the directory was not in `package.json` `files[]` — so they shipped in no package and installed for no agent, including the main dev agent. That violated **Agent Awareness** ("a capability the agent doesn't know about, it effectively doesn't have") and **Framework-Agnostic** ("one shared source of truth, never hand-maintained per engine").
+
+The fix: an authored `BUNDLED_DEV_SKILLS` allowlist + a generic `installBundledDevSkills()` copy-loop in `init.ts` (install-if-missing, recursive for `scripts/`/`templates/` subdirs); `skills/` added to `files[]` so the sources ship; the three port-hardcoded skill files rewritten to `${INSTAR_PORT:-4040}`; and a ratchet test that locks the "tracked-but-never-shipped" class shut. Existing agents receive the skills through the existing `migrateBuiltinSkills` path on update — no new migrator. `skills/` stays the single source (it is referenced there by `SourceTreeGuard`/`crossModelReviewer`).
+
+This is the bounded, lowest-risk slice; the full single-source consolidation (materialize the inline-dict skills, generator-validates-against-allowlist) is the documented follow-on in the spec.
+
+## What to Tell Your User
+
+Internal capability — nothing to configure. Your agent now has the full set of Instar-development tools — the spec convergence cycle, the instar-dev workflow, structured debugging, and more — so it can help develop and improve Instar with the same tools Instar uses on itself.
+
+## Summary of New Capabilities
+
+| Capability | How to use |
+|-----------|-----------|
+| The developer-skill toolkit installs to every agent | Automatic on `init` and on update; the skills appear as slash commands in `.claude/skills/` |
+| Add a skill to the canonical bundled set | Add the slug to `BUNDLED_DEV_SKILLS` in `src/commands/init.ts`; the ratchet test enforces it ships + installs |
+
+## Evidence
+
+Spec went through a 3-round `/spec-converge` (5 internal reviewers + a gemini cross-model pass) which caught 4 real flaws pre-code; operator-approved. Ratchet test `tests/unit/builtin-dev-skills.test.ts` — 6 assertions (source-present, ships via `files[]`, materializes-on-install, subdirs carried, no bare `localhost:<port>`, idempotent), green. `tsc --noEmit` clean. Convergence report: `docs/specs/reports/builtin-skill-install-single-source-convergence.md`.

package/upgrades/side-effects/builtin-skill-install-single-source.md

@@ -0,0 +1,80 @@
+# Side-Effects Review — Built-in Skill Install (bundled dev toolkit)
+
+**Version / slug:** `builtin-skill-install-single-source`
+**Date:** `2026-06-09`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (3-round /spec-converge with 5 internal reviewers + gemini external already performed; see convergence report)`
+
+## Summary of the change
+
+Ships the developer-skill toolkit (`spec-converge`, `instar-dev`, `systematic-debugging`,
+`smart-web-fetch`, `knowledge-base`, `instar-scheduler`, `agent-memory`, `agent-identity`,
+`instar-identity`, `credential-leak-detector`) to every agent. These skills lived in the
+git-tracked `skills/` dir but no code installed them and the dir was not in `package.json
+files[]`, so they reached no agent. The fix: an authored `BUNDLED_DEV_SKILLS` allowlist + a
+generic `installBundledDevSkills()` copy-loop in `init.ts` (install-if-missing, recursive for
+subdirs), `skills/` added to `files[]` so the sources ship, the 3 port-hardcoded files rewritten
+to `${INSTAR_PORT:-4040}`, and a ratchet test locking the "tracked-but-never-shipped" class shut.
+
+This is the bounded, lowest-risk slice of the converged spec; the full single-source
+consolidation (materialize the 16 inline skills, generator-validates-against-allowlist, files
+glob) is the documented follow-on.
+
+## Decision-point inventory
+
+No new block/allow/route gate. The only decision is install-if-missing vs overwrite (chosen:
+install-if-missing, preserving user customizations — verified by an idempotency test).
+
+## 1. Over-block
+
+None — the change adds files; it rejects no inputs. An agent that already has a same-named
+custom skill keeps it untouched (install-if-missing), verified by the idempotency test.
+
+## 2. Under-block
+
+The ratchet test covers the 10 allowlisted skills (source-present, ships, materializes, no bare
+port, idempotent) but does NOT yet assert `npm pack --dry-run` contents directly (it asserts
+`skills` ∈ `files[]` as the ship-proxy). The full generator-validation ratchet is the documented
+follow-on. No safety-relevant under-block.
+
+## 3. Level-of-abstraction fit
+
+Right layer: `installBuiltinSkills` is the existing install entry point; `installBundledDevSkills`
+sits beside `installBuildSkill`/`installAutonomousSkill` (same proven bundled-copy pattern).
+`skills/` stays the single source (referenced by SourceTreeGuard/crossModelReviewer) — relocating
+would have broken those references.
+
+## 4. Signal vs authority compliance
+
+N/A — no new gate, no blocking authority, no LLM judgment. Pure deterministic file install.
+
+## 5. Interactions
+
+- Reuses the existing `migrateBuiltinSkills` → `installBuiltinSkills` path (PostUpdateMigrator:1776),
+  so existing agents receive the skills on update with NO new migrator (Migration Parity mechanism #5).
+- Preserves the `claudeEnabled` gate (codex-only agents still skip `.claude/skills/`).
+- `installBundledDevSkills` resolves bundled source via `__dirname/../../skills` — correct in both
+  the published package (dist/ + skills/ are siblings at package root) and vitest.
+
+## 6. External surfaces
+
+Adds 10 slash commands to every agent's `.claude/skills/`. `skills/` is now shipped in the npm
+package (size: ~250KB of markdown). No new HTTP route, no message surface, no auth change.
+
+## 7. Rollback cost
+
+Low and clean. The change is additive + install-if-missing. Back-out = revert the commit; already
+installed skill dirs are inert markdown (an agent simply has extra slash commands). No state
+migration, no destructive op, no irreversibility.
+
+## Conclusion
+
+Low-risk, additive, fleet-wide install of the dev toolkit, behind a ratchet test, reusing the
+established bundled-skill pattern and the existing migrator. Operator-approved (D6 = fleet-wide).
+
+## Evidence pointers
+
+- Converged spec: `docs/specs/BUILTIN-SKILL-INSTALL-SINGLE-SOURCE.md` (review-convergence + approved).
+- Convergence report (3 rounds, 4 bugs caught): `docs/specs/reports/builtin-skill-install-single-source-convergence.md`.
+- Ratchet test: `tests/unit/builtin-dev-skills.test.ts` (6 assertions, green).
+- `tsc --noEmit` clean; CI push suite green except 1 unrelated environmental E2E flake (LLM-unavailable in local run).

package/upgrades/side-effects/subscription-inuse-account.md

@@ -0,0 +1,26 @@
+# Side-effects review — subscription-pool "in-use account" dashboard surface
+
+## What changed
+- New `src/core/InUseAccountResolver.ts`: resolves which pool account the agent is CURRENTLY running on, by probing `claude auth status` (the authoritative active-account surface) and matching its email to a pool account. Read-only; probe + clock injected; result cached (TTL 60s) with concurrent-probe coalescing.
+- `src/server/routes.ts`: new `GET /subscription-pool/in-use` → `{ enabled, activeAccountId, activeEmail }`. Registered before `/subscription-pool/:id` (literal beats param). Lazy-constructs a resolver if none on ctx; never 500s/503s.
+- `src/server/AgentServer.ts` + `src/commands/server.ts`: wire a single shared resolver instance through the ctor → RouteContext (so the cache is honored).
+- `dashboard/subscriptions.js`: controller fetches `/in-use` (best-effort, its failure can't blank the accounts list) and badges the in-use account card. `renderAccounts` gained an OPTIONAL trailing `inUseAccountId` param (backward compatible — existing callers/tests unaffected).
+- `dashboard/index.html`: CSS for the in-use badge + card highlight.
+
+## Blast radius
+- Purely ADDITIVE + READ-ONLY. No change to session launch, account selection, swapping, or any mutation path. A pool of zero accounts → route answers `{ enabled:false }`; single-account agents unaffected.
+- The only new side effect is spawning `claude auth status` (read-only, 15s timeout, maxBuffer bounded) at most once per 60s when the dashboard `/in-use` route is hit. If `claude` is missing or errors, the resolver degrades to `activeAccountId:null` (no badge) — never throws, never blocks.
+
+## Framework generality
+- Does NOT touch the session launch/inject abstraction (frameworkSessionLaunch / MessageDelivery). The resolver is claude-code-specific by design (it answers "which Claude account"), and `matchAccountByEmail` filters to anthropic/claude-code accounts, so a codex/gemini account can never be mis-reported as the active Claude login.
+
+## Honest scope note
+- This is the DISPLAY half of the request ("show which account is in use"). It reflects reality: normal sessions run on the default config, which this resolves authoritatively. The DETERMINISM half (pinning sessions to an explicit pool account so the default is never ambiguous) touches the critical session-launch path and is intentionally a separate, carefully-reviewed change — not bundled here. <!-- tracked: CMT-1185 -->
+
+## Migration parity
+- No agent-installed files change (no settings.json, config defaults, CLAUDE.md template, hooks, or skills). New route + dashboard asset ship with the package; existing agents get them on update. No `PostUpdateMigrator` entry needed.
+
+## Tests
+- Unit: `in-use-account-resolver.test.ts` (matcher both sides, resolve, cache TTL, coalescing, failure-degradation); `subscriptions-render.test.ts` (in-use badge present/absent).
+- Integration: `subscription-inuse-route.test.ts` (HTTP route: match / no-match / dark / does-not-shadow-`:id`).
+- E2E: `subscription-inuse-lifecycle.test.ts` (feature-alive: 200 in dark + live).