jeo-code 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -6,6 +6,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The README mirrors the latest 5 entries — regenerate with `bun run changelog:sync`.
 
+## [Unreleased]
+
+## [0.9.2] - 2026-07-26
+_Released the jeo-native GJC v0.11.6–v0.11.9 parity improvements after a complete cross-audit and live verification pass._
+
+### Added
+- **Bounded, non-destructive `/handoff [focus]` summaries** (`src/agent/compaction.ts`, `src/commands/launch.ts`) — generates a session handoff document without mutating history, preserves touched-file references, supports an optional configured focus, and exposes the command through help/autocomplete.
+- **Bounded inbound Telegram attachment downloads** (`src/agent/notify/telegram-api.ts`) — rejects oversized bodies before/while buffering and keeps caption delivery text-only when an attachment is rejected.
+- **Platform-native TUI modifier hints** (`src/tui/components/hints.ts`, `src/tui/app.ts`) — renders macOS `⌃` labels or portable `Ctrl+` labels with an ASCII fallback.
+
+### Fixed
+- **Durable fatal crash breadcrumbs** (`src/util/crash-log.ts`) — writes owner-only, UTF-8-bounded, secret-redacted crash records before fatal stderr handling, resetting at the file ceiling and never masking the original exception.
+
+### Verified
+- Focused parity suite: 191 pass / 0 fail across handoff, crash-log, Telegram attachment, TUI hint, slash registry, and autocomplete tests.
+- `bun run typecheck`: clean.
+- Live piped `jeo --no-tui` `/handoff` scenario: short history is rejected non-destructively with an explicit message.
+- Full `bun test` was attempted for 300 seconds but remained affected by pre-existing host-load timeouts/failures in write-parallel, team-parallel, engine-multitool, team-subagent, and daemon timing tests; no focused parity test failed.
+
 ## [0.9.1] - 2026-07-24
 _User request (paraphrased, Korean): "make the TUI resize responsively like gjc's TUI when terminal width/height changes, without breaking the layout — also borrow forge's layout and table components." Investigated the existing resize infrastructure first (already extensive: throttled live-frame resize repaint, a poll-based SIGWINCH safety net, resize-aware interactive pickers) before assuming a gap. Found one concrete un-responsive panel — `jeo doctor`'s Provider connectivity table — and, while rebuilding it on forge's own box-drawn table renderer, also found and fixed a real, previously-unknown overflow bug in `formatForgeBox` itself, shared by every tool card across the whole live TUI._
 

package/README.ja.md

@@ -284,11 +284,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[Unreleased]**
+- **[0.9.2]** (2026-07-26) — Released the jeo-native GJC v0.11.6–v0.11.9 parity improvements after a complete cross-audit and live verification pass.
 - **[0.9.1]** (2026-07-24) — User request (paraphrased, Korean): "make the TUI resize responsively like gjc's TUI when terminal width/height changes, without breaking the layout — also borrow forge's layout and table components." Investigated the existing resize infrastructure first (already extensive: throttled live-frame resize repaint, a poll-based SIGWINCH safety net, resize-aware interactive pickers) before assuming a gap. Found one concrete un-responsive panel — `jeo doctor`'s Provider connectivity table — and, while rebuilding it on forge's own box-drawn table renderer, also found and fixed a real, previously-unknown overflow bug in `formatForgeBox` itself, shared by every tool card across the whole live TUI.
 - **[0.9.0]** (2026-07-22) — Session-scoped async execution, detached subagent control, background monitors, and parallel TUI activity are now documented and shipped for the gjc-parity release line.
 - **[0.8.42]** (2026-07-21) — Request (paraphrased): "adopt gjc's subagent execution model and TUI parallel-processing monitoring — all the async/parallel parts — into jeo-code, with real operational verification." Investigated live before assuming a gap: jeo already has a mature, gjc-parity concurrent fan-out worker pool (`MAX_FANOUT`-bounded `Promise.all`, broadcast steering hub, detached/subagent/job/irc tools, a live TUI panel for concurrent subagents). Booted real `jeo --tmux` sessions with real credentials and repeatedly drove a genuine 3-file concurrent executor fan-out to verify this stack end to end — not to re-implement what already works, but to find what's actually broken in it. Found and fixed three real, live-reproduced bugs across the fan-out call path, none of them "missing gjc parity" — all pre-existing defects in jeo's own already-built implementation.
