viber-channel 0.8.39 → 0.8.41

package/lib/agent_tools.ts

@@ -190,7 +190,10 @@ export async function messageAgent(
   try {
     outcome = await openDm(ctx.baseUrl(), ctx.instanceToken(), trimmedPeerId);
   } catch (err) {
-    return errorText(`message_agent failed: ${String(err)}`);
+    // #694: openDm already retried a network failure once. No message was posted.
+    return errorText(
+      `message_agent could not open the DM (network error, retried once; nothing was posted): ${String(err)}`,
+    );
   }
   if (!outcome.ok) {
     let friendly: string;
@@ -240,7 +243,8 @@ export async function messageAgent(
     return errorText(`message_agent post failed: ${String(err)}`);
   }
   if (!result.ok) {
-    return errorText(result.detail);
+    // #694: name the step — the DM opened, the post is what failed.
+    return errorText(`message_agent: the DM is open, but the post failed: ${result.detail}`);
   }
   if (outcome.redirect) {
     // #692: say which agent was reached, and that the id used is stale.

package/lib/claude_runtime_publisher.ts

@@ -0,0 +1,86 @@
+/**
+ * claude_runtime_publisher.ts — a claude agent's model, effort and context, left for
+ * the runner after each reply (#708 step-04).
+ *
+ * JP's rule (2026-10-17): the figures move on a round trip — a message in, the
+ * agent's answer out — and are pushed only if they changed. So nothing watches the
+ * session log: when the agent replies on the channel (`send_message`, or
+ * `message_agent` for an agent that only talks in DMs), the channel reads its own
+ * claude's log once and rewrites `<presenceDir>/<id>.runtime.json` if what the chip
+ * shows changed. The runner then pushes it, like a codex agent's file.
+ *
+ * The read waits `delayMs`: the assistant entry carrying the reply's tool call lands
+ * in the log within 200 ms of the call starting (measured, plan 708 step-01). Replies
+ * within that window are coalesced into one read.
+ */
+import { readClaudeRuntime } from "./claude_session_log.js";
+import { runtimeFilePath, writeRuntimeFile } from "./codex_runtime.js";
+import { processStartTimeAsync } from "./process_start.js";
+import { type RuntimeV1, sameRuntime } from "./runtime_info.js";
+
+export const PUBLISH_DELAY_MS = 500;
+
+export interface ClaudeRuntimePublisherOptions {
+  /** The claude process this channel serves (parent watchdog); null = none found. */
+  getClaudePid: () => number | null;
+  identityBaseUrl: string;
+  /** Read at publish time: the instance registers after the channel starts. */
+  getInstanceId: () => string;
+  lockDir?: string;
+  delayMs?: number;
+  probeStartTime?: (pid: number) => Promise<number | undefined>;
+  read?: (q: { pid: number; startTimeMs: number }) => RuntimeV1 | undefined;
+  write?: (path: string, instanceId: string, r: RuntimeV1) => void;
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  log?: (line: string) => void;
+}
+
+export class ClaudeRuntimePublisher {
+  private startTime: number | undefined;
+  private startPid: number | null = null;
+  private pending = false;
+  private last: RuntimeV1 | undefined;
+  private lastInstance = "";
+
+  constructor(private readonly opts: ClaudeRuntimePublisherOptions) {}
+
+  /** The agent just replied on the channel. Never throws, never blocks the reply. */
+  afterReply(): void {
+    if (this.opts.getClaudePid() === null || this.pending) return;
+    this.pending = true;
+    const setTimer =
+      this.opts.setTimer ??
+      ((fn: () => void, ms: number) => {
+        const t = setTimeout(fn, ms);
+        (t as { unref?: () => void }).unref?.();
+        return t;
+      });
+    setTimer(() => {
+      this.pending = false;
+      void this.publish().catch((err) => this.log(`[runtime] publish failed: ${String(err)}\n`));
+    }, this.opts.delayMs ?? PUBLISH_DELAY_MS);
+  }
+
+  /** One read and, if what the chip shows changed, one write. Exposed for tests. */
+  async publish(): Promise<void> {
+    const pid = this.opts.getClaudePid();
+    const instanceId = this.opts.getInstanceId();
+    if (pid === null || instanceId === "") return;
+    if (this.startTime === undefined || this.startPid !== pid) {
+      this.startPid = pid;
+      this.startTime = await (this.opts.probeStartTime ?? ((p: number) => processStartTimeAsync(p)))(pid);
+      if (this.startTime === undefined) return; // retried on the next reply
+    }
+    const r = (this.opts.read ?? readClaudeRuntime)({ pid, startTimeMs: this.startTime });
+    // Unknown: keep the file as it is — a torn read is not a reason to clear the chip.
+    if (r === undefined) return;
+    if (instanceId === this.lastInstance && sameRuntime(this.last, r)) return;
+    (this.opts.write ?? writeRuntimeFile)(runtimeFilePath(this.opts.identityBaseUrl, instanceId, this.opts.lockDir), instanceId, r);
+    this.last = r;
+    this.lastInstance = instanceId;
+  }
+
+  private log(line: string): void {
+    (this.opts.log ?? ((l: string) => process.stderr.write(l)))(line);
+  }
+}

package/lib/claude_session_log.ts

@@ -0,0 +1,186 @@
+/**
+ * claude_session_log.ts — read a Claude agent's model, effort and context from its
+ * session log (#708 step-02).
+ *
+ * Two files, both internal to Claude Code (undocumented, may change between
+ * versions — every field is optional here, and a miss yields "unknown", never 0):
+ *
+ * - `~/.claude/sessions/<pid>.json`: the live registry of a claude process. It
+ *   names the CURRENT session (it follows `/clear` and resume), so it is re-read
+ *   on every call, never cached. Its `procStart` (Windows FILETIME) equals the
+ *   process start time measured by `process_start.ts` to the millisecond
+ *   (measured, plan 708 step-01): a pid recycled by another process is refused.
+ * - `~/.claude/projects/<slug(cwd)>/<sessionId>.jsonl`: one entry per event. The
+ *   last `assistant` entry carries `message.model`, `effort` and `message.usage`;
+ *   occupation = input + cache_creation + cache_read of that LAST call (the status
+ *   line's formula). It is written within 200 ms of a tool call starting.
+ *
+ * Known lag, by construction: after `/compact` or `/model`, the figures stay those of
+ * the last call until the next one is logged.
+ */
+import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CLAUDE_CONTEXT_WINDOW, type RuntimeV1, buildRuntime, isEmptyRuntime } from "./runtime_info.js";
+
+/** FILETIME epoch (1601-01-01) to Unix epoch, in ms. */
+const FILETIME_UNIX_OFFSET_MS = 11_644_473_600_000;
+/** `procStart` and the CIM probe agree to the ms today (measured); the slack absorbs a
+ *  rounding change between versions — a recycled pid never starts within 5 ms. */
+const START_TOLERANCE_MS = 5;
+/** Tail windows, tried in order: an assistant entry carrying a big tool input can be large. */
+export const TAIL_BYTES: readonly number[] = [256 * 1024, 4 * 1024 * 1024];
+
+export interface LiveSession {
+  sessionId: string;
+  cwd: string;
+}
+
+/** The `/resume` bucket of a working directory: every non-alphanumeric char → '-'. */
+export function projectSlug(cwd: string): string {
+  return cwd.replace(/[^A-Za-z0-9]/g, "-");
+}
+
+/** FILETIME string (100 ns ticks since 1601) → Unix ms, or undefined. */
+export function fileTimeToMs(raw: unknown): number | undefined {
+  if (typeof raw !== "string" || !/^\d{1,20}$/.test(raw)) return undefined;
+  // Rounded like the CIM probe (`[int64]` of a fractional ms rounds), measured equal.
+  const ms = Number((BigInt(raw) + 5_000n) / 10_000n) - FILETIME_UNIX_OFFSET_MS;
+  return ms > 0 ? ms : undefined;
+}
+
+/**
+ * The live session of claude process `pid`, or undefined when the registry is
+ * missing, unreadable, or belongs to another process (pid recycled).
+ */
+export function readLiveSession(home: string, pid: number, startTimeMs: number): LiveSession | undefined {
+  let d: Record<string, unknown>;
+  try {
+    d = JSON.parse(readFileSync(join(home, ".claude", "sessions", `${pid}.json`), "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (typeof d !== "object" || d === null || d.pid !== pid) return undefined;
+  const started = fileTimeToMs(d.procStart);
+  if (started === undefined || Math.abs(started - startTimeMs) > START_TOLERANCE_MS) return undefined;
+  if (typeof d.sessionId !== "string" || !/^[0-9a-f-]{36}$/i.test(d.sessionId)) return undefined;
+  if (typeof d.cwd !== "string" || d.cwd === "") return undefined;
+  return { sessionId: d.sessionId, cwd: d.cwd };
+}
+
+/** The session log path: the cwd's bucket first, then any bucket holding that id. */
+export function resolveSessionLog(home: string, live: LiveSession): string | undefined {
+  const projects = join(home, ".claude", "projects");
+  const file = `${live.sessionId}.jsonl`;
+  const direct = join(projects, projectSlug(live.cwd), file);
+  if (existsSync(direct)) return direct;
+  try {
+    for (const bucket of readdirSync(projects)) {
+      const p = join(projects, bucket, file);
+      if (existsSync(p)) return p;
+    }
+  } catch {
+    // no projects directory: unknown
+  }
+  return undefined;
+}
+
+function readTail(path: string, bytes: number): { text: string; whole: boolean } | undefined {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, "r");
+    const size = fstatSync(fd).size;
+    const len = Math.min(size, bytes);
+    const buf = Buffer.alloc(len);
+    readSync(fd, buf, 0, len, size - len);
+    return { text: buf.toString("utf8"), whole: len === size };
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export interface LastTurn {
+  model?: string;
+  effort?: string;
+  contextTokens?: number;
+}
+
+const count = (n: unknown): number | undefined =>
+  typeof n === "number" && Number.isInteger(n) && n >= 0 ? n : undefined;
+
+/** The last real main-thread assistant call in a chunk of log, or undefined. */
+export function lastTurnOf(text: string, whole: boolean): LastTurn | undefined {
+  const lines = text.split("\n");
+  // A tail cut mid-line: the first line is a fragment. The last may be a write in progress.
+  const start = whole ? 0 : 1;
+  for (let i = lines.length - 1; i >= start; i--) {
+    const line = lines[i]?.trim();
+    if (!line || !line.includes('"assistant"')) continue;
+    let e: Record<string, unknown>;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (e.type !== "assistant" || e.isSidechain === true) continue;
+    const m = e.message as Record<string, unknown> | undefined;
+    // An API error is logged as a "<synthetic>" assistant entry with zero usage: not a call.
+    if (!m || m.model === "<synthetic>") continue;
+    const u = m.usage as Record<string, unknown> | undefined;
+    const parts = u ? [count(u.input_tokens), count(u.cache_creation_input_tokens), count(u.cache_read_input_tokens)] : [];
+    return {
+      model: typeof m.model === "string" ? m.model : undefined,
+      effort: typeof e.effort === "string" ? e.effort : undefined,
+      contextTokens: parts.length === 3 && parts.every((p) => p !== undefined)
+        ? (parts as number[]).reduce((a, b) => a + b, 0)
+        : undefined,
+    };
+  }
+  return undefined;
+}
+
+/** The last turn of a session log, widening the tail once if the first window holds none. */
+export function readLastTurn(path: string, tails: readonly number[] = TAIL_BYTES): LastTurn | undefined {
+  for (const bytes of tails) {
+    const tail = readTail(path, bytes);
+    if (!tail) return undefined;
+    const turn = lastTurnOf(tail.text, tail.whole);
+    if (turn || tail.whole) return turn;
+  }
+  return undefined;
+}
+
+export interface ClaudeRuntimeQuery {
+  pid: number;
+  startTimeMs: number;
+  home?: string;
+  now?: () => number;
+}
+
+/** The runtime of a claude agent, or undefined when nothing about it is known. */
+export function readClaudeRuntime(q: ClaudeRuntimeQuery): RuntimeV1 | undefined {
+  const home = q.home ?? homedir();
+  const live = readLiveSession(home, q.pid, q.startTimeMs);
+  if (!live) return undefined;
+  const log = resolveSessionLog(home, live);
+  if (!log) return undefined;
+  const turn = readLastTurn(log);
+  return turn ? runtimeOfTurn(turn, (q.now ?? Date.now)()) : undefined;
+}
+
+/** A claude turn as a runtime, on the fixed 1 M window; undefined when nothing is known. */
+export function runtimeOfTurn(turn: LastTurn, observedAt: number): RuntimeV1 | undefined {
+  const r = buildRuntime(
+    {
+      model: turn.model,
+      effort: turn.effort,
+      contextTokens: turn.contextTokens,
+      // A window alone says nothing about this agent.
+      contextWindow: turn.contextTokens === undefined ? undefined : CLAUDE_CONTEXT_WINDOW,
+    },
+    observedAt,
+  );
+  return isEmptyRuntime(r) ? undefined : r;
+}

package/lib/codex_runtime.ts

@@ -0,0 +1,123 @@
+/**
+ * codex_runtime.ts — model, effort and context of a codex agent, left for the
+ * runner in `<presenceDir>/<instance_id>.runtime.json` (#708 step-03).
+ *
+ * Sources, measured on codex-cli 0.163.0 (plan 708 step-01):
+ * - `thread/start` / `thread/resume` answer the EFFECTIVE `model` and
+ *   `reasoningEffort` (null = not reported) — the template's pair is only what was
+ *   asked;
+ * - `thread/tokenUsage/updated` carries `tokenUsage.last.totalTokens` (occupation of
+ *   the last call, right after a compaction too) and `tokenUsage.modelContextWindow`.
+ *   `total` is cumulative over the thread's life and `last.inputTokens` drops to a
+ *   false 0 right after a compaction: neither is read.
+ *
+ * The file is rewritten only when a business field changes (`observed_at` excluded),
+ * atomically, so the runner never reads half of it.
+ */
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isInstanceId, presenceDir } from "./presence_record.js";
+import { type RuntimeV1, buildRuntime, isEmptyRuntime, parseRuntime, sameRuntime } from "./runtime_info.js";
+
+/** A runtime file name — never a presence record (`<id>.json`) nor a temp file. */
+export const RUNTIME_FILE_RE = /^[0-9a-f]{32}\.runtime\.json$/;
+
+export function runtimeFilePath(identityBaseUrl: string, instanceId: string, lockDir?: string): string {
+  if (!isInstanceId(instanceId)) {
+    throw new Error(`runtimeFilePath: not an instance id: ${JSON.stringify(instanceId)}`);
+  }
+  return join(presenceDir(identityBaseUrl, lockDir), `${instanceId.toLowerCase()}.runtime.json`);
+}
+
+export interface RuntimeFile extends RuntimeV1 {
+  instance_id: string;
+}
+
+/** Atomic write: a reader sees the old file or the new one, never half of one. */
+export function writeRuntimeFile(path: string, instanceId: string, runtime: RuntimeV1): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  const body: RuntimeFile = { ...runtime, instance_id: instanceId.toLowerCase() };
+  writeFileSync(tmp, JSON.stringify(body), "utf8");
+  try {
+    renameSync(tmp, path);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // the tmp may already be gone; the rename error is the one that matters
+    }
+    throw err;
+  }
+}
+
+/** The runtime in a file, or undefined when absent, torn or for another instance. */
+export function readRuntimeFile(path: string, instanceId: string): RuntimeV1 | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null) return undefined;
+  const { instance_id, ...rest } = parsed as Record<string, unknown>;
+  if (instance_id !== instanceId.toLowerCase()) return undefined;
+  return parseRuntime(rest);
+}
+
+const count = (n: unknown): number | undefined =>
+  typeof n === "number" && Number.isInteger(n) && n >= 0 ? n : undefined;
+
+/** Collects what codex says and writes the file when it changes. */
+export class CodexRuntimeWriter {
+  private model?: string;
+  private effort?: string;
+  private contextTokens?: number;
+  private contextWindow?: number;
+  private last: RuntimeV1 | undefined;
+
+  constructor(
+    private readonly path: string,
+    private readonly instanceId: string,
+    private readonly now: () => number = Date.now,
+    private readonly write: (path: string, id: string, r: RuntimeV1) => void = writeRuntimeFile,
+    private readonly log: (line: string) => void = (l) => process.stderr.write(l),
+  ) {}
+
+  /** The answer to `thread/start` or `thread/resume`. */
+  onThread(result: unknown): void {
+    const r = (typeof result === "object" && result !== null ? result : {}) as Record<string, unknown>;
+    if (typeof r.model === "string") this.model = r.model;
+    // null = "not reported": keep what we knew rather than forget it.
+    if (typeof r.reasoningEffort === "string") this.effort = r.reasoningEffort;
+    this.flush();
+  }
+
+  /** The params of `thread/tokenUsage/updated`. */
+  onTokenUsage(params: unknown): void {
+    const usage = (params as { tokenUsage?: { last?: { totalTokens?: unknown }; modelContextWindow?: unknown } } | null)
+      ?.tokenUsage;
+    const tokens = count(usage?.last?.totalTokens);
+    const window = count(usage?.modelContextWindow);
+    // Both terms or neither: a percent from a stale numerator and a fresh window is a guess.
+    if (tokens === undefined || window === undefined || window === 0) return;
+    this.contextTokens = tokens;
+    this.contextWindow = window;
+    this.flush();
+  }
+
+  private flush(): void {
+    const next = buildRuntime(
+      { model: this.model, effort: this.effort, contextTokens: this.contextTokens, contextWindow: this.contextWindow },
+      this.now(),
+    );
+    if (isEmptyRuntime(next) || sameRuntime(this.last, next)) return;
+    try {
+      this.write(this.path, this.instanceId, next);
+      this.last = next;
+    } catch (err) {
+      // The file serves the web only: an agent never dies of it. Retried on the next change.
+      this.log(`[codex-runtime] write failed (${this.path}): ${String(err)}\n`);
+    }
+  }
+}

