instar 1.3.212 → 1.3.214

package/src/templates/scripts/secret-drop-retrieve.mjs

@@ -25,6 +25,16 @@
  *     → opt into one-shot semantics (the submission is removed after read).
  *     Default is peek (non-destructive) per the 2026-05-20 hardening.
  *
+ *   node .instar/scripts/secret-drop-retrieve.mjs <token> <field> --run -- <cmd...>
+ *     → ATOMIC use-and-consume. Retrieves the field value, runs <cmd> with the
+ *     value piped to its stdin, and consumes the submission ONLY if <cmd> exits
+ *     0. On any non-zero exit the secret is left intact for retry. This makes it
+ *     structurally impossible to drop a secret on a failed handoff — the
+ *     2026-06-02 failure mode where a standalone `--consume` was fired after a
+ *     step that had not actually succeeded. Prefer this over a separate
+ *     retrieve-then-consume whenever the value feeds a single command.
+ *     Example: `... <token> github_token --run -- gh auth login --with-token`
+ *
  * Config:
  *   Reads `authToken` and `port` from `.instar/config.json` relative to cwd.
  *   `INSTAR_PORT` env var overrides the config port.
@@ -36,14 +46,31 @@
  */
 
 import * as fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
 
 const args = process.argv.slice(2);
 const token = args[0];
 const mode = args[1];
 const consume = args.includes('--consume');
 
