waku-memory 0.1.0 → 0.3.0

package/dist/hook.js

@@ -1,40 +1,71 @@
 // The `hook` subcommand's decision logic. Wired by cli.ts: run() reads one
-// Claude Code hook event as JSON off stdin (that part deliberately does not
-// live here -- see the note on handleHookEvent below) and calls
-// handleHookEvent with the parsed event and a real deps bag. Everything in
-// this file takes its inputs as plain values, so hook.test.mjs can call it
-// directly against temp files and an injected fetchImpl, the same way
-// cli.test.mjs drives applyToHarness without touching a real ~/.claude.json.
+// hook event as JSON off stdin (that part deliberately does not live here --
+// see the note on handleHookEvent below) and calls handleHookEvent with the
+// parsed event and a real deps bag. Everything in this file takes its
+// inputs as plain values, so hook.test.mjs can call it directly against temp
+// files and an injected fetchImpl, the same way cli.test.mjs drives
+// applyToHarness without touching a real ~/.claude.json.
+//
+// Claude Code and Codex both land here (spec 012 §4): the event shape and
+// the stdin fields this file reads were measured identical across the two,
+// so this module itself never asks which harness sent an event -- deps
+// carries a HarnessId, handleHookEvent resolves it to one HarnessProfile
+// (harnesses.ts's PROFILES) up front, and every harness-specific choice
+// (content format, delta formatter, timing budgets, how the brief is
+// printed) reads off that one value. A third harness is a third profile,
+// never a new branch in this file.
 //
 // This is the one piece of the shim that runs unattended, on every turn, in
 // the middle of somebody else's tool -- see task 14's brief for the full
 // argument. Two consequences shape every decision below:
 //
 //   1. It must never throw and never leave a nonzero exit behind. A capture
-//      bug must not read to the user as their actual Claude Code session
-//      failing. handleHookEvent wraps its entire body in one try/catch for
-//      exactly this reason, and every expected failure (missing config, no
-//      new bytes, a non-2xx response, a rejected fetch) returns through its
-//      own branch before ever reaching that catch -- the catch is the net
-//      under the net, for whatever this file's author did not think of.
-//   2. Content goes to the ingest endpoint and nowhere else. No transcript
-//      byte, no delta, no response body is ever passed to console.log or
-//      console.error -- only counts, status codes, and the event/session
-//      names Claude Code itself already put on stdin.
+//      bug must not read to the user as their actual session failing.
+//      handleHookEvent wraps its entire body in one try/catch for exactly
+//      this reason, and every expected failure (missing config, no new
+//      bytes, a non-2xx response, a rejected fetch) returns through its own
+//      branch before ever reaching that catch -- the catch is the net under
+//      the net, for whatever this file's author did not think of.
+//   2. Content goes to the ingest endpoint and nowhere else, with one
+//      deliberate exception: SessionStart's postBrief writes POST /brief's
+//      `text` (run through the harness profile's briefOutput -- identity
+//      for Claude Code, the hook JSON contract for Codex) to stdout, which
+//      the harness folds into the session's context -- that is the entire
+//      point of task 9. stdout carries the brief and nothing else, ever.
+//      Every other channel is stderr (console.error), and never carries a
+//      transcript byte, a delta, or any other response body -- only counts,
+//      status codes, and the event/session names already on stdin. The one
+//      further exception is ruling R4 (spec 012 §4.1): the Codex profile
+//      stays silent on stderr too when there is no usable credential, since
+//      Codex has no interactive onboarding to have warned the user first.
 //
