instar 1.3.199 → 1.3.201

package/upgrades/1.3.200.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Your agent can now answer "how long have I been running, and how much time is left?" instead of guessing.
+
+For any active time-boxed (autonomous) session, a new read-only endpoint computes elapsed + remaining from the session's durable record. This is Step 1 of a fix for a real problem where an agent in a long autonomous run lost track of time and wound down far too early. (Step 2 — injecting that clock into every turn automatically — follows.)
+
+## What to Tell Your User
+
+Nothing to configure. If you run timed autonomous sessions, your agent can now check its own elapsed/remaining time accurately (and you can see it too). A normal short chat is unaffected — the clock only appears when there's actually a timed session to report on.
+
+## Summary of New Capabilities
+
+- New read-only `GET /session/clock` (optional `?topic=N`) returns, for each active time-boxed session, `{ label, kind, startedAt, endsAt, elapsedSeconds, remainingSeconds, elapsedHuman, remainingHuman, percentElapsed, status }`. Bearer-gated; `{ sessions: [] }` when nothing is time-boxed; per-machine.
+- The clock is computed by a pure `SessionClock` module (clock-skew-clamped, never negative). The session's task text is sanitized + length-capped into a `label` before it's ever surfaced — the raw goal is never exposed (prompt-injection + leak safety).
+- CLAUDE.md gains a "Session Clock" awareness entry (proactive trigger: quote the real numbers before reporting progress or deciding a session is done) — delivered to existing agents via migration.
+
+## Evidence
+
+- All three test tiers green: 20 unit (`SessionClock` 14 + `SessionClockReader` 6), 4 integration (`session-clock-route`), 4 E2E (`session-clock-lifecycle`, real AgentServer boot — alive 200 not 503, Bearer-required, read-only, leak-bound). No regressions (AutonomousSessions 13, migrateClaudeMd 3). `tsc --noEmit` clean.
+- Spec: `docs/specs/ROBUST-SESSION-TIME-AWARENESS-SPEC.md` (converged 3 rounds, approved). Side-effects: `upgrades/side-effects/session-clock-step1.md`.

package/upgrades/1.3.201.md

