instar 1.2.11 → 1.2.13

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-21T19:17:56.169Z",
-  "instarVersion": "1.2.11",
+  "generatedAt": "2026-05-21T21:36:06.272Z",
+  "instarVersion": "1.2.13",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "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": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "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": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "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": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "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": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "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": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "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": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "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": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "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": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "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": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "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": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "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": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "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": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1472,7 +1472,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "e32c85f03cb2d4d440172949fb5f7654c7c224a7cd64c78ed1c7b83759e1c2c9",
+      "contentHash": "c05e308a956d13c08a2aecdbec64591b4a94ef3c083e4b4ce95202b03ebce284",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.2.12.md

@@ -0,0 +1,82 @@
+# Upgrade Guide — v1.2.12 (hybrid wizard for Codex runtime)
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**New: hybrid setup wizard for Codex-runtime installs.**
+
+`npx instar` → pick Codex CLI at the runtime prompt → now reaches
+an actual conversational walkthrough. Before this release, Codex
+ignored the wizard skill's behavioral contract and executed the
+entire setup non-interactively, leaving the user with a generic
+agent identity they never got to shape.
+
+The fix is a two-layer architecture under
+`src/commands/setup-wizard/`:
+
+1. **State machine** owns the conversation flow. Each state has a
+   structural prompt printed verbatim by instar, a deterministic
+   transition function, and (for action states) a side effect call
+   to existing CLI commands. Order is fixed in TypeScript code; no
+   LLM can drift it.
+
+2. **Codex driver** drives the state machine turn-by-turn. For each
+   conversational state, the driver runs `codex exec -s read-only
+   -m gpt-5.3-codex --ephemeral` with a tightly-constrained prompt
+   asking Codex to generate ONE warm 2-3 sentence intro paragraph.
+   The structural prompt is printed by instar; readline reads the
+   answer. Codex cannot use tools, cannot reword the question,
+   cannot decide to execute the setup itself.
+
+3. **Telegram setup phase** hands off to Codex as a full agentic
+   session (sandbox bypass + Playwright access) — driving the
+   browser is execution, which is Codex's strength.
+
+Claude-runtime users see no change. The Claude path keeps the
+existing `/setup-wizard` slash-command spawn.
+
+Settings the user picks during the wizard (agent name, focus,
+autonomy level, messaging channel) can all be changed later just
+by chatting the agent. The farewell text and the autonomy step's
+narrative both surface this affordance.
+
+Spec: `specs/dev-infrastructure/hybrid-wizard.md`.
+ELI16: `specs/dev-infrastructure/hybrid-wizard.eli16.md`.
+Side-effects review: `upgrades/side-effects/feat-hybrid-wizard.md`.
+
+## What to Tell Your User
+
+The setup wizard now walks you through identity, autonomy, and
+messaging conversationally, regardless of which runtime you picked.
+On Codex, the wizard runs as a state machine in instar itself with
+Codex generating the warm narrative for each step; on Claude it
+runs the same way it always has. Anything you set up can be
+changed later just by chatting your agent — no need to re-run setup.
+
+## Summary of New Capabilities
+
+- New module: `src/commands/setup-wizard/` (state machine + Codex
+  driver + model constants).
+- New CLI behavior: `npx instar` → pick Codex CLI → conversational
+  wizard with per-step narrative from Codex.
+- Existing CLI surface unchanged.
+
+## Evidence
+
+Reproduction prior to fix: ran v1.2.11 install via bareword `npx
+instar` → picked Codex. Codex received the wizard skill prompt and
+executed the entire setup non-interactively. Full log captured at
+`setup-logs.md` in the test project — 2940 lines, zero
+conversational walkthrough.
+
+After fix:
+- 12 new state-machine unit tests cover the choice resolver, graph
+  integrity, identity-answer threading, messaging branching, and
+  the post-server completion chain.
+- 5 updated canary tests cover the dispatch contract: setup.ts
+  imports `runCodexWizard` for codex-cli, no codex exec argv with
+  the wizard skill prompt remains in setup.ts, the driver's codex
+  exec spawns still pin `-m WIZARD_CODEX_MODEL`.
+- End-to-end re-test on the Codex install path pending on publish.

package/upgrades/1.2.13.md