-if (!token || !mode || mode === '--consume') {
-  process.stderr.write('usage: secret-drop-retrieve.mjs <token> <field-name|--names> [--consume]\n');
+// Atomic use-and-consume: `<token> <field> --run -- <cmd...>`. Everything after
+// the first `--` (which must follow `--run`) is the command to run with the
+// field value piped to its stdin. The submission is consumed only if the
+// command exits 0, so a failed handoff never destroys the secret.
+const runIdx = args.indexOf('--run');
+const runMode = runIdx !== -1;
+let runCmd = [];
+if (runMode) {
+  const sep = args.indexOf('--', runIdx + 1);
+  runCmd = sep !== -1 ? args.slice(sep + 1) : [];
+}
+
+if (!token || !mode || mode === '--consume' || mode === '--run') {
+  process.stderr.write('usage: secret-drop-retrieve.mjs <token> <field-name|--names> [--consume | --run -- <cmd...>]\n');
+  process.exit(2);
+}
+if (runMode && runCmd.length === 0) {
+  process.stderr.write('usage: --run requires a command after `--`, e.g. --run -- gh auth login --with-token\n');
   process.exit(2);
 }
 
@@ -127,6 +154,42 @@ if (typeof v !== 'string') {
   process.exit(1);
 }
 
+// Helper: consume the submission (idempotent best-effort). Used only after a
+// verified-successful handoff in --run mode.
+async function consumeSubmission() {
+  try {
+    await fetch(`http://localhost:${resolvedPort}/secrets/retrieve/${token}?consume=true`, {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${authToken}` },
+    });
+  } catch {
+    // Non-fatal — the sliding/absolute-cap cleanup will reclaim it regardless.
+  }
+}
+
+if (runMode) {
+  // Pipe the value into the command's stdin; never let it touch argv (process
+  // listings / shell history) or stdout (transcript). Inherit stdout/stderr so
+  // the operator sees the command's own (non-secret) output.
+  const child = spawnSync(runCmd[0], runCmd.slice(1), {
+    input: v,
+    stdio: ['pipe', 'inherit', 'inherit'],
+    encoding: 'utf-8',
+  });
+  if (child.error) {
+    process.stderr.write(`run: failed to launch '${runCmd[0]}': ${child.error.message} — secret NOT consumed (safe to retry)\n`);
+    process.exit(1);
+  }
+  const code = child.status ?? 1;
+  if (code === 0) {
+    await consumeSubmission();
+    process.stderr.write('run: command succeeded — secret consumed.\n');
+  } else {
+    process.stderr.write(`run: command exited ${code} — secret NOT consumed (safe to retry).\n`);
+  }
+  process.exit(code);
+}
+
 // Stream the value to stdout, no trailing newline so it pipes cleanly into
 // `gh secret set` or `bw unlock --raw`. process.stdout.write (not console.log)
 // — no extra newline, no trailing whitespace to confuse downstream consumers.

package/upgrades/1.3.213.md

@@ -0,0 +1,50 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A scheduled codex job (`codex exec --json`) can wedge: the process stays alive but
+makes no progress — 0% CPU, no output. One such job sat wedged ~12h undetected. The
+StaleSessionBackstop (which raises a "stale but unkillable" attention item, never
+kills) missed it because its forward-progress check used process **existence**:
+`hasActiveProcesses` walks descendant processes and returns true if any non-baseline
+child is alive — which a wedged-but-alive job is. So the backstop read it as
+"active" and never escalated. (Conversational claude sessions are saved by transcript
+growth, so only jobs — whose codex transcript doesn't resolve — were exposed.)
+
+The fix gives the backstop a real CPU signal: `SessionManager.descendantCpuSeconds`
+reads each non-baseline descendant's accumulated CPU time, and the backstop compares
+the delta across its two snapshots — real CPU *used* in the interval, not mere
+existence. This is scoped to **job sessions** (which have no legitimate-idle state):
+a job that uses no CPU between snapshots reads as no-progress and escalates.
+Conversational sessions keep the existing existence-based check, so a legitimately-idle
+session with a background process is *not* falsely flagged.
+
+## What to Tell Your User
+
+If one of my scheduled background jobs ever freezes — alive but doing nothing — I'll
+now actually notice it and flag it for attention, instead of mistaking "the process
+is still running" for "it's making progress." Before, a job could sit stuck for hours
+unseen; now a job that stops using any CPU gets surfaced. This only adds an
+attention notice — it never kills anything — and it doesn't change how I treat your
+normal interactive sessions.
+
+## Summary of New Capabilities
+
+- The stale-session backstop now detects a wedged-but-alive **job** (0% CPU, no
+  output) and raises its existing attention notice, where it previously read process
+  existence as "progress" and stayed silent.
+- New `SessionManager.descendantCpuSeconds` (accumulated CPU-seconds of a session's
+  real children) + `parseProcTimeToSeconds` — a CPU-delta progress signal.
+- Scoped to job sessions only; conversational sessions are unchanged (no new
+  false-positives on idle-with-a-background-process). Never kills — attention-only.
+
+## Evidence
+
+- 19 tests: `stale-session-backstop` (13 — incl. wedged-job→escalate, busy-job→no,
+  conversational-idle-with-bg→no-regression) + `parseProcTimeToSeconds` (6, covering
+  `MM:SS` / `MM:SS.ss` / `HH:MM:SS` / `DD-HH:MM:SS`). `tsc --noEmit` + `pnpm build` clean.
+- The escalation path is unchanged (still attention-only, never a kill); only the
+  forward-progress test gains a CPU-delta requirement for job sessions.

package/upgrades/1.3.214.md

@@ -0,0 +1,65 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Secret Drop's stored-submission lifetime was reworked so a submitted secret can no
+longer be deleted out from under an active consumer.
+
+- **Server (`SecretDrop.ts`)** — the post-submission store now uses a **sliding idle
+  window** instead of a fixed 5-minute timer. The cleanup timer re-arms on every
+  `peekReceived`, so a secret that is actively being retrieved never expires. The idle
+  window is 15 minutes (was 5) and a new per-token `receivedDeadline` enforces a hard
+  **30-minute absolute cap** (`armReceivedCleanup` clamps each re-arm with
+  `Math.min(idle, deadline − now)`), so even a continuously-polled secret is purged.
+  `consumeReceived`/`shutdown` clear the new deadline map; the stuck-consumer event's
+  `minutesUntilCleanup` is derived from the deadline.
+- **Consumer (`secret-drop-retrieve.mjs`)** — new `--run -- <cmd>` mode performs an
+  **atomic use-and-consume**: it pipes the field value to the command's stdin and
+  consumes the submission only if the command exits 0. A failed or launch-error
+  handoff never destroys the secret, making consume-on-failure structurally impossible.
+- **Awareness/migration** — the CLAUDE.md scaffold documents `--run` for new agents;
+  an idempotent `PostUpdateMigrator` block adds the guidance to existing agents that
+  already have the hardened helper. The helper script itself ships via the existing
+  always-overwrite relay-script refresh.
+
+## What to Tell Your User
+
+- **Secret Drop is now sturdier**: "If you hand me a password or key through a secure
+  link, it won't quietly expire while I'm in the middle of using it anymore — so you
+  shouldn't have to send the same thing twice. And if a step fails, I keep what you
+  sent so we can retry, instead of throwing it away." (Note: a secret still lives only
+  in memory, so a server restart still clears anything not yet used — that's the
+  security trade-off, unchanged.)
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Sliding retrieval window + 30-min cap | automatic |
+| Atomic use-and-consume | `secret-drop-retrieve.mjs TOKEN field --run -- <cmd>` |
+
+## Evidence
+
+**Reproduction (observed live, 2026-06-02):** during a multi-step credential handoff
+(Bitwarden login, then a GitHub token) the operator had to resubmit the same secret
+roughly six times. Each time, the submission sat in the store while a multi-step
+retrieval ran; the fixed 5-minute timer deleted it mid-flow regardless of the active
+retrievals, and a standalone consume fired after a step that had not yet succeeded —
+destroying the secret with no recovery but resubmission.
+
+**Before/after (deterministic, fake-timer unit tests in
+`tests/unit/SecretDrop.test.ts`):**
+- Before this change, a submission was unconditionally deleted 5 minutes after
+  submit. After it: a submission peeked at 14 min and again at 28 min is still present
+  (the window slid on each read); an untouched submission is still cleaned up after the
+  idle window; and a submission polled every 10 min is nonetheless purged once past the
+  30-min absolute cap.
+- `--run` mode: consume is invoked only on child exit 0; on non-zero exit or a launch
+  error the submission is left intact (verified by inspecting the spawnSync branch and
+  the documented `gh auth login --with-token` example).
+
+Suites: SecretDrop 37/37, migration 15/15 green; `tsc --noEmit` clean. An independent
+second-pass reviewer concurred with the side-effects review.

package/upgrades/side-effects/codex-wedged-job-cpu-detection.md

@@ -0,0 +1,118 @@
+# Side-Effects Review — Codex wedged-job CPU-stall detection
+
+**Version / slug:** `codex-wedged-job-cpu-detection`
+**Date:** `2026-06-03`
+**Author:** `Echo`
+**Second-pass reviewer:** `Echo (self) — Tier-1; the regression analysis below is the load-bearing part`
+
+## Summary of the change
+
+StaleSessionBackstop's `hasForwardProgress` gains a CPU-delta progress signal for
+**job sessions**, replacing the existence-based `mainProcessActive` check for them.
+A wedged-but-alive codex job (0% CPU) now reads as no-progress and triggers the
+existing attention escalation (never a kill). Files: `SessionManager.ts`
+(`descendantCpuSeconds` + `parseProcTimeToSeconds`), `StaleSessionBackstop.ts`
+(ProgressSnapshot fields `descendantCpuSeconds`/`isJobSession`, the job-scoped
+`hasForwardProgress` branch, `cpuFloorSeconds` option), `server.ts` (snapshot
+populates the two fields). The only decision point: *is this session making forward
+progress* — and the change narrows what counts as progress for jobs.
+
+## Decision-point inventory
+
+- `StaleSessionBackstop.hasForwardProgress` (ii) — modify — for job sessions, require
+  cpu-seconds delta > floor instead of process existence.
+- No message block/allow surface. No kill/terminate surface (the backstop has none —
+  asserted by an existing structural test).
+
+## 1. Over-block
+
+No block/allow surface. The analogue ("does it raise a false attention notice?") is
+THE risk and is handled by scoping: the stricter cpu-delta test applies ONLY to job
+sessions (`!!session.jobSlug`). A conversational session that's legitimately idle
+with a background process keeps the existence-based check → not flagged. Verified by
+the `conversational-idle-with-bg → no` test.
+
+## 2. Under-block
+
+A job that uses *some* CPU between two 120s snapshots (above `cpuFloorSeconds=1`) is
+treated as progressing — so a job that's busy-looping (high CPU, no real output)
+would not be flagged by this signal. That's acceptable: this targets the 0%-CPU
+freeze; a CPU-burning runaway is a different detector's concern (and would show on
+load). I/O-bound jobs at 0% CPU with no output would be flagged — but a job has no
+legitimate long idle-wait state (it runs to completion), so flagging it for attention
+(not killing) is correct.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. This is a cheap, deterministic process-metric read feeding an existing
+attention-raising backstop. It reuses `hasActiveProcesses`'s exact descendant
+tree-walk + baseline filter, adding only the CPU-time accumulation. No LLM needed —
+the signal is objective (CPU seconds), and the escalation it feeds is attention-only.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no message block/allow surface.
+
+It refines a SIGNAL (forward-progress) consumed by an existing smart-ish gate
+(the backstop's episode state machine), which only ever raises an attention item and
+never kills. No new authority.
+
+## 5. Interactions
+
+- **Shadowing:** The change is inside `hasForwardProgress`, one branch (ii). Branches
+  (i) transcript-growth and (iii) idle-token-change are unchanged and still short-
+  circuit to "progress" first, so a job that IS producing output/transcript is still
+  exempt before the CPU test is consulted.
+- **Double-fire:** None — same single escalation path, same per-episode dedup
+  (`episodeActive`), so a persistently-wedged job still raises exactly one item.
+- **Races:** `descendantCpuSeconds` is a synchronous `ps` read per snapshot, same
+  cadence/shape as the existing `hasActiveProcesses` call; no shared mutable state.
+- **Feedback loops:** None — the output is an attention notice, which does not feed
+  back into the session.
+
+## 6. External surfaces
+
+- **Persistent state:** none new. ProgressSnapshot lives in memory per tick.
+- **External systems:** none (the attention item uses the existing poster).
+- **Other agents/users:** none — per-agent backstop.
+- **`ps` cost:** one extra `ps -eo pid,ppid,time,command` per session per 120s tick —
+  negligible, same class as the existing `hasActiveProcesses` `ps`.
+- **Cross-platform:** `parseProcTimeToSeconds` handles the `ps -o time` formats
+  (`MM:SS`, `MM:SS.ss`, `HH:MM:SS`, `DD-HH:MM:SS`); a bad parse reads as 0 (no growth),
+  which is safe (the delta just shows no progress; attention, never kill).
+
+## 7. Rollback cost
+
+Pure code change; no persistent state, no migration. Back-out is `git revert` + ship
+the next patch — the backstop reverts to existence-based progress (the prior, looser
+behavior). No user-visible regression during rollback (it only changes whether a
+*job* gets a stale-attention notice). Worst case if the floor is mis-tuned: a busy
+job flagged spuriously (attention only) or a wedged job missed — both are
+attention-level, never destructive.
+
+## Conclusion
+
+The review's central risk — falsely flagging legitimately-idle sessions — is closed
+by scoping the cpu-delta requirement to job sessions (no legitimate-idle state) and
+leaving conversational sessions on the existing existence check. That scoping is the
+load-bearing design decision and is directly tested. The escalation remains
+attention-only (never a kill), and the change reuses the existing process-walk. Clear
+to ship.
+
+## Second-pass review (if required)
+
+**Reviewer:** Echo (self) — Tier-1.
+**Independent read of the artifact: concur**
+
+The job-scoping is the right way to avoid the idle-with-bg false-positive; the three
+behavior tests pin both the fix and the no-regression case; rollback is a revert.
+No concerns.
+
+## Evidence pointers
+
+- `tests/unit/stale-session-backstop.test.ts` (13: incl. the 3 new behavior cases),
+  `tests/unit/parseProcTimeToSeconds.test.ts` (6). `tsc` + `pnpm build` clean.
+- Root-cause + design trail: `.instar/autonomous/13435.local.md` item 2 (the iterative
+  diagnosis that caught the idle-with-bg / extended-think regression traps).

package/upgrades/side-effects/secret-drop-sliding-window.md

@@ -0,0 +1,83 @@
+# Side-effects review — Secret Drop Sliding Window + Atomic Use-and-Consume
+
+**Spec:** `docs/specs/secret-drop-sliding-window.md`
+**Files:** `src/server/SecretDrop.ts`, `src/templates/scripts/secret-drop-retrieve.mjs`, `tests/unit/SecretDrop.test.ts`, `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts`, `src/core/PostUpdateMigrator.ts`, `src/scaffold/templates.ts`
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+Nothing new is rejected. Submission validation (CSRF, required fields, R1a signature)
+is unchanged. The sliding window only affects how long an accepted submission is
+*retained*; it never rejects a submission or a retrieve. `--run` adds a code path but
+the default retrieve/`--names`/`--consume` behaviors are byte-for-byte unchanged.
+
+## 2. Under-block — what failure modes does this still miss?
+
+- **Server restart loses an unconsumed secret.** Explicitly out of scope (in-memory by
+  design); contract documented in the spec; encrypted-at-rest tracked as follow-up
+  (`fb-391a4a30-de9`).
+- **An agent that uses the destructive `consumeReceived`/`--consume` mid-flow can still
+  drop a secret.** The `--run` mode + CLAUDE.md guidance steer away from this, but the
+  standalone `--consume` is retained for back-compat and is still misusable. Mitigated,
+  not eliminated. Accepted: removing `--consume` outright would be a breaking change to
+  any caller already using it.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. Lifetime management belongs in `SecretDrop` (it owns the store and the
+timers). The atomic use-and-consume belongs in the consumer helper (it owns the
+hand-off to the command). No higher/lower layer is a better owner, and no smarter gate
+exists that this should feed instead.
+
+## 4. Signal vs authority compliance
+
+Compliant. This adds no decision point that gates information flow or blocks actions.
+The `--run` "consume only on exit 0" is a success gate on a local subprocess, not an
+authority over agent behavior. No brittle-check-with-blocking-authority is introduced.
+(Ref: `docs/signal-vs-authority.md`.)
+
+## 5. Interactions
+
+- **Stuck-consumer timer:** still fires at 60s; `minutesUntilCleanup` now derives from
+  `receivedDeadline` (true purge time) — more accurate, not less. The stuck timer is
+  NOT re-armed on peek (deliberate: it's a "nobody has consumed this yet" nudge, and
+  the absolute deadline it reports is fixed at submit). No double-fire, no race.
+- **Cleanup timer:** centralized in `armReceivedCleanup`; each re-arm clears the prior
+  timer first (no timer leak). `consumeReceived`/`shutdown` clear the timer, the stuck
+  timer, AND the new `receivedDeadline` map (no map leak).
+- **`--consume` flag and `--run`:** mutually independent; `--run` consumes via the same
+  `?consume=true` endpoint after success. No shadowing.
+
+## 6. External surfaces
+
+- **Other agents:** the helper template change reaches every agent via the
+  always-overwrite relay-script refresh; the server change ships via npm. CLAUDE.md
+  awareness reaches new agents (scaffold) and existing agents (idempotent migrator
+  block, tested). No external API shape change — `/secrets/retrieve/:token` and
+  `?consume=true` are unchanged.
+- **Timing/runtime dependence:** the window is wall-clock based (setTimeout); fake-timer
+  tests cover the boundaries deterministically. No dependence on conversation state.
+
+## 7. Rollback cost
+
+Pure code revert — no data migration, no agent-state repair. Reverting restores the
+fixed 5-min window and removes `--run`; the standalone `--consume` path is untouched
+throughout, so nothing depends on the new behavior to function. The migrator block is
+idempotent and additive (a revert simply stops adding the bullet; already-migrated
+CLAUDE.md files keep a harmless accurate bullet).
+
+## Tier
+
+**Tier 2.** Risk floor 2 (safety-invariant proximity: SecretDrop / never-on-disk).
+Declared at the floor — not below it. Full ceremony: converged + approved spec, ELI16,
+this artifact, second-pass review, trace.
+
+## Second-pass review (independent)
+
+An independent reviewer audited this artifact against the code and verified each
+claim: (1) no timer/`receivedDeadline` map leak — every add has a matching clear on
+consume/shutdown/re-arm; (2) the sliding window cannot exceed the 30-min cap (the
+`Math.min(IDLE, deadline−now)` clamp enforces it); (3) `--run` consumes only on exit
+0, never on launch error or non-zero exit, and the value reaches the subprocess via
+stdin only — never stdout/argv; (4) signal-vs-authority compliant (no brittle gate
+with blocking authority); (5) the stuck-consumer timer is correctly NOT re-armed on
+peek. **Verdict: "Concur with the review."**