@@ -0,0 +1,46 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Ships the shared routine that renders your session clock, and installs it on every agent.
+
+Step 1 added the `/session/clock` endpoint (how long have I been running / how much is left). This adds `emit-session-clock.sh` — the small routine that turns that into a one-line "⏱ SESSION CLOCK: Nh elapsed · Mh remaining (NN%)" string. It has a render mode (format already-computed values) and a query mode (ask the endpoint). The hooks that call it on every turn land next (tracked in issue #682).
+
+Your autonomous agent now sees how much of its time window is left — on every turn.
+
+This is the fix for the failure where an agent in a long autonomous run wound down far too early because it had lost track of time. The autonomous stop-hook now feeds back a rich `⏱ SESSION CLOCK: Nh elapsed · Mh remaining (NN%)` line on every continuation, rendered from the hook's own elapsed/remaining numbers, so the agent always knows where it is in the window before deciding anything.
+
+The session clock now shows on your own messages too, not just autonomous turns.
+
+Step 2b wired the clock into autonomous continuations; this wires the second site: when you message the agent, the UserPromptSubmit hook now also surfaces "⏱ SESSION CLOCK: Nh elapsed · Mh remaining (NN%)" if a time-boxed session is active. Both call sites of the shared routine (render + query) are now live — completing the per-turn, every-turn time awareness.
+
+## What to Tell Your User
+
+Nothing to do. This is plumbing for the time-awareness feature — a small script that gets installed automatically. You'll see its effect once the per-turn hooks are wired (next step): your agent will quote real elapsed/remaining time instead of guessing.
+
+Nothing to do. If you run timed autonomous sessions, the agent will now quote accurate elapsed/remaining time as it works instead of guessing — and won't conclude a session is "done" with hours left. Existing agents get the updated hook automatically on update.
+
+Nothing to do. If a timed session is running, your agent now sees its elapsed/remaining time on your turns too, so "how far along are we?" always has a real answer.
+
+## Summary of New Capabilities
+
+- New `.instar/scripts/emit-session-clock.sh` — renders the SESSION CLOCK line. `render` mode formats values the caller already computed (no re-resolution); `query` mode curls `GET /session/clock`. Signal-only (pure stdout, never blocks), and only ever echoes the already-sanitized label, never a raw goal.
+- Installed on new agents (init) and existing agents (always-overwrite migration), so the whole fleet has the routine ready for the per-turn wiring.
+
+- The autonomous stop-hook injects a SESSION CLOCK line into every blocked continuation, rendered by `emit-session-clock.sh` from the hook's own computed numbers (no re-resolution → it can never disagree with the hook's own duration-expiry check). Additive and fail-safe: unbounded runs or a missing script simply omit the segment.
+- Delivered to existing agents via the autonomous-skill re-deploy migration (marker bumped to `CLOCK_SEG`); customized hooks are left untouched.
+
+- `telegram-topic-context.sh` (built-in UserPromptSubmit hook) now calls `emit-session-clock.sh query` after resolving port/auth/topic, surfacing the SESSION CLOCK line on user turns. Signal-only; emits nothing when no time-boxed session is active or the server is unreachable. Delivered to existing agents via the always-overwrite built-in-hook migration.
+
+## Evidence
+
+- 7 golden tests (render/percent/clamp/formatting/unbounded/query-unreachable/no-op) + 3 migration tests (installs, always-overwrite, executable) green; secret-drop migration regression (13) green; `tsc --noEmit` clean.
+- Spec: `docs/specs/ROBUST-SESSION-TIME-AWARENESS-SPEC.md` (Component 2). Side-effects: `upgrades/side-effects/session-clock-step2a.md`. Call-site wiring: #682.
+
+- Functional wiring test (`autonomous-stop-hook-session-clock.test.ts`): a blocked continuation of a timed run feeds back the SESSION CLOCK line (runs the real hook); fail-safe path with the script absent verified. `bash -n` clean; autonomous-stop-hook regression suites (P13/completion/topic-keyed, 23) green; `tsc --noEmit` clean.
+- Spec: `docs/specs/ROBUST-SESSION-TIME-AWARENESS-SPEC.md` (Component 2). Side-effects: `upgrades/side-effects/session-clock-step2b.md`. The user-turn injection site: #682.
+
+- `telegram-topic-context-session-clock.test.ts` (2): generated hook carries the query call + passes `bash -n` (escaping guard). Regression (12) green; lint clean. Spec: Component 2.

package/upgrades/side-effects/session-clock-step1.md

