instar 1.3.200 → 1.3.201

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.200",
+  "version": "1.3.201",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,9 +1,9 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-02T07:00:19.416Z",
-  "instarVersion": "1.3.200",
-  "entryCount": 193,
+  "generatedAt": "2026-06-02T07:52:52.700Z",
+  "instarVersion": "1.3.201",
+  "entryCount": 194,
   "entries": {
     "hook:session-start": {
       "id": "hook:session-start",
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1092,6 +1092,14 @@
       "contentHash": "b0475554bde6729d2d9a1f8005dcada6a8e4c767203d8293c09a212f9bf0a196",
       "since": "2025-01-01"
     },
+    "template:emit-session-clock.sh": {
+      "id": "template:emit-session-clock.sh",
+      "type": "template",
+      "domain": "operations",
+      "sourcePath": "src/templates/scripts/emit-session-clock.sh",
+      "contentHash": "c83cff5728bef544c20ca4a8bce432981175161a4ac2272e112edc612949806d",
+      "since": "2025-01-01"
+    },
     "template:git-sync-gate.sh": {
       "id": "template:git-sync-gate.sh",
       "type": "template",
@@ -1489,7 +1497,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "b180f4f8bc074315fa049333883cb6defef23774007b7165a0aec6cae9be67f4",
+      "contentHash": "e8270e118c93a86da1982ba20f6432a566e59f6ae77c3e04c05d81fb3d79b386",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/templates/scripts/emit-session-clock.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# emit-session-clock.sh — render the SESSION CLOCK line for an active time-boxed
+# session, so an agent always sees how much of a timed run remains and never
+# winds down early. Signal-only: pure stdout, never blocks.
+#
+# Spec: docs/specs/ROBUST-SESSION-TIME-AWARENESS-SPEC.md (Component 2). The math
+# of record (clock-skew clamping, status) lives in SessionClock.compute() (TS);
+# this script only FORMATS values it is given (render) or queries the route.
+#
+# Modes:
+#   render <startedISO> <durationSec> <elapsedSec> <remainingSec> <label>
+#     Prints ONE SESSION CLOCK line from the given (already-sanitized, already-
+#     computed) values. The caller (autonomous-stop-hook) has already resolved
+#     the record + computed elapsed/remaining, so there is NO re-resolution —
+#     the injected clock can never disagree with the hook's expiry verdict.
+#   query <topic> <port> <auth>
+#     Curls GET /session/clock?topic=<topic> and prints the SESSION CLOCK line
+#     for the first active session (or nothing if none / server unreachable).
+
+humanize() { # seconds -> "Xh Ym" / "Ym" / "Xs"
+  local s="${1:-0}"
+  case "$s" in (*[!0-9-]*) s=0 ;; esac
+  [ "$s" -lt 0 ] 2>/dev/null && s=0
+  local h=$((s / 3600)) m=$(((s % 3600) / 60))
+  if [ "$h" -gt 0 ]; then echo "${h}h ${m}m"; elif [ "$m" -gt 0 ]; then echo "${m}m"; else echo "${s}s"; fi
+}
+
+render_line() { # startedISO durationSec elapsedSec remainingSec label
+  local dur="$2" el="${3:-0}" rem="$4" label="$5"
+  local pct="" remstr="" lbl=""
+  if [ -n "$dur" ] && [ "$dur" -gt 0 ] 2>/dev/null; then pct=" ($((el * 100 / dur))% elapsed)"; fi
+  if [ -n "$rem" ]; then remstr=" · $(humanize "$rem") remaining"; fi
+  if [ -n "$label" ]; then lbl=" [$label]"; fi
+  echo "⏱ SESSION CLOCK${lbl}: $(humanize "$el") elapsed${remstr}${pct}. Do NOT conclude the session is over while remaining is large."
+}
+
+MODE="${1:-}"
+shift 2>/dev/null || true
+
+case "$MODE" in
+  render)
+    render_line "${1:-}" "${2:-}" "${3:-0}" "${4:-}" "${5:-}"
+    ;;
+  query)
+    TOPIC="${1:-}"; PORT="${2:-}"; AUTH="${3:-}"
+    [ -z "$PORT" ] && exit 0
+    URL="http://localhost:${PORT}/session/clock"
+    [ -n "$TOPIC" ] && URL="${URL}?topic=${TOPIC}"
+    RESP=$(curl -s --max-time 3 -H "Authorization: Bearer ${AUTH}" "$URL" 2>/dev/null)
+    [ -z "$RESP" ] && exit 0
+    printf '%s' "$RESP" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+sessions = d.get('sessions') or []
+if not sessions:
+    sys.exit(0)
+c = sessions[0]
+label = c.get('label') or ''
+el = c.get('elapsedHuman') or '?'
+rem = c.get('remainingHuman')
+pct = c.get('percentElapsed')
+line = '⏱ SESSION CLOCK' + ((' [' + label + ']') if label else '') + ': ' + el + ' elapsed'
+if rem is not None:
+    line += ' · ' + rem + ' remaining'
+if pct is not None:
+    line += ' (' + str(pct) + '% elapsed)'
+line += '. Do NOT conclude the session is over while remaining is large.'
+print(line)
+" 2>/dev/null
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+exit 0

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-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.