package/lib/messages.ts

@@ -136,13 +136,144 @@ export interface MessagePostError {
   ok: false;
   status: number;
   detail: string;
-  retriable: boolean;
 }
 
 export type MessagePostResult = MessagePostSuccess | MessagePostError;
 
 /**
- * POST /api/conversations/:conversationId/messages
+ * `detail` of viber-api's GLOBAL notFound (`viber-api/src/index.ts`): what a server
+ * that predates `POST …/messages/idempotent` answers on that route (#694). The
+ * ONLY cue that allows falling back to the legacy route. Tied to the server's text
+ * by a cross test (test/messages.test.ts), so a change there breaks the build here.
+ */
+export const SERVER_NOT_FOUND_DETAIL = "Not found";
+
+/** Statuses an edge or a tunnel answers for a request that may never have run: resent once (#694). */
+const RESEND_STATUSES: ReadonlySet<number> = new Set([502, 503, 504]);
+
+/**
+ * Pause before the single resend (#694). The failed attempt reused a keep-alive
+ * socket a Cloudflare datacenter switch had killed; Bun drops it from its pool, so
+ * the resend opens a fresh connection.
+ */
+export const RESEND_DELAY_MS = 250;
+
+/** Test seams of postMessage; production never passes them. */
+export interface PostMessageOptions {
+  /** Pause before the resend. Default RESEND_DELAY_MS. */
+  resendDelayMs?: number;
+  /** Client message id generator. Default crypto.randomUUID. */
+  newClientMessageId?: () => string;
+}
+
+/** One HTTP attempt: a response whose body was read IN FULL, or a network failure. */
+type Attempt =
+  | { kind: "response"; status: number; statusText: string; body: string }
+  | { kind: "network"; error: unknown };
+
+async function attemptPost(
+  fetchImpl: typeof fetch,
+  url: string,
+  conversationToken: string,
+  payload: Record<string, unknown>,
+  signal: AbortSignal | undefined,
+): Promise<Attempt> {
+  try {
+    const resp = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${conversationToken}`,
+        "Content-Type": "application/json",
+        ...cfAccessHeaders(),
+      },
+      body: JSON.stringify(payload),
+      signal,
+    });
+    // Read the body here: a socket reset can also land mid-body, and a 404 whose body
+    // was lost must never be mistaken for the global notFound (#694).
+    const body = await resp.text();
+    return { kind: "response", status: resp.status, statusText: resp.statusText, body };
+  } catch (error) {
+    return { kind: "network", error };
+  }
+}
+
+/**
+ * True for the global notFound body BYTE FOR BYTE — `{"detail":"Not found"}`, as
+ * Hono's `c.json` serializes it — and nothing else: not a reformatted variant, not
+ * a different detail, not a body cut by a reset (Codex review, step-02).
+ */
+function isServerNotFound(attempt: Attempt): boolean {
+  return (
+    attempt.kind === "response" &&
+    attempt.status === 404 &&
+    attempt.body === JSON.stringify({ detail: SERVER_NOT_FOUND_DETAIL })
+  );
+}
+
+/** Worth one resend with the same client id: a network failure (not an abort) or 502/503/504. */
+function isResendable(attempt: Attempt, signal: AbortSignal | undefined): boolean {
+  if (signal?.aborted) return false;
+  return attempt.kind === "network" || RESEND_STATUSES.has(attempt.status);
+}
+
+/**
+ * Map one attempt to the result the tools see.
+ * @throws ConversationTokenExpiredError on HTTP 401
+ */
+function toResult(attempt: Attempt, resent: boolean): MessagePostResult {
+  // After a resend the first attempt may have been written: say so, never "lost".
+  const resendNote = resent
+    ? " Resent once with the same client_message_id: delivery is NOT confirmed, it may already be delivered." +
+      " Do not resend unless the user asks: a resend is a new message and could appear twice."
+    : "";
+  if (attempt.kind === "network") {
+    return { ok: false, status: 0, detail: `Network error: ${String(attempt.error)}.${resendNote}` };
+  }
+  const { status, statusText, body } = attempt;
+  if (status === 401) throw new ConversationTokenExpiredError();
+  if (status >= 500) {
+    return {
+      ok: false,
+      status,
+      detail: `Server error (HTTP ${status}): ${body || statusText}.${resendNote || " Retry the call."}`,
+    };
+  }
+  if (status < 200 || status >= 300) {
+    let detail = `HTTP ${status}`;
+    try {
+      const json = JSON.parse(body) as { detail?: unknown };
+      if (typeof json.detail === "string") detail = `HTTP ${status}: ${json.detail}`;
+    } catch {
+      if (body) detail = `HTTP ${status}: ${body}`;
+    }
+    return { ok: false, status, detail: `${detail}${resendNote}` };
+  }
+  // 200 or 201 — the saved message (a 200 on the idempotent route is the one an
+  // earlier attempt wrote).
+  try {
+    const message = JSON.parse(body) as { id: string };
+    return { ok: true, message_id: message.id };
+  } catch (err) {
+    return { ok: false, status, detail: `Failed to parse response JSON: ${String(err)}` };
+  }
+}
+
+/**
+ * POST a message, at most once (#694).
+ *
+ * A Cloudflare datacenter switch kills idle keep-alive sockets; the next POST on
+ * one fails in ~20 ms with ECONNRESET, and Bun never resends a POST itself. So:
+ *   1. one client message id per logical send, sent to `…/messages/idempotent`;
+ *   2. a network failure (not an abort) or 502/503/504 → ONE resend, same id, after
+ *      RESEND_DELAY_MS — the server answers the row the first attempt wrote, if any;
+ *   3. a server that predates the idempotent route answers its global notFound:
+ *      ONLY on the FIRST attempt, and only on that exact, fully read body, the send
+ *      falls back to the legacy `…/messages`, without resend (today's behaviour).
+ *      After an ambiguous first attempt a notFound means a rollback between the two
+ *      attempts: the first may have been written, so the legacy route would
+ *      duplicate it — that is an error, never a fallback.
+ * No timer, no periodic request: a request is added only when a send fails.
  *
  * @throws ConversationTokenExpiredError on HTTP 401
  * @returns MessagePostResult — success with message_id, or error with detail
@@ -157,7 +288,7 @@ export async function postMessage(
    * Optional abort signal (#303 step-12.03): the codex bridge passes its stream's
    * signal so a reply in flight is cancelled atomically if the stream is aborted
    * (re-join / revoke / shutdown) — closing the check-then-post window that a bare
-   * `signal.aborted` guard before the call cannot.
+   * `signal.aborted` guard before the call cannot. An aborted send is never resent.
    */
   signal?: AbortSignal,
   /**
@@ -167,85 +298,26 @@ export async function postMessage(
    * that cannot see the notice cannot prove the fix that exists to emit it.
    */
   fetchImpl: typeof fetch = fetch,
+  options: PostMessageOptions = {},
 ): Promise<MessagePostResult> {
   if (!text || text.trim().length === 0) {
-    return {
-      ok: false,
-      status: 0,
-      detail: "text must be a non-empty string",
-      retriable: false,
-    };
-  }
-
-  const url = `${baseUrl}/api/conversations/${conversationId}/messages`;
-  let resp: Response;
-  try {
-    resp = await fetchImpl(url, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${conversationToken}`,
-        "Content-Type": "application/json",
-        ...cfAccessHeaders(),
-      },
-      body: JSON.stringify(artifact ? { content: text, artifact } : { content: text }),
-      signal,
-    });
-  } catch (err) {
-    return {
-      ok: false,
-      status: 0,
-      detail: `Network error: ${String(err)}`,
-      retriable: true,
-    };
-  }
-
-  if (resp.status === 401) {
-    throw new ConversationTokenExpiredError();
+    return { ok: false, status: 0, detail: "text must be a non-empty string" };
   }
 