-// Zero dependencies, per the brief: only node:fs and node:path here, plus
-// the global fetch (Node 18+, no import needed) that deps.fetchImpl
-// defaults to at the real call site in cli.ts.
-import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+// Zero dependencies, per the brief: only node:fs and node:path here (plus
+// the sibling dialogue.ts and harnesses.ts modules -- local files, not npm
+// packages), plus the global fetch (Node 18+, no import needed) that
+// deps.fetchImpl defaults to at the real call site in cli.ts.
+import { appendFileSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
+import { formatDelta, renderEntries } from "./dialogue.js";
+import { profileFor } from "./harnesses.js";
+import { resolveProject } from "./project.js";
+// SESSION_END_HOOK_TIMEOUT_S/SESSION_END_TIMEOUT_MS are the Claude Code
+// profile's numbers (harnesses.ts's PROFILES.claude_code) -- defined there,
+// not here, to avoid an import cycle (this file imports profileFor from
+// harnesses.ts; harnesses.ts must not import back). Re-exported unchanged so
+// capture.ts's existing `import { ... } from './hook.ts'` keeps working. See
+// harnesses.ts's own comment on them for the full derivation.
+export { SESSION_END_HOOK_TIMEOUT_S, SESSION_END_TIMEOUT_MS } from "./harnesses.js";
 // Bumped by hand at release time alongside package.json's "version" -- the
 // brief's call: a build-time constant here is fine, and it keeps this file
 // free of any fs reach into its own package.json (which would also be
 // wrong at runtime, since dist/hook.js does not sit next to package.json
-// the way src/hook.ts does).
-const SHIM_VERSION = '0.1.0';
-const HARNESS = 'claude_code';
-const CONFIG_FILE_NAME = 'config.json';
+// the way src/hook.ts does). Exported since postBrief's request body and
+// hook.test.mjs's drift check (against package.json) both need it; task 14
+// (spec 012 §9) bumps this, package.json and the plugin manifest
+// (.codex-plugin/plugin.json) to 0.3.0 together.
+export const SHIM_VERSION = '0.3.0';
+// Exported for capture.ts, which writes the file this module reads.
+export const CONFIG_FILE_NAME = 'config.json';
 // Same-directory temp file + rename, exactly atomicWriteJson's technique in
 // cli.ts (see its comment for the full why: rename is only atomic within
 // one filesystem, so the temp file has to be a sibling of the real one).
@@ -81,7 +112,9 @@ function atomicWriteText(path, text) {
 // this module's own atomicWriteText writing it (that always writes a clean
 // non-negative integer), so this is cheap insurance against a corrupted
 // local file, not a path this module's own writes are expected to hit.
-function readWatermark(watermarkPath) {
+// Exported: a later run (spec 011 §8's bootstrap) reads watermarks with
+// the hook's own rule rather than re-implementing it.
+export function readWatermark(watermarkPath) {
     try {
         const raw = readFileSync(watermarkPath, 'utf8').trim();
         if (!/^\d+$/.test(raw))
@@ -93,25 +126,55 @@ function readWatermark(watermarkPath) {
         return 0;
     }
 }
-// Pure read: computes the delta and the watermark it would advance to, but
-// writes nothing. handleHookEvent only persists nextWatermark after the
-// POST built from `content` actually succeeds -- see its own comment.
-export function readDelta(transcriptPath, watermarkPath) {
+// Exported so postDelta (and a later run -- spec 011 §8's bootstrap) can
+// advance the watermark the same way after each piece that succeeds: one
+// atomic write, never a partial one a crash could leave mid-byte.
+export function writeWatermark(watermarkPath, offset) {
+    atomicWriteText(watermarkPath, String(offset));
+}
+// spec 011 §3: beside the watermark, not instead of it -- a session that
+// drops one span is still capturing everything else, and this file is the
+// record of where the holes are.
+export function droppedMarkerPath(watermarkPath) {
+    return watermarkPath + '.dropped';
+}
+// Pure read: formats what the file holds past the watermark by the
+// cc-dialogue-v1 rule and returns the surviving pieces with absolute byte
+// offsets, but writes nothing -- handleHookEvent only persists a piece's
+// `end` after the POST built from its `text` actually succeeds (see
+// postDelta). null covers two different "nothing to send yet" cases that
+// the caller treats the same way: no transcript to read at all (missing or
+// unreadable file -- e.g. transcript_path's documented async-write lag,
+// research doc §2, means the file may not exist yet on a very short
+// session), or bytes past the watermark that do not yet contain one
+// complete line (spec 011 §2 -- a read landing inside a write must not
+// send half a JSON record; the next event's read starts from the same
+// watermark and sees the completed line). A non-null result can still hold
+// zero pieces -- every new line was dropped by the formatting rule -- and
+// the caller still advances the watermark to `end` in that case, per
+// formatDelta's own contract.
+export function readDelta(transcriptPath, watermarkPath, 
+// Which formatting rule to run past the watermark -- dialogue.ts's
+// cc-dialogue-v1 by default (every caller before task 8, and every reader
+// test above, wants exactly that); postDelta below passes the running
+// event's profile.formatDelta instead, so the same watermark/piece
+// machinery serves codex-dialogue-v1 too without a second copy of this
+// function.
+formatDeltaFn = formatDelta) {
     let buf;
     try {
         buf = readFileSync(transcriptPath);
     }
     catch {
-        // Missing or unreadable transcript -- e.g. transcript_path's documented
-        // async-write lag (research doc §2) means the file may not exist yet at
-        // all on a very short session. Nothing to send is not an error.
         return null;
     }
-    const size = buf.length;
     const offset = readWatermark(watermarkPath);
-    if (offset >= size)
+    if (offset >= buf.length)
         return null; // nothing new since last watermark (also covers a shrunk/rotated file)
-    return { content: buf.subarray(offset).toString('utf8'), nextWatermark: size };
+    const { pieces, end } = formatDeltaFn(buf.subarray(offset));
+    if (end === 0)
+        return null; // the only new bytes are an incomplete trailing line
+    return { pieces: pieces.map((p) => ({ ...p, end: offset + p.end })), end: offset + end, offset };
 }
 // Reads {url, key} from <configDir>/config.json. Anything short of a clean
 // {url: string, key: string} object -- the file absent (task 15 has not run
@@ -154,59 +217,122 @@ function postJson(deps, config, path, body, signal) {
         signal,
     });
 }
-// SessionEnd hooks share a 1.5s budget by default (raisable only to 60s),
-// cannot block Claude Code's own exit, and must be fire-and-forget --
-// research doc §2. An unbounded await here risks the process being killed
-// mid-request with no chance to exit cleanly or log why.
-//
-// 800ms is the network budget specifically, not the process's whole
-// lifetime -- measured against a real build (dist/index.js hook, real
-// fetch, a genuinely unresponsive local server), total process time from
-// spawn to exit-0 on an abort was ~1.33s with a 1000ms network timeout,
-// i.e. ~330ms of Node startup/stdin/fs overhead on this machine outside
-// the network wait itself. 800ms leaves that overhead roughly 2x the
-// margin (~370ms) under the *default* 1.5s budget rather than ~170ms, on
-// the assumption other machines' startup cost varies and Claude Code's own
-// pre-dispatch overhead, if any, is unknown and not ours to spend down.
-// Stop is not bounded this way (600s budget, and can run "async": true),
-// so its path through postDelta below does not use this.
-const SESSION_END_TIMEOUT_MS = 800;
+// undici wraps every network-level failure as TypeError("fetch failed") and
+// puts the reason on `cause` -- a DNS name, a refused connection, our own
+// abort, or (2026-09-04) an Authorization header carrying a control
+// character. The wrapper alone told an operator nothing. The cause is an
+// error class, a code and a sentence, never the request that failed, so
+// printing it keeps rule 2 of the module comment.
 function errorMessage(err) {
-    return err instanceof Error ? err.message : String(err);
+    if (!(err instanceof Error))
+        return String(err);
+    const cause = err.cause;
+    if (!(cause instanceof Error))
+        return err.message;
+    const code = cause.code;
+    const codePart = typeof code === 'string' ? ` ${code}` : '';
+    return `${err.message} (cause: ${cause.name}${codePart}: ${cause.message})`;
 }
-async function postHeartbeat(deps) {
-    const configPath = join(deps.configDir, CONFIG_FILE_NAME);
+// §6: 0.16 s start-up + one round trip measured 0.6-1.2 s; a black hole
+// (server up but never answering) would otherwise hold the session's first
+// turn open indefinitely, since nothing before postBrief bounds this wait.
+export const BRIEF_TIMEOUT_MS = 3000;
+// The memories a session opens with (spec 011 §5, §6, A9): posts the
+// harness/version/project triple to /brief and writes whatever `text` it
+// answers with to stdout, which Claude Code folds straight into the
+// session's context. Mirrors postHeartbeat's shape (same config read, same
+// do-nothing-and-log branches) but now bounded by an AbortController --
+// unlike a heartbeat nobody was waiting on, a hung /brief request sits in
+// the middle of the user's SessionStart, so this cannot wait forever.
+async function postBrief(event, deps, profile) {
     const config = readConfig(deps.configDir);
     if (!config) {
-        console.error(`waku-memory hook: no usable config at ${configPath} -- skipping heartbeat.`);
+        // Ruling R4 (spec 012 §4.1): Codex-only, quiet without a credential --
+        // no stdout, no stderr, no fetch call. Claude Code keeps this line
+        // (spec 011 A9: its output is unchanged).
+        if (!profile.silentWithoutCredential) {
+            console.error(`waku-memory hook: no usable config at ${join(deps.configDir, CONFIG_FILE_NAME)} -- no brief.`);
+        }
         return;
     }
+    if (typeof event.cwd !== 'string' || event.cwd === '') {
+        // No project to ask for. A do-nothing branch says why (conventions §8).
+        console.error('waku-memory hook: no cwd on this SessionStart event -- no brief.');
+        return;
+    }
+    const project = resolveProject(event.cwd);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.briefTimeoutMs ?? BRIEF_TIMEOUT_MS);
     try {
-        // No local state to advance on success and nothing useful to retry on
-        // failure (the next SessionStart supersedes it), so unlike postDelta
-        // there is no follow-up write gated on the response -- but the
-        // response is still worth a log line. hook_heartbeat.version exists so
-        // an operator can tell what is running on a machine that stopped
-        // reporting; silently treating a 401 (revoked key) or a 5xx the same
-        // as success would throw that signal away.
-        const res = await postJson(deps, config, '/ingest/heartbeat', { harness: HARNESS, version: SHIM_VERSION });
+        // POST, not GET: `project` is caller-supplied free text and a query
+        // string would put it in every access log (spec 011 §5). session_id
+        // travels here too (spec 012 §4) -- every harness, not just Codex.
+        const res = await postJson(deps, config, '/brief', { harness: profile.id, version: SHIM_VERSION, project, session_id: event.session_id }, controller.signal);
         if (!res.ok) {
-            console.error(`waku-memory hook: /ingest/heartbeat responded ${res.status}.`);
+            console.error(`waku-memory hook: /brief responded ${res.status} -- no brief.`);
+            return;
+        }
+        const body = (await res.json());
+        if (typeof body.text === 'string' && body.text !== '') {
+            // Identity for Claude Code (plain text); Codex wraps it in the hook
+            // JSON contract (spec 012 §4) -- the only place that knows which is
+            // profile.briefOutput itself, never a check here.
+            (deps.stdout ?? defaultStdout)(profile.briefOutput(body.text));
+        }
+        else {
+            // A 2xx with missing, non-string, or empty text is a failure like any other.
+            console.error('waku-memory hook: /brief responded with no usable text -- no brief.');
         }
     }
     catch (err) {
-        console.error(`waku-memory hook: POST /ingest/heartbeat failed -- ${errorMessage(err)}.`);
+        // This catch also handles a 2xx response whose body is not valid JSON.
+        console.error(`waku-memory hook: POST /brief failed -- ${errorMessage(err)}.`);
     }
-}
-async function postDelta(event, deps, source) {
-    if (!event.transcript_path) {
-        console.error(`waku-memory hook: no transcript_path on this ${event.hook_event_name} event -- skipping.`);
-        return;
+    finally {
+        clearTimeout(timer);
     }
+}
+const defaultStdout = (text) => {
+    process.stdout.write(text + '\n');
+};
+const squash = (s) => s.replace(/\s+/g, ' ').trim();
+// spec 011 §2: the text of every assistant: entry after the last user:
+// entry, joined by one space -- what "Claude's final response" (the hooks
+// reference's own words for last_assistant_message) means at record
+// granularity. assistant used tool: entries (role 'tool') are names, not
+// text, and are skipped rather than treated as a boundary. Scoping to the
+// trailing run, instead of searching the whole delta, is deliberate: a
+// short reply like "Done." that also occurred several turns earlier must
+// not be mistaken for the current turn's reply just because the words
+// match.
+export function trailingAssistantText(entries) {
+    let lastUser = -1;
+    entries.forEach((e, i) => {
+        if (e.role === 'user')
+            lastUser = i;
+    });
+    return entries
+        .slice(lastUser + 1)
+        .filter((e) => e.role === 'assistant')
+        .map((e) => e.text)
+        .join(' ');
+}
+async function postDelta(event, deps, source, profile) {
+    // Config is checked before transcript_path, deliberately: ruling R4 (spec
+    // 012 §4.1) says a Codex event with no usable config.json exits quietly
+    // regardless of what else about the event is missing or malformed --
+    // checking transcript_path first would let that branch's stderr line fire
+    // ahead of the credential check and break the "no stderr at all" promise.
     const configPath = join(deps.configDir, CONFIG_FILE_NAME);
     const config = readConfig(deps.configDir);
     if (!config) {
-        console.error(`waku-memory hook: no usable config at ${configPath} -- skipping.`);
+        if (!profile.silentWithoutCredential) {
+            console.error(`waku-memory hook: no usable config at ${configPath} -- skipping.`);
+        }
+        return;
+    }
+    if (!event.transcript_path) {
+        console.error(`waku-memory hook: no transcript_path on this ${event.hook_event_name} event -- skipping.`);
         return;
     }
     // session_id arrives parsed from stdin and is used as a path segment
@@ -215,79 +341,127 @@ async function postDelta(event, deps, source) {
     // configDir/state. The same-user trust boundary already limits the blast
     // radius, but this removes the footgun rather than relying on that alone.
     const watermarkPath = join(deps.configDir, 'state', basename(event.session_id));
-    const delta = readDelta(event.transcript_path, watermarkPath);
+    let delta = readDelta(event.transcript_path, watermarkPath, profile.formatDelta);
     if (delta === null) {
-        console.error(`waku-memory hook: nothing new in the transcript for session ${event.session_id} -- skipping.`);
-        return;
-    }
-    const body = {
-        harness: HARNESS,
-        session_id: event.session_id,
-        source,
-        content: delta.content,
-    };
-    if (event.cwd)
-        body.project = basename(event.cwd);
-    // Only session-end is bounded -- see SESSION_END_TIMEOUT_MS's comment.
-    // Stop's controller stays undefined, so its postJson call below gets
-    // `signal: undefined`, identical to not passing one at all.
-    const controller = source === 'session-end' ? new AbortController() : undefined;
-    const timer = controller ? setTimeout(() => controller.abort(), SESSION_END_TIMEOUT_MS) : undefined;
-    let res;
-    try {
-        res = await postJson(deps, config, '/ingest/session', body, controller?.signal);
-    }
-    catch (err) {
-        // Network error, DNS failure, our own SessionEnd timeout firing -- all
-        // reject rather than resolving with a bad status. Leaving the
-        // watermark alone resends exactly this delta next time; the ingest
-        // inbox's (user_id, session_id, content_hash) dedupe recognizes a retry
-        // of byte-identical content as already-seen and no-ops it for free.
-        // That guarantee is specific to retrying *this* unchanged delta -- see
-        // readWatermark's comment for the resend it does NOT cover.
-        console.error(`waku-memory hook: POST /ingest/session failed -- ${errorMessage(err)}.`);
-        return;
-    }
-    finally {
-        // Must run before any of the res.ok handling below, success or not --
-        // an uncleared timer holds the process open for the rest of
-        // SESSION_END_TIMEOUT_MS for no reason once the request has settled.
-        if (timer)
-            clearTimeout(timer);
-    }
-    if (!res.ok && res.status !== 413) {
-        // Covers everything except 2xx and 413 (handled below): 422 (should
-        // not happen -- body shape is fixed here), 5xx, 401/403. Leaving the
-        // watermark unchanged means the next event resends the same bytes; see
-        // the catch block above for exactly what the inbox dedupe does and
-        // does not guarantee about that resend.
-        console.error(`waku-memory hook: /ingest/session responded ${res.status} -- watermark left unchanged.`);
-        return;
-    }
-    if (res.status === 413) {
-        // The endpoint has no server-side chunking (MAX_INGEST_CONTENT_BYTES in
-        // ingest.py, checked before any repository call) -- this exact span can
-        // never succeed as-is. Since the watermark only advances on success and
-        // the transcript only grows, leaving it unchanged here would 413 again
-        // next time with an even larger span, permanently wedging capture for
-        // the rest of this session. Advancing past it loses this one delta but
-        // keeps every later turn capturable -- the strictly better of the two.
-        console.error(`waku-memory hook: /ingest/session responded 413 for session ${event.session_id} -- ` +
-            `dropping this span (too large to ever fit) and advancing past it.`);
+        // spec 011 §2: the transcript can lag the turn past every complete
+        // line it holds. On Stop, a non-empty last_assistant_message is
+        // Claude's own record of what it just said (the hooks reference: "use
+        // this field rather than reading transcript_path" for exactly this
+        // reason) -- when the file has nothing new at all, that reply has not
+        // landed in it yet, and this is the only chance to send it before the
+        // next event finds it in the file for real and skips it (the
+        // trailing-run check below). The piece's `end` is the current
+        // watermark: nothing from the file is being consumed, only the
+        // out-of-band message.
+        if (source === 'stop' && typeof event.last_assistant_message === 'string' && event.last_assistant_message.trim() !== '') {
+            const current = readWatermark(watermarkPath);
+            const entry = { role: 'assistant', text: event.last_assistant_message };
+            delta = { pieces: [{ entries: [entry], text: renderEntries([entry]), end: current }], end: current, offset: current };
+        }
+        else {
+            console.error(`waku-memory hook: nothing new in the transcript for session ${event.session_id} -- skipping.`);
+            return;
+        }
     }
-    // Past this point: res.ok (202 queued / 200 deduped) or 413 (see above)
-    // both advance the watermark the same way.
-    try {
-        atomicWriteText(watermarkPath, String(delta.nextWatermark));
+    // spec 011 §2: append last_assistant_message as one more assistant:
+    // entry unless the trailing run already reads it, on normalised
+    // whitespace -- so a final turn split across two text blocks (joined by
+    // the harness with a newline or a blank line) still matches. This runs
+    // on the structured entries, never on a piece's already-joined text,
+    // because a text can itself contain a blank line and the joined form
+    // cannot be split back to find the boundary between records.
+    if (source === 'stop' && typeof event.last_assistant_message === 'string' && event.last_assistant_message.trim() !== '') {
+        const msg = event.last_assistant_message;
+        const all = delta.pieces.flatMap((p) => p.entries);
+        const present = squash(trailingAssistantText(all)).includes(squash(msg));
+        if (!present) {
+            const entry = { role: 'assistant', text: msg };
+            const last = delta.pieces[delta.pieces.length - 1];
+            if (last) {
+                last.entries.push(entry);
+                last.text = renderEntries(last.entries);
+            }
+            else {
+                delta.pieces.push({ entries: [entry], text: renderEntries([entry]), end: delta.end });
+            }
+        }
     }
-    catch (err) {
-        // The POST outcome is already decided -- the local bookkeeping just
-        // did not keep up. A 202/200 that fails to persist here resends the
-        // same (now server-known) delta next time, same as any other write
-        // failure; a 413 that fails to persist here will simply 413 again on
-        // its own next attempt, same as if this write had never been tried.
-        console.error(`waku-memory hook: could not persist the watermark for session ${event.session_id} -- ${errorMessage(err)}.`);
+    // Only session-end is bounded -- see harnesses.ts's SESSION_END_TIMEOUT_MS
+    // comment. One deadline for the whole flush, not one budget per piece:
+    // several pieces each getting the full budget would let a many-piece
+    // session run far longer than the budget the installed hook entry
+    // actually gives the process. Stop's deadline stays undefined, so every
+    // piece's controller below is undefined too -- identical to not passing a
+    // signal at all. profile.sessionEndTimeoutMs is Codex's 2000 ms or Claude
+    // Code's 5000 ms; deps.sessionEndTimeoutMs (test-only) overrides either.
+    const budgetMs = deps.sessionEndTimeoutMs ?? profile.sessionEndTimeoutMs;
+    const deadline = source === 'session-end' ? Date.now() + budgetMs : undefined;
+    let previousEnd = delta.offset;
+    for (const piece of delta.pieces) {
+        const controller = deadline !== undefined ? new AbortController() : undefined;
+        const timer = controller ? setTimeout(() => controller.abort(), Math.max(0, deadline - Date.now())) : undefined;
+        let res;
+        try {
+            res = await postJson(deps, config, '/ingest/session', {
+                harness: profile.id,
+                session_id: event.session_id,
+                source,
+                content: piece.text,
+                content_format: profile.contentFormat,
+                ...(event.cwd ? { project: resolveProject(event.cwd) } : {}),
+            }, controller?.signal);
+        }
+        catch (err) {
+            // Network error, DNS failure, our own SessionEnd timeout firing --
+            // all reject rather than resolving with a bad status. The watermark
+            // stays at the last piece that succeeded; the ingest inbox's
+            // (user_id, session_id, content_hash) dedupe recognizes a retry of
+            // byte-identical content as already-seen and no-ops it for free.
+            // That guarantee is specific to retrying *this* unchanged piece --
+            // see readWatermark's comment for the resend it does NOT cover.
+            console.error(`waku-memory hook: POST /ingest/session failed -- ${errorMessage(err)}.`);
+            return;
+        }
+        finally {
+            // Must run before any of the res.ok handling below, success or not --
+            // an uncleared timer holds the process open for no reason once the
+            // request has settled.
+            if (timer)
+                clearTimeout(timer);
+        }
+        if (res.status === 413) {
+            // The endpoint has no server-side chunking (MAX_INGEST_CONTENT_BYTES
+            // in ingest.py, checked before any repository call) -- a piece is
+            // already cut under MAX_PIECE_BYTES, so this is the backstop for the
+            // one record that is itself over the cap (spec 011 §3), which no
+            // dialogue record should ever be. One span per line, appended -- a
+            // second drop in the same session adds a line, never overwrites the
+            // first, so bootstrap (§8) can see every hole.
+            mkdirSync(dirname(watermarkPath), { recursive: true });
+            appendFileSync(droppedMarkerPath(watermarkPath), `${previousEnd}-${piece.end}\n`);
+            console.error(`waku-memory hook: /ingest/session responded 413 for session ${event.session_id} -- ` +
+                `dropping this piece and advancing past it.`);
+        }
+        else if (!res.ok) {
+            // 422 included (spec 011 §4, deployment order): an API that does not
+            // yet know content_format leaves the watermark where it is, same as
+            // any other non-2xx (5xx, 401/403) -- the next event resends the
+            // whole growing delta rather than losing this piece.
+            console.error(`waku-memory hook: /ingest/session responded ${res.status} -- watermark left unchanged.`);
+            return;
+        }
+        // Past this point: res.ok (202 queued / 200 deduped) or 413 (see
+        // above) both advance the watermark the same way, to this piece's end.
+        writeWatermark(watermarkPath, piece.end);
+        previousEnd = piece.end;
     }
+    // spec 011 §3: a delta that produced zero pieces (every new line was
+    // dropped by the formatting rule) still consumes to `delta.end` --
+    // formatDelta's own contract -- so those lines are never re-read. The
+    // same catches a trailing run of dropped lines after the last real
+    // piece, when that piece's own `end` stops short of the full delta.
+    if (delta.pieces.length === 0 || delta.end > previousEnd)
+        writeWatermark(watermarkPath, delta.end);
 }
 // Entry point cli.ts's run() calls after reading and JSON.parsing stdin --
 // stdin reading deliberately does not live here (see the module comment and
@@ -308,15 +482,21 @@ export async function handleHookEvent(event, deps) {
             console.error('waku-memory hook: received a malformed hook event on stdin -- skipping.');
             return;
         }
+        // The only place that asks "which harness?" -- everything downstream
+        // (postBrief, postDelta, readDelta) takes the answer as a profile, never
+        // as a string to compare against. deps.harness is typed HarnessId, so
+        // profileFor always finds an entry in PROFILES; cli.ts's dispatch() is
+        // what rejects an unknown --harness value before this is ever reached.
+        const profile = profileFor(deps.harness ?? 'claude_code');
         switch (event.hook_event_name) {
             case 'SessionStart':
-                await postHeartbeat(deps);
+                await postBrief(event, deps, profile);
                 return;
             case 'Stop':
-                await postDelta(event, deps, 'stop');
+                await postDelta(event, deps, 'stop', profile);
                 return;
             case 'SessionEnd':
-                await postDelta(event, deps, 'session-end');
+                await postDelta(event, deps, 'session-end', profile);
                 return;
             default:
                 console.error(`waku-memory hook: ignoring unhandled event "${String(event.hook_event_name)}".`);