instar 1.3.326 → 1.3.328

package/src/templates/hooks/telegram-topic-context.sh

@@ -105,6 +105,12 @@ fi
 # Format and output context with unanswered message detection
 echo "$RECENT_MSGS" | python3 -c "
 import sys, json
+def _localts(raw):
+    try:
+        from datetime import datetime
+        return datetime.fromisoformat(str(raw).replace('Z', '+00:00')).astimezone().strftime('%Y-%m-%d %H:%M %Z')
+    except Exception:
+        return str(raw)[:16].replace('T', ' ')
 try:
     data = json.load(sys.stdin)
     msgs = data.get('messages', [])
@@ -114,7 +120,7 @@ try:
     print('TOPIC ${TOPIC_ID} RECENT HISTORY (auto-injected — read this before responding):')
 
     for m in msgs:
-        ts = m.get('timestamp', '')[:16].replace('T', ' ')
+        ts = _localts(m.get('timestamp', ''))
         from_user = m.get('fromUser', m.get('direction', 'in') == 'in')
         text = m.get('text', '').strip()
         sender = 'User' if from_user else 'Agent'
@@ -139,7 +145,7 @@ try:
         print('*** UNANSWERED MESSAGE(S) FROM USER ***')
         for pm in pending_user:
             pm_text = pm.get('text', '')[:200]
-            pm_ts = pm.get('timestamp', '')[:16].replace('T', ' ')
+            pm_ts = _localts(pm.get('timestamp', ''))
             print(f'  [{pm_ts}] \"{pm_text}\"')
         print()
         print('You MUST address these messages substantively. Do NOT respond with just')

package/upgrades/1.3.327.md

