@turmind/halo 0.1.9 → 0.2.0

package/bundled-docs/plans/cron-tasks.md

@@ -1,362 +0,0 @@
-# Cron Tasks
-
-Global, cross-workspace scheduled agent runs. The user defines a job
-(workspace + agent + prompt + schedule + channel targets); the server
-schedules it via croner; on fire, a `halo cli` child runs the prompt;
-the captured stdout is fanned out to the bound channels and the run is
-recorded in an audit log.
-
-Two trigger modes:
-
-- **Recurring** — standard 5-field cron expression; fires on every match.
-- **One-shot (at-mode)** — exact instant via `runAt` (epoch ms); fires
-  once at that time, then auto-disables (the row is kept for history /
-  rerun, but `enabled=0` so reload doesn't re-instantiate the schedule).
-  Same shape as `at(1)`. Picked when the user says "remind me at 3pm",
-  "send the report next Monday" — anything that doesn't repeat.
-
-## Goal
-
-Enable scheduled agent work — daily reports, periodic monitoring digests,
-one-off reminders, scheduled data refreshes — without leaving a session
-open or wiring external schedulers (cron, systemd timers, etc.).
-
-Non-goals:
-
-- **One-off ad-hoc invocations bound to "fresh state" per fire.** Each
-  job has a stable `cron-<jobId>` session id; first fire creates it,
-  subsequent fires resume it. So history accumulates over time and the
-  user can review the full conversation in the admin Sessions tab.
-  Threading via `-s cron-<jobId>` lets the agent remember what it told
-  the channel last week without each prompt needing to bootstrap from
-  `.halo/memory/`.
-- **Conditional / event-driven triggers.** Only time-based scheduling.
-- **Cross-job orchestration.** Each job is independent.
-
-## Components
-
-### Storage
-
-`~/.halo/global/cron.db` (sqlite + drizzle, parallel to `evo.db`).
-
-```sql
-cron_jobs(
-  id              TEXT PRIMARY KEY,
-  label           TEXT,                  -- nullable
-  workspace_path  TEXT NOT NULL,
-  agent_id        TEXT NOT NULL,
-  user_prompt     TEXT NOT NULL,
-  schedule        TEXT NOT NULL,         -- 5-field cron; '' for at-mode
-  run_at          INTEGER,               -- one-shot fire time (epoch ms);
-                                         -- mutually exclusive with `schedule`
-  timezone        TEXT,                  -- IANA zone, null = host TZ
-  targets         TEXT NOT NULL          -- JSON array of
-                                         -- {channelType, accountId, chatId?}
-                  DEFAULT '[]',
-  enabled         INTEGER NOT NULL DEFAULT 1,
-  last_run_status TEXT,                  -- runner-managed cache
-  last_run_at     INTEGER,
-  last_run_id     TEXT,
-  created_at      INTEGER NOT NULL,
-  updated_at      INTEGER NOT NULL
-)
-
-cron_runs(
-  id               TEXT PRIMARY KEY,
-  job_id           TEXT NOT NULL,
-  trigger_kind     TEXT NOT NULL,        -- 'scheduled' | 'manual'
-  status           TEXT NOT NULL,        -- running | succeeded | failed | timeout
-  started_at       INTEGER NOT NULL,
-  completed_at     INTEGER,
-  output           TEXT,                 -- final cli stdout
-  exit_code        INTEGER,
-  failure_reason   TEXT,
-  log_path         TEXT,                 -- absolute path to per-run log file
-  dispatch_results TEXT                  -- JSON array of per-recipient outcomes
-                                         -- {channelType, accountId, chatId?, ok, error?}
-)
-```
-
-`run_at` is added in-place to pre-existing dbs via a `PRAGMA table_info`
-guard in `createCronDb` (idempotent ALTER) — no manual migration step.
-
-Per-target `chatId` pins delivery to a specific conversation. For
-**telegram / slack / feishu** it is required — the dispatchers reject
-targets without one (the old "fan out to allowedUsers" / "fall back to
-lastActiveChatId" behaviour was removed because in practice the most-
-recent inbound was rarely the cron creator, and the result kept landing
-in a stranger's chat). For **wechat** it stays optional — wechat has a
-QR-bound owner so single-recipient delivery has an obvious target.
-
-Cron jobs created from inside a chat via the `manage-cron-jobs` skill auto-pin
-the originating `chatId` (the channel context exposes it as
-`{{channel.chat_id}}`). Admin-UI cron jobs that don't specify a chatId
-for tg/slack/feishu run silently — the result shows in the cron log,
-nothing is pushed.
-
-Why a separate db: same reasoning as `evo.db` — global, cross-workspace
-state shouldn't live inside any one workspace's `.halo/`. The runner
-itself is workspace-agnostic.
-
-### Runner — `packages/server/src/cron/runner.ts`
-
-Boot path:
-1. `startCronDaemon()` is called from server `index.ts` after
-   `setCronDb(...)`.
-2. Reads every `enabled=1` row, instantiates a croner schedule per job.
-   - Recurring rows: `new Cron(job.schedule, { timezone }, fn)`.
-   - One-shot rows (`runAt` set): `new Cron(new Date(job.runAt), …, fn)`.
-     croner accepts a `Date` and self-stops after firing once. Past-due
-     `runAt` is logged and skipped — the user can still fire via run-now.
-3. Starts two timers:
-   - `pruneOldLogs` — daily, drops log files past 30-day retention and
-     `cron_runs` rows past 60 days.
-   - `reconcileFromDb` — every 10 seconds, syncs the in-memory schedule
-     map against db rows. Detects adds / removes / schedule / runAt /
-     timezone / enabled changes and patches the croner instances
-     accordingly. Cheap (small table) and covers out-of-band edits (the
-     `manage-cron-jobs` skill writes via `sqlite3` rather than the REST
-     API). Per-row fingerprint = `enabled|schedule|runAt|timezone`.
-
-When a fire happens:
-1. `runJob(jobId, 'scheduled')` writes a `cron_runs` row with
-   `status='running'`.
-2. Spawns `halo cli -a <agentId> -s cron-<jobId> -w <workspacePath>` with
-   the prompt piped on **stdin** (not argv — a long prompt would overflow the
-   Windows command-line limit). A Node timer kills the child after
-   `CLI_TIMEOUT_SEC` and reports exit 124 — same contract as the Linux-only
-   `timeout(1)` binary, but cross-platform.
-   On Windows `resolveHaloCli()` returns `halo.cmd` (not bare `halo`):
-   the desktop installer drops `halo.cmd` and `Halo.exe` into the same
-   dir on PATH, and PATHEXT ranks `.EXE` above `.CMD`, so a bare `halo`
-   would launch the GUI instead of the cli. Spawning a `.cmd` directly is
-   rejected by Node ≥21.7 (EINVAL), so the child is routed through
-   `cmd.exe /c` on Windows.
-   On **macOS** bare `halo` resolves via PATH to the `/usr/local/bin`
-   launcher, but a Finder/Dock-launched desktop app has only launchd's
-   minimal PATH — so the Electron main process prepends the standard CLI
-   dirs to the server child's `env.PATH` (see `dev/desktop-packaging.md`),
-   otherwise this spawn would `ENOENT`.
-   The `-s` flag uses **create-on-missing semantics** (added alongside
-   cron): if the session id already exists in `agent_sessions`, cli
-   resumes it; if not, cli creates a new row with that exact id. So the
-   first fire bootstraps the session, every subsequent fire continues
-   the same conversation, and the user can review history in the admin
-   Sessions tab. The `cron-<jobId>` prefix avoids collision with normal
-   `cli_*` / `tg_*` / `wx_*` ids.
-   Same shape as the evo wrapper (`spawn` + tee'd stdout/stderr to
-   `~/.halo/global/logs/cron/<runId>.log`).
-3. On exit:
-   - Exit 0 + non-empty stdout → `succeeded`, dispatch the trimmed
-     stdout to every target.
-   - Exit 124 → `timeout`.
-   - Anything else → `failed` with stderr tail as `failure_reason`.
-   - Empty output on exit 0 → `failed: cli produced no output`.
-4. If every target's dispatch failed, downgrade the run status to
-   `failed` so the UI surfaces the issue (and so a job that always
-   times-out on telegram doesn't keep showing green).
-5. **At-mode auto-disable.** `finalize` looks up the row; when `runAt`
-   is set, it patches `enabled=0` alongside the lastRunStatus update.
-   Reconcile then tears down the croner instance on its next pass.
-   The row is kept (so the admin UI shows it under run history; user
-   can still hit run-now to refire).
-
-### Dispatcher — `packages/server/src/cron/dispatcher.ts` (registry)
-
-The dispatcher is **channel-agnostic**. It exposes a tiny registry
-(`registerCronDispatcher`) and a single fan-out entry-point
-(`dispatchToTargets`); each channel module supplies its own
-`CronChannelDispatcher` and registers it at server boot. There is no
-switch-on-channelType anywhere in `cron/`.
-
-```ts
-interface CronChannelDispatcher {
-  channelType: string
-  dispatch: (accountId: string, text: string, chatId?: string) => Promise<DispatchResult[]>
-  listTargets?: () => CronTargetOption[]   // for admin UI dropdown
-}
-```
-
-`dispatch` returns one `DispatchResult` row per recipient. Today every
-channel is single-recipient (one explicit chatId → one row), but the
-array shape is preserved so a future channel that supports broadcast
-could return N. Throwing wraps into a single failed-result.
-
-Channel modules:
-
-- `packages/server/src/channels/telegram/cron-dispatcher.ts` —
-  `registerTelegramCronDispatcher()`. Requires explicit numeric `chatId`;
-  errors otherwise. (Previous build fanned out to `allowedUsers` and fell
-  back to `lastActiveChatId`; both removed because cron output kept
-  landing in unrelated chats.)
-- `packages/server/src/channels/wechat/cron-dispatcher.ts` —
-  `registerWechatCronDispatcher()`. Single-recipient with chained
-  fallback: explicit `chatId` → account `userId` (QR-bind owner) →
-  cached `lastActiveChatId`. WeChat keeps the fallback because the
-  QR-bound owner is a stable, unambiguous target.
-- `packages/server/src/channels/slack/cron-dispatcher.ts` —
-  `registerSlackCronDispatcher()`. Requires explicit `chatId` shaped as
-  `D…` (DM), `C…` (channel top-level), or `C…:<thread_ts>` (anchored
-  inside a thread). Posts via `postMessage` with `thread_ts` set when
-  present.
-- `packages/server/src/channels/feishu/cron-dispatcher.ts` —
-  `registerFeishuCronDispatcher()`. Requires explicit `chatId` shaped as
-  `oc_…`. Posts via the v1 messages API with `receive_id_type=chat_id`.
-  (A `:rootId` suffix is accepted in the storage shape for forward-compat
-  but currently ignored — Feishu's open API has no thread-anchored
-  sendMessage path analogous to Slack's `thread_ts`.)
-
-Both register at server boot in `index.ts`. **Adding a new channel = ship
-a `cron-dispatcher.ts` next to its handler + register it once.** Nothing
-in `cron/` or `routes/cron.ts` needs to change.
-
-`listTargets()` per channel feeds the admin UI's create-form dropdown
-via `listAllCronTargets()` (aggregator). `ready` flag: wechat = QR-bind
-userId OR cached lastActiveChatId; telegram / slack / feishu always
-report `ready=true` (readiness depends on the per-target `chatId` the
-admin picks, not on prior inbound history). The admin form has a
-per-target chatId input + search dropdown for slack/feishu, backed by
-`users.conversations` / `/im/v1/chats`. Channels with no UI-pickable
-surface (a hypothetical webhook channel) can omit `listTargets`.
-
-`DispatchResult` shape:
-
-```ts
-{ channelType, accountId, chatId?, ok, error? }
-```
-
-`chatId` is recorded so the admin UI can render per-recipient outcomes
-("slack:T01234/D012345 ✓ · feishu:appA/oc_xxx ✗ (no permission)") when a
-job has multiple targets, instead of just a single ok/fail roll-up.
-
-### Realtime updates — WS broadcast (no client polling)
-
-The admin UI subscribes to `cron:job_changed` and `cron:run_changed`
-events on the existing `/ws` channel rather than polling on a timer.
-Server emits them at every state-change point:
-
-- `runner.runJob` insert of the `running` cron_runs row →
-  `cron:run_changed status='running'`
-- `runner.finalize` (success/failure/timeout) →
-  `cron:run_changed status='succeeded'|'failed'|'timeout'` plus a
-  `cron:job_changed` so the list's "last run" badge updates
-- REST routes (POST/PUT/DELETE on `/cron/jobs[/:id]`) →
-  `cron:job_changed kind='created'|'updated'|'deleted'`
-
-Broadcast is fan-out via `ws/broadcast.ts` to every connected admin
-socket. Idle traffic is ~zero.
-
-### REST routes — `packages/server/src/routes/cron.ts`
-
-Standard CRUD over `cron_jobs` plus:
-
-- `POST /api/cron/jobs/:id/run-now` — fire-and-forget; returns
-  immediately, run status flips broadcast as cron:run_changed events.
-- `GET /api/cron/jobs/:id/runs?limit=N&before=<runId>` — cursor-paged
-  history. `runId` is `<isoTimestamp>-<slug>`, so its lexicographic
-  order matches time — `id < cursor` gives "older than" without a
-  numeric sequence column. Response: `{ runs, hasMore, nextCursor }`.
-- `GET /api/cron/runs/:runId/log` — raw log content (or null if past
-  retention).
-- `GET /api/cron/channel-targets` — the create-form's list of bindable
-  channel accounts. Aggregated from the registry via
-  `listAllCronTargets()` — routes/cron.ts is channel-agnostic. `ready`
-  flag is computed inside each channel's `listTargets()` (see
-  "Dispatcher" above for the per-channel rules).
-- `POST /api/cron/reload` — force re-read all schedules. Rarely needed
-  (reconcile already polls); useful after manual db edits if you don't
-  want to wait 10 seconds.
-
-All routes go through the standard auth middleware — same cookie/token
-as the rest of `/api`.
-
-### Agent skill — `templates/skills/manage-cron-jobs/`
-
-Registered in `init.ts`'s `BUILTIN_SKILL_IDS`. Frontmatter has
-`requiresAccess: full`, so readonly / workspace channels (like a
-public-facing telegram bot) can't see or invoke this skill — only
-admin-shell agents can. The skill ships with a `manage-cron.py` helper
-that the agent calls via `shell_exec`; the script handles id
-generation, target JSON encoding, and timestamps so the agent isn't
-hand-crafting SQL.
-
-The runner's reconcile loop picks up db changes within ~10 seconds and
-broadcasts `cron:job_changed { kind: 'reconciled' | 'deleted' }` so
-admin UIs in another tab/browser see the same edit. The skill doesn't
-need REST/auth — it's filesystem + sqlite, with the in-process runner
-catching up on its own pace.
-
-The skill walks the agent through:
-1. Identifying user intent (list / create / edit / delete).
-2. Defaulting workspace (current), agent (`default`), targets (current
-   chat when invoked from a channel — see channel context below).
-3. Translating spoken-time → 5-field cron (recurring) **or** ISO-8601
-   instant (`--run-at`, one-shot at-mode).
-4. Querying `channels.db` for available targets and surfacing
-   readiness warnings (currently only wechat can be `ready=false`).
-5. Writing the appropriate INSERT/UPDATE/DELETE.
-
-**Channel context at skill invocation.** When the user triggers the
-`manage-cron-jobs` skill from inside a telegram / wechat / slack / feishu
-chat, the channel handler injects structured origin into the skill's
-render context as built-in placeholders: `{{channel.type}}`,
-`{{channel.account_id}}`, `{{channel.chat_id}}`. The skill body uses
-these to default the `--targets` flag to `<type>:<account_id>:<chat_id>`
-so the schedule keeps replying in the same conversation. Admin/WS
-invocations leave the placeholders empty — the skill then either asks
-for an explicit chatId or accepts a silent (no-target) cron.
-
-**Reverse-lookup by chatId.** Inside a chat the user doesn't know the
-cron `id` ("delete the daily digest I set up here"). The helper script
-exposes `list --chat-id <id>` that filters `cron_jobs` to those whose
-`targets[].chatId` matches. The skill uses
-`list --chat-id {{channel.chat_id}}` to find candidate jobs, confirms
-with the user, then deletes by id. Different channels' chatId formats
-don't collide (telegram numeric, slack `D…/C…`, feishu `oc_…`,
-wechat `o…`), so a single chatId match is unambiguous across channels.
-
-### Admin UI — `packages/admin/src/features/cron/cron-main.tsx`
-
-Activity-bar entry next to Evolution. Two-pane layout matching
-Evolution's: list of jobs on the left, detail panel on the right with
-run history and edit/run-now/delete actions. Form supports both create
-and edit. Form pulls workspace + agent + channel-target options from
-existing APIs (`/api/agent-configs`, `/api/cron/channel-targets`).
-
-## Boot
-
-`packages/server/src/index.ts`:
-```ts
-setChannelDb(channelDb)                              // for dispatcher's getChannelDb()
-setCronDb(createCronDb(path.join(HALO_HOME, 'global')))
-// `bootChannels` walks `defaultChannelDescriptors` and calls each
-// descriptor's `registerCronDispatcher` (alongside its handler/route
-// setup). Order is irrelevant — the registry is keyed by channelType.
-bootChannels(app, defaultChannelDescriptors, { registry, db: channelDb })
-// Daemon starts after channels boot so the registry is fully populated
-// before the first scheduled fire.
-startCronDaemon()
-```
-
-`packages/server/src/init.ts` `BUILTIN_SKILL_IDS` includes
-`manage-cron-jobs` so `halo setup` deploys the skill.
-
-## Known limits
-
-- **No mid-run heartbeat.** If the server crashes between the
-  `cron_runs.insert(status='running')` and the cli exit handler, the row
-  is stranded in `running`. (Evo handles this via heartbeat + ticker
-  recovery.) For cron, runs are short (<10 minutes by `timeout`) and
-  infrequent; we accept the rough edge for now. Fix: add a daily
-  scanner that flips stale-running rows to `failed: server crashed`.
-- **Web channel can't deliver.** SSE channel is reactive-only; cron
-  records a clear failure rather than swallowing.
-- **No retry.** Failed runs stay failed; user sees them in history and
-  decides whether to investigate or wait for the next fire.
-- **Single-process scheduler.** Two server instances against the same
-  global db would both schedule the same jobs. Today there's only ever
-  one server per host (pid lock); document & enforce when that
-  assumption ever breaks.
-- **`run-now` ignores enabled flag.** A disabled job can still be
-  fired manually from the UI for testing — the schedule is paused, the
-  runner code path isn't.

package/bundled-docs/plans/design-suggestions.md

@@ -1,203 +0,0 @@
-# Session persistence and orchestration — design suggestions
-
-Captured while debugging the "third message freeze" bug (`text content blocks must be non-empty`) — documents the structural issues found and proposes improvements over the current state. Everything revolves around **session message state**: multiple write paths, multiple sources of truth, and lossy backward inferences — the shared root of that bug.
-
----
-
-## 1. Make message persistence one-way — `rawMessages` as the single source of truth
-
-### Current state
-
-Each session maintains two copies:
-
-- **`rawMessages`**: Strands Agent's internal `agent.messages`, Bedrock's native format including full `tool_use` / `tool_result` pairs. Persisted by `saveAgentState` at turn end.
-- **`messages`**: the UI display log, assembled by `event-processor` from streaming events (assistant text, tool_call cards, usage badges, etc.). Rendered directly on refresh.
-
-The two paths write independently; consistency relies on order-of-ops going right.
-
-### Problem
-
-This bug came from a third path — `handler.ts`'s `restoreHistory(sid, client.messageLog)` — that tried to reverse the UI log back into `rawMessages`. Tool-only assistant turns in the UI log have empty-string content (tool cards don't live in the content field), so the inverse maps them to `{type: 'text', text: ''}` and Bedrock rejects it.
-
-As long as the "UI log → rawMessages" direction exists, "restore agent state from UI" will keep producing bugs like this.
-
-### Suggestion
-
-- **`rawMessages` is the sole source of truth**; the UI log is derived.
-- **Never infer `rawMessages` from the UI log.**
-- On refresh / reconnect: UI log is loaded directly from disk (for rendering), `rawMessages` is lazily loaded by `ensureSession` (for the next Bedrock call). The two paths run **in parallel and don't rebuild each other.**
-- Compact should also operate on `rawMessages` — summarise, replace the old slice, then derive the new UI log from the event stream. Not "edit UI log then reverse-derive".
-
----
-
-## 2. Run repair once before every Bedrock call
-
-### Current state
-
-`repairConversationMessages` currently runs:
-
-- At turn end (end of `runAgentTurn`)
-- After interrupt / stop
-- After compact
-
-But **not before `sendUserMessage` hands over to Bedrock**.
-
-### Problem
-
-On-disk `rawMessages` may be unhealthy due to older bugs, external edits, version upgrades, etc. Today, once `ensureSession` loads bad state from disk, it gets sent to Bedrock and triggers the same kind of crash we just hit.
-
-I've added "drop empty text blocks" as a safety net in `conversation-repair.ts`; still, moving the defensive step forward catches future unknown bad data.
-
-### Suggestion
-
-- In `sendUserMessage`, before hitting `handleUserTurn`, call `repairConversationMessages(session.agent.messages)`.
-- Repair becomes the "last gate into Bedrock", so wherever rawMessages came from (new / disk restore / older-version file), it's cleansed.
-- Performance is fine: repair is O(n) and n is not large.
-
----
-
-## 3. Sub-session log persistence: move "merge-save" out of event-processor, into SessionManager
-
-### Current state
-
-`event-processor.ts`'s `saveSubSession`:
-
-```
-On every query_session / start_session
-  → subSessionLogs initialised in memory
-  → event stream writes into it
-  → on agent_done: read from disk → merge by message id → write back
-```
-
-`subSessionLogs` is client-connection-level (WebSocket), rebuilt per query and holding only this turn's events. Hence the merge.
-
-### Problem
-
-- **merge-by-id depends on "ids are consistent and unique"**. Any id jitter, reconnect-leftover state, or duplicate `initSubSessionLog` call produces lost or duplicate messages.
-- **Persistence is coupled to the network layer**. event-processor should just forward events to the WS; here it also takes on "cross-connection disk merge". Violates CLAUDE.md's "persistence must not depend on in-memory transient state" — `subSessionLogs` is in-memory transient state.
-- **Reconnect / refresh is error-prone**: a new connection creates a new `subSessionLogs`; unflushed events from the old one are lost; detach creates yet another independent copy in `backgroundHandler`, and reconciling both is a hazard.
-
-### Event loss risk (extended)
-
-This is a separate risk beyond the merge mechanism — an **eye-vs-disk** inconsistency where **events actually happened, but the log doesn't reflect them**. Scenarios:
-
-1. **Stream buffer not flushed before a crash**. `stream` events aggregate into in-memory `turnContentBlocks` / `streamBuffer`; only `usage` / `agent_done` / `complete` trigger `flushAssistantMessage` + `saveSubSession`. Crash beforehand (OOM, uncaught exception, kill) loses every piece of streaming text and tool_call for the turn — disk has no trace the agent said anything.
-
-2. **WS-disconnect brief window**. Between disconnect and `backgroundHandler` takeover is a window where `sendJson` fails and the event is silently dropped; grace expiry triggers a single `save()`, and a crash in between loses the whole stretch.
-
-3. **Merge id jitter losing messages**. `saveSubSession` dedupes by `m.id`, but `genId()`'s counter is process-scoped — process restart resets the counter. A restart between two flushes can produce same-id-different-message entries; merge overwrites them.
-
-4. **Event semantics vs disk state out of sync**. Frontend / logs already saw a `tool_call` fire (went through `sendJson`), but it's only in the in-memory `messageLog`; the next `saveSubSession` writes it. Checking disk in between makes it look like nothing happened. Fatal for audit-log use cases.
-
-### Suggestion
-
-**Short-term (bundle with the merge issue)**:
-- SessionManager **owns** the sub-session UI log (persisted alongside `rawMessages`), append-only, single-process concurrency-safe.
-- event-processor reverts to **pure forwarding**: receive event → push to WS; no persistence duty.
-- Tighten flush granularity from "key events" to "every tool_call / tool_result / every N seconds" to shrink the crash window.
-
-**Long-term (fully eliminate event loss)**:
-- Switch to an **append-only JSONL event log**: every agent event lands as a new line in `.halo/sessions/{agentId}/{sessionId}.jsonl` the moment it fires.
-- Renderers aggregate to `SessionMessage[]` on load (event-sourcing projection).
-- Cost: higher disk I/O (one-write-per-stream-delta is too much). Compromise: "every tool_call / tool_result / end-of-assistant-paragraph / every 500 ms batch append".
-- Benefit: crash window shrinks from "whole turn" to "last flush interval"; disk is a faithful log of events, no code-path skipping `save()` loses a whole stretch.
-
----
-
-## 4. `query_session` to an IDLE target: `onComplete` vs `releaseSession` race
-
-### Current state
-
-```typescript
-// session-manager.ts :1166
-this.runSession(targetSessionId, prefix + message).then((result) => {
-  onComplete?.(result)
-})
-return `Message sent to session ${targetSessionId}...`
-```
-
-`runSession` is fire-and-forget with `onComplete` in `.then()`. But `runSession`'s own `finally` (:1030) immediately calls `releaseSession`.
-
-### Problem
-
-JavaScript microtask scheduling usually keeps `finally` before the `.then()` callback, but the race exists:
-
-- `finally`'s `releaseSession` drops the session from memory.
-- Immediately after, `.then(onComplete)` fires; `onComplete` itself calls `querySession(sessionId, childSessionId, result)` (auto-report to source), and that `querySession` does `ensureSession(childSessionId)` — which has to go through the disk restore path since memory is gone.
-- If the disk save hasn't fully flushed (`saveAgentState` is synchronous but can be interleaved by the Node event loop), or something else is writing concurrently, `ensureSession` might read stale state.
-
-Not guaranteed, but the window exists. E3 (query_session to an idle sub-agent) can likely reproduce under concurrency / repetition.
-
-### Suggestion
-
-- Chain `onComplete` onto `session.promise` itself, so "`runSession` fully finishes (including `releaseSession`) → `onComplete` → next `querySession`" runs strictly in sequence.
-- Or simpler: have `querySession` itself `await runSession` and call `onComplete` synchronously, avoiding `.then()` entirely.
-- Add a "just-released session stays in memory for N ms" cache window in `ensureSession` to damp rapid release/restore cycles.
-
----
-
-## 5. Post-disconnect event replay needs a barrier on reconnect
-
-### Current state
-
-WS disconnects:
-- Session marked "detached", `backgroundHandler` registered
-- Events flow into `detached.pendingEvents`
-
-WS reconnects:
-- `handleSubscribe` detects the detached session → replays `pendingEvents` one by one via `sendJson`
-- Meanwhile switches the listener back to the new WS's live callback
-
-### Problem
-
-There's no barrier between listener switch and `pendingEvents` replay. If SessionManager is currently emitting a new event:
-
-- The new event (B) goes through the live listener to the new WS
-- Older `pendingEvents` (A) are still being sent one-by-one
-- Frontend sees B before A — out of order
-
-F2 ("disconnect → reconnect") + "steady events during disconnect + fresh events at the moment of reconnect" can reproduce it.
-
-### Suggestion
-
-- On reconnect, hold a lock: `pendingEvents` keeps accepting but doesn't **drain**; the listener is still on the background handler.
-- Atomic switchover: `listener replace + pendingEvents drain + subSessionLogs restore` is one transaction; new events during this keep flowing to `pendingEvents`.
-- After the transaction, flush `pendingEvents` and switch the listener to the new WS.
-- Add an integration test: F2 scenario + forced concurrent events; watch the sequence numbers arriving on the frontend are monotonically increasing.
-
----
-
-## 6. Clean up the deprecated `destroySessions`
-
-### Current state
-
-`session-manager.ts` has a `@deprecated`-tagged `destroySessions` method with a doc saying "Use deleteSession + deleteSessionLogs in Phase 3".
-
-### Problem
-
-- It's debt — deprecated methods can still be called accidentally, and they raise eyebrows in review.
-- New readers get confused: which one do I use?
-- Keeping two deletion paths means every future change has to consider both.
-
-### Suggestion
-
-- Just delete `destroySessions`.
-- Grep-verify no callers (from `.halo/docs/` through `packages/`).
-- If stragglers exist, migrate them to `deleteSession` + `deleteSessionLogs`, then delete.
-
----
-
-## Priority
-
-By fix-value vs change-footprint:
-
-| # | Suggestion | Priority | Scope |
-|---|---|---|---|
-| 2 | Repair before sendUserMessage | High | one line |
-| 6 | Delete destroySessions | High | one method |
-| 1 | One-way (forbid UI→raw inverse) | High | architectural principle |
-| 4 | Fix onComplete race | Medium | one callback |
-| 5 | Reconnect event barrier | Medium | one subsystem |
-| 3 | Sink sub-session persistence | Low, long-term | larger refactor |
-
-1, 2, 6 can be done right away; 4, 5 deserve integration tests first. 3 is the long-term direction — not urgent, but inevitable.