-- **[0.8.41]** (2026-07-21) — Ponytail-mode review requested directly ("review ponytail") over the two files this session's most recent pass (v0.8.40) touched: `src/agent/notify/daemon-control.ts` and `src/commands/launch/route-slash.ts`. Self-review found no correctness bugs (the v0.8.40 logic held up), but did find real, concrete style-bloat and one genuine test-coverage gap — both fixed with evidence, per the established convention.
-- **[0.8.40]** (2026-07-21) — User report (paraphrased): "the /route command doesn't work, fix it." Investigated live before assuming a defect — booted a real `jeo --tmux` session with real Anthropic OAuth credentials from the actual `~/.jeo/config.json` and drove `/route status|on|off|why|history|bogus` plus real end-to-end routed turns. Every subcommand and the routing engine itself (heuristic tiering, `roles.smol` resolution, live provider call, per-turn "thinking" card showing the routed model) worked correctly, including a real stale-catalog edge case (`roles.smol: "claude-haiku-4-5"`, removed from jeo's own catalog in an earlier curation pass, still being accepted directly by the Anthropic API). The one genuine, reproducible gap: `/route on` is SESSION-LOCAL ONLY — `config.routing.enabled` in `~/.jeo/config.json` is never written, so a user has to retype `/route on` at the start of every single session, and (separately, working as designed but easy to miss) an explicit `--model`/`/model` pin silently blocks routing from ever engaging unless `/route on` is run to override it that session. The "settings don't stick" experience is the most likely reading of "doesn't work."
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -285,11 +285,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[Unreleased]**
+- **[0.9.2]** (2026-07-26) — Released the jeo-native GJC v0.11.6–v0.11.9 parity improvements after a complete cross-audit and live verification pass.
 - **[0.9.1]** (2026-07-24) — User request (paraphrased, Korean): "make the TUI resize responsively like gjc's TUI when terminal width/height changes, without breaking the layout — also borrow forge's layout and table components." Investigated the existing resize infrastructure first (already extensive: throttled live-frame resize repaint, a poll-based SIGWINCH safety net, resize-aware interactive pickers) before assuming a gap. Found one concrete un-responsive panel — `jeo doctor`'s Provider connectivity table — and, while rebuilding it on forge's own box-drawn table renderer, also found and fixed a real, previously-unknown overflow bug in `formatForgeBox` itself, shared by every tool card across the whole live TUI.
 - **[0.9.0]** (2026-07-22) — Session-scoped async execution, detached subagent control, background monitors, and parallel TUI activity are now documented and shipped for the gjc-parity release line.
 - **[0.8.42]** (2026-07-21) — Request (paraphrased): "adopt gjc's subagent execution model and TUI parallel-processing monitoring — all the async/parallel parts — into jeo-code, with real operational verification." Investigated live before assuming a gap: jeo already has a mature, gjc-parity concurrent fan-out worker pool (`MAX_FANOUT`-bounded `Promise.all`, broadcast steering hub, detached/subagent/job/irc tools, a live TUI panel for concurrent subagents). Booted real `jeo --tmux` sessions with real credentials and repeatedly drove a genuine 3-file concurrent executor fan-out to verify this stack end to end — not to re-implement what already works, but to find what's actually broken in it. Found and fixed three real, live-reproduced bugs across the fan-out call path, none of them "missing gjc parity" — all pre-existing defects in jeo's own already-built implementation.
-- **[0.8.41]** (2026-07-21) — Ponytail-mode review requested directly ("review ponytail") over the two files this session's most recent pass (v0.8.40) touched: `src/agent/notify/daemon-control.ts` and `src/commands/launch/route-slash.ts`. Self-review found no correctness bugs (the v0.8.40 logic held up), but did find real, concrete style-bloat and one genuine test-coverage gap — both fixed with evidence, per the established convention.
-- **[0.8.40]** (2026-07-21) — User report (paraphrased): "the /route command doesn't work, fix it." Investigated live before assuming a defect — booted a real `jeo --tmux` session with real Anthropic OAuth credentials from the actual `~/.jeo/config.json` and drove `/route status|on|off|why|history|bogus` plus real end-to-end routed turns. Every subcommand and the routing engine itself (heuristic tiering, `roles.smol` resolution, live provider call, per-turn "thinking" card showing the routed model) worked correctly, including a real stale-catalog edge case (`roles.smol: "claude-haiku-4-5"`, removed from jeo's own catalog in an earlier curation pass, still being accepted directly by the Anthropic API). The one genuine, reproducible gap: `/route on` is SESSION-LOCAL ONLY — `config.routing.enabled` in `~/.jeo/config.json` is never written, so a user has to retype `/route on` at the start of every single session, and (separately, working as designed but easy to miss) an explicit `--model`/`/model` pin silently blocks routing from ever engaging unless `/route on` is run to override it that session. The "settings don't stick" experience is the most likely reading of "doesn't work."
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -292,11 +292,11 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[Unreleased]**
+- **[0.9.2]** (2026-07-26) — Released the jeo-native GJC v0.11.6–v0.11.9 parity improvements after a complete cross-audit and live verification pass.
 - **[0.9.1]** (2026-07-24) — User request (paraphrased, Korean): "make the TUI resize responsively like gjc's TUI when terminal width/height changes, without breaking the layout — also borrow forge's layout and table components." Investigated the existing resize infrastructure first (already extensive: throttled live-frame resize repaint, a poll-based SIGWINCH safety net, resize-aware interactive pickers) before assuming a gap. Found one concrete un-responsive panel — `jeo doctor`'s Provider connectivity table — and, while rebuilding it on forge's own box-drawn table renderer, also found and fixed a real, previously-unknown overflow bug in `formatForgeBox` itself, shared by every tool card across the whole live TUI.
 - **[0.9.0]** (2026-07-22) — Session-scoped async execution, detached subagent control, background monitors, and parallel TUI activity are now documented and shipped for the gjc-parity release line.
 - **[0.8.42]** (2026-07-21) — Request (paraphrased): "adopt gjc's subagent execution model and TUI parallel-processing monitoring — all the async/parallel parts — into jeo-code, with real operational verification." Investigated live before assuming a gap: jeo already has a mature, gjc-parity concurrent fan-out worker pool (`MAX_FANOUT`-bounded `Promise.all`, broadcast steering hub, detached/subagent/job/irc tools, a live TUI panel for concurrent subagents). Booted real `jeo --tmux` sessions with real credentials and repeatedly drove a genuine 3-file concurrent executor fan-out to verify this stack end to end — not to re-implement what already works, but to find what's actually broken in it. Found and fixed three real, live-reproduced bugs across the fan-out call path, none of them "missing gjc parity" — all pre-existing defects in jeo's own already-built implementation.
-- **[0.8.41]** (2026-07-21) — Ponytail-mode review requested directly ("review ponytail") over the two files this session's most recent pass (v0.8.40) touched: `src/agent/notify/daemon-control.ts` and `src/commands/launch/route-slash.ts`. Self-review found no correctness bugs (the v0.8.40 logic held up), but did find real, concrete style-bloat and one genuine test-coverage gap — both fixed with evidence, per the established convention.
-- **[0.8.40]** (2026-07-21) — User report (paraphrased): "the /route command doesn't work, fix it." Investigated live before assuming a defect — booted a real `jeo --tmux` session with real Anthropic OAuth credentials from the actual `~/.jeo/config.json` and drove `/route status|on|off|why|history|bogus` plus real end-to-end routed turns. Every subcommand and the routing engine itself (heuristic tiering, `roles.smol` resolution, live provider call, per-turn "thinking" card showing the routed model) worked correctly, including a real stale-catalog edge case (`roles.smol: "claude-haiku-4-5"`, removed from jeo's own catalog in an earlier curation pass, still being accepted directly by the Anthropic API). The one genuine, reproducible gap: `/route on` is SESSION-LOCAL ONLY — `config.routing.enabled` in `~/.jeo/config.json` is never written, so a user has to retype `/route on` at the start of every single session, and (separately, working as designed but easy to miss) an explicit `--model`/`/model` pin silently blocks routing from ever engaging unless `/route on` is run to override it that session. The "settings don't stick" experience is the most likely reading of "doesn't work."
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -284,11 +284,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[Unreleased]**
+- **[0.9.2]** (2026-07-26) — Released the jeo-native GJC v0.11.6–v0.11.9 parity improvements after a complete cross-audit and live verification pass.
 - **[0.9.1]** (2026-07-24) — User request (paraphrased, Korean): "make the TUI resize responsively like gjc's TUI when terminal width/height changes, without breaking the layout — also borrow forge's layout and table components." Investigated the existing resize infrastructure first (already extensive: throttled live-frame resize repaint, a poll-based SIGWINCH safety net, resize-aware interactive pickers) before assuming a gap. Found one concrete un-responsive panel — `jeo doctor`'s Provider connectivity table — and, while rebuilding it on forge's own box-drawn table renderer, also found and fixed a real, previously-unknown overflow bug in `formatForgeBox` itself, shared by every tool card across the whole live TUI.
 - **[0.9.0]** (2026-07-22) — Session-scoped async execution, detached subagent control, background monitors, and parallel TUI activity are now documented and shipped for the gjc-parity release line.
 - **[0.8.42]** (2026-07-21) — Request (paraphrased): "adopt gjc's subagent execution model and TUI parallel-processing monitoring — all the async/parallel parts — into jeo-code, with real operational verification." Investigated live before assuming a gap: jeo already has a mature, gjc-parity concurrent fan-out worker pool (`MAX_FANOUT`-bounded `Promise.all`, broadcast steering hub, detached/subagent/job/irc tools, a live TUI panel for concurrent subagents). Booted real `jeo --tmux` sessions with real credentials and repeatedly drove a genuine 3-file concurrent executor fan-out to verify this stack end to end — not to re-implement what already works, but to find what's actually broken in it. Found and fixed three real, live-reproduced bugs across the fan-out call path, none of them "missing gjc parity" — all pre-existing defects in jeo's own already-built implementation.
-- **[0.8.41]** (2026-07-21) — Ponytail-mode review requested directly ("review ponytail") over the two files this session's most recent pass (v0.8.40) touched: `src/agent/notify/daemon-control.ts` and `src/commands/launch/route-slash.ts`. Self-review found no correctness bugs (the v0.8.40 logic held up), but did find real, concrete style-bloat and one genuine test-coverage gap — both fixed with evidence, per the established convention.
-- **[0.8.40]** (2026-07-21) — User report (paraphrased): "the /route command doesn't work, fix it." Investigated live before assuming a defect — booted a real `jeo --tmux` session with real Anthropic OAuth credentials from the actual `~/.jeo/config.json` and drove `/route status|on|off|why|history|bogus` plus real end-to-end routed turns. Every subcommand and the routing engine itself (heuristic tiering, `roles.smol` resolution, live provider call, per-turn "thinking" card showing the routed model) worked correctly, including a real stale-catalog edge case (`roles.smol: "claude-haiku-4-5"`, removed from jeo's own catalog in an earlier curation pass, still being accepted directly by the Anthropic API). The one genuine, reproducible gap: `/route on` is SESSION-LOCAL ONLY — `config.routing.enabled` in `~/.jeo/config.json` is never written, so a user has to retype `/route on` at the start of every single session, and (separately, working as designed but easy to miss) an explicit `--model`/`/model` pin silently blocks routing from ever engaging unless `/route on` is run to override it that session. The "settings don't stick" experience is the most likely reading of "doesn't work."
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
   "main": "src/cli.ts",

package/src/agent/compaction.ts

@@ -486,3 +486,87 @@ export async function maybeCompact(
     touchedFiles: touched.length ? touched : undefined,
   };
 }
+export interface HandoffOptions {
+  model?: string;
+  /** Cap the summarizer prompt/output so a handoff document itself cannot balloon context. */
+  maxSummaryInputTokens?: number;
+  /** Optional focus text — CLI-typed `/handoff <focus>` argument, or the
+   *  configured `compaction.handoffFocus` default when no argument is given.
+   *  APPEND-ONLY: rendered as its own trailing section, never merged into or
+   *  replacing the base handoff sections above it. */
+  focus?: string;
+  signal?: AbortSignal;
+}
+
+export interface HandoffResult {
+  ok: boolean;
+  document?: string;
+  error?: string;
+  touchedFiles?: string[];
+}
+
+/** Below this many non-system messages there is nothing meaningful to hand off. */
+const MIN_HANDOFF_MESSAGES = 2;
+
+/**
+ * Generate a bounded, read-only handoff document from the CURRENT history —
+ * jeo-native subset of gjc `/handoff` parity. Unlike `maybeCompact`, this
+ * NEVER mutates `history`: jeo has no ACP/SDK-broker managed-session boundary
+ * to hand off INTO, so this is a display/export operation (like
+ * `exportSession`), not a session-transition primitive. It reuses the same
+ * LLM summarizer and touched-file extraction as compaction so the base shape
+ * (state/decisions/files/open TODOs) matches what `/compact` already
+ * produces, then appends the optional focus text as its OWN trailing
+ * section — append-only, it never edits the base sections.
+ */
+export async function buildHandoffDocument(
+  history: Message[],
+  opts: HandoffOptions = {},
+): Promise<HandoffResult> {
+  const hasSystem = history.length > 0 && history[0].role === "system";
+  const body = history.slice(hasSystem ? 1 : 0);
+  if (body.length < MIN_HANDOFF_MESSAGES) {
+    return {
+      ok: false,
+      error: `Nothing to hand off yet — need at least ${MIN_HANDOFF_MESSAGES} conversation messages (have ${body.length}).`,
+    };
+  }
+
+  const maxSummaryInputTokens = opts.maxSummaryInputTokens ?? DEFAULT_SUMMARY_INPUT_TOKENS;
+  const formatted = formatMessagesForSummaryByTokens(body, maxSummaryInputTokens);
+  const touched = extractTouchedFiles(body);
+  const touchedNote = touched.length
+    ? `\nFiles touched in this session (PRESERVE this list verbatim): ${touched.join(", ")}`
+    : "";
+
+  const systemPrompt =
+    "Write a concise handoff document for the next person/agent continuing this coding session. " +
+    "Capture: current goal/state, key decisions, files touched, open TODOs, and approaches already tried " +
+    "and failed (with cause) so they are not repeated. Be concise." +
+    touchedNote;
+
+  let summary: string;
+  try {
+    summary = await callLlm(
+      [{ role: "user", content: formatted }],
+      { model: opts.model, systemPrompt, reasoningEffort: "none", signal: opts.signal },
+    );
+  } catch (err) {
+    if (opts.signal?.aborted) {
+      return { ok: false, error: "Handoff cancelled." };
+    }
+    return {
+      ok: false,
+      error: `Handoff summary failed: ${(err as Error)?.message ?? "error"}. History was left untouched — retry, or use /export for a raw transcript.`,
+    };
+  }
+
+  const bounded = truncateRecentContentByTokens(summary, maxSummaryInputTokens);
+  const filesHeader = touched.length ? `Files touched: ${touched.join(", ")}\n` : "";
+
+  const sections = ["# Session Handoff", "", `${filesHeader}${bounded}`.trim()];
+  const focus = opts.focus?.trim();
+  if (focus) sections.push("", "## Focus", "", focus);
+
+  return { ok: true, document: sections.join("\n"), touchedFiles: touched.length ? touched : undefined };
+}

package/src/agent/config-schema.ts

@@ -220,6 +220,17 @@ export const ConfigSchema = z
         enabled: z.boolean().optional(),
       })
       .optional(),
+    /** Threaded through the existing compaction/summary settings (gjc `/handoff`
+     *  parity, jeo-native subset). `handoffFocus` is an operator-configured
+     *  default focus text for the interactive `/handoff [focus]` command —
+     *  used ONLY when the command is invoked with no CLI-typed focus argument,
+     *  and always appended as its own trailing section (never merged into or
+     *  replacing the generated handoff document's base sections). */
+    compaction: z
+      .object({
+        handoffFocus: z.string().optional(),
+      })
+      .optional(),
   })
   .passthrough();
 