@@ -0,0 +1,52 @@
+# Side-Effects Review — Session Clock Step 1 (SessionClock + GET /session/clock)
+
+**Slug:** `session-clock-step1`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Tier:** 2 (driven by the converged + approved spec `ROBUST-SESSION-TIME-AWARENESS-SPEC.md`)
+**Spec:** `docs/specs/ROBUST-SESSION-TIME-AWARENESS-SPEC.md` (review-convergence iteration 3, approved)
+
+## Summary of the change
+
+Step 1 of the time-awareness fix: the compute + query surface.
+- `src/core/SessionClock.ts` — pure tier0 module: `computeSessionClock(input, nowMs)` (elapsed/remaining with clock-skew clamping + the status matrix), `deriveLabel(goal)` (the sanitized, cap-80, control-char/angle-bracket-stripped label that is the ONLY task text ever injected/served), `humanizeDuration`.
+- `src/core/SessionClockReader.ts` — read-only I/O layer: maps ACTIVE autonomous-state records → computed clocks, with optional topic binding. Reuses `AutonomousSessions.activeAutonomousJobs()`.
+- `src/core/AutonomousSessions.ts` — `AutonomousJobSummary` gains `durationSeconds` (parsed from the existing `duration_seconds` front-matter field). Additive.
+- `src/server/routes.ts` — new read-only `GET /session/clock` (optional `?topic=N`). Bearer-gated (inherits app-wide auth). Leak-bounded: returns the computed clock + sanitized `label` only, never the raw `goal`.
+- `src/scaffold/templates.ts` + `src/core/PostUpdateMigrator.ts` — CLAUDE.md "Session Clock" awareness (template for new agents; content-sniffed `migrateClaudeMd` block for existing agents).
+
+## Decision-point inventory
+- route exposure: read vs write → read-only (GET only; POST → 404). No gate, no mutation.
+- label: inject raw goal vs derived → derived + sanitized + capped. The raw goal never leaves the record.
+- record field: `end_at` vs `started_at`+`duration_seconds` → the latter (canonical, matches the stop-hook + setup-autonomous.sh schema); `endsAt` is derived.
+
+## 1. Over-correction risk
+None — purely additive observability. No existing behavior changes. A healthy agent with no time-boxed record gets `{ sessions: [] }`.
+
+## 2. Under-correction risk
+Step 1 is the QUERY surface only; the per-turn INJECTION (the higher-impact fix for the incident) is Step 2 (emit-session-clock.sh + hooks), a separate PR. Documented in the spec sequencing.
+
+## 3. Level-of-abstraction fit
+Compute is pure (SessionClock.ts, no I/O, fully unit-tested both sides of every boundary); I/O is isolated (SessionClockReader.ts); the route is a thin reader. The record-enumeration reuses the existing AutonomousSessions module rather than duplicating frontmatter parsing.
+
+## 4. Signal vs Authority
+Tier0, deterministic, no LLM, no gate. Pure computation + a read route. Appropriate.
+
+## 5. External surfaces
+One new read-only HTTP route (`GET /session/clock`), Bearer-gated like `/tokens/summary`. **Leak-bound:** the response carries the sanitized `label` only — never the raw `goal`/task text (verified by integration + E2E assertions). No config/schema change.
+
+## 6. Interactions with existing primitives
+`AutonomousJobSummary.durationSeconds` is additive (existing consumers unaffected — AutonomousSessions unit tests still green). The route composes with the existing auth middleware. No change to the autonomous-state writer or the stop-hook.
+
+## 7. Rollback cost
+Trivial: remove the route + the two new modules + the additive `durationSeconds` field + the CLAUDE.md block. No persistent state, no migration of data.
+
+## Migration parity
+- New agents: the route ships in code; the CLAUDE.md template carries the awareness.
+- Existing agents: the route reaches them on the normal dist update (code); `migrateClaudeMd` content-sniffs `/session/clock` and appends the awareness block (idempotent).
+
+## Tests (all three tiers)
+- Unit: `SessionClock` (14 — full status matrix, clock-skew clamp, label derivation/sanitization incl. `<promise>`-token stripping + cap-80) + `SessionClockReader` (6 — record parsing, topic binding, goal→label end-to-end, missing dir).
+- Integration: `session-clock-route` (4 — 200 with computed fields, `{sessions:[]}` when none, topic filter, leak-bound: raw goal never in the response).
+- E2E: `session-clock-lifecycle` (4 — real AgentServer boot, route alive 200 not 503, leak-bound, Bearer required, read-only POST→404).
+- No regressions: AutonomousSessions (13) + migrateClaudeMd (3) still green; `tsc --noEmit` clean.

package/upgrades/side-effects/session-clock-step2a.md

