waku-memory 0.2.0 → 0.4.0

package/dist/cli.js

@@ -13,16 +13,17 @@
 // --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 { spawnSync } from 'node:child_process';
-import { readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, 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 { fileURLToPath } from 'node:url';
 import { DEFAULT_WINDOW_DAYS } from "./bootstrap.js";
-import { getHarnesses, getManualHarnesses, harnessConfigExists, mergeMcpConfig, } from "./harnesses.js";
+import { getHarnesses, harnessConfigExists, mergeMcpConfig, profileFor, } from "./harnesses.js";
 import { SHIM_VERSION, handleHookEvent } from "./hook.js";
-import { KEYS_PAGE_URL, disable, enable } from "./capture.js";
+import { DISCLOSURE, KEYS_PAGE_URL, disable, enable, status, urlPair, } from "./capture.js";
+import { login } from "./login.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
@@ -73,6 +74,9 @@ export function parseArgs(argv) {
     let since;
     let all = false;
     let noBootstrap = false;
+    let harness;
+    let login = false;
+    let key;
     const positional = [];
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -85,12 +89,28 @@ export function parseArgs(argv) {
         else if (arg === '--since' && i + 1 < argv.length) {
             since = argv[++i];
         }
+        else if (arg === '--harness' && i + 1 < argv.length) {
+            harness = argv[++i];
+        }
         else if (arg === '--all') {
             all = true;
         }
         else if (arg === '--no-bootstrap') {
             noBootstrap = true;
         }
+        else if (arg === '--login') {
+            login = true;
+        }
+        else if (arg === '--key') {
+            // Unlike --name/--url/--since/--harness above, a value starting with
+            // "--" is deliberately NOT consumed here -- "--key --url x" must
+            // leave --url for its own branch to see, not swallow it as the key's
+            // literal value. Left undefined (with the token itself still in argv,
+            // for dispatch()'s argv.includes('--key') check) either way: no next
+            // token at all, or the next token is itself a flag.
+            if (i + 1 < argv.length && !argv[i + 1].startsWith('--'))
+                key = argv[++i];
+        }
         else if (!arg.startsWith('--')) {
             positional.push(arg);
         }
@@ -98,21 +118,34 @@ export function parseArgs(argv) {
     // 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, since, all, noBootstrap };
+    return { command: positional[0], subcommand: positional[1], name, url, since, all, noBootstrap, harness, login, key };
 }
 export function printUsage() {
+    console.log('Usage: waku-memory login [--url <ingest-base>]');
+    console.log('');
+    console.log('  Signs in through the browser and mints an API key, without you ever seeing');
+    console.log('  it -- the same flow "capture enable" offers as its first question, run on');
+    console.log('  its own. Shows the disclosure first; prints "Signed in as <email>" on');
+    console.log(`  success, and stores the key in ~/.waku-memory/config.json.`);
+    console.log('');
     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('  If a harness was found, setup then asks whether to also turn on automatic');
+    console.log('  capture -- the same flow as "capture enable", asked so you do not have to');
+    console.log('  type a second command. Default is no; press Enter to skip it.');
+    console.log('');
+    console.log('Usage: waku-memory hook [--harness <claude_code|codex>]');
     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('  Reads one hook event as JSON on stdin and reports it to the server named');
+    console.log('  in ~/.waku-memory/config.json. Invoked by the harness itself (see');
+    console.log('  "capture enable") -- not meant to be run by hand.');
     console.log('');
-    console.log('Usage: waku-memory capture enable [--url <ingest-base>] [--since <N>d] [--all] [--no-bootstrap]');
+    console.log('  --harness  which harness sent the event (default: "claude_code")');
+    console.log('');
+    console.log('Usage: waku-memory capture enable [--url <ingest-base>] [--since <N>d] [--all] [--no-bootstrap] [--login] [--key <key>]');
     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');
@@ -127,11 +160,18 @@ export function printUsage() {
     console.log(`  --since <N>d    only scan transcripts from the last N days (default: ${DEFAULT_WINDOW_DAYS}d)`);
     console.log('  --all           scan full history instead, ignoring --since');
     console.log('  --no-bootstrap  skip the scan and the third question entirely');
+    console.log('  --login         sign in in the browser without asking');
+    console.log('  --key <key>     use this key without asking');
     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.');
+    console.log('');
+    console.log('Usage: waku-memory capture status');
+    console.log('');
+    console.log('  Prints whether capture is installed for Claude Code and for Codex, and');
+    console.log('  whether a key is saved. Reads only -- never writes.');
 }
 // The default third question: on, with the full DEFAULT_WINDOW_DAYS window
 // (spec 011 §8/§9, task 14). Used both as dispatch()'s no-flags-given result
@@ -158,23 +198,64 @@ export function dispatch(argv) {
     // 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, since, all, noBootstrap } = parseArgs(argv);
+    const { command, subcommand, name, url, since, all, noBootstrap, harness, login: loginFlag, key } = parseArgs(argv);
     if (command === undefined)
         return { kind: 'no-command' };
-    if (command === 'hook')
-        return { kind: 'hook' };
+    if (command === 'login') {
+        // Same urlPair() rule "capture enable" uses -- see its own comment
+        // below: whatever shape --url was typed in, the ingest base is what
+        // realLoginDeps(d.url) (run()) and login.ts's own apiBase param need,
+        // never the "/mcp"-suffixed mcpUrl.
+        return { kind: 'login', url: urlPair(url).ingestUrl };
+    }
+    if (command === 'hook') {
+        // --harness with no value: parseArgs only consumes it when a next token
+        // exists, so a trailing "--harness" leaves `harness` undefined the same
+        // way a trailing "--since" does -- but unlike --since (which falls back
+        // to a default), a bare --harness is treated the same as an unknown id,
+        // per the brief: both are the caller trying to say something this shim
+        // does not understand.
+        if (argv.includes('--harness') && harness === undefined) {
+            return {
+                kind: 'bad-flag',
+                message: 'waku-memory hook: --harness requires a value (e.g. "codex") -- got none.',
+            };
+        }
+        const harnessId = harness ?? 'claude_code';
+        if (!profileFor(harnessId)) {
+            return {
+                kind: 'bad-flag',
+                message: `waku-memory hook: unknown harness "${harnessId}" -- expected one of: claude_code, codex.`,
+            };
+        }
+        return { kind: 'hook', harness: harnessId };
+    }
     if (command === 'capture') {
-        if (subcommand !== 'enable' && subcommand !== 'disable')
+        if (subcommand !== 'enable' && subcommand !== 'disable' && subcommand !== 'status') {
             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.
-        const ingestUrl = argv.includes('--url') ? url : DEFAULT_INGEST_URL;
+        }
+        if (subcommand === 'status')
+            return { kind: 'capture', action: 'status' };
+        // parseArgs's `url` already defaults to DEFAULT_URL (the "/mcp" literal)
+        // whenever --url is absent, so no argv.includes('--url') check is needed
+        // here any more (fix round 1 had one, to avoid trusting parseArgs's
+        // setup-shaped default -- round 2 replaces the whole thing with
+        // urlPair(), which produces the right pair from DEFAULT_URL exactly the
+        // same way it does from any --url a person types).
+        //
+        // Fix round 2 (re-review finding #1, spec 012 §4.2): urlPair() (capture.ts)
+        // is the one place that decides "given this one URL, what is the ingest
+        // base and what is the MCP endpoint" -- round 1's own rule (strip a
+        // trailing "/mcp" from mcpUrl to get ingestUrl) only worked when the
+        // input was already MCP-shaped; an ingest-shaped --url (no "/mcp" to
+        // strip, exactly the shape cli.ts's own usage text documents:
+        // "capture enable [--url <ingest-base>]") left mcpUrl === ingestUrl,
+        // reproducing the original defect. urlPair always derives the ingest
+        // base first and always appends "/mcp" to build mcpUrl, so every shape
+        // (bare, trailing slash, "/mcp"-suffixed) converges on the same pair.
+        const { ingestUrl, mcpUrl } = urlPair(url);
         if (subcommand === 'disable') {
-            return { kind: 'capture', action: 'disable', url: ingestUrl, bootstrap: DEFAULT_BOOTSTRAP };
+            return { kind: 'capture', action: 'disable', url: ingestUrl, mcpUrl, bootstrap: DEFAULT_BOOTSTRAP };
         }
         // --since is validated unconditionally (even alongside --all) so a typo
         // is never silently swallowed by an --all that happened to be present
@@ -195,7 +276,33 @@ export function dispatch(argv) {
         }
         if (all)
             windowDays = null;
-        return { kind: 'capture', action: 'enable', url: ingestUrl, bootstrap: { windowDays, enabled: !noBootstrap } };
+        // --login / --key <key> (task 13, spec 012 §7): the credential decision
+        // capture.ts's enable() now takes as its own parameter -- see
+        // Credential's own comment (capture.ts) for why it lives there and not
+        // on CaptureDeps. Both bad-flag checks run unconditionally, the same
+        // way --since's does above, so a scripted caller gets a loud, specific
+        // error instead of the question silently being asked anyway.
+        if (loginFlag && key !== undefined) {
+            return {
+                kind: 'bad-flag',
+                message: 'waku-memory capture enable: --login and --key cannot be used together -- pick one.',
+            };
+        }
+        if (argv.includes('--key') && key === undefined) {
+            return {
+                kind: 'bad-flag',
+                message: 'waku-memory capture enable: --key requires a value -- got none.',
+            };
+        }
+        const credential = key !== undefined ? { kind: 'key', key } : loginFlag ? { kind: 'login' } : { kind: 'ask' };
+        return {
+            kind: 'capture',
+            action: 'enable',
+            url: ingestUrl,
+            mcpUrl,
+            bootstrap: { windowDays, enabled: !noBootstrap },
+            credential,
+        };
     }
     if (command !== 'setup')
         return { kind: 'unknown', command };
@@ -209,12 +316,22 @@ export function dispatch(argv) {
 // 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`);
+//
+// Shared by every writer below it (task 10, spec 012 §4.6): atomicWriteJson
+// (settings.json, config files), writeJsonFile (Codex's hooks.json and the
+// personal marketplace file) and writeCodexText (Codex's config.toml, whose
+// content is already a complete file, not a value to serialise). The
+// mkdirSync up front is new with those two Codex JSON writers -- neither
+// ~/.codex nor ~/.agents/plugins is guaranteed to exist yet the first time
+// capture enable runs on a Codex machine, unlike ~/.claude (whose presence
+// is what enable() already checked before writing anything under it).
+function atomicWrite(path, content) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmpPath = join(dir, `.${basename(path)}.${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);
+        writeFileSync(tmpPath, content, 'utf8');
+        renameSync(tmpPath, path);
     }
     catch (err) {
         try {
@@ -228,7 +345,21 @@ export const atomicWriteJson = (configPath, data) => {
         }
         throw err;
     }
-};
+}
+export const atomicWriteJson = (configPath, data) => atomicWrite(configPath, JSON.stringify(data, null, 2) + '\n');
+// capture.ts's CaptureDeps.writeJsonFile (task 10): the same atomic write as
+// atomicWriteJson above, generalised to `unknown` -- capture.ts has no more
+// opinion about CodexHooksFile vs MarketplaceFile than atomicWriteJson has
+// about McpConfig beyond JSON.stringify, which is exactly why a function
+// typed `(data: unknown) => void` is assignable wherever `WriteJson` is
+// expected (parameter types are contravariant) and the reverse is not worth
+// forcing through a cast.
+export const writeJsonFile = (path, data) => atomicWrite(path, JSON.stringify(data, null, 2) + '\n');
+// capture.ts's CaptureDeps.writeText (task 10): writes `text` exactly as
+// given, no JSON.stringify and no added newline -- mergeCodexToml
+// (codex-config.ts) already returns the complete file text, trailing
+// newline included when the original file had one.
+export const writeCodexText = (path, text) => atomicWrite(path, text);
 // 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
@@ -337,7 +468,49 @@ export function summarize(results) {
         hadError: results.some((r) => r.status === 'error'),
     };
 }
-export function setup(name, url, harnesses = getHarnesses(), manualHarnesses = getManualHarnesses()) {
+// The one-shot readline prompt setup()'s own new question needs, real
+// default for SetupPrompt below -- a plain rl.question(), not the
+// async-iterator dance runCaptureCommand's own prompt uses for enable()'s
+// two sequential questions (see that function's own comment): setup() only
+// ever asks one question of its own before handing off to runCaptureEnable,
+// which opens (and closes) its own readline in turn, so there is no shared
+// interface for two overlapping .question() calls to race over.
+function realSetupPrompt(question) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+// Verbatim -- cli.test.mjs depends on this exact string, the same contract
+// capture.ts's own SIGN_IN_QUESTION carries.
+export const TURN_ON_CAPTURE_QUESTION = 'Also turn on automatic capture? It sends what you type and what the agent replies to Waku. [y/N]: ';
+export async function setup(name, url, harnesses = getHarnesses(), 
+// R20 (final review, spec 012): the real default, injected the same way
+// realCaptureDeps below builds it -- so cli.test.mjs can point this at a
+// temp path instead of the machine's actual ~/.codex/config.toml, the
+// same reason every other real path in this file is a parameter with a
+// real default rather than a bare homedir() call inline.
+codexConfigPath = join(homedir(), '.codex', 'config.toml'), 
+// The two additions that make setup() async (this task): the question
+// itself (realSetupPrompt, above) and what a "y" answer actually runs.
+// Both injectable, the same reason every real path/writer/fetch in this
+// file is a parameter with a real default rather than a bare call inline
+// -- so cli.test.mjs never opens real stdin and never runs a real
+// capture enable. The real runCaptureEnable below is nothing but the
+// existing "capture enable" command path (runCaptureCommand, same as
+// dispatch()'s own 'capture'/'enable' case), called with no flags -- the
+// Sign-in question, enable()'s own disclosure and typed "y" gate, the
+// credential step, the hooks, and the bootstrap question all run exactly
+// as they do from the command line. Nothing here may skip, weaken, or
+// pre-answer any of that: the only thing this buys the person is not
+// having to type "npx waku-memory capture enable" a second time.
+prompt = realSetupPrompt, runCaptureEnable = () => {
+    const { ingestUrl, mcpUrl } = urlPair(url);
+    return runCaptureCommand('enable', ingestUrl, mcpUrl, DEFAULT_BOOTSTRAP, { kind: 'ask' });
+}) {
     const results = runSetup(harnesses, name, url);
     for (const r of results) {
         if (r.status === 'error')
@@ -345,42 +518,40 @@ export function setup(name, url, harnesses = getHarnesses(), manualHarnesses = g
         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;
+    // Task 14 (spec 012 §9): setup() no longer has a manual-harness list to
+    // consult here -- Codex was its only member, and Codex now has a real,
+    // automatic route of its own ("capture enable", task 10), so there is
+    // nothing left this function can detect but not write. getHarnesses()
+    // still does not carry Codex (harnesses.ts's own comment has the fuller
+    // account), so a Codex-only machine still falls through to the plain "no
+    // supported harness config was found" branch below -- R20 below is what
+    // stops that from being a flatly false thing to print on such a machine.
+    const { foundAny, wroteAny, hadError } = summarize(results);
     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) {
+    else if (foundAny && !hadError) {
         console.log('Already configured correctly -- nothing to change.');
     }
-    else if (autoFound && hadError) {
+    else if (foundAny && 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.');
     }
+    // R20 (final review, spec 012): the regression this whole-branch review
+    // caught -- "no supported harness config was found" is false on a machine
+    // that has ~/.codex/config.toml. setup() still writes nothing for Codex
+    // (getHarnesses() does not carry it, above), so this is advice, not a
+    // result: it fires independently of the found/wrote/error branch above,
+    // including alongside a real Claude Code result on a machine with both.
+    if (existsSync(codexConfigPath)) {
+        console.log('');
+        console.log('Codex was found. Run "npx waku-memory capture enable" to configure it.');
+    }
     // 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
@@ -392,6 +563,20 @@ export function setup(name, url, harnesses = getHarnesses(), manualHarnesses = g
     }
     if (hadError)
         process.exitCode = 1;
+    // The new question this task adds: asked only once there is something to
+    // turn capture on for -- a machine with no harness found has nothing for
+    // "capture enable" to install into either, so asking would just repeat
+    // the "nothing was added" message above in question form. Default is no
+    // (an empty answer, from pressing Enter, keeps today's behaviour exactly)
+    // -- capture is a much bigger step than writing an MCP config, so unlike
+    // enable()'s own SIGN_IN_QUESTION (whose default path still requires
+    // choosing 1 or 2), this one must never be opted into by accident.
+    if (foundAny) {
+        const answer = (await prompt(TURN_ON_CAPTURE_QUESTION)).trim().toLowerCase();
+        if (answer === 'y') {
+            await runCaptureEnable();
+        }
+    }
 }
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
@@ -415,7 +600,7 @@ function readStdin() {
 // 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() {
+async function runHookCommand(harness) {
     let raw;
     try {
         raw = await readStdin();
@@ -429,13 +614,99 @@ async function runHookCommand() {
         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.
+        // Malformed input is a no-op, not a crash: some future 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 });
+    await handleHookEvent(event, { configDir: join(homedir(), '.waku-memory'), fetchImpl: fetch, harness });
+}
+// The platform opener login.ts's LoginDeps.openBrowser needs (spec 012 §7):
+// spawned detached and unref'd so it never blocks -- or waits on -- this
+// process, and never throws: a failed spawn (no browser installed, no
+// `xdg-open` on a headless machine) is fine, because the authorize URL is
+// always printed first (login.ts's own login(), right before this runs).
+// The 'error' listener exists for the same reason as the try/catch: a spawn
+// failure can surface asynchronously (an ENOENT for a missing xdg-open,
+// say) rather than as a synchronous throw, and an unhandled 'error' event
+// on a ChildProcess crashes the process if nothing is listening for it.
+// The argv/options openBrowser (below) hands to child_process.spawn, kept
+// as a pure function of (platform, url) so a unit test can assert the exact
+// shape without spawning a real process or opening a real browser (fix
+// round 1, finding 1). The previous win32 shape --
+// `spawn('cmd', ['/c', 'start', '""', url])`, no shell, no verbatim-argument
+// flag -- was Critical-broken for any real authorize URL: Node's default
+// Windows argv quoting only wraps an argument in quotes when it contains
+// whitespace, so an `&`-separated OAuth URL passed through untouched, and
+// cmd.exe then read each `&` as its own command separator, truncating the
+// URL at the first `&` and failing on every parameter after it as an
+// unrecognized command.
+//
+// Chosen fix: shape (a) from the controller's ruling, not (b)
+// (`rundll32 url.dll,FileProtocolHandler`) -- `cmd /c start` is the
+// documented way to hand a URL to the OS's own default-handler resolution
+// (same as double-clicking a link), while rundll32's undocumented internal
+// entry point is a narrower target to keep behaving identically across
+// Windows versions.
+// `windowsVerbatimArguments: true` stops Node from re-quoting each argv
+// entry (the exact thing that let `""` and the URL arrive at cmd.exe
+// unquoted in the first place); wrapping the URL in its own literal double
+// quotes (`` `"${url}"` ``) is then what makes cmd.exe treat everything
+// between them -- `&` included -- as one argument instead of a command
+// separator. The leading `'""'` argument is unrelated to the URL: it is
+// `start`'s own window-title argument, required so `start` does not
+// mistake a quoted first argument (the URL, if it came first) for a title
+// instead of the command to run. Reproduced directly from Bash on this
+// machine, adapted from the reviewer's own repro (see cli.test.mjs's
+// nearby test and this task's report for the transcript): `cmd /c echo ""
+// "https://x/a?b=1&c=2"` under `windowsVerbatimArguments: true` prints the
+// URL whole, `&` and all -- `echo` standing in for `start` the same way the
+// reviewer's own reproduction used it.
+//
+// darwin/linux are untouched: `open`/`xdg-open` never go through a shell,
+// so Node's own (correct, non-Windows) argv handling was never the problem
+// there.
+export function buildBrowserOpener(platform, url) {
+    if (platform === 'win32') {
+        return {
+            command: 'cmd',
+            args: ['/c', 'start', '""', `"${url}"`],
+            options: { detached: true, stdio: 'ignore', windowsVerbatimArguments: true },
+        };
+    }
+    if (platform === 'darwin') {
+        return { command: 'open', args: [url], options: { detached: true, stdio: 'ignore' } };
+    }
+    return { command: 'xdg-open', args: [url], options: { detached: true, stdio: 'ignore' } };
+}
+function openBrowser(url) {
+    try {
+        const { command, args, options } = buildBrowserOpener(process.platform, url);
+        const child = spawn(command, args, options);
+        child.on('error', () => {
+            // Never throws -- the URL was already printed (login.ts's login()).
+        });
+        child.unref();
+    }
+    catch {
+        // Same reasoning as the 'error' listener above, for the rarer case
+        // where spawn() itself throws synchronously.
+    }
+}
+// login.ts's LoginDeps, built the one way this shim ever builds it -- both
+// `waku-memory login` (run()'s own 'login' case) and "capture enable"'s
+// login Credential (realCaptureDeps below) call this with the same
+// ingest-base `apiBase` dispatch() already computed.
+function realLoginDeps(apiBase) {
+    return {
+        apiBase,
+        configDir: join(homedir(), '.waku-memory'),
+        fetchImpl: fetch,
+        openBrowser,
+        stdout: (text) => console.log(text),
+        version: SHIM_VERSION,
+    };
 }
 // 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
@@ -460,8 +731,22 @@ async function runHookCommand() {
 // --since/--all/--no-bootstrap (or their absence) into this same shape, so
 // this function's only job is to place it on the deps bag unchanged, the
 // same way `prompt` already arrives built by its own call site below.
-function realCaptureDeps(prompt, bootstrap) {
+function realCaptureDeps(prompt, bootstrap, 
+// Fix round 1 (spec 012 §4.2): the MCP-shaped url (dispatch()'s mcpUrl,
+// computed from --url BEFORE it was stripped to the ingest base) --
+// passed alongside bootstrap the same way disable()'s and status()'s call
+// sites already pass a bootstrap they never use, so every caller builds
+// deps the same way regardless of whether its own action reads the field.
+mcpUrl, 
+// Task 13's addition (spec 012 §7): the ingest base (dispatch()'s
+// ingestUrl) realLoginDeps needs for deps.login below -- every call site
+// already has this value (it is enable()'s own `url` parameter, or
+// disable's/status's respective stand-ins), so, like bootstrap and mcpUrl
+// above, it is threaded through unconditionally rather than only for the
+// one action that can actually reach the credential question.
+ingestUrl) {
     const claudeDir = join(homedir(), '.claude');
+    const codexDir = join(homedir(), '.codex');
     return {
         claudeDir,
         settingsPath: join(claudeDir, 'settings.json'),
@@ -474,6 +759,20 @@ function realCaptureDeps(prompt, bootstrap) {
         writeSettingsJson: (path, data) => atomicWriteJson(path, data),
         fetchImpl: fetch,
         bootstrap,
+        // Codex (task 10, spec 012 §4.6): detected the same way claudeDir is --
+        // existence of the path is the evidence. codexPluginsCacheDir matches
+        // codexPluginPresent's own comment (codex-config.ts) on where Codex
+        // caches an installed plugin; marketplacePath is the personal
+        // marketplace every machine gets one of, regardless of which harnesses
+        // it has (~/.agents is not itself Codex-specific).
+        codexConfigPath: join(codexDir, 'config.toml'),
+        codexHooksPath: join(codexDir, 'hooks.json'),
+        codexPluginsCacheDir: join(codexDir, 'plugins', 'cache'),
+        marketplacePath: join(homedir(), '.agents', 'plugins', 'marketplace.json'),
+        mcpUrl,
+        writeText: writeCodexText,
+        writeJsonFile,
+        login: () => login(realLoginDeps(ingestUrl)),
     };
 }
 // Not awaited by run() below, for the same structural reason runHookCommand
@@ -484,7 +783,12 @@ function realCaptureDeps(prompt, bootstrap) {
 // 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, bootstrap) {
+async function runCaptureCommand(action, url, mcpUrl, bootstrap, 
+// undefined for 'disable' (Dispatch's disable variant carries no
+// credential at all -- see its own comment); always one of the three
+// Credential kinds for 'enable', built by dispatch()'s capture-enable
+// branch from --login/--key or their absence.
+credential) {
     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
@@ -493,7 +797,7 @@ async function runCaptureCommand(action, url, bootstrap) {
         // itself never reads deps.bootstrap either.
         const deps = realCaptureDeps(() => {
             throw new Error('waku-memory capture disable: unexpectedly tried to prompt.');
-        }, bootstrap);
+        }, bootstrap, mcpUrl, url);
         const result = await disable(deps);
         if (result === 'refused')
             process.exitCode = 1;
@@ -531,7 +835,7 @@ async function runCaptureCommand(action, url, bootstrap) {
             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, bootstrap));
+        const result = await enable(url, realCaptureDeps(prompt, bootstrap, mcpUrl, url), credential);
         if (result === 'refused')
             process.exitCode = 1;
     }
@@ -539,6 +843,17 @@ async function runCaptureCommand(action, url, bootstrap) {
         rl.close();
     }
 }
+// status() never prompts, never touches deps.bootstrap, and (ruling R8,
+// fix round 1) needs no url at all -- same as disable() -- see
+// runCaptureCommand's own stub above), so the prompt stub, DEFAULT_BOOTSTRAP
+// and DEFAULT_URL here exist only to satisfy realCaptureDeps's shape, the
+// same reason disable's call site needs them.
+async function runCaptureStatusCommand() {
+    const deps = realCaptureDeps(() => {
+        throw new Error('waku-memory capture status: unexpectedly tried to prompt.');
+    }, DEFAULT_BOOTSTRAP, DEFAULT_URL, DEFAULT_INGEST_URL);
+    await status(deps);
+}
 export function run(argv) {
     const d = dispatch(argv);
     switch (d.kind) {
@@ -561,7 +876,29 @@ export function run(argv) {
             process.exitCode = 1;
             return;
         case 'setup':
-            setup(d.name, d.url);
+            void setup(d.name, d.url).catch((err) => {
+                console.error(`waku-memory setup: unexpected failure -- ${errorMessage(err)}.`);
+                process.exitCode = 1;
+            });
+            return;
+        case 'login':
+            // Ruling R15: the disclosure (and a blank line), no y/n gate -- unlike
+            // "capture enable", signing in on its own asks nothing about consent
+            // to *capture*, only about signing in, so there is no gate to hold it
+            // behind. Exit-code mapping mirrors "capture enable"'s own (see
+            // runCaptureCommand's own comment): 0 only on the fully successful
+            // 'signed-in', 1 for 'timeout' or 'refused' -- the one outcome
+            // distinction worth a nonzero exit for a scripted caller.
+            console.log(DISCLOSURE);
+            console.log('');
+            void login(realLoginDeps(d.url))
+                .then((result) => {
+                process.exitCode = result === 'signed-in' ? 0 : 1;
+            })
+                .catch((err) => {
+                console.error(`waku-memory login: unexpected failure -- ${errorMessage(err)}.`);
+                process.exitCode = 1;
+            });
             return;
         case 'hook':
             // Exits 0 always, per the brief: set up front, not left to whatever
@@ -573,12 +910,19 @@ export function run(argv) {
             // 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) => {
+            void runHookCommand(d.harness).catch((err) => {
                 console.error(`waku-memory hook: unexpected failure -- ${errorMessage(err)}.`);
             });
             return;
         case 'capture':
-            void runCaptureCommand(d.action, d.url, d.bootstrap).catch((err) => {
+            if (d.action === 'status') {
+                void runCaptureStatusCommand().catch((err) => {
+                    console.error(`waku-memory capture: unexpected failure -- ${errorMessage(err)}.`);
+                    process.exitCode = 1;
+                });
+                return;
+            }
+            void runCaptureCommand(d.action, d.url, d.mcpUrl, d.bootstrap, d.action === 'enable' ? d.credential : undefined).catch((err) => {
                 console.error(`waku-memory capture: unexpected failure -- ${errorMessage(err)}.`);
                 process.exitCode = 1;
             });