package/src/agent/notify/telegram-api.ts

@@ -100,6 +100,17 @@ export interface AnswerCallbackQueryOptions {
 
 export type FetchLike = typeof fetch;
 
+/** Conservative fixed default cap on a downloaded Telegram file (photo or
+ *  document), enforced before/while buffering the response body so a
+ *  malicious or oversized remote attachment can't allocate unbounded memory
+ *  on the daemon. Same order of magnitude as jeo's local image-attachment
+ *  bound (`MAX_ATTACH_IMAGE_BYTES` in `src/util/file-attachment.ts`) — kept
+ *  as an independent constant rather than importing that one, since this
+ *  guards a different codepath (network download vs. local `stat`+`readFile`).
+ *  Injectable per call via {@link TelegramApi.downloadFile}'s `maxBytes`
+ *  argument for callers/tests that need a different policy. */
+export const MAX_TELEGRAM_DOWNLOAD_BYTES = 25 * 1024 * 1024;
+
 export class TelegramApi {
   constructor(
     private readonly token: string,
@@ -206,15 +217,49 @@ export class TelegramApi {
    * since this is new network I/O every caller must treat as fallible
    * (gjc `downloadTelegramFile` parity, minus the retry logic gjc layers on
    * top at the daemon level).
+   *
+   * Bounded by `maxBytes` (default {@link MAX_TELEGRAM_DOWNLOAD_BYTES}):
+   * a `content-length` over the cap short-circuits before any read, and
+   * the body is otherwise streamed and counted chunk-by-chunk so a
+   * remote server that lies about (or omits) `content-length` still can't
+   * buffer past the cap — the read is aborted and `undefined` returned the
+   * moment the running total exceeds it, never after buffering the whole
+   * oversized body first.
    */
-  async downloadFile(filePath: string): Promise<Uint8Array | undefined> {
+  async downloadFile(filePath: string, maxBytes: number = MAX_TELEGRAM_DOWNLOAD_BYTES): Promise<Uint8Array | undefined> {
     if (filePath.includes("..") || filePath.startsWith("/") || filePath.includes("\\")) return undefined;
     const encodedPath = filePath.split("/").map(encodeURIComponent).join("/");
     const url = `https://api.telegram.org/file/bot${this.token}/${encodedPath}`;
     try {
       const res = await this.fetchImpl(url);
       if (!res.ok) return undefined;
-      return new Uint8Array(await res.arrayBuffer());
+      const declaredLength = Number(res.headers?.get?.("content-length"));
+      if (Number.isFinite(declaredLength) && declaredLength > maxBytes) return undefined;
+      if (!res.body) {
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        return bytes.byteLength > maxBytes ? undefined : bytes;
+      }
+      const reader = res.body.getReader();
+      const chunks: Uint8Array[] = [];
+      let total = 0;
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (!value) continue;
+        total += value.byteLength;
+        if (total > maxBytes) {
+          await reader.cancel();
+          return undefined;
+        }
+        chunks.push(value);
+      }
+      const out = new Uint8Array(total);
+      let offset = 0;
+      for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      return out;
     } catch {
       return undefined;
     }

package/src/agent/notify/telegram-daemon.ts

@@ -218,6 +218,10 @@ export interface TelegramDaemonOptions {
   /** Injectable temp-file writer for downloaded inbound attachments — defaults
    *  to a real `os.tmpdir()` write. Returns the written file's absolute path. */
   writeTempFile?: (bytes: Uint8Array, suggestedName: string) => Promise<string>;
+  /** Injectable cap (bytes) on an inbound photo/document download, passed
+   *  through to `TelegramApi.downloadFile` — defaults to that method's own
+   *  conservative fixed default (`MAX_TELEGRAM_DOWNLOAD_BYTES`) when unset. */
+  maxAttachmentBytes?: number;
 }
 
 /** Outbound payload the shared `RateLimitPool` schedules; `flushPool` maps each
@@ -421,14 +425,18 @@ export class TelegramDaemon {
 
   /** Download a Telegram-hosted file into a local temp file for relay into a
    *  session's `[image #N]` attachment pipeline (`attachImagePaths`, see
-   *  `src/util/file-attachment.ts`). Returns `undefined` on any failure — the
-   *  message still delivers as text-only rather than being dropped entirely. */
+   *  `src/util/file-attachment.ts`). Bounded by `opts.maxAttachmentBytes`
+   *  (or `TelegramApi.downloadFile`'s own default when unset) — an oversized
+   *  remote file is rejected there and this returns `undefined` exactly as
+   *  it would for any other download failure. Returns `undefined` on any
+   *  failure — the message still delivers as text-only rather than being
+   *  dropped entirely. */
   private async downloadAttachment(fileId: string, suggestedName: string): Promise<string | undefined> {
     try {
       const got = await this.opts.telegram.getFile(fileId);
       const filePath = got.result?.file_path;
       if (!filePath) return undefined;
-      const bytes = await this.opts.telegram.downloadFile(filePath);
+      const bytes = await this.opts.telegram.downloadFile(filePath, this.opts.maxAttachmentBytes);
       if (!bytes) return undefined;
       const write = this.opts.writeTempFile ?? defaultWriteTempFile;
       return await write(bytes, suggestedName);

package/src/cli.ts

@@ -2,6 +2,7 @@
 import { dispatch } from "./cli/runner";
 import { restoreTerminalState } from "./util/terminal-restore";
 import { isBrokenPipeError, BROKEN_PIPE_EXIT_CODE } from "./util/broken-pipe";
+import { writeCrashLog } from "./util/crash-log";
 import pkg from "../package.json";
 
 const APP_NAME = "jeo";
@@ -28,9 +29,15 @@ process.title = APP_NAME;
 // socket peer) makes the NEXT stdout/stderr write throw EPIPE from an async tick
 // outside any user try/catch — that is NOT a real fatal, so it exits quietly
 // (matching the shell's own SIGPIPE exit code) instead of dumping the raw error.
+//
+// gjc PR #3051 parity: a genuine fatal also gets a best-effort, synchronous,
+// owner-only, bounded crash-log entry (secrets redacted) under jeo's config
+// dir BEFORE the clean stderr line — writeCrashLog() never throws, so it can
+// never mask the original error.
 const fatal = (err: unknown): never => {
   restoreTerminalState();
   if (isBrokenPipeError(err)) process.exit(BROKEN_PIPE_EXIT_CODE);
+  writeCrashLog(err);
   const msg = (err as Error)?.message ?? String(err);
   process.stderr.write(`error: ${msg}\n`);
   process.exit(1);

package/src/commands/launch/slash-views.ts

@@ -74,3 +74,37 @@ export function historyViewLines(history: Message[], arg: string, columns: numbe
   ];
 }
 
+/** Recognizes `/handoff` or `/handoff <focus text>` — returns `undefined` when
+ *  `input` is not a handoff invocation. A missing or whitespace-only argument
+ *  is treated as "no CLI focus" (the caller falls back to the configured
+ *  `compaction.handoffFocus` default, if any). Pure string parsing so command
+ *  recognition is testable without wiring up the REPL. */
+export function parseHandoffCommand(input: string): { focus?: string } | undefined {
+  if (input === "/handoff") return {};
+  if (!input.startsWith("/handoff ")) return undefined;
+  const focus = input.slice("/handoff ".length).trim();
+  return focus ? { focus } : {};
+}
+
+/** Renders a generated handoff document (or its failure) for scrollback —
+ *  pure over the already-computed result so the bounded-document formatting
+ *  and the non-destructive failure path are both testable without an LLM
+ *  call or a live REPL. History is never touched by this presenter (or by
+ *  the `/handoff` command it renders for) — it only ever reads and prints. */
+export function handoffLines(
+  result: { ok: boolean; document?: string; error?: string },
+  columns: number | undefined,
+): string[] {
+  if (!result.ok || !result.document) {
+    return [`(handoff not generated: ${result.error ?? "unknown error"} — history left untouched)`];
+  }
+  const sep = "─".repeat(Math.min(48, Math.max(20, (columns ?? 80) - 1)));
+  return [
+    sep,
+    "/handoff · bounded session summary (display/export only — history left untouched)",
+    sep,
+    ...result.document.split("\n"),
+    sep,
+  ];
+}
+

package/src/commands/launch.ts

@@ -103,7 +103,7 @@ import { formatDuration, formatUsage } from "../tui/components/duration";
 import { bashTool } from "../agent/tools";
 
 import { loadProjectContext, withProjectContext } from "../agent/context-files";
-import { maybeCompact, historyTokens } from "../agent/compaction";
+import { maybeCompact, historyTokens, buildHandoffDocument } from "../agent/compaction";
 import * as path from "node:path";
 import * as fs from "node:fs";
 import { listThemes, resolveTheme, themeGradient, accentPaint, accentShadowPaint } from "../tui/components/themes";
@@ -203,6 +203,8 @@ import {
   hotkeysLines,
   contextUsageLines,
   historyViewLines,
+  parseHandoffCommand,
+  handoffLines,
 } from "./launch/slash-views";
 import { formatTranscript } from "../tui/components/transcript";
 
@@ -1996,6 +1998,18 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
         if (result && "lines" in result) for (const line of result.lines) console.log(line);
         return;
       }
+      if (cmd === "/handoff" || cmd.startsWith("/handoff ")) {
+        const parsed = parseHandoffCommand(cmd) ?? {};
+        const cfg = await readGlobalConfig();
+        const activeModel = sessionModel || defaultModel;
+        // `Config` (state.ts) predates config-schema.ts's `compaction` field and is
+        // out of this change's scope — read the passthrough-preserved value via a
+        // narrow structural cast instead of widening the shared interface.
+        const focus = parsed.focus ?? (cfg as { compaction?: { handoffFocus?: string } }).compaction?.handoffFocus;
+        const res = await buildHandoffDocument(history, { model: activeModel, focus });
+        for (const line of handoffLines(res, process.stdout.columns)) console.log(line);
+        return;
+      }
       if (cmd === "/theme" || cmd.startsWith("/theme ")) {
         const decision = decideThemeSlash(cmd, listThemes(), resolveTheme().name);
         for (const line of decision.lines) console.log(line);
@@ -4273,6 +4287,22 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
         }
         continue;
       }
+      if (input === "/handoff" || input.startsWith("/handoff ")) {
+        // jeo-native subset of gjc `/handoff` parity: bounded, read-only handoff
+        // document (like /compact's summary, framed for a session handoff) — jeo
+        // has no ACP/SDK-broker managed-session boundary to hand off INTO, so this
+        // NEVER mutates history (see buildHandoffDocument's doc comment).
+        const parsed = parseHandoffCommand(input) ?? {};
+        const activeModel = sessionModel || defaultModel;
+        const cfg = await readGlobalConfig();
+        // `Config` (state.ts) predates config-schema.ts's `compaction` field and is
+        // out of this change's scope — read the passthrough-preserved value via a
+        // narrow structural cast instead of widening the shared interface.
+        const focus = parsed.focus ?? (cfg as { compaction?: { handoffFocus?: string } }).compaction?.handoffFocus;
+        const res = await buildHandoffDocument(history, { model: activeModel, focus });
+        logLines(handoffLines(res, process.stdout.columns));
+        continue;
+      }
       if (input === "/session" || input.startsWith("/session ")) {
         const result = await runSessionSlash(input, {
           cwd, history, noSession: flags.noSession, sessionId, sessionModel, rl,

package/src/tui/app.ts

@@ -1898,7 +1898,7 @@ export class LaunchTui {
     // TTY only: keep the same query input box visible above the footer while the
     // turn is running; typed text edits the next-prompt draft, not a side queue.
     if (fit) {
-      bottom.push(formatHintBar(undefined, { unicode: this.unicode, color: this.theme.color, cols: innerWidth }));
+      bottom.push(formatHintBar(undefined, { unicode: this.unicode, color: this.theme.color, cols: innerWidth, platform: process.platform }));
       bottom.push(...this.renderLiveInputBox(innerWidth));
     }
     // Live animated step strip appended to the footer when the turn has steps.

package/src/tui/components/hints.ts

@@ -32,11 +32,35 @@ export interface HintBarOptions {
   cols?: number;
   /** Indent prefix (default two spaces). */
   indent?: string;
+  /**
+   * Host platform used to relabel modifier-key hints (e.g. "^C" -> "⌃C" on
+   * macOS vs "Ctrl+C" elsewhere). Omitted by default, which keeps every raw
+   * `KeyHint.key` string exactly as authored — existing callers/tests that
+   * never pass `platform` see no behavior change.
+   */
+  platform?: NodeJS.Platform;
+}
+
+/**
+ * Rewrite a raw modifier-key token (e.g. "^C") into a platform-appropriate
+ * display label. Non-modifier keys ("Tab", "/help", …) pass through
+ * unchanged. macOS gets the compact "⌃" glyph when unicode is allowed;
+ * every other platform (and the ASCII fallback) spells out "Ctrl+".
+ */
+export function modifierKeyLabel(key: string, platform: NodeJS.Platform, unicode = true): string {
+  const m = /^\^(.+)$/.exec(key);
+  if (!m) return key;
+  return platform === "darwin" && unicode ? `\u2303${m[1]}` : `Ctrl+${m[1]}`;
 }
 
 /** Render one hint as "<key> <label>" with the key highlighted. */
-export function formatHint(hint: KeyHint, color = true): string {
-  const key = color ? chalk.cyan.bold(hint.key) : hint.key;
+export function formatHint(
+  hint: KeyHint,
+  color = true,
+  labelOpts: { platform?: NodeJS.Platform; unicode?: boolean } = {},
+): string {
+  const rawKey = labelOpts.platform ? modifierKeyLabel(hint.key, labelOpts.platform, labelOpts.unicode !== false) : hint.key;
+  const key = color ? chalk.cyan.bold(rawKey) : rawKey;
   const label = color ? chalk.gray(hint.label) : hint.label;
   return `${key} ${label}`;
 }
@@ -49,6 +73,6 @@ export function formatHintBar(hints: readonly KeyHint[] = DEFAULT_HINTS, opts: H
   const indent = opts.indent ?? "  ";
   const sepRaw = unicode ? " · " : " | ";
   const sep = color ? chalk.gray(sepRaw) : sepRaw;
-  const row = indent + hints.map(h => formatHint(h, color)).join(sep);
+  const row = indent + hints.map(h => formatHint(h, color, { platform: opts.platform, unicode })).join(sep);
   return opts.cols ? truncate(row, opts.cols) : row;
 }

package/src/tui/components/slash.ts

@@ -35,6 +35,7 @@ export const SLASH_COMMAND_DETAILS: readonly SlashCommandInfo[] = [
   { command: "/dump", usage: "/dump", description: "Copy the session transcript to the clipboard", group: "session" },
   { command: "/btw", usage: "/btw <question>", description: "Ask an ephemeral side question (history untouched)", group: "session" },
   { command: "/compact", usage: "/compact", description: "Summarize older turns to free context", group: "session" },
+  { command: "/handoff", usage: "/handoff [focus]", description: "Generate a bounded handoff summary without mutating session history", group: "session" },
   { command: "/goal", usage: "/goal <condition>", description: "Set a natural language stop condition for the session", group: "session" },
   { command: "/model", usage: "/model [id|#N|save|thinking <level>|subagent <role> <model|#N|thinking L>]", description: "Show/switch model; picker can apply to default or any subagent role and set thinking", group: "models" },
   { command: "/fast", usage: "/fast [on|off|status]", description: "Toggle fast thinking mode when the active model supports it", group: "models" },

package/src/util/crash-log.ts

@@ -0,0 +1,121 @@
+/**
+ * Best-effort, synchronous, owner-only crash log — gjc PR #3051 parity, scoped to
+ * jeo-native persistence only (no daily-logger/archive infrastructure ported).
+ *
+ * Written directly from `src/cli.ts`'s process-level `uncaughtException`/
+ * `unhandledRejection` handler, BEFORE the clean "error: …" line hits stderr, so a
+ * fatal that tears the process down still leaves one bounded, redacted breadcrumb
+ * under jeo's existing config dir for later triage — without depending on the TUI
+ * being alive or the terminal being in a readable state.
+ *
+ * Every entry: (1) redacts common bearer/API-key/secret-shaped substrings, (2) is
+ * capped and UTF-8-safely truncated so one huge error can't itself blow the file
+ * past its ceiling in a single write, and (3) is appended to a single file that
+ * gets RESET (not grown forever) once that ceiling is crossed — a crash loop can
+ * never fill the disk. `writeCrashLog` NEVER throws: a broken log path/permission
+ * issue must never mask the real fatal error it's trying to record.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { jeoEnv } from "./env";
+
+/** Total file size ceiling (bytes); once exceeded the log is RESET (overwritten
+ *  with just the new entry) on the next write instead of appended to. */
+export const CRASH_LOG_MAX_BYTES = 1_000_000;
+/** Per-record cap (bytes), applied to the formatted message+stack body before it
+ *  is written — independent of the file-level ceiling above. */
+export const CRASH_LOG_MAX_ENTRY_BYTES = 8_000;
+
+function crashLogDir(): string {
+  return jeoEnv("CONFIG_DIR") || path.join(os.homedir(), ".jeo");
+}
+
+export function crashLogPath(): string {
+  return path.join(crashLogDir(), "crash.log");
+}
+
+// Bearer tokens (e.g. `Authorization: Bearer sk-…`) carry the secret AFTER a
+// space, so they need their own pattern — a generic `key: value` matcher stops
+// at the first space and would leave the actual token unredacted.
+const BEARER_RE = /\bBearer\s+[^\s"'`]+/gi;
+// `key: value` / `key=value`, optionally quoted; value stops at the first
+// delimiter (space, quote, comma, closing brace/bracket).
+const KV_SECRET_RE =
+  /\b(api[_-]?key|access[_-]?token|refresh[_-]?token|auth[_-]?token|secret|password|passwd|token)\b(\s*[:=]\s*)("?)([^\s"'`,}\]]+)\3/gi;
+// `"authorization": "value"` / `"apiKey": "value"` style JSON fields, including
+// ones whose value legitimately contains spaces (e.g. an embedded auth header).
+const JSON_SECRET_RE =
+  /("(?:api[_-]?key|access[_-]?token|refresh[_-]?token|auth[_-]?token|authorization|secret|password|passwd|token)"\s*:\s*")[^"]*(")/gi;
+
+/** Redact common bearer/API-key/secret-shaped substrings. Conservative pattern
+ *  match, not a secret scanner — best-effort only, applied before persistence. */
+export function redactCrashText(input: string): string {
+  return input
+    .replace(BEARER_RE, "Bearer <redacted>")
+    .replace(JSON_SECRET_RE, "$1<redacted>$2")
+    .replace(KV_SECRET_RE, (_m, key: string, sep: string, quote: string) => `${key}${sep}${quote}<redacted>${quote}`);
+}
+
+/** Truncate to a byte budget without splitting a UTF-8 multi-byte sequence — a
+ *  naive string/byte slice can cut mid-codepoint (or mid-surrogate-pair on the
+ *  JS-string side), corrupting the tail into replacement characters on decode. */
+function truncateUtf8(text: string, maxBytes: number): string {
+  const buf = Buffer.from(text, "utf-8");
+  if (buf.length <= maxBytes) return text;
+  let end = maxBytes;
+  // A UTF-8 continuation byte is 10xxxxxx (0x80-0xBF); back off the boundary so
+  // the cut never lands inside a multi-byte codepoint.
+  while (end > 0 && (buf[end]! & 0xc0) === 0x80) end--;
+  return `${buf.subarray(0, end).toString("utf-8")}…`;
+}
+
+function describeReason(reason: unknown): string {
+  if (reason instanceof Error) {
+    const header = `${reason.name || "Error"}: ${reason.message || ""}`;
+    return reason.stack && reason.stack !== header ? `${header}\n${reason.stack}` : header;
+  }
+  if (typeof reason === "string") return reason;
+  if (reason === undefined) return "undefined";
+  if (reason === null) return "null";
+  try {
+    return JSON.stringify(reason) ?? String(reason);
+  } catch {
+    return String(reason);
+  }
+}
+
+function formatEntry(reason: unknown): string {
+  const redacted = redactCrashText(describeReason(reason));
+  const bounded = truncateUtf8(redacted, CRASH_LOG_MAX_ENTRY_BYTES);
+  return `[${new Date().toISOString()}] ${bounded}\n`;
+}
+
+/** Append one crash record to the bounded, owner-only crash log (resetting the
+ *  file first if it has crossed the size ceiling). Synchronous so it can run
+ *  directly inside `uncaughtException`/`unhandledRejection` handlers before the
+ *  process exits. NEVER throws. */
+export function writeCrashLog(reason: unknown): void {
+  try {
+    const dir = crashLogDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const target = crashLogPath();
+    const entry = formatEntry(reason);
+    let reset = false;
+    try {
+      reset = fs.statSync(target).size > CRASH_LOG_MAX_BYTES;
+    } catch {
+      // No existing (or unreadable) file — nothing to reset, just create it.
+    }
+    if (reset) fs.writeFileSync(target, entry, { mode: 0o600 });
+    else fs.appendFileSync(target, entry, { mode: 0o600 });
+    try {
+      fs.chmodSync(target, 0o600); // owner-only even if the file pre-existed with looser perms
+    } catch {
+      // Best-effort permission tightening only.
+    }
+  } catch {
+    // Crash logging is a diagnostic nicety, never a dependency of the fatal
+    // path itself — a write failure here must never mask the real fatal error.
+  }
+}