@@ -0,0 +1,42 @@
+# Upgrade Guide — vNEXT (current-time injection in agent hooks)
+
+<!-- bump: patch -->
+<!-- patch = behavior fix that closes a recurring failure mode, no new surface -->
+
+## What Changed
+
+**Fix: every instar agent now sees the current wall-clock time at session start AND on every user prompt.**
+
+Claude Code's harness injects `currentDate: YYYY-MM-DD` into the agent's system prompt — but NOT the current time of day. In long-running sessions (hours, days), agents that try to say "it's 2am" or "you've been up X hours" or "we just talked an hour ago" were either hallucinating clock times outright or pulling stale time strings from earlier conversation context. Iris hit this on 2026-05-21: she told a user "it's 2am" when it was actually 5:45am, and only realized it after the user contradicted her with a timestamped screenshot.
+
+The fix is structural, not behavioral. Two existing hooks every instar agent already runs now emit a `--- CURRENT TIME ---` block backed by a live `date(1)` call:
+
+- **`session-start.sh`** (SessionStart hook, startup / resume / clear) — emits the time block immediately after `=== SESSION START ===`, before any other context. Refreshed on every session lifecycle event including post-compaction resume.
+- **`telegram-topic-context.sh`** (UserPromptSubmit hook) — emits the time block on **every** user prompt, BEFORE the `[telegram:N]` prefix early-exit. So agents get a fresh wall-clock anchor on every turn, not just at session start, regardless of whether the prompt arrived via Telegram or direct CLI use.
+
+Format: `2026-05-21 14:15:29 -0500 (CDT)` — ISO date + 24h time + signed offset + tz abbreviation. Same line every time. Agents are told explicitly: "Quote this — do not carry stale clock times from prior context."
+
+The hook content lives inline in `src/core/PostUpdateMigrator.ts` (functions `getSessionStartHook()` and `getTelegramTopicContextHook()`), which is the source of truth that both `init` (new agents) and `migrate` (existing agents) write to disk. Built-in hooks are unconditionally overwritten on every migration run, so existing agents pick up the fix automatically on their next `npx instar` invocation — no manual migration required.
+
+## What to Tell Your User
+
+If your agent has ever made a clock-time claim that turned out to be wrong (saying it's the middle of the night when it isn't, miscalculating "how long ago" something happened, mismatching AM/PM), that failure mode is closed after this release. Your agent now sees the actual current time on every interaction and is structurally instructed to quote it rather than guess.
+
+No action needed from you. The next time your agent updates, the fix lands.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Wall-clock time injected at session start | Automatic — `--- CURRENT TIME ---` block at the top of session-start output |
+| Wall-clock time refreshed on every user prompt | Automatic — same block emitted ahead of telegram-topic-context every UserPromptSubmit |
+
+## Evidence
+
+- New test: `tests/unit/PostUpdateMigrator-time-injection.test.ts` — 13 cases. Static assertions on the inlined bash (date format, guard, delimiters, ordering) PLUS end-to-end execution of both hook scripts against a fresh sandboxed temp dir, asserting the actual emitted output matches the expected `YYYY-MM-DD HH:MM:SS +ZZZZ (TZ)` shape.
+- Existing tests still pass: `tests/unit/PostUpdateMigrator-sharedState.test.ts` (Integrated-Being session-start regression) and `tests/unit/scaffold-identity-hooks.test.ts` (scaffold integrity) verified green against the patched migrator.
+- Side-effects review: `upgrades/side-effects/inject-current-time-into-hooks.md`.
+
+## Original Incident
+
+Iris session, Business Plan topic, 2026-05-21 ~5:45am CDT. Agent said "It's 2am. The laptop can wait. Goodnight." User's actual local time was 5:45am Central. Memory note `feedback_clock_time_must_call_date.md` captured the rule per-agent; this release lifts the fix to the framework so every instar agent benefits without each agent having to learn the lesson independently.

package/upgrades/side-effects/feat-hybrid-wizard.md

