instar 1.3.509 → 1.3.511

package/upgrades/1.3.511.md

@@ -0,0 +1,46 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- **`GET /jobs?scope=pool`** merges every online machine's scheduled jobs into one
+  view, each tagged with the machine that runs it — mirroring the proven
+  `sessions?scope=pool` / `attention?scope=pool` family: per-peer 5s timeout with a
+  `pool.failed[]` marker on a dark/offline peer (never a 500), a 3s short-TTL cache,
+  non-recursive peer calls. Plain `GET /jobs` is byte-for-byte unchanged.
+- **F8 placement-divergence detector** (observe-only, `pool.divergences[]`): flags a
+  machine that DECLARES jobs (N>0) but RUNS none of them locally — "config says jobs
+  here, this machine isn't running them." Derived honestly from each machine's own
+  `/jobs` reply; no fabricated counts; never gates. A machine with zero jobs is NOT
+  flagged (legitimate scheduler-less/dispatcher machine).
+- CLAUDE.md template + idempotent PostUpdateMigrator bullet (Agent Awareness +
+  Migration Parity).
+
+This is the READ half of WS4.3. The role-guard-at-spawn (refuse state-writing jobs on
+a read-only standby → re-route or attention) and the journal-lease claim cutover are
+SEPARATE follow-up slices. <!-- tracked: CMT-1416 -->
+
+## What to Tell Your User
+
+On a multi-machine setup, "what jobs are running where?" now answers across all your
+machines at once — each scheduled job tagged with the machine running it, a machine
+that's offline noted rather than dropped, and a heads-up if a machine is configured to
+run jobs but isn't actually running any.
+
+## Summary of New Capabilities
+
+- One pooled view of scheduled jobs across the fleet (`GET /jobs?scope=pool`),
+  machine-tagged, dark peers surfaced as `failed`, plus an observe-only placement-
+  divergence signal.
+
+## Evidence
+
+- `tests/integration/jobs-pool-scope.test.ts` (9, new): plain GET self-tags identity;
+  scope=pool merges a REAL peer server's jobs; offline peer → failed without waiting;
+  unreachable peer → failed, local still answers; no-peers → local-only; divergence
+  flags declares-N-runs-0; a zero-jobs peer is NOT flagged; scheduler-less shape.
+- `tests/unit/PostUpdateMigrator-jobsPoolScope.test.ts` (4, new): migration + template
+  parity, idempotent. `tsc --noEmit` clean. Existing jobs-endpoints-auth (15) +
+  guardian-jobs (11) + attention-pool-scope (7) all still green.

package/upgrades/side-effects/multi-machine-seamlessness-ws43-jobs-pool-read.md