@@ -0,0 +1,57 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixes a **time-incoherency** class of bug: every context block that shows an
+agent its conversation history rendered timestamps as **unlabeled UTC**
+(`[21:23:10]`), while the CURRENT TIME hook block speaks labeled local time.
+Agents read both as one clock — live incident 2026-06-05: an agent told its
+user "you heard nothing between **9:23pm** and now" about an event at
+**2:23pm** the user's local time.
+
+Now every agent-facing timestamp renders in the **host's local timezone with
+an explicit tz label and date**: `[2026-06-05 14:23 PDT]`.
+
+Surfaces covered:
+
+- Bootstrap Thread History (new/respawned sessions), auto-spawn history
+- Moved-session context relay (multi-machine transfers)
+- Per-message Telegram topic history hook + unanswered-messages block
+- Post-compaction recovery context (Telegram + Slack blocks)
+- Session-start RECENT MESSAGES, TopicMemory context blocks
+- Slack channel context (tz label added)
+- Lifeline "Last healthy" status line
+
+New shared helper `src/utils/localTime.ts` (`formatLocalTimestamp`); hook
+python blocks carry an equivalent `_localts()` with a safe fallback to the
+old rendering on any parse failure. Stored timestamps remain ISO-UTC —
+rendering only. Existing agents pick the hook changes up automatically
+(built-in hooks are always-overwritten on migration).
+
+## What to Tell Your User
+
+Your agent no longer gets confused about what time things happened. Before
+this, the agent saw conversation history stamped in UTC but the current time
+in your local timezone — and could misquote a 2pm event as "9pm." Now every
+timestamp it reads carries your local time and timezone, so "when did I last
+hear from you?" answers come out right.
+
+## Summary of New Capabilities
+
+- None user-invocable — this is a correctness fix to how agents perceive
+  time. (Internal: `formatLocalTimestamp()` in `src/utils/localTime.ts` is
+  the one helper all history/status renderers now use.)
+
+## Evidence
+
+- New `tests/unit/localTime.test.ts` pins local-not-UTC semantically
+  (TZ-portable: compares against the same instant's local Date getters),
+  including the verbatim incident instant `2026-06-05T21:23:10Z`.
+- Hook python smoke test: the incident payload now renders
+  `[2026-06-05 14:23 PDT] Agent: executing now` (was `[2026-06-05 21:23]`).
+- Updated `ForwardedTopicContext` / `compactionResumePayload` /
+  `telegram-autospawn-history` tests to TZ-portable assertions through the
+  helper; affected-area suites green; `tsc --noEmit` clean.

package/upgrades/1.3.328.md

@@ -0,0 +1,44 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The ServerSupervisor's slow-retry mode (respawn a dead server every 2h, forever)
+is a sanctioned Eternal Sentinel under the new "No Unbounded Loops" standard —
+but it violated condition 4: it never told anyone. A multi-day crash-revive loop
+was indistinguishable from silence. Now a pure one-shot latch
+(`SlowRetrySentinelEscalation`, the AgeKillBackoff suppressor shape) fires
+exactly once per outage episode after a sustained-failure threshold (default
+12h ≈ 6 failed cycles): the supervisor emits `sentinelStalled` and the lifeline
+sends ONE operator message with the two useful levers (`/lifeline doctor`,
+`/lifeline reset`), then the sentinel keeps quietly retrying. The message goes
+directly to the Telegram Bot API from the lifeline process — no dependency on
+the (down) agent server. Recovery re-arms the latch via the single
+`resetCircuitBreaker()` funnel; retry/kill/spawn decisions are unchanged.
+
+## What to Tell Your User
+
+If your agent's server ever gets stuck in a crash loop, you'll now get one
+clear heads-up after ~12 hours — "still down, here's how to diagnose or force a
+retry, I'll keep trying" — instead of discovering the outage by noticing your
+agent went quiet for days. One message per outage, never a stream.
+
+## Summary of New Capabilities
+
+- Slow-retry escalation: a sustained server outage (default 12h in slow-retry)
+  produces exactly one operator notification per episode; the never-give-up
+  revival behavior is unchanged. In-code default; no config required.
+
+## Evidence
+
+Loop-safety audit finding (CMT-1109), verified at source: the slow-retry block
+in `src/lifeline/ServerSupervisor.ts` was annotated "never truly give up" with
+no operator signal. Fix is the first PR under constitution P19 ("No Unbounded
+Loops", incl. Justin's Eternal Sentinel caveat — this loop is its namesake
+case). Tests: 10 green in `tests/unit/SlowRetrySentinelEscalation.test.ts`
+including the P19 sustained-failure bound (week-long never-recovering episode →
+exactly 1 escalation) and source-shape wiring pins. Independent adversarial
+second-pass: CONCUR (all probes safe — per-tick reachability, no double-fire,
+server-independent delivery, emit-before-spawn ordering). tsc clean.

package/upgrades/local-time-coherence.eli16.md

@@ -0,0 +1,11 @@
+# The agent stops misreading its own clock
+
+The agent kept two clocks without knowing it. Every hook that tells the agent "here's the current time" speaks in YOUR local time ("5:49pm PDT") — but every block that shows it conversation history spoke in unlabeled UTC ("[21:23]"). The agent has no way to tell those apart, so it did the natural thing: read both as the same clock. That's how it told Justin "you heard nothing between **9:23pm** and now" about a message sent at **2:23pm** his time — off by exactly the 7-hour UTC gap. The user experiences this as the agent being confused about basic reality.
+
+The fix makes every timestamp the agent ever sees speak ONE language: the machine's local time, with the timezone written right on it — `[2026-06-05 14:23 PDT]` instead of `[21:23:10]`. History lines also now carry the date, so a conversation spanning midnight can't be misread either ("was that 12:30am today or yesterday?" stops being a guess).
+
+Where this applies — every surface that renders history or status timestamps into an agent's context: the thread history a new session boots with, the history relayed when a conversation moves between machines, the recent-messages block injected on every Telegram message, the post-compaction recovery context, the Slack channel context, the session-start recent messages, and the lifeline's "last healthy" status line. One new shared helper does the rendering in code; the hook scripts get a tiny equivalent helper with a safe fallback (if a timestamp ever fails to parse, it renders the old way instead of crashing the hook).
+
+Existing agents get this automatically: the built-in hook scripts are always refreshed on update, and the code paths ship with the next release. Nothing about WHEN things happen changes — only how the time is written down. There is no new config, no new decision surface, and the worst possible failure (a malformed timestamp) renders the way it used to render rather than breaking anything.
+
+What you need to decide: nothing — this is a pure rendering fix for a live mis-statement the agent made to you. The PR is the review surface.

package/upgrades/side-effects/local-time-coherence.md

@@ -0,0 +1,89 @@
+# Side-Effects Review — Local-time + tz-label rendering for all agent-facing timestamps
+
+**Version / slug:** `local-time-coherence`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (no block/allow surface, no lifecycle decisions — pure rendering)`
+
+## Summary of the change
+
+Every surface that renders timestamps into agent-facing context blocks switched from unlabeled UTC (`toISOString().slice(11, 19)` in TS, `timestamp[:16].replace('T', ' ')` in hook python) to host-local time with an explicit timezone label and date (`[2026-06-05 14:23 PDT]`). New shared helper `src/utils/localTime.ts` (`formatLocalTimestamp`, `localTzAbbreviation`); call sites: `ForwardedTopicContext.ts`, `TopicMemory.ts` ×2, `commands/server.ts` (bootstrap Thread History), `server/routes.ts` ×2 (auto-spawn/respawn history), `compactionResumePayload.ts`, `TelegramLifeline.ts` (status line). Hook python blocks get an equivalent `_localts()` helper with parse-failure fallback to the old rendering: `templates/hooks/telegram-topic-context.sh`, `templates/hooks/compaction-recovery.sh` (telegram + slack blocks), `templates/hooks/slack-channel-context.sh` (tz label only), and the `PostUpdateMigrator.ts` inline copies (session-start, telegram-topic-context, compaction-recovery). Driven by the 2026-06-05 live incident: the agent reported a 14:23-local event as "9:23pm" because history was unlabeled UTC while CURRENT TIME blocks are local-labeled.
+
+## Decision-point inventory
+
+No decision-point surface. This change renders strings; it adds, removes, or modifies no block/allow decision, no gate, no lifecycle action. The only conditional logic is "did the timestamp parse?" with a render-the-old-way fallback.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable.
+
+---
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Right layer: a formatting primitive at the render chokepoints. The alternative — teaching agents (prompt-level) that history is UTC — is exactly the willpower-dependent design that caused the incident. A lower-level primitive did not exist (`formatLocalTimeHHMM` in `RestartCascadeDampener.ts` is HH:MM-only, no tz label, no date, not exported for this purpose); this PR creates the shared primitive and routes all sites through it. Hook python cannot import TS, so it carries a minimal equivalent — acceptable duplication at the language boundary, kept identical across all blocks.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface.
+
+Pure rendering. Nothing here holds authority over any action.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** none — no checks run before/after; the rendered string feeds the same downstream consumers (context injection, tmux paste) unchanged in shape (`[ts] Sender: text`).
+- **Double-fire:** none — formatting is idempotent and side-effect-free.
+- **Races:** none — no shared mutable state; `Intl.DateTimeFormat` is constructed per call.
+- **Feedback loops:** one considered: agents QUOTE history timestamps back into conversation, and those quotes can land in future history. Since both the injected history and the CURRENT TIME hook now speak local-labeled time, the loop converges toward coherence instead of propagating UTC misreads.
+- **Unanswered-message detection:** verified untouched — detection logic compares message order/sender, never parses the rendered timestamp.
+- **Tests that mirror renderers:** `telegram-autospawn-history.test.ts` contains a local mirror of the routes.ts logic; updated in the same PR so the mirror stays faithful.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** the hook-template changes reach every instar agent on next update (built-in hooks are always-overwritten by `PostUpdateMigrator`). The change is rendering-only; no agent behavior contract depends on UTC timestamps (verified: no consumer parses the bracketed time back out of context blocks — grepped for consumers of the rendered format).
+- **External systems:** none — Telegram/Slack/GitHub payloads unchanged; only locally-injected context strings change.
+- **Persistent state:** none written. Stored timestamps remain ISO-UTC everywhere (JSONL, SQLite); ONLY rendering changes. No migration of stored data.
+- **Timing/runtime:** `%Z` in python `strftime` and `Intl` tz short-names vary by platform locale data; on a host where no label resolves, the label is simply omitted (TS) or the naive fallback renders (python) — degraded to the status quo, never an error.
+
+---
+
+## 7. Rollback cost
+
+Pure code + template change — revert and ship a patch. No persistent state, no data migration, no agent state repair. During a rollback window, agents would briefly render local-labeled and then UTC again; cosmetic only.
+
+---
+
+## Conclusion
+
+The review confirmed no decision surface and no persistence surface; the main risks identified and addressed were (a) hook python crashing on unparseable timestamps — covered by the try/except fallback to the previous rendering, and (b) test mirrors drifting from real renderers — the mirror was updated in the same change. One pre-existing inconsistency was found and normalized: `formatInlineHistory` treated numeric-0 timestamps as missing while `ForwardedTopicContext` rendered them; the shared helper renders them (epoch is a valid instant). Clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required
+**Independent read of the artifact:** not required — no messaging block/allow, no session lifecycle, no sentinel/gate/guard surface.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/localTime.test.ts` — semantic local-not-UTC pinning incl. the verbatim incident instant `2026-06-05T21:23:10Z`.
+- Hook python smoke test: incident payload renders `[2026-06-05 14:23 PDT] Agent: executing now` (was `[2026-06-05 21:23]`).
+- Full local suite (74 min on a loaded box): 28329 passed / 8 failed across 5 files. The one failure whose identity survived output truncation (`session-management-e2e`, a waitFor timeout) re-ran green in isolation; a full re-run with complete capture was started for the rest, and CI (clean, sharded runners) is the merge gate either way.

package/upgrades/side-effects/supervisor-sentinel-escalation.md

@@ -0,0 +1,61 @@
+# Side-Effects Review — Slow-Retry Sentinel Escalation
+
+**Version / slug:** `supervisor-sentinel-escalation`
+**Date:** `2026-06-05`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `independent adversarial reviewer subagent — CONCUR (all four probes safe; no blocking defects; non-blocking notes recorded below)`
+
+## Summary of the change
+
+The ServerSupervisor's slow-retry mode (2h respawn cadence, deliberately forever) gains the Eternal Sentinel's condition-4 observability: a pure one-shot latch (`src/lifeline/SlowRetrySentinelEscalation.ts`) fires once per outage episode after `escalateAfterMs` (default 12h), the supervisor emits `'sentinelStalled'`, and `TelegramLifeline.notifySentinelStalled` delivers ONE operator message (doctor/reset levers), after which the sentinel keeps retrying unchanged. `resetCircuitBreaker()` — the single episode-ending funnel — re-arms the latch in lockstep with zeroing `slowRetryStartedAt`. Files: `SlowRetrySentinelEscalation.ts` (new, pure), `ServerSupervisor.ts` (declaration comment + per-tick check + emit + reset hook + one constructor option), `TelegramLifeline.ts` (listener + notify method), one test file.
+
+## Decision-point inventory
+
+- `ServerSupervisor` slow-retry block — **modify (additive)** — gains a read-only latch check + event emit; the retry decision, cadence, kill, and spawn are untouched.
+- `SlowRetrySentinelEscalation` — **add** — a pure signal producer with no authority of any kind.
+- `TelegramLifeline` event wiring — **add** — delivery only; mirrors the existing `circuitBroken` handler shape (fire-and-forget, catch-swallowed).
+
+## 1. Over-block
+
+Nothing is blocked — this change cannot suppress, delay, or alter any retry or recovery action. The only "cost" added is one Telegram message per ≥12h outage episode.
+
+## 2. Under-block
+
+(a) A lifeline PROCESS restart zeroes the in-memory latch with all breaker state; after ~13.5h of freshly rebuilt sustained failure it would notify again. Reviewer-assessed as correct-by-design ("still broken after a bounce" is a legitimate re-notification), and persisting the latch was explicitly rejected — a stale on-disk latch could suppress a legitimate notification, the worse failure. (b) The threshold is time-based, not attempt-based: a machine asleep for 12h would escalate on wake even though few attempts ran — acceptable; the operator-facing claim ("down ~N hours") remains true. (c) Other eternal-sentinel-shaped loops (lease pull) are NOT covered here — next audit PR <!-- tracked: CMT-1109 -->.
+
+## 3. Level-of-abstraction fit
+
+Yes. The latch lives beside the loop it observes (lifeline package), as a pure helper in the established suppressor shape (`AgeKillBackoff`: injectable clock, bounded state, unit-testable). Delivery rides the existing supervisor→lifeline event channel (`circuitBroken` precedent) rather than inventing a new notification path — and deliberately does NOT use the agent server's attention queue, which is definitionally down when this fires.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** `docs/signal-vs-authority.md`
+
+- [x] No — pure signal. The latch can only cause one message; it holds no authority over retries, kills, spawns, or the circuit breaker. The healer's behavior is byte-identical with the latch removed.
+
+## 5. Interactions
+
+- **Double-fire:** impossible within a process — the episode key (`slowRetryStartedAt`) is written only at episode start (when 0) and zeroed only inside `resetCircuitBreaker()`, which re-arms the latch in the same method; key and latch cannot desync (reviewer traced every write).
+- **Starvation:** the slow-retry block runs every 10s health-check tick while broken (the branch returns without resetting `consecutiveFailures`), so the latch check cannot be starved (reviewer traced `evaluateUnhealthyServer` → `handleUnhealthy` reachability).
+- **Ordering:** the emit's listener is fire-and-forget and catch-swallowed; it cannot block or throw into the same tick's kill/spawn (mirrors `circuitBroken`).
+- **Feedback loops:** none — a message cannot change health-check outcomes.
+
+## 6. External surfaces
+
+- **User-visible:** one new Telegram message class, bounded at one per episode (Bounded Notification Surface-compatible: no topic creation — it posts to the existing lifeline topic).
+- **Delivery independence:** `sendToTopic` → Telegram Bot API directly over HTTPS from the lifeline process; zero dependency on the down agent server (reviewer-verified at `apiCall`).
+- **Persistent state / config / schema:** none. In-code default; `slowRetryEscalateAfterMs` is a constructor option for tests only. No migration (Migration Parity: nothing installed changes).
+
+## 7. Rollback cost
+
+Revert the commit. No state to clean, no config to unwind. The only observable regression of rollback is the silence returning.
+
+## Conclusion
+
+Signal-only observability for the constitution's namesake Eternal Sentinel: persistence preserved, silence eliminated, volume bounded at one message per episode and proven by the P19 sustained-failure test (week-long never-recovering episode → exactly 1). Second-pass reviewer CONCUR with zero blocking findings; both non-blocking notes (restart re-fire window, no Tier-2/3 for a route-less signal change) are recorded in §2/§6 with their rationale.
+
+---
+
+## Phase 5 — Second-pass review (server-lifecycle-adjacent → performed)
+
+An independent adversarial reviewer audited the diff and final files at line level against four probes: (1) any >1-fire-per-outage path — traced every `slowRetryStartedAt`/`circuitBroken` write; none desync the episode key from the latch; lifeline-restart re-fire requires ~13.5h of rebuilt failure and is a correct re-notification; (2) any never-fire path — the slow-retry branch is reached every 10s tick while broken (per-tick reachability traced through `evaluateUnhealthyServer`/`handleUnhealthy`); (3) delivery dependence on the down server — none: the lifeline posts straight to the Telegram Bot API; (4) emit-vs-spawn ordering — fire-and-forget listener, cannot block or throw into the spawn. Ran the 10-test suite (green) and `tsc --noEmit` (clean). **Verdict: CONCUR.**