@@ -0,0 +1,122 @@
+# Side-effects review — Hybrid wizard
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER for Codex-runtime users. The bareword runtime prompt
+let users pick Codex, which then spawned Codex with the wizard skill.
+Codex ignored the skill's conversational contract and executed setup
+non-interactively. Generic agent identity, no walkthrough.
+
+After: precisely targeted. instar's state machine owns the
+conversation flow; Codex is restricted per-turn to narrative-only
+generation. Claude users see zero change (they keep the existing
+SKILL.md-driven spawn). API-key Codex users keep the same auth
+posture they had before. The agentic Telegram phase still uses
+Codex with full sandbox bypass — that's the right tool for browser
+automation.
+
+## 2. Level-of-abstraction fit
+
+A new directory `src/commands/setup-wizard/` holds three files:
+- `state-machine.ts` — pure data + transition functions, no I/O.
+- `codex-driver.ts` — I/O (codex spawn, readline, CLI subcommands).
+- `model-constants.ts` — single constant import target.
+
+setup.ts adds one dispatch branch (~12 LOC). It dynamically imports
+the codex driver only when the user picks Codex, keeping the
+setup.ts module load lightweight.
+
+The state machine is intentionally a flat record of states; no
+class hierarchy, no event emitters. Drivers consume it via simple
+lookups. Adding a state is one edit.
+
+## 3. Signal vs Authority compliance
+
+- The user's runtime choice from the bareword prompt remains an
+  operator-intent SIGNAL flowing into `enabledFrameworks` and the
+  wizard dispatch.
+- The state graph's transition functions are deterministic AUTHORITIES
+  for "what state comes next" given a user answer. Codex never sees
+  the transition function and cannot influence routing.
+- `WIZARD_CODEX_MODEL` is the AUTHORITY for which Codex model the
+  narrative spawns use, drawn from the existing empirically-probed
+  availability table at `src/providers/adapters/openai-codex/models.ts`.
+- The agentic Telegram phase respects the existing AUTHORITY for
+  Telegram bot creation (BotFather / OpenAI Codex's tool access /
+  Playwright MCP).
+
+## 4. Interactions with adjacent systems
+
+- **v1.2.1 runtime prompt** (`promptForFramework`): unchanged. Still
+  reads `1`/`2`/`codex` and returns the chosen runtime.
+- **`checkFrameworkPrerequisite`**: unchanged. Still validates the
+  chosen runtime's binary is detected.
+- **`ensureSecretBackend`** (Phase 2.5): unchanged in v1.2.12. Still
+  spawns the chosen framework with `/secret-setup` for the secret
+  backend choice. A future PR can route secret-setup through the
+  state machine too, but for v1.2.12 we keep that scope bounded.
+- **Existing wizard SKILL.md**: unchanged. Still owned by the Claude
+  path; the Codex path uses it ONLY as a reference target for the
+  Telegram-agentic phase prompt.
+- **CLI subcommands the wizard calls** (`init`, `user add`, `server
+  start`, `autostart install`): unchanged. The driver calls them via
+  `execFileSync('npx', ['instar', ...])` the same way the existing
+  SKILL.md tells Claude to call them.
+- **PR #299's canary**: updated. Previously asserted every `codex exec`
+  in setup.ts carries `-m WIZARD_CODEX_MODEL`. v1.2.12 asserts setup.ts
+  no longer has codex exec spawns (they moved into codex-driver.ts),
+  setup.ts dispatches via `runCodexWizard`, and the driver's codex
+  exec spawns still carry `-m WIZARD_CODEX_MODEL`.
+
+## 5. Rollback cost
+
+Low. Three new files in a new directory plus one ~12-LOC dispatch
+branch in setup.ts. The old `codex exec` argv shape in setup.ts is
+removed; reverting reintroduces it. Claude path untouched.
+
+`git revert` restores the v1.2.11 broken-on-Codex behavior. No state
+migration; no agent-installed-files changes; no `PostUpdateMigrator`
+work needed.
+
+## 6. Backwards compatibility / drift surface
+
+Fully backwards-compatible.
+
+- Claude-runtime users: zero change.
+- Codex-runtime users: now get a working conversational wizard
+  driven by instar with Codex-generated narrative. Previously got
+  broken non-interactive setup.
+- API-key Codex users: auth posture unchanged. `CODEX_MODEL` env
+  still overrides the wizard's `-m` flag if they prefer a different
+  model.
+- No config schema change. No agent file template change. No hook
+  change.
+
+Drift surface: the state graph and per-turn narrative prompts. Both
+are flat data structures, so drift is visible in PR diffs. The
+canary covers the dispatch shape; manual review covers narrative
+prompt quality.
+
+## 7. Authorization / Trust posture
+
+No new authority. The per-turn narrative codex spawns use `-s
+read-only` (a strictly lower-privilege sandbox than the
+`--dangerously-bypass-approvals-and-sandbox` the existing wizard
+spawn uses). The Telegram-agentic phase keeps the existing sandbox-
+bypass posture so it can drive Playwright. The action states call
+`execFileSync('npx', ...)` for `init`, `user add`, `server start`,
+`autostart install` — the same CLI surface the existing wizard
+calls.
+
+No new auth, no new gate, no new privilege.
+
+## Outcome
+
+Ship. Closes the broken-on-Codex install experience that the v1.2.11
+instar-codey log surfaced. Per-framework specialization preserves
+each runtime's strengths (Claude's reliable skill-following, Codex's
+strong execution mode for agentic phases). Structure-as-guarantee
+prevents the regression class. Canary in CI guards the dispatch
+contract.

