waku-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Waku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/capture.js

@@ -0,0 +1,231 @@
+// `capture enable` / `capture disable` -- the one gesture that turns
+// automatic memory capture on, and the disclosure gate it exists to carry.
+// Wired by cli.ts, the same split hook.ts established: everything here
+// takes its inputs as plain values (a deps bag, an already-decided action)
+// so capture.test.mjs can drive it against temp directories and an injected
+// prompt, never a real ~/.claude or ~/.waku-memory and never real stdin.
+//
+// This command is where status.md item 9's disclosure obligation is
+// actually discharged: enabling capture means every turn of the user's
+// Claude Code sessions is posted to our server and sent on to Anthropic for
+// extraction. The gate below is deliberately not a formality -- see
+// DISCLOSURE and enable()'s ordering, which prints it and requires a typed
+// "y" before anything else happens, including asking for a key.
+//
+// Zero dependencies, per the shim's package.json: only node:fs, node:path
+// and node:util (all built in) below.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+// The marker every hook command this tool writes contains, and the only
+// thing removeHookSettings uses to tell "ours" from a foreign hook on the
+// same event. Deliberately just the tail of the real command (not the full
+// "npx -y waku-memory hook" string) so a hand-edited variant --
+// different flags, a pinned version -- is still recognized as ours.
+export const WAKU_HOOK_MARKER = 'waku-memory hook';
+// No separate script file to install, version, or leave stale (spec 005):
+// every event runs the shim package itself via npx. `-y` skips npm's
+// install-confirmation prompt, which would otherwise hang a hook that has
+// no terminal to answer it.
+const WAKU_HOOK_COMMAND = `npx -y ${WAKU_HOOK_MARKER}`;
+// Must match hook.ts's own (unexported) CONFIG_FILE_NAME -- the two files
+// agree on this only by convention, not by import, because hook.ts is
+// deliberately dependency-free of this file (it is the piece that runs
+// unattended on every turn; this is the piece a human runs once).
+const CONFIG_FILE_NAME = 'config.json';
+// `Stop` is where captured content is actually sent -- "async": true so it
+// runs in the background without blocking the turn (600s default budget,
+// research doc §2). `SessionStart` posts the liveness heartbeat on the same
+// fire-and-forget basis. `SessionEnd` is the flush: all SessionEnd hooks
+// share a 1.5s-by-default exit budget (raisable only to 60s) and cannot
+// block Claude Code's own exit -- hook.ts's SESSION_END_TIMEOUT_MS comment
+// has the measured detail -- so it carries a `timeout` instead of `async`.
+// `async` only affects whether a hook keeps running after Claude Code moves
+// on; for an event that already cannot block exit, that distinction does
+// not apply, so it is left off rather than set to a value the harness
+// ignores anyway (pinned by the given test's `sessionEnd.async === undefined`).
+const HOOK_EVENTS = {
+    Stop: { type: 'command', command: WAKU_HOOK_COMMAND, async: true },
+    SessionStart: { type: 'command', command: WAKU_HOOK_COMMAND, async: true },
+    SessionEnd: { type: 'command', command: WAKU_HOOK_COMMAND, timeout: 10 },
+};
+// A group is "ours" only if every hook inside it is ours -- mergeHookSettings
+// only ever writes single-hook groups, so in practice this means exactly
+// one hook whose command carries the marker, but the "every" check (rather
+// than "some") is what makes removeHookSettings's contract exact: it must
+// never delete a group that also carries someone else's hook.
+function isOwnGroup(group) {
+    return group.hooks.length > 0 && group.hooks.every((h) => h.command.includes(WAKU_HOOK_MARKER));
+}
+// Appends one group per event in HOOK_EVENTS, skipping any event that
+// already carries one of ours -- running `enable` twice must not duplicate
+// entries (pinned by the brief's idempotence test and this file's "running
+// twice" orchestration test). A foreign group already on the same event is
+// never inspected beyond isOwnGroup's check and is never reordered or
+// rewritten -- only ours is ever added.
+export function mergeHookSettings(existing) {
+    const hooks = { ...(existing.hooks ?? {}) };
+    for (const [event, entry] of Object.entries(HOOK_EVENTS)) {
+        const groups = hooks[event] ?? [];
+        if (!groups.some(isOwnGroup)) {
+            hooks[event] = [...groups, { hooks: [entry] }];
+        }
+    }
+    return { ...existing, hooks };
+}
+// The exact inverse: drops every group that is entirely ours, and drops an
+// event key altogether once nothing is left under it -- a stray
+// `"SessionStart": []` would be exactly as misleading as leaving the hook in
+// place, since both read as "something runs here". Not exported as
+// disable()'s whole job: disable() also decides whether there was anything
+// to remove at all (see its own comment).
+export function removeHookSettings(existing) {
+    if (!existing.hooks)
+        return existing;
+    const hooks = {};
+    for (const [event, groups] of Object.entries(existing.hooks)) {
+        const kept = groups.filter((g) => !isOwnGroup(g));
+        if (kept.length > 0)
+            hooks[event] = kept;
+    }
+    if (Object.keys(hooks).length === 0) {
+        const { hooks: _drop, ...rest } = existing;
+        return rest;
+    }
+    return { ...existing, hooks };
+}
+// The exact two sentences spec 005's "Disclosure" section requires, shown
+// at the moment that discharges status.md item 9's obligation for capture:
+// "before anyone outside the three of us is invited, and no later than the
+// day a worker is deployed, they need to be told the environment can lose
+// their data and that importing [or capturing] sends its contents to
+// Anthropic." Both facts, two sentences, nothing softened.
+export const DISCLOSURE = 'Captured content is sent to our servers and to Anthropic for extraction. ' +
+    'This is an alpha whose data can be lost.';
+// Exported so cli.ts's usage text can point at the same URL without a
+// second copy of it drifting out of sync.
+//
+// www.waku.one, not waku-mem.vercel.app, which this was until 2026-09-01 --
+// changed before the first npm publish rather than after, because `npx`
+// ships a default and an installed user keeps it until they update. That is
+// exactly how the API address became a cutover instead of an edit (spec
+// 008): a string that reaches strangers is expensive to move afterwards and
+// free to move now. tech.md calls the Vercel host an earlier one, kept and
+// not retired; this is the product's own address.
+export const KEYS_PAGE_URL = 'https://www.waku.one/account/keys';
+// Reads settings.json the same way applyToHarness (cli.ts) reads a harness
+// config: missing or blank is a blank slate (undefined here would wrongly
+// refuse the single most common first run -- no settings.json yet at all);
+// anything non-blank that fails to parse, or does not parse to a plain
+// object, is real corruption and returns undefined so the caller refuses
+// rather than risks merging into -- and later overwriting -- a file it
+// could not understand.
+function readClaudeSettings(settingsPath) {
+    let raw;
+    try {
+        raw = readFileSync(settingsPath, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    if (raw.trim() === '')
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+// The one gesture that turns capture on. Order is deliberate and each step
+// depends on the one before it having succeeded:
+//   1. refuse if Claude Code itself is not on this machine -- the directory
+//      is the evidence, the shim's own edit-don't-create rule adapted from
+//      cli.ts's harness handling;
+//   2. refuse if the existing settings.json cannot be safely read -- checked
+//      here, before the disclosure, so a machine this can never work on
+//      fails fast instead of making the user type through a consent flow
+//      first only to hit a wall at the end;
+//   3. print the disclosure and demand a typed "y" -- before anything else,
+//      including asking for the key, so declining costs the user nothing
+//      and asks for nothing;
+//   4. only then ask for the key;
+//   5. write config.json, then merge and write settings.json. Everything
+//      before this point (refusing, declining) writes nothing at all --
+//      that guarantee is real. This step itself is not atomic across the
+//      two files, though: config.json is committed to disk first, so a
+//      failure on the settings.json write right after -- disk full, a
+//      permission error -- does leave a real credential saved with no
+//      hook actually installed, i.e. capture silently not active despite
+//      config.json existing. Accepted rather than guarded against (no
+//      rollback, no pre-write dry run): the failure still propagates out
+//      of enable() to cli.ts's runCaptureCommand, which reports it and
+//      sets a nonzero exit code, so it is not silent; it fails toward
+//      "capture not enabled" rather than a consent bypass; and re-running
+//      `enable` repairs it, since writing config.json again is a plain
+//      overwrite (capture.test.mjs's "running twice" test).
+export async function enable(url, deps) {
+    if (!existsSync(deps.claudeDir)) {
+        console.error(`Claude Code not found at ${deps.claudeDir} -- install Claude Code first, then run ` +
+            `"npx waku-memory capture enable" again.`);
+        return 'refused';
+    }
+    const existingSettings = readClaudeSettings(deps.settingsPath);
+    if (existingSettings === undefined) {
+        console.error(`${deps.settingsPath}'s content is not something this tool can safely merge into -- ` +
+            `leaving it untouched. Nothing was written.`);
+        return 'refused';
+    }
+    console.log(DISCLOSURE);
+    console.log('');
+    const confirmation = await deps.prompt('Type "y" to continue, anything else to cancel: ');
+    if (confirmation.trim().toLowerCase() !== 'y') {
+        console.log('Capture not enabled -- nothing was written.');
+        return 'declined';
+    }
+    const key = (await deps.prompt(`Paste an API key from ${KEYS_PAGE_URL} (it is shown once, at mint time): `)).trim();
+    mkdirSync(deps.configDir, { recursive: true }); // first run: ~/.waku-memory may not exist yet
+    const configPath = join(deps.configDir, CONFIG_FILE_NAME);
+    // {mode: 0o600} is a request, not a guarantee: Windows has no POSIX
+    // owner-only bit for writeFileSync to set, so this line is best-effort
+    // there and fully effective on Unix. Correct to pass on every platform
+    // regardless -- harmless where it cannot apply, the right thing where it
+    // can. Not routed through atomicWriteJson: that writer has no mode
+    // parameter, and this file is small, freshly created, and not something
+    // Claude Code itself reads concurrently the way settings.json is -- the
+    // atomic temp-file-plus-rename technique earns its complexity there, not
+    // here.
+    writeFileSync(configPath, JSON.stringify({ url, key }, null, 2) + '\n', { mode: 0o600 });
+    const merged = mergeHookSettings(existingSettings);
+    deps.writeSettingsJson(deps.settingsPath, merged);
+    console.log('');
+    console.log(`Capture enabled -- wrote ${configPath} and merged hooks into ${deps.settingsPath}.`);
+    console.log('Start a new Claude Code session to pick up the hooks.');
+    return 'enabled';
+}
+// Removes exactly what enable() added and nothing else. Deliberately leaves
+// config.json in place: the key is the user's to revoke on the keys page,
+// not this tool's to delete -- disabling capture and revoking the
+// credential are two different decisions, and conflating them would make
+// "disable" destructive in a way its name does not promise.
+export async function disable(deps) {
+    const existingSettings = readClaudeSettings(deps.settingsPath);
+    if (existingSettings === undefined) {
+        console.error(`${deps.settingsPath}'s content is not something this tool can safely modify -- leaving it untouched.`);
+        return 'refused';
+    }
+    const removed = removeHookSettings(existingSettings);
+    if (isDeepStrictEqual(removed, existingSettings)) {
+        console.log('Capture was not enabled here -- nothing to remove.');
+        return 'nothing-to-disable';
+    }
+    deps.writeSettingsJson(deps.settingsPath, removed);
+    const configPath = join(deps.configDir, CONFIG_FILE_NAME);
+    console.log(`Capture disabled -- removed the hook entries from ${deps.settingsPath}.`);
+    console.log(`Your API key is still saved at ${configPath}. Revoke it at ${KEYS_PAGE_URL} if you want to ` +
+        `fully remove access.`);
+    return 'disabled';
+}

package/dist/cli.js

@@ -0,0 +1,501 @@
+// The argument dispatch and per-harness logic behind `npx waku-memory
+// setup` (see index.ts for the shim's overall job and the credential
+// story -- this file is everything downstream of "here is argv").
+//
+// Split out of index.ts on review: everything exported here is a plain
+// function with no top-level side effects, so cli.test.mjs can import and
+// call it directly against temp files. index.ts, by contrast, calls run()
+// the instant it's loaded -- which is exactly why nothing imports
+// index.ts itself in a test. Decision logic (dispatch, runSetup,
+// summarize) is also kept separate from the imperative shell that prints
+// and sets process.exitCode (run, setup), so the two things that were
+// actually wrong during manual testing -- argument dispatch dropping
+// --help, and the found/wrote/error tri-state collapsing into one boolean
+// -- are pinned by plain assertions on return values, not by mocking
+// console.log.
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { getHarnesses, getManualHarnesses, harnessConfigExists, mergeMcpConfig, } from "./harnesses.js";
+import { handleHookEvent } from "./hook.js";
+import { KEYS_PAGE_URL, disable, enable } from "./capture.js";
+export const DEFAULT_URL = 'https://api.waku.one/mcp';
+export const DEFAULT_NAME = 'waku';
+// The ingest base capture.ts writes into config.json -- deliberately not
+// DEFAULT_URL: that one carries setup's "/mcp" suffix, which is the wrong
+// shape for hook.ts's endpointUrl() to append "/ingest/session" etc. onto.
+export const DEFAULT_INGEST_URL = 'https://api.waku.one';
+// The step after the server is configured, and the one the whole product
+// claim rests on: nothing has been imported yet, so there is nothing in
+// another harness to find.
+//
+// spec.md's "The shim" section said this shim "triggers the import". It
+// never could: the same sentence says it obtains no credential, and
+// memory.import is an authenticated MCP call, so triggering it would need
+// exactly the credential ops-design §5 forbids this to hold. The spec is
+// amended (2026-08-25); this is the achievable half of what it wanted --
+// the user is told what to ask for, in words they can paste, by the one
+// thing on this machine that already knows the server is now configured.
+//
+// Names the two files by convention rather than reading the directory:
+// `npx waku-memory setup` is not necessarily run from a project root, and
+// listing files that are not there would be worse than naming the ones
+// people actually have.
+//
+// The last two lines are item 9's other half (spec 005 "Disclosure",
+// corrected 2026-08-28 during that spec's execution): this function was
+// once documented as already carrying that disclosure, and it never did --
+// memory.import has been reachable since spec 004, so a person could send a
+// file's contents to Anthropic having been told nothing. Matches
+// capture.ts's DISCLOSURE in voice and content, worded for import rather
+// than capture.
+export function importNote() {
+    return (`Then, to put this project's conventions into Waku, ask the agent:\n` +
+        `\n` +
+        `    Run memory.import with this project's CLAUDE.md and AGENTS.md.\n` +
+        `\n` +
+        `The agent reads the files and makes the call -- this installer cannot,\n` +
+        `because it holds no credential, by design. Extraction is asynchronous,\n` +
+        `so the memories appear shortly rather than in that call. After that they\n` +
+        `are available in your other projects and other harnesses, which is the\n` +
+        `point of importing them at all.\n` +
+        `\n` +
+        `Imported content is sent to our servers and to Anthropic for extraction.\n` +
+        `This is an alpha whose data can be lost.`);
+}
+export function parseArgs(argv) {
+    let name = DEFAULT_NAME;
+    let url = DEFAULT_URL;
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--name' && i + 1 < argv.length) {
+            name = argv[++i];
+        }
+        else if (arg === '--url' && i + 1 < argv.length) {
+            url = argv[++i];
+        }
+        else if (!arg.startsWith('--')) {
+            positional.push(arg);
+        }
+    }
+    // subcommand is only meaningful to the caller for "capture enable" /
+    // "capture disable" -- setup and hook both ignore it, same as they always
+    // ignored any positional beyond the first.
+    return { command: positional[0], subcommand: positional[1], name, url };
+}
+export function printUsage() {
+    console.log('Usage: npx waku-memory setup [--name <name>] [--url <url>]');
+    console.log('');
+    console.log(`  --name  key to add under mcpServers (default: "${DEFAULT_NAME}")`);
+    console.log(`  --url   server URL to write (default: ${DEFAULT_URL})`);
+    console.log('');
+    console.log('Usage: waku-memory hook');
+    console.log('');
+    console.log('  Reads one Claude Code hook event as JSON on stdin and reports it to');
+    console.log('  the server named in ~/.waku-memory/config.json. Invoked by Claude Code');
+    console.log('  itself (see "capture enable") -- not meant to be run by hand.');
+    console.log('');
+    console.log('Usage: waku-memory capture enable [--url <ingest-base>]');
+    console.log('');
+    console.log('  Turns on automatic capture: every turn of your Claude Code sessions is');
+    console.log('  sent to our server and on to Anthropic for extraction. Shows that');
+    console.log('  disclosure and demands a typed "y" before asking for anything else, then');
+    console.log(`  asks for an API key (mint one at ${KEYS_PAGE_URL})`);
+    console.log('  and installs the hook into ~/.claude/settings.json.');
+    console.log('');
+    console.log('Usage: waku-memory capture disable');
+    console.log('');
+    console.log('  Removes exactly the hook entries "capture enable" added. Your saved key');
+    console.log('  is left in place -- revoke it on the keys page if you want it gone too.');
+}
+export function dispatch(argv) {
+    // Checked ahead of parseArgs deliberately: --help/-h are flags, so
+    // parseArgs (which only special-cases --name/--url) would otherwise drop
+    // them silently and this would fall through to "no command" with the
+    // wrong exit code -- that was a real bug, caught by hand before any test
+    // existed to pin it. See cli.test.mjs's dispatch block.
+    if (argv.includes('--help') || argv.includes('-h'))
+        return { kind: 'help' };
+    const { command, subcommand, name, url } = parseArgs(argv);
+    if (command === undefined)
+        return { kind: 'no-command' };
+    if (command === 'hook')
+        return { kind: 'hook' };
+    if (command === 'capture') {
+        if (subcommand !== 'enable' && subcommand !== 'disable')
+            return { kind: 'unknown', command: 'capture' };
+        // parseArgs's `url` defaults to DEFAULT_URL (setup's "/mcp" endpoint)
+        // whenever --url is absent -- the wrong default here. Checking argv
+        // directly for the flag, rather than trusting that default, is the
+        // cheapest way to tell "the user passed --url" apart from "parseArgs's
+        // unrelated default happened to apply" without giving parseArgs a
+        // second, command-dependent default of its own.
+        return { kind: 'capture', action: subcommand, url: argv.includes('--url') ? url : DEFAULT_INGEST_URL };
+    }
+    if (command !== 'setup')
+        return { kind: 'unknown', command };
+    return { kind: 'setup', name, url };
+}
+// Same-directory temp file + rename: rename is only atomic within one
+// filesystem, so the temp file has to live next to the real one -- a
+// different directory (or /tmp on another device) would make the rename
+// itself non-atomic, which defeats the point. Without this,
+// writeFileSync(configPath, ...) truncates the real file before it writes
+// a single byte back; a crash, a kill, or a full disk in that window
+// leaves a real, in-use config -- ~78 KB and ~80 keys, by measurement --
+// truncated or corrupted.
+export const atomicWriteJson = (configPath, data) => {
+    const dir = dirname(configPath);
+    const tmpPath = join(dir, `.${basename(configPath)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`);
+    try {
+        writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+        renameSync(tmpPath, configPath);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch {
+            // Best-effort cleanup only -- the error below is the one that matters,
+            // and a failed cleanup must not hide it. Also fires harmlessly
+            // (ENOENT, swallowed the same way) if writeFileSync itself never got
+            // far enough to create tmpPath at all.
+        }
+        throw err;
+    }
+};
+// Adds `name` -> `url` to one harness's config file. Never throws: every
+// fallible step -- read, parse, merge, write -- is caught right here, so a
+// bad harness cannot stop the others from being tried and cannot crash the
+// process with a raw stack trace. Failure is the 'error' branch of the
+// return value, for runSetup()/setup() to tally and report.
+export function applyToHarness(configPath, harnessLabel, name, url, writeJson = atomicWriteJson) {
+    let existing;
+    try {
+        const raw = readFileSync(configPath, 'utf8');
+        if (raw.trim() === '') {
+            // An empty file is a blank slate, not corruption -- and it is the
+            // shipped initial state of a freshly installed harness. Measured
+            // 2026-08-26: ~/.cursor/mcp.json on this machine is zero bytes, with
+            // Cursor installed and never having had an MCP server added.
+            // JSON.parse('') throws, so without this branch the single most
+            // likely first-run state would be reported as "could not read or
+            // parse ... leaving it untouched" and setup would fail for exactly
+            // the people who had done nothing wrong -- the worst population to
+            // fail on, since they have no configuration to inspect for a clue.
+            // Deliberately narrow: only whitespace qualifies. Any non-blank
+            // content that fails to parse is real corruption and is still
+            // refused by the catch below, because overwriting a file whose
+            // contents we could not understand is the one thing this function
+            // must never do.
+            existing = {};
+        }
+        else {
+            const parsed = JSON.parse(raw);
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                // Valid JSON, but not a shape this tool can safely merge into.
+                // existing.mcpServers below would throw on a null base -- optional
+                // chaining only guards the property *lookup* (the "?.[name]" part),
+                // not "existing" itself being null -- reproduced against the
+                // compiled binary with a config file whose entire content is the
+                // JSON literal "null". Arrays and other primitives don't throw the
+                // same way, but spreading them into the merged object would
+                // silently corrupt the file instead, which is just as wrong.
+                // Refused for the same reason mergeMcpConfig refuses a same-name
+                // entry with a different URL: loud and legible beats a raw stack
+                // trace or silent corruption.
+                return {
+                    status: 'error',
+                    message: `${harnessLabel}: ${configPath}'s content is not a JSON object -- leaving it untouched.`,
+                };
+            }
+            existing = parsed;
+        }
+    }
+    catch (err) {
+        return {
+            status: 'error',
+            message: `${harnessLabel}: could not read or parse ${configPath} -- leaving it untouched.\n` +
+                `  ${err.message}`,
+        };
+    }
+    const alreadyPresent = existing.mcpServers?.[name] !== undefined;
+    let merged;
+    try {
+        merged = mergeMcpConfig(existing, name, url);
+    }
+    catch (err) {
+        // mergeMcpConfig's refusal: same name, different URL already there.
+        return { status: 'error', message: `${harnessLabel}: ${err.message}` };
+    }
+    if (alreadyPresent) {
+        return {
+            status: 'unchanged',
+            message: `${harnessLabel}: "${name}" already points at ${url} -- nothing to change.`,
+        };
+    }
+    try {
+        writeJson(configPath, merged);
+    }
+    catch (err) {
+        return {
+            status: 'error',
+            message: `${harnessLabel}: could not write ${configPath} -- ${err.message}`,
+        };
+    }
+    return { status: 'wrote', message: `${harnessLabel}: added "${name}" -> ${url} (${configPath}).` };
+}
+export function runSetup(harnesses, name, url, writeJson = atomicWriteJson) {
+    return harnesses.map((harness) => {
+        if (!harnessConfigExists(harness)) {
+            return {
+                harness: harness.name,
+                configPath: harness.configPath,
+                status: 'not-found',
+                message: `${harness.name}: not found at ${harness.configPath} -- skipping.`,
+            };
+        }
+        const { status, message } = applyToHarness(harness.configPath, harness.name, name, url, writeJson);
+        return { harness: harness.name, configPath: harness.configPath, status, message };
+    });
+}
+// Tracked as three separate facts on purpose: "found but already correct"
+// and "not found at all" collapsed into one boolean in an earlier draft,
+// which made a re-run on an already-configured machine print "no
+// supported harness config was found" -- false, and actively misleading
+// on what is probably the most common real invocation. See
+// cli.test.mjs's runSetup + summarize block.
+export function summarize(results) {
+    return {
+        foundAny: results.some((r) => r.status !== 'not-found'),
+        wroteAny: results.some((r) => r.status === 'wrote'),
+        hadError: results.some((r) => r.status === 'error'),
+    };
+}
+export function setup(name, url, harnesses = getHarnesses(), manualHarnesses = getManualHarnesses()) {
+    const results = runSetup(harnesses, name, url);
+    for (const r of results) {
+        if (r.status === 'error')
+            console.error(r.message);
+        else
+            console.log(r.message);
+    }
+    // Only the ones actually on this machine. A manual harness is reported
+    // as found -- it just cannot be written to -- so it counts toward
+    // "did we find anything at all" below, and specifically toward whether
+    // the import step is worth mentioning: someone who follows the
+    // instructions has a working server, same as an auto-configured one.
+    const manualPresent = manualHarnesses.filter(harnessConfigExists);
+    for (const h of manualPresent) {
+        console.log('');
+        console.log(h.note(name, url));
+    }
+    console.log('');
+    const { foundAny: autoFound, wroteAny, hadError } = summarize(results);
+    const foundAny = autoFound || manualPresent.length > 0;
+    if (wroteAny) {
+        console.log('Next: open the harness and use a waku tool. The first call will get a 401, ' +
+            'the harness will open your browser to sign in, and the call will then go ' +
+            'through on retry -- that browser popup is expected, not an error.');
+    }
+    else if (autoFound && !hadError) {
+        console.log('Already configured correctly -- nothing to change.');
+    }
+    else if (autoFound && hadError) {
+        console.log('Could not update every harness found -- see the messages above.');
+    }
+    else if (manualPresent.length > 0) {
+        // Deliberately its own branch rather than falling into "already
+        // configured": a manual harness being *present* is not the same as it
+        // being *configured*, and telling someone nothing needs changing when
+        // they still have a TOML block to paste is the more expensive of the
+        // two possible wrong messages.
+        console.log('Nothing was written: the only harness found here is one this shim does not ' +
+            'configure automatically -- follow the instructions above to finish.');
+    }
+    else {
+        console.log('Nothing was added: no supported harness config was found on this machine.');
+    }
+    // Printed whenever a usable server exists on this machine -- which
+    // includes the already-configured re-run, since a configured server with
+    // nothing imported is exactly the state a re-runner is most likely to be
+    // in. Withheld only when nothing was found at all, where the next step is
+    // to install a harness, not to import.
+    if (foundAny) {
+        console.log('');
+        console.log(importNote());
+    }
+    if (hadError)
+        process.exitCode = 1;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// Reads all of stdin and joins it back into one string. A hook event is a
+// single JSON object, normally delivered as one line -- readline is used
+// for it anyway (rather than collecting raw 'data' chunks) because it is
+// the built-in that already handles encoding and end-of-stream correctly,
+// and it is on the shim's short allowed-built-ins list for exactly this.
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        const lines = [];
+        process.stdin.on('error', reject);
+        const rl = createInterface({ input: process.stdin, terminal: false });
+        rl.on('line', (line) => lines.push(line));
+        rl.on('close', () => resolve(lines.join('\n')));
+    });
+}
+// The imperative shell around handleHookEvent: read stdin, parse it, hand
+// the result to the tested decision logic with the real deps (the user's
+// actual config dir, the real global fetch). Deliberately never awaited by
+// run() below -- see that call site's comment for why that is safe here
+// specifically, which is not the same as it being safe in general.
+async function runHookCommand() {
+    let raw;
+    try {
+        raw = await readStdin();
+    }
+    catch (err) {
+        console.error(`waku-memory hook: could not read stdin -- ${errorMessage(err)}.`);
+        return;
+    }
+    let event;
+    try {
+        event = JSON.parse(raw);
+    }
+    catch (err) {
+        // Malformed input is a no-op, not a crash: some future Claude Code
+        // hook event this shim was not written against, or a hand test of
+        // `waku-memory hook` with no stdin piped in at all.
+        console.error(`waku-memory hook: stdin was not valid JSON -- ${errorMessage(err)}.`);
+        return;
+    }
+    await handleHookEvent(event, { configDir: join(homedir(), '.waku-memory'), fetchImpl: fetch });
+}
+// The real deps enable()/disable() run against outside a test: real paths
+// under the user's home directory, an injected prompt (built by the two
+// call sites below), and cli.ts's own atomicWriteJson as the settings
+// writer -- capture.ts never imports atomicWriteJson itself (that would
+// import cli.ts from capture.ts, which already imports capture.ts the
+// other way around), so the cast below is the one place the two files'
+// JSON-shaped types meet. Safe in practice: atomicWriteJson only ever does
+// JSON.stringify(data) -- it has no opinion about McpConfig vs
+// ClaudeSettings beyond the type checker's.
+function realCaptureDeps(prompt) {
+    const claudeDir = join(homedir(), '.claude');
+    return {
+        claudeDir,
+        settingsPath: join(claudeDir, 'settings.json'),
+        configDir: join(homedir(), '.waku-memory'),
+        prompt,
+        writeSettingsJson: (path, data) => atomicWriteJson(path, data),
+    };
+}
+// Not awaited by run() below, for the same structural reason runHookCommand
+// isn't (see run()'s 'hook' case) -- but unlike hook, which must always
+// exit 0 so a capture bug can never read as the user's own session failing,
+// this command is interactive and its exit code is meant to mean something:
+// 'refused' (Claude Code missing, or a settings.json this tool cannot
+// safely touch) is the one outcome that should make a scripted caller
+// notice. 'declined' and the disable no-op are both a normal, successful
+// run that did exactly what was asked -- nothing.
+async function runCaptureCommand(action, url) {
+    if (action === 'disable') {
+        // disable() never prompts (see its own comment) -- no readline interface
+        // is created at all, and this stub is a fail-loud guard against that
+        // ever silently stopping being true.
+        const deps = realCaptureDeps(() => {
+            throw new Error('waku-memory capture disable: unexpectedly tried to prompt.');
+        });
+        const result = await disable(deps);
+        if (result === 'refused')
+            process.exitCode = 1;
+        return;
+    }
+    // One node:readline interface for both of enable()'s questions, answered
+    // visibly on the real terminal (the frontend keys page already told the
+    // user their pasted key shows once, so echoing it back is not a new
+    // exposure). Deliberately NOT rl.question() called twice: readline's
+    // 'line' event fires as soon as a full line is parsed out of whatever is
+    // currently buffered, with no listener to catch it unless a .question()
+    // call happens to already be pending at that exact moment. Over a piped
+    // (non-TTY) stdin, both answers can arrive in the same chunk before the
+    // second .question() has even been called -- its one-time listener
+    // attaches too late, the line that already fired is gone, and the
+    // returned promise never resolves. An unresolved promise alone does not
+    // keep Node's event loop alive, so the process then exits 0 having
+    // written nothing, with no error and no hang to point at it. Proven by
+    // hand against the compiled binary with piped stdin (Node's own
+    // top-level-await detector reproduces the identical stuck-callback
+    // symptom against a two-line pipe), not by the unit tests, which inject a
+    // prompt function and never touch real readline.
+    //
+    // Iterating the interface as an async iterator instead -- pulling one
+    // line per question from the same queue -- does not have this race: the
+    // iterator protocol buffers whatever arrives until something actually
+    // asks for it, so no line can be dropped between one answer and the next
+    // question being asked. Confirmed against the same two-line pipe before
+    // landing here.
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const lines = rl[Symbol.asyncIterator]();
+    try {
+        const prompt = async (question) => {
+            process.stdout.write(question);
+            const { value, done } = await lines.next();
+            return done ? '' : value; // stdin closed before an answer arrived -- treated as "declined"
+        };
+        const result = await enable(url, realCaptureDeps(prompt));
+        if (result === 'refused')
+            process.exitCode = 1;
+    }
+    finally {
+        rl.close();
+    }
+}
+export function run(argv) {
+    const d = dispatch(argv);
+    switch (d.kind) {
+        case 'help':
+            printUsage();
+            process.exitCode = 0;
+            return;
+        case 'no-command':
+            printUsage();
+            process.exitCode = 1;
+            return;
+        case 'unknown':
+            console.error(`Unknown command "${d.command}".`);
+            printUsage();
+            process.exitCode = 1;
+            return;
+        case 'setup':
+            setup(d.name, d.url);
+            return;
+        case 'hook':
+            // Exits 0 always, per the brief: set up front, not left to whatever
+            // the default happens to be, and never touched again on any failure
+            // path below this line. Not awaited -- index.ts does not await run()
+            // either, and a floating promise is only safe because
+            // runHookCommand() cannot reject: handleHookEvent already wraps its
+            // own body in a catch-all, and the try/catches above cover the stdin
+            // read and the JSON.parse that happen before it. The .catch() here is
+            // a second backstop, not the mechanism this relies on.
+            process.exitCode = 0;
+            void runHookCommand().catch((err) => {
+                console.error(`waku-memory hook: unexpected failure -- ${errorMessage(err)}.`);
+            });
+            return;
+        case 'capture':
+            void runCaptureCommand(d.action, d.url).catch((err) => {
+                console.error(`waku-memory capture: unexpected failure -- ${errorMessage(err)}.`);
+                process.exitCode = 1;
+            });
+            return;
+        default: {
+            const exhaustive = d;
+            throw new Error(`unhandled dispatch kind: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}

package/dist/harnesses.js

@@ -0,0 +1,52 @@
+// Where each harness keeps its MCP config, and how to add to it without
+// destroying what is there. One file per harness would be tidier and is not
+// worth it yet: the shapes are nearly identical, and the differences are
+// worth seeing side by side while there are only two.
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function mergeMcpConfig(existing, name, url) {
+    const servers = existing.mcpServers ?? {};
+    const current = servers[name];
+    if (current && current.url !== url) {
+        // Refuse rather than overwrite. Someone configured this by hand, with a
+        // different URL or with headers we cannot see the purpose of, and
+        // silently replacing it would undo a deliberate choice with no trace.
+        throw new Error(`"${name}" is already configured with a different URL (${current.url}). ` +
+            `Remove it or pass --name to use a different key.`);
+    }
+    return { ...existing, mcpServers: { ...servers, [name]: { type: 'http', url } } };
+}
+export function getHarnesses() {
+    return [{ name: 'Claude Code', configPath: join(homedir(), '.claude.json') }];
+}
+// Structurally typed rather than taking a Harness, so the same check serves
+// both lists -- a manual harness needs exactly the same "is it here?"
+// question answered, and duplicating existsSync for it would let the two
+// drift.
+export function harnessConfigExists(harness) {
+    return existsSync(harness.configPath);
+}
+// Printed only when ~/.codex/config.toml actually exists. Before 2026-08-26
+// this went to everyone on every run, including the Claude-Code-only user
+// who has no Codex and no use for a TOML block -- noise that made the
+// output worse the more harnesses we knew about, which is the wrong
+// direction for that to scale.
+export function codexNote(name, url) {
+    return (`Codex: found here, but not configured automatically -- this shim's\n` +
+        `knowledge of Codex's format comes from OpenAI's docs\n` +
+        `(learn.chatgpt.com/docs/extend/mcp), never from a real install, and\n` +
+        `writing a guessed shape into a config that is really there is worse\n` +
+        `than leaving it alone. Add this yourself, then run\n` +
+        `"codex mcp login ${name}" (Codex does not sign in on first use the way\n` +
+        `Claude Code does):\n` +
+        `    [mcp_servers.${name}]\n` +
+        `    url = "${url}"\n` +
+        `Codex also has a "codex mcp" subcommand (add/list/login), which would\n` +
+        `be the better route -- but its documented CLI syntax covers stdio\n` +
+        `servers only (checked 2026-08-26), so the TOML above is the part that\n` +
+        `can be stated exactly.`);
+}
+export function getManualHarnesses() {
+    return [{ name: 'Codex', configPath: join(homedir(), '.codex', 'config.toml'), note: codexNote }];
+}

package/dist/hook.js

@@ -0,0 +1,329 @@
+// 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.
+//
+// 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.
+//
+// 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';
+import { basename, dirname, join } from 'node:path';
+// 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';
+// 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).
+// Not the same function, because this file writes plain decimal text (the
+// watermark), not the McpConfig-shaped JSON atomicWriteJson's type signature
+// is fixed to -- reusing the pattern rather than reusing the export.
+function atomicWriteText(path, text) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true }); // first watermark for a session: state/ may not exist yet
+    const tmpPath = join(dir, `.${basename(path)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`);
+    try {
+        writeFileSync(tmpPath, text, 'utf8');
+        renameSync(tmpPath, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch {
+            // Best-effort cleanup only -- the error below is the one that
+            // matters, and a failed cleanup must not hide it.
+        }
+        throw err;
+    }
+}
+// Reads the byte offset left by a previous run. Missing file (first event
+// for this session) or blank/unparseable content are all the same thing to
+// the caller: "trust nothing, start from the top" -- never a throw.
+//
+// The whole trimmed string must be digits: Number.parseInt("1200\x00junk",
+// 10) === 1200, not NaN, so a bare parseInt would trust the numeric prefix
+// of a partially-corrupted file. A trusted-but-wrong offset that lands past
+// the real transcript size makes readDelta report "nothing new" while
+// content that was never actually sent sits unsent -- silent data loss, not
+// merely an extra resend, which is why this is stricter than it looks.
+//
+// Falling back to 0 after several prior *successful* sends resends a
+// concatenation the server has never hashed before -- content_hash
+// (job_repository.py) is a whole-body SHA-256, not overlap-aware, so the
+// inbox dedupe does NOT catch this case the way it catches a byte-identical
+// retry (see postDelta). That resend is re-enqueued and re-extracted:
+// bounded cost (duplicate jobs/facts), not lost or corrupted data. A
+// garbled watermark can in practice only come from something other than
+// 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) {
+    try {
+        const raw = readFileSync(watermarkPath, 'utf8').trim();
+        if (!/^\d+$/.test(raw))
+            return 0;
+        const n = Number.parseInt(raw, 10);
+        return Number.isFinite(n) && n >= 0 ? n : 0;
+    }
+    catch {
+        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) {
+    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)
+        return null; // nothing new since last watermark (also covers a shrunk/rotated file)
+    return { content: buf.subarray(offset).toString('utf8'), nextWatermark: size };
+}
+// 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
+// yet, or this is a harness other than Claude Code with capture never
+// enabled), empty, malformed JSON, or missing/empty fields -- is reported
+// as "no config" rather than distinguished further: the caller's response
+// (log one line, send nothing) is identical either way, and the specific
+// reason is exactly the kind of detail that is not worth a second log line
+// per conventions.md §8's "every do-nothing branch logs why", not "logs
+// why in detail".
+function readConfig(configDir) {
+    try {
+        const raw = readFileSync(join(configDir, CONFIG_FILE_NAME), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        const { url, key } = parsed;
+        if (typeof url !== 'string' || url === '' || typeof key !== 'string' || key === '')
+            return null;
+        return { url, key };
+    }
+    catch {
+        return null;
+    }
+}
+// config.url is the bare API origin (e.g. "https://api.example.test"); this
+// is the one place that turns it into a full endpoint, so a trailing slash
+// in a hand-edited config.json can't produce "https://host//ingest/...".
+function endpointUrl(baseUrl, path) {
+    return baseUrl.replace(/\/+$/, '') + path;
+}
+function postJson(deps, config, path, body, signal) {
+    return deps.fetchImpl(endpointUrl(config.url, path), {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${config.key}`,
+        },
+        body: JSON.stringify(body),
+        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;
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function postHeartbeat(deps) {
+    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 heartbeat.`);
+        return;
+    }
+    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 });
+        if (!res.ok) {
+            console.error(`waku-memory hook: /ingest/heartbeat responded ${res.status}.`);
+        }
+    }
+    catch (err) {
+        console.error(`waku-memory hook: POST /ingest/heartbeat 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;
+    }
+    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.`);
+        return;
+    }
+    // session_id arrives parsed from stdin and is used as a path segment
+    // below -- basename() strips any embedded separators (e.g. "../../x") so
+    // a malformed value cannot walk the watermark path outside
+    // 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);
+    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.`);
+    }
+    // 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));
+    }
+    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)}.`);
+    }
+}
+// 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
+// task 14's brief) so this function's whole surface is plain values a test
+// can construct directly, no process.stdin involved.
+//
+// The one try/catch below is not "the error handling"; it is the backstop
+// behind branches that already handle every failure mode the brief names
+// (missing/malformed config, an empty delta, a non-2xx response, a rejected
+// fetch) without throwing. Reaching this catch means something those
+// branches did not anticipate happened -- possibly even `event` itself
+// being null or some other non-object JSON.parse handed back for
+// degenerate stdin (e.g. literal "null") -- and it still must not become an
+// uncaught rejection in cli.ts's fire-and-forget call.
+export async function handleHookEvent(event, deps) {
+    try {
+        if (event === null || typeof event !== 'object') {
+            console.error('waku-memory hook: received a malformed hook event on stdin -- skipping.');
+            return;
+        }
+        switch (event.hook_event_name) {
+            case 'SessionStart':
+                await postHeartbeat(deps);
+                return;
+            case 'Stop':
+                await postDelta(event, deps, 'stop');
+                return;
+            case 'SessionEnd':
+                await postDelta(event, deps, 'session-end');
+                return;
+            default:
+                console.error(`waku-memory hook: ignoring unhandled event "${String(event.hook_event_name)}".`);
+                return;
+        }
+    }
+    catch (err) {
+        console.error(`waku-memory hook: unexpected failure -- ${errorMessage(err)}.`);
+    }
+}

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// npx waku-memory setup -- writes the waku MCP server's URL into every
+// harness config this shim knows how to edit safely, without disturbing
+// anything already there (harnesses.ts:mergeMcpConfig).
+//
+// This obtains no credential and stores none. The harness itself hits the
+// server, gets a 401 naming a protected-resource document, runs discovery,
+// opens a browser, and holds the resulting token -- ops-design §5 and spec
+// 003's real client both settled that a URL is all an install step needs to
+// write. The import itself is not this shim's job either: the agent does
+// that afterwards, through memory.import, because by then it already has
+// both the file access and the token.
+//
+// The actual argument dispatch and per-harness logic lives in cli.ts,
+// which has no top-level side effects on import -- cli.test.mjs imports it
+// directly, without this file (or its shebang, or process.argv) coming
+// along for the ride.
+import { run } from "./cli.js";
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "waku-memory",
+  "version": "0.1.0",
+  "description": "Install Waku Memory into your agent harness, and turn on automatic session capture.",
+  "keywords": ["mcp", "memory", "claude-code", "agent", "waku"],
+  "homepage": "https://github.com/ShenSeanChen/waku-memory-backend/tree/spec-driven/shim#readme",
+  "bugs": "https://github.com/ShenSeanChen/waku-memory-backend/issues",
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShenSeanChen/waku-memory-backend.git",
+    "directory": "shim"
+  },
+  "type": "module",
+  "bin": { "waku-memory": "./dist/index.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test \"src/**/*.test.mjs\"",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": { "typescript": "^5.7.3", "@types/node": "^22.10.7" }
+}