-  if (resp.status >= 500) {
-    let body = "";
-    try {
-      body = await resp.text();
-    } catch {
-      // ignore
-    }
-    return {
-      ok: false,
-      status: resp.status,
-      detail: `Server error (HTTP ${resp.status}): ${body || resp.statusText}. Retry the call.`,
-      retriable: true,
-    };
-  }
+  const messagesUrl = `${baseUrl}/api/conversations/${conversationId}/messages`;
+  const content: Record<string, unknown> = artifact ? { content: text, artifact } : { content: text };
+  const clientMessageId = (options.newClientMessageId ?? (() => crypto.randomUUID()))();
+  const idempotent = { ...content, client_message_id: clientMessageId };
 
-  if (!resp.ok) {
-    let detail = `HTTP ${resp.status}`;
-    try {
-      const json = (await resp.json()) as { detail?: string };
-      if (typeof json.detail === "string") detail = `HTTP ${resp.status}: ${json.detail}`;
-    } catch {
-      try {
-        const body = await resp.text();
-        if (body) detail = `HTTP ${resp.status}: ${body}`;
-      } catch {
-        // ignore
-      }
-    }
-    return { ok: false, status: resp.status, detail, retriable: false };
-  }
-
-  // 200 or 201 — parse the saved message
-  let message: { id: string };
-  try {
-    message = (await resp.json()) as { id: string };
-  } catch (err) {
-    return {
-      ok: false,
-      status: resp.status,
-      detail: `Failed to parse response JSON: ${String(err)}`,
-      retriable: false,
-    };
+  const first = await attemptPost(fetchImpl, `${messagesUrl}/idempotent`, conversationToken, idempotent, signal);
+  if (isServerNotFound(first)) {
+    const legacy = await attemptPost(fetchImpl, messagesUrl, conversationToken, content, signal);
+    return toResult(legacy, false);
   }
+  if (!isResendable(first, signal)) return toResult(first, false);
 
-  return { ok: true, message_id: message.id };
+  await new Promise((resolve) => setTimeout(resolve, options.resendDelayMs ?? RESEND_DELAY_MS));
+  if (signal?.aborted) return toResult(first, false);
+  const second = await attemptPost(fetchImpl, `${messagesUrl}/idempotent`, conversationToken, idempotent, signal);
+  return toResult(second, true);
 }