package/upgrades/side-effects/inject-current-time-into-hooks.md

@@ -0,0 +1,63 @@
+# Side-Effects Review — inject current time into agent hooks
+
+**Version / slug:** `inject-current-time-into-hooks`
+**Date:** `2026-05-21`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (Layer 1 hook-template content change, signal-only, no gate authority — Phase 5 trigger inventory below)
+
+## Summary of the change
+
+`PostUpdateMigrator.getSessionStartHook()` and `getTelegramTopicContextHook()` (the inlined bash templates that get unconditionally overwritten onto every agent's disk on update) now each emit a `--- CURRENT TIME ---` block backed by a fresh `date(1)` invocation. The block contains an ISO-formatted wall-clock timestamp with signed offset and timezone abbreviation, plus a one-line instruction to the agent: "Quote this — do not carry stale clock times from prior context."
+
+**Files touched:**
+- `src/core/PostUpdateMigrator.ts` — 14 lines added to `getSessionStartHook()` (after the `=== SESSION START ===` echo, before the TOPIC CONTEXT block); 14 lines added to `getTelegramTopicContextHook()` (immediately before the [telegram:N] early-exit, so the block fires on every UserPromptSubmit regardless of prefix).
+- `tests/unit/PostUpdateMigrator-time-injection.test.ts` — new file, 13 test cases. Static assertions on the inlined bash (date format string, non-empty guard, delimiter strings, relative ordering within each hook) PLUS end-to-end `execFileSync` of each hook script against a fresh temp dir, asserting the actual emitted output matches the expected `YYYY-MM-DD HH:MM:SS +ZZZZ (TZ)` shape on a non-telegram prompt, a telegram-prefixed prompt, and a session-start invocation.
+- `upgrades/NEXT.md` — new vNEXT entry, classified `patch` (behavior fix, no new surface).
+
+## Decision-point inventory
+
+- **Where the time block lands in session-start output** — *modify*. Placed AFTER `=== SESSION START ===` and BEFORE the TOPIC CONTEXT block. Rationale: the wall-clock is generic orientation, not topic-specific — it belongs at the top of the orientation frame, ahead of the per-conversation context. Asserted by test `places the time block BEFORE the TOPIC CONTEXT block`.
+- **Where the time block lands in UserPromptSubmit** — *modify*. Placed BEFORE the `[telegram:N]` early-exit. Rationale: the script's filename suggests telegram-only, but UserPromptSubmit fires on every prompt — emitting the time block before the early-exit makes the fix universal (Telegram and direct-CLI sessions both get it). Asserted by test `emits the time block BEFORE the [telegram:N] early-exit`.
+- **Output guard against a broken `date(1)`** — *new*. Wrap the emission in `if [ -n "$NOW" ]; then ... fi` so a hypothetical environment where `date(1)` returns empty (extremely unlikely on macOS/Linux) doesn't produce a `--- CURRENT TIME ---` header with no value. Asserted by test `wraps the emission in a non-empty guard`.
+- **Date format choice** — *new*. `'%Y-%m-%d %H:%M:%S %z (%Z)'`. Portable across BSD date (macOS) and GNU date (Linux); produces both machine-parseable (`%z`) and human-readable (`%Z`) timezone forms. Verified by the end-to-end test which `execFileSync`s the hook and regex-matches the emitted body.
+- **Delimiter style** — *match existing*. `--- CURRENT TIME ---` / `--- END CURRENT TIME ---` mirrors the dashed delimiters already used in session-start for other blocks (`--- CONVERSATION CONTEXT ---`, `--- INTEGRATED-BEING ---`, `--- PROJECT CONTEXT ---`). No new visual convention introduced.
+
+## Level-of-abstraction fit
+
+This is a Layer 1 (hook content) change. It belongs at the migrator level — both because the migrator is the source of truth for hook content (init and update both write from `getSessionStartHook()` / `getTelegramTopicContextHook()`) and because the failure mode (stale clock in long agent sessions) is a cross-cutting infrastructure gap, not a per-agent or per-feature concern. Solving it per-agent (e.g. Iris's memory file `feedback_clock_time_must_call_date.md`) closed the gap for one agent. Lifting it to the framework means every instar agent gets the same anchor without each one having to learn the lesson independently — which matches the **Structure > Willpower** principle stated in CLAUDE.md.
+
+## Signal-vs-authority compliance
+
+The hook injection emits text. It does not gate, block, modify, or veto any agent action. It is pure signal — the agent reads the wall-clock and is told to quote it. Authority over whether to use the time, what time to claim, or whether to call `date` again later remains entirely with the agent. No new blocking authority introduced.
+
+## Interactions
+
+- **Compaction recovery** (`compaction-recovery.sh`): On `compact` event, `session-start.sh` `exec`s away to `compaction-recovery.sh` BEFORE the time block is reached. So the time block does not run during compact-recovery. Compaction-recovery's own injection pipeline is separate and is not regressed by this change. The block DOES run on resume, which fires after compaction completes. No double-emission.
+- **Telegram early-exit**: Adding output BEFORE the `[telegram:N]` early-exit means the hook now produces output on every UserPromptSubmit, including non-telegram prompts. This is intentional — direct-CLI sessions need the time anchor too. Effect on Claude Code: an additional ~3-line block in the agent's prompt buffer per turn. Token cost negligible (~30 tokens).
+- **Integrated-Being v2 session-bind**: The session-bind block in `session-start.sh` lives AFTER the time block but runs independently. Time injection produces output via stdout; session-bind makes HTTP calls and writes a token file. No shared variables, no ordering dependency.
+- **Existing PostUpdateMigrator-sharedState test**: Asserts the integrated-being injection survives in `getSessionStartHook()`. The new time block sits BEFORE the integrated-being block; the existing assertion (`expect(hook).toContain('/shared-state/render?limit=50')`) continues to pass — verified in test run.
+
+## Over/under-block check
+
+- **Under-block**: Could the fix miss any cases where an agent says a clock time?
+  - **Mid-session tool-result handoffs**: If an agent receives a Claude Code tool result and immediately replies with a time claim, the most recent time anchor is the previous UserPromptSubmit. Up to 5 minutes stale in fast back-and-forths, less for slow ones. Acceptable — within a single turn, ±a-few-minutes is fine. Worst-case would be a multi-hour autonomous-mode tool loop without user prompts, in which case the agent could go stale. Mitigated separately by autonomous-mode's existing periodic re-orientation; not in scope here.
+  - **Subagent invocations**: Sub-agents started via the `Agent` tool inherit the parent's prompt context, not the live hook output. So a subagent's time anchor is the parent's at-spawn time. Acceptable — subagents are short-lived and rarely make wall-clock claims; their job is task execution.
+- **Over-block**: Could the fix cause an unintended block, refusal, or behavior change elsewhere?
+  - **Hook timeout (5s budget for UserPromptSubmit)**: Adding a `date` call adds <1ms. No timeout risk.
+  - **Token bloat in long sessions**: ~30 tokens per turn × thousands of turns = a few hundred-K tokens over a long session. Compared to the existing telegram-topic-context block (~500 tokens / turn for recent history), this is a rounding error.
+  - **Test pollution**: The end-to-end test uses `mkdtempSync` + per-test env var override, no persistent state. No effect on parallel test runs.
+
+## Rollback cost
+
+Two-line `git revert` of the migrator edit, plus deleting the new test file. Hooks are unconditionally overwritten on next migration run, so a revert propagates to all deployed agents on their next `npx instar`. No data migration, no persistent state, no fan-out — zero rollback friction.
+
+## Phase 5 trigger check
+
+Was a second-pass reviewer required? No.
+
+- **Not a gate change**: No new authority, no blocking, no veto, no permission alteration. Signal-only.
+- **Not a security-sensitive surface**: No new file reads outside the hook's existing scope (it only adds a `date` call); no new network calls; no new credential or token handling.
+- **No new persistent state**: Output flows to stdout, consumed by Claude Code's prompt injector. No disk writes, no SQLite, no JSONL.
+- **No cross-agent or cross-machine effect**: Per-agent hook content. No threadline message, no shared state, no remote operation.
+
+The change crosses **none** of the second-pass triggers from the side-effects review standard. A single-pass review by the author with this written record is sufficient.