@@ -0,0 +1,88 @@
+# Side-Effects Review — WS4.3 read-side: GET /jobs?scope=pool + divergence detector
+
+**Version / slug:** `multi-machine-seamlessness-ws43-jobs-pool-read`
+**Date:** `2026-06-12`
+**Author:** `Instar Agent (echo)`
+**Second-pass reviewer:** `workflow adversarial reviewer (CONCUR — 1 LOW fixed)`
+
+## Summary of the change
+
+The read-side of WS4.3 (MULTI-MACHINE-SEAMLESSNESS-SPEC §WS4.3): `GET /jobs?scope=pool`
+merges every online peer's jobs into one view (which machine runs each job),
+mirroring the proven `sessions?scope=pool` / WS4.1 `attention?scope=pool` family —
+per-peer 5s timeout, `pool.failed[]` markers (never a 500), offline-peer skip, 3s
+short-TTL cache, machine tagging. Plus an observe-only F8 placement-divergence
+detector. Files: `src/server/routes.ts` (route + `jobsPoolMerge` + `detectJobDivergences`),
+`src/scaffold/templates.ts` + `src/core/PostUpdateMigrator.ts` (Agent Awareness +
+Migration Parity). The role-guard-at-spawn and journal-lease cutover are SEPARATE
+follow-up slices (not in this PR). <!-- tracked: CMT-1416 -->
+
+## Decision-point inventory
+
+- `GET /jobs?scope=pool` merge — **add** — read-only aggregation; never mutates a
+  job, never gates; tolerant fan-out.
+- `detectJobDivergences` — **add** — observe-only signal in `pool.divergences[]`;
+  flags ONLY `declared>0 && running===0` (a machine that should run jobs but isn't).
+
+---
+
+## 1. Over-block
+No block/allow surface — read-only. The divergence detector after the LOW fix flags
+ONLY the real case (declares N>0, runs 0). A machine declaring 0 jobs is NOT flagged
+(was self-noise — fixed: a scheduler-less/dispatcher-only machine legitimately has none).
+
+## 2. Under-block
+Capacity carries no declared-job count, so divergence is derived from each machine's
+own `/jobs` reply (declared = jobs returned, running = `runsOnThisMachine===true`
+count). A machine that is DOWN (no reply) is in `pool.failed[]`, not `divergences` —
+so a fully-dark machine's jobs aren't flagged as "running 0" (correct; it's a
+reachability failure, surfaced separately). No fabricated counts.
+
+## 3. Level-of-abstraction fit
+Right layer — mirrors the sessions/attention pool-scope route code exactly (same
+fan-out/timeout/failed/cache/tag shape); the divergence helper is a pure function
+over the merged replies.
+
+## 4. Signal vs authority compliance
+Compliant — pure read + an observe-only signal. Gates nothing.
+
+## 5. Interactions
+- Plain `GET /jobs` is byte-for-byte unchanged (`{jobs,queue}`; no `pool` object, no
+  machine tags) — only `?scope=pool` adds them.
+- The cache key is fixed (`'jobs'`) and read/written only inside `jobsPoolMerge`;
+  there are no status/scope variants to cross-contaminate (stronger isolation than
+  attention's status-keyed cache).
+- Peers are called WITHOUT `scope` → no recursive fan-out storm.
+
+## 6. External surfaces
+- New query mode on an existing route; old callers (no `?scope=pool`) unaffected.
+- Calls each peer's `GET /jobs` with the agent bearer (same pattern as
+  sessions/attention pool scope). An old peer returns its local jobs → merges fine.
+
+## Framework generality
+No framework-launch abstraction touched (this is a read/merge route only; no change
+to `frameworkSessionLaunch.ts`). The job model is framework-agnostic; the merge tags
+machines, not frameworks. N/A beyond that.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+**proxied-on-read** — fans out to peers per request (cached 3s), each job tagged with
+its owning machine; consults the pool registry's online flag to skip dark peers
+cheaply. No replication, no durable cross-machine state in this slice. Phase-C clean:
+per-online-peer fan-out, O(jobs) divergence, no 2-peer assumption.
+
+## 8. Rollback cost
+Trivial: additive scope branch; reverting restores today's local-only `GET /jobs`.
+No durable state; the CLAUDE.md migrator bullet is idempotent (content-sniffed).
+
+---
+
+## Second-pass review
+
+Workflow adversarial reviewer: **CONCUR** (tscClean, testsPass; all 7 audit points
+verified incl. tolerant fan-out, back-compat, cache isolation, observe-only +
+no-fabricated-count divergence, non-recursive peers, awareness+migration parity,
+tests proven failing pre-change). One **LOW**: a scheduler-less/no-jobs machine
+self-flagged a "declares 0 jobs while online" divergence (self-noise). **FIXED**:
+the detector now flags ONLY `declared>0 && running===0`; the 0-jobs case is dropped
+(legitimate, not a divergence), and its test now asserts NO divergence for a
+zero-jobs peer.

package/upgrades/side-effects/topic-effort-pin.md

@@ -0,0 +1,117 @@
+# Side-Effects Review — per-topic effort pin (--effort at spawn)
+
+**Version / slug:** `topic-effort-pin`
+**Date:** `2026-06-12`
+**Author:** `Instar Agent (echo)`
+**Second-pass reviewer:** `workflow adversarial reviewer (CONCUR — 1 MEDIUM fixed, see below)`
+
+## Summary of the change
+
+Adds an optional `effort` field (enum `low|medium|high|xhigh|max`) to the
+topic-profile system, threaded through validation, store, resolver, write
+surface, change-classifier, orchestrator, conversational ingress, types, and the
+two routes; and injects `--effort <level>` into the Claude Code launch argv
+(interactive + headless builders in `frameworkSessionLaunch.ts`), resolved from
+the topic profile at spawn in `SessionManager`/`server.ts`. Mirrors `thinkingMode`'s
+plumbing. Operator request: Justin, topic 13481, "set ultracode for this topic"
+(ultracode is not a CLI value; this pins the CLI ceiling `max`).
+
+## Decision-point inventory
+
+- Topic-profile resolution — **modify** — adds an `effort` resolution arm
+  (pin > config-default > unset); off-enum value → fail-open `undefined`.
+- Launch argv builders — **modify** — push `--effort` for claude-code only when
+  set + enum-valid; non-claude untouched.
+- `classifyProfileChange` — **modify** — adds a dedicated effort-only row
+  (kill+resume, none-loss when resume-ready) so it is not misclassified as a
+  thinking change (the second-pass MEDIUM finding, now fixed).
+- Write surface / routes / ingress — **modify** — accept + validate `effort`.
+
+---
+
+## 1. Over-block
+Off-enum values are rejected at the write API (HTTP 400, profile unchanged) — that
+is the intended block. No legitimate input is rejected; the five CLI-valid levels
+all pass. `ultracode` is deliberately refused (not a CLI value).
+
+## 2. Under-block
+A value that is enum-valid but unsupported by the *running model* (e.g. `xhigh`
+on a model that floors to `high`) is passed through — the CLI itself floors it
+(documented behavior), so no instar-side block is needed. Headless one-shot/job
+spawns do NOT thread effort (interactive-only); acceptable — per-topic effort is
+a per-conversation pin, and the headless builder support is forward-looking
+defense-in-depth (flagged by the reviewer as a deliberate choice, not a bug).
+
+## 3. Level-of-abstraction fit
+Right layer: mirrors `thinkingMode` exactly across the same files; the resolver
+owns precedence, the launch builder owns argv, the classifier owns respawn
+semantics. No parallel machinery invented.
+
+## 4. Signal vs authority compliance
+N/A as a gate — this is a config field, not a decision point. The one authority-
+adjacent concern (a bad value reaching the CLI) is defended by three independent
+fail-open/validate layers.
+
+## 5. Interactions
+- Interacts with the `thinkingMode`→`--effort` mapping in the interactive builder:
+  a direct effort pin WINS and suppresses the thinkingMode-derived mapping, so
+  `--effort` is emitted exactly once (unit-tested).
+- The change-classifier effort row composes with model/tier/thinking rows: a
+  combined change is handled by those rows (their respawn carries the new flag);
+  only effort-only needed the new row.
+
+## 6. External surfaces
+- `GET /topic-profile/:id` gains `resolved.effort` + `sources.effort` (additive).
+- POST profile/propose accept `effort` (additive; off-enum → 400).
+- A spawned Claude session's argv gains `--effort <level>` when the topic pins it.
+  Old behavior (no pin) is byte-identical.
+
+## Framework generality
+
+The change DOES route through the framework abstraction (`frameworkSessionLaunch.ts`
+builders), and is **deliberately Claude-optimizing, not Claude-leaking**:
+
+- `--effort <low|medium|high|xhigh|max>` is a **Claude Code CLI flag**. Only the
+  `claudeCodeBuilder` (interactive) and `claudeCodeHeadlessBuilder` (headless) push
+  it. `InteractiveLaunchOptions.effort` / `HeadlessLaunchOptions.effort` are optional
+  inputs the non-Claude builders simply **ignore** — `codexCliBuilder`,
+  `geminiCliBuilder`, and `piCliBuilder` are untouched and emit no effort flag.
+- This is the "Framework-Agnostic — and Framework-Optimizing" standard satisfied:
+  the abstraction stays framework-agnostic (every builder receives the same options
+  object; none is forced to honor a flag it doesn't have), while Claude gets its
+  native knob. Codex/Gemini have their own reasoning/effort controls
+  (e.g. codex `-c model_reasoning_effort`); wiring those is explicitly OUT OF SCOPE
+  here and would be a separate per-framework mapping (a future `resolveEffortForFramework`
+  analogous to `resolveModelForFramework`), not a generalization of this Claude flag.
+- The topic-profile `effort` field itself is framework-agnostic (it's a profile
+  value); only its TRANSLATION to a launch flag is Claude-specific, which is the
+  correct layer for framework specificity (mirrors how `model` resolves per-framework
+  via `resolveModelForFramework`).
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+**proxied-on-read / machine-local-by-design.** The topic profile already resolves
+per-machine at spawn; effort rides the same path. When a topic transfers machines,
+its profile carrier (the existing topic-profile pull-at-acquire seam) carries
+`effort` along with the other fields (it's in `PROFILE_FIELDS`), so the pin
+follows the conversation. No new replication surface; no new URL/notice.
+
+## 8. Rollback cost
+Trivial: additive field, unset by default. Reverting the PR removes the field and
+the argv injection; no durable migration (the field simply stops being read). A
+stored `effort` on a profile file is ignored by older code (additive JSON).
+
+---
+
+## Second-pass review
+
+Workflow adversarial reviewer: **CONCUR** (tscClean, testsPass). Two findings:
+- **MEDIUM — effort half-wired in `classifyProfileChange`** (in AXES but no
+  branch → effort-only change fell through to the thinkingMode row, wrong reason
+  + wrong verification gate). **FIXED**: added a dedicated effort-only row
+  (kill+resume, none-loss when resume-ready; fresh recent-only otherwise) with an
+  effort-specific reason; +4 classifier unit tests asserting it resolves as
+  `resume`/none-loss, is NOT gated on the thinking flags, and the reason says
+  "effort change" not "thinking".
+- **LOW — headless builder has no live caller** (interactive-only data flow).
+  Acknowledged as a deliberate, documented forward-looking choice (per-topic
+  effort is a per-conversation interactive pin), not a bug (§2 above).