@@ -0,0 +1,52 @@
+# Side-Effects Review — Session Clock Step 2a (emit-session-clock.sh shared routine + delivery)
+
+**Slug:** `session-clock-step2a`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Tier:** 2 (driven by the converged + approved `ROBUST-SESSION-TIME-AWARENESS-SPEC.md`)
+**Spec:** `docs/specs/ROBUST-SESSION-TIME-AWARENESS-SPEC.md` (Component 2 — the shared routine)
+
+## Summary of the change
+
+Ships the **shared time-awareness routine** and its delivery to every agent. Step 1 (merged #683) added the compute + `/session/clock` query surface; this adds the bash routine that formats the SESSION CLOCK line, plus install-everywhere. Its call sites (the two hooks) are the next sequenced step, tracked in #682.
+
+- `src/templates/scripts/emit-session-clock.sh` — the routine (a real template file, like `telegram-reply.sh`/`secret-drop-retrieve.mjs`; NOT an inline TS string, so no escaping risk). Two modes:
+  - **render** `<startedISO> <durationSec> <elapsedSec> <remainingSec> <label>` — formats ONE SESSION CLOCK line from values the caller already computed (no re-resolution → can never disagree with the caller's own clock).
+  - **query** `<topic> <port> <auth>` — curls `GET /session/clock` and formats the first active session; prints nothing if none / server unreachable.
+- `src/core/PostUpdateMigrator.ts` — `migrateScripts` installs it to `.instar/scripts/` always-overwrite (existing agents, mirrors the secret-drop-retrieve.mjs block).
+- `src/commands/init.ts` — `installEmitSessionClock` installs it at scaffold time (new agents).
+
+## Decision-point inventory
+- install policy: install-if-missing vs always-overwrite → always-overwrite (new, non-user-customizable shared routine; must stay current). Custom forks live elsewhere and are untouched.
+- routine value source: render (caller's numbers) vs re-resolve → render uses the caller's already-computed values (no double-resolution; adversarial round-2 fix in the spec).
+
+## 1. Over-correction risk
+None — purely additive. The routine is a standalone script; until a hook calls it (the next step, #682), it has zero runtime effect. Installing it changes no behavior.
+
+## 2. Under-correction risk
+The routine is shipped + delivered + tested but its call sites (the two hooks) land with #682; that is the sequenced wiring step. The routine is complete and independently testable.
+
+## 3. Level-of-abstraction fit
+A single shared routine both call sites will use; render math lives in it, the compute-of-record stays in `SessionClock.compute()` (TS). The bash routine only formats.
+
+## 4. Signal vs Authority
+Tier0, signal-only: pure stdout, never blocks, never mutates. Appropriate.
+
+## 5. External surfaces
+None new. query mode calls the existing Bearer-gated `/session/clock`. The routine echoes only the already-sanitized `label` the route/caller supplies (never a raw goal).
+
+## 6. Interactions with existing primitives
+The `migrateScripts` addition mirrors the secret-drop-retrieve.mjs install exactly (verified: that test suite stays green). No change to existing scripts/hooks.
+
+## 7. Rollback cost
+Trivial: remove the script + the two install calls. No state, no data migration.
+
+## Migration parity
+- New agents: `installEmitSessionClock` (init.ts).
+- Existing agents: `migrateScripts` always-overwrite install on the normal dist update.
+- Both verified by tests.
+
+## Tests
+- Unit/golden (`emit-session-clock.test.ts`, 7): render formats elapsed/remaining/percent; omits the remaining clause when unbounded; clamps negative elapsed to 0s; minutes/seconds formatting; no-label; query-unreachable → empty exit 0; unknown mode → no-op.
+- Migration (`PostUpdateMigrator-emitSessionClock.test.ts`, 3): migrateScripts installs the script, always-overwrite (restores a stale copy, idempotent), mode 0o755.
+- Regression: secret-drop migration (13) stays green; `tsc --noEmit` clean.

package/upgrades/side-effects/session-clock-step2b.md

@@ -0,0 +1,49 @@
+# Side-Effects Review — Session Clock Step 2b (autonomous-continuation injection)
+
+**Slug:** `session-clock-step2b`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Tier:** 2 (converged+approved `ROBUST-SESSION-TIME-AWARENESS-SPEC.md`)
+**Spec:** `docs/specs/ROBUST-SESSION-TIME-AWARENESS-SPEC.md` (Component 2 — the stop-hook render call site)
+
+## Summary of the change
+
+Wires the time-awareness injection into the **autonomous stop-hook** — the actual fix for the wind-down-early incident. On every blocked continuation of a time-boxed run, the hook now feeds back a rich `⏱ SESSION CLOCK: Nh elapsed · Mh remaining (NN%)` line so the autonomous agent always SEES how much of its window remains.
+
+- `.claude/skills/autonomous/hooks/autonomous-stop-hook.sh`: after the existing `(${REMAINING_MIN}m remaining)` slot (kept untouched), an additive `${CLOCK_SEG}` segment is rendered by `emit-session-clock.sh render` **from the hook's OWN already-computed `STARTED_AT`/`DURATION_SECONDS`/`ELAPSED`/`REMAINING`** — no re-resolution, so the injected clock can never disagree with the hook's own duration-expiry verdict (adversarial round-2 concern). Fail-safe: if the script is absent or the run is unbounded (no `ELAPSED`), the segment is simply omitted.
+- `src/core/PostUpdateMigrator.ts`: the existing `migrateAutonomousStopHookTopicKeyed` marker is bumped `p13_stop_allowed → CLOCK_SEG`, re-deploying the wired hook to existing agents (Migration Parity; customized hooks with no stock fingerprint untouched).
+
+The query-mode call site (user-turn injection via `telegram-topic-context.sh`) is the second, separate injection site, tracked in #682; the routine's query mode is shipped + tested and ready for it.
+
+## Decision-point inventory
+- placement: enrich the `(...)` slot vs add a segment → add a separate `${CLOCK_SEG}` segment (the existing slot is untouched = lowest risk).
+- value source: render from the hook's own numbers vs re-resolve → render (no double-resolution).
+
+## 1. Over-correction risk
+None — additive. The existing `(${REMAINING_MIN}m remaining)` slot and the expiry logic are unchanged; only an extra informational segment is appended.
+
+## 2. Under-correction risk
+The user-turn (query-mode) site is the separate injection point tracked in #682; this change covers the autonomous-continuation site, which is the incident's actual failure mode.
+
+## 3. Level-of-abstraction fit
+The hook calls the single shared `emit-session-clock.sh render`; the format lives there, the numbers come from the hook. No duplication.
+
+## 4. Signal vs Authority
+Signal-only: the injected line is informational; it never changes the block/exit decision (which is the unchanged expiry logic).
+
+## 5. External surfaces
+None. The hook reads the locally-installed script; nothing new is exposed.
+
+## 6. Interactions with existing primitives
+Reuses the established `migrateAutonomousStopHookTopicKeyed` re-deploy mechanism (marker bump) and the hook's own computed values. `bash -n` clean; the existing autonomous-stop-hook tests (P13, completion-condition, topic-keyed) stay green.
+
+## 7. Rollback cost
+Trivial: remove the `CLOCK_SEG` block + the two `${CLOCK_SEG}` insertions + revert the marker. No state.
+
+## Migration parity
+- New agents: `installBuiltinSkills`/`init` ship the wired hook.
+- Existing agents: `migrateAutonomousStopHookTopicKeyed` (marker `CLOCK_SEG`) re-deploys the wired hook on update; customized hooks untouched.
+
+## Tests
+- `autonomous-stop-hook-session-clock.test.ts` (2): a blocked continuation of a timed run feeds back the SESSION CLOCK line (functional, runs the real hook with the installed script); fail-safe with the script absent (continuation still fires, segment omitted).
+- Regression: `bash -n` clean; PostUpdateMigrator-autonomousStopHook (8), autonomous-completion-condition + evaluate-stop (15) green; `tsc --noEmit` clean.

package/upgrades/side-effects/session-clock-step2c.md

@@ -0,0 +1,32 @@
+# Side-Effects Review — Session Clock Step 2c (user-turn query injection)
+
+**Slug:** `session-clock-step2c` · **Date:** `2026-06-02` · **Author:** `echo` · **Tier:** 2
+**Spec:** `docs/specs/ROBUST-SESSION-TIME-AWARENESS-SPEC.md` (Component 2 — the query call site)
+
+## Summary
+Completes the time-awareness injection's SECOND call site: the `telegram-topic-context.sh`
+UserPromptSubmit hook now, after resolving PORT + AUTH_TOKEN + TOPIC_ID, calls
+`emit-session-clock.sh query` so the SESSION CLOCK line surfaces on the user's OWN turns too
+(not just autonomous continuations). With Step 2b (the stop-hook render site), both call sites
+of Component 2 are now wired — the routine's render AND query modes are both consumed.
+
+- `src/core/PostUpdateMigrator.ts` `getTelegramTopicContextHook()`: an additive query call after
+  the existing CURRENT TIME block + AUTH resolution. Signal-only: emits nothing when no time-boxed
+  session is active or the server is unreachable. Guarded on the script existing.
+
+## 1-7 (brief)
+Over/under-correction: additive; the CURRENT TIME block + history fetch are unchanged; emits only
+when a clock exists. Abstraction: reuses the shared routine. Signal vs Authority: pure stdout, no
+gate. External surfaces: calls the existing Bearer-gated `/session/clock`; only the already-sanitized
+label is surfaced. Interactions: composes with the hook's existing AUTH/PORT/TOPIC resolution.
+Rollback: remove the ~3-line block.
+
+## Migration parity
+`telegram-topic-context.sh` is a BUILT-IN `instar/` hook → always-overwritten on every migration
+(migrateHooks), so existing agents receive the query injection automatically. No new migration needed.
+
+## Tests
+`telegram-topic-context-session-clock.test.ts` (2): the generated hook contains the
+`query "$TOPIC_ID" "$PORT" "$AUTH_TOKEN"` call AND is syntactically valid bash (`bash -n` — guards
+the TS-template escaping). Regression: migration-parity-hooks + neutralRelayPath + emit-session-clock
+migration (12) green; `npm run lint` (tsc + custom linters) clean.