waku-memory 0.1.0 → 0.2.0

package/dist/hook.js

@@ -17,24 +17,35 @@
 //      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.
+//   2. Content goes to the ingest endpoint and nowhere else, with one
+//      deliberate exception: SessionStart's postBrief writes POST /brief's
+//      `text` to stdout, which Claude Code folds into the session's
+//      context -- that is the entire point of task 9. stdout carries the
+//      brief and nothing else, ever. Every other channel is stderr
+//      (console.error), and never carries a transcript byte, a delta, or
+//      any other response body -- only counts, status codes, and the
+//      event/session names 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';
+// Zero dependencies, per the brief: only node:fs and node:path here (plus
+// the sibling dialogue.ts module for the cc-dialogue-v1 rule, spec 011
+// §1 -- a local file, not an npm package), plus the global fetch (Node
+// 18+, no import needed) that deps.fetchImpl defaults to at the real call
+// site in cli.ts.
+import { appendFileSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
+import { CONTENT_FORMAT, formatDelta, renderEntries } from "./dialogue.js";
+import { resolveProject } from "./project.js";
 // Bumped by hand at release time alongside package.json's "version" -- the
 // brief's call: a build-time constant here is fine, and it keeps this file
 // free of any fs reach into its own package.json (which would also be
 // wrong at runtime, since dist/hook.js does not sit next to package.json
-// the way src/hook.ts does).
-const SHIM_VERSION = '0.1.0';
+// the way src/hook.ts does). Exported since postBrief's request body and
+// hook.test.mjs's drift check (against package.json) both need it; task 14
+// bumps this and package.json to 0.2.0 together.
+export const SHIM_VERSION = '0.2.0';
 const HARNESS = 'claude_code';
-const CONFIG_FILE_NAME = 'config.json';
+// Exported for capture.ts, which writes the file this module reads.
+export const CONFIG_FILE_NAME = 'config.json';
 // Same-directory temp file + rename, exactly atomicWriteJson's technique in
 // cli.ts (see its comment for the full why: rename is only atomic within
 // one filesystem, so the temp file has to be a sibling of the real one).
@@ -81,7 +92,9 @@ function atomicWriteText(path, text) {
 // this module's own atomicWriteText writing it (that always writes a clean
 // non-negative integer), so this is cheap insurance against a corrupted
 // local file, not a path this module's own writes are expected to hit.
-function readWatermark(watermarkPath) {
+// Exported: a later run (spec 011 §8's bootstrap) reads watermarks with
+// the hook's own rule rather than re-implementing it.
+export function readWatermark(watermarkPath) {
     try {
         const raw = readFileSync(watermarkPath, 'utf8').trim();
         if (!/^\d+$/.test(raw))
@@ -93,25 +106,48 @@ function readWatermark(watermarkPath) {
         return 0;
     }
 }
-// Pure read: computes the delta and the watermark it would advance to, but
-// writes nothing. handleHookEvent only persists nextWatermark after the
-// POST built from `content` actually succeeds -- see its own comment.
+// Exported so postDelta (and a later run -- spec 011 §8's bootstrap) can
+// advance the watermark the same way after each piece that succeeds: one
+// atomic write, never a partial one a crash could leave mid-byte.
+export function writeWatermark(watermarkPath, offset) {
+    atomicWriteText(watermarkPath, String(offset));
+}
+// spec 011 §3: beside the watermark, not instead of it -- a session that
+// drops one span is still capturing everything else, and this file is the
+// record of where the holes are.
+export function droppedMarkerPath(watermarkPath) {
+    return watermarkPath + '.dropped';
+}
+// Pure read: formats what the file holds past the watermark by the
+// cc-dialogue-v1 rule and returns the surviving pieces with absolute byte
+// offsets, but writes nothing -- handleHookEvent only persists a piece's
+// `end` after the POST built from its `text` actually succeeds (see
+// postDelta). null covers two different "nothing to send yet" cases that
+// the caller treats the same way: no transcript to read at all (missing or
+// unreadable file -- e.g. transcript_path's documented async-write lag,
+// research doc §2, means the file may not exist yet on a very short
+// session), or bytes past the watermark that do not yet contain one
+// complete line (spec 011 §2 -- a read landing inside a write must not
+// send half a JSON record; the next event's read starts from the same
+// watermark and sees the completed line). A non-null result can still hold
+// zero pieces -- every new line was dropped by the formatting rule -- and
+// the caller still advances the watermark to `end` in that case, per
+// formatDelta's own contract.
 export function readDelta(transcriptPath, watermarkPath) {
     let buf;
     try {
         buf = readFileSync(transcriptPath);
     }
     catch {
-        // Missing or unreadable transcript -- e.g. transcript_path's documented
-        // async-write lag (research doc §2) means the file may not exist yet at
-        // all on a very short session. Nothing to send is not an error.
         return null;
     }
-    const size = buf.length;
     const offset = readWatermark(watermarkPath);
-    if (offset >= size)
+    if (offset >= buf.length)
         return null; // nothing new since last watermark (also covers a shrunk/rotated file)
-    return { content: buf.subarray(offset).toString('utf8'), nextWatermark: size };
+    const { pieces, end } = formatDelta(buf.subarray(offset));
+    if (end === 0)
+        return null; // the only new bytes are an incomplete trailing line
+    return { pieces: pieces.map((p) => ({ ...p, end: offset + p.end })), end: offset + end, offset };
 }
 // Reads {url, key} from <configDir>/config.json. Anything short of a clean
 // {url: string, key: string} object -- the file absent (task 15 has not run
@@ -154,50 +190,118 @@ function postJson(deps, config, path, body, signal) {
         signal,
     });
 }
-// SessionEnd hooks share a 1.5s budget by default (raisable only to 60s),
-// cannot block Claude Code's own exit, and must be fire-and-forget --
-// research doc §2. An unbounded await here risks the process being killed
-// mid-request with no chance to exit cleanly or log why.
+// The SessionEnd flush has to finish inside the hook entry capture.ts
+// installs for it, or Claude Code kills the process mid-request with no
+// chance to log why. That entry's `timeout` (seconds) is
+// SESSION_END_HOOK_TIMEOUT_S, defined here so capture.ts imports it and the
+// two numbers cannot drift apart again: until 2026-09-04 the network budget
+// below was 800 ms, derived from Claude Code's 1.5 s *default* SessionEnd
+// budget, while the installed entry had already raised that budget to 10 s
+// -- and 800 ms is one cold round trip to api.waku.one from Yang's machine
+// (three real POST /ingest/session calls measured 822, 644 and 1174 ms), so
+// two of every three flushes were aborted by our own timer. That is the
+// last turn of every session, and all of a single-turn one.
 //
-// 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;
+// The network budget is the process budget minus what happens before the
+// request: `npx -y waku-memory hook` took 2.8 s to reach this code cold
+// (2026-09-04), and Node startup, stdin and the transcript read are a few
+// hundred milliseconds more. 5 s leaves about 2 s of the 10 s for a slower
+// machine. hook.test.mjs pins both bounds. Stop is not bounded this way
+// (600 s budget, and runs "async": true), so its path through postDelta
+// below does not use this.
+export const SESSION_END_HOOK_TIMEOUT_S = 10;
+export const SESSION_END_TIMEOUT_MS = 5000;
+// undici wraps every network-level failure as TypeError("fetch failed") and
+// puts the reason on `cause` -- a DNS name, a refused connection, our own
+// abort, or (2026-09-04) an Authorization header carrying a control
+// character. The wrapper alone told an operator nothing. The cause is an
+// error class, a code and a sentence, never the request that failed, so
+// printing it keeps rule 2 of the module comment.
 function errorMessage(err) {
-    return err instanceof Error ? err.message : String(err);
+    if (!(err instanceof Error))
+        return String(err);
+    const cause = err.cause;
+    if (!(cause instanceof Error))
+        return err.message;
+    const code = cause.code;
+    const codePart = typeof code === 'string' ? ` ${code}` : '';
+    return `${err.message} (cause: ${cause.name}${codePart}: ${cause.message})`;
 }
-async function postHeartbeat(deps) {
-    const configPath = join(deps.configDir, CONFIG_FILE_NAME);
+// §6: 0.16 s start-up + one round trip measured 0.6-1.2 s; a black hole
+// (server up but never answering) would otherwise hold the session's first
+// turn open indefinitely, since nothing before postBrief bounds this wait.
+export const BRIEF_TIMEOUT_MS = 3000;
+// The memories a session opens with (spec 011 §5, §6, A9): posts the
+// harness/version/project triple to /brief and writes whatever `text` it
+// answers with to stdout, which Claude Code folds straight into the
+// session's context. Mirrors postHeartbeat's shape (same config read, same
+// do-nothing-and-log branches) but now bounded by an AbortController --
+// unlike a heartbeat nobody was waiting on, a hung /brief request sits in
+// the middle of the user's SessionStart, so this cannot wait forever.
+async function postBrief(event, deps) {
     const config = readConfig(deps.configDir);
     if (!config) {
-        console.error(`waku-memory hook: no usable config at ${configPath} -- skipping heartbeat.`);
+        console.error(`waku-memory hook: no usable config at ${join(deps.configDir, CONFIG_FILE_NAME)} -- no brief.`);
+        return;
+    }
+    if (typeof event.cwd !== 'string' || event.cwd === '') {
+        // No project to ask for. A do-nothing branch says why (conventions §8).
+        console.error('waku-memory hook: no cwd on this SessionStart event -- no brief.');
         return;
     }
+    const project = resolveProject(event.cwd);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.briefTimeoutMs ?? BRIEF_TIMEOUT_MS);
     try {
-        // No local state to advance on success and nothing useful to retry on
-        // failure (the next SessionStart supersedes it), so unlike postDelta
-        // there is no follow-up write gated on the response -- but the
-        // response is still worth a log line. hook_heartbeat.version exists so
-        // an operator can tell what is running on a machine that stopped
-        // reporting; silently treating a 401 (revoked key) or a 5xx the same
-        // as success would throw that signal away.
-        const res = await postJson(deps, config, '/ingest/heartbeat', { harness: HARNESS, version: SHIM_VERSION });
+        // POST, not GET: `project` is caller-supplied free text and a query
+        // string would put it in every access log (spec 011 §5).
+        const res = await postJson(deps, config, '/brief', { harness: HARNESS, version: SHIM_VERSION, project }, controller.signal);
         if (!res.ok) {
-            console.error(`waku-memory hook: /ingest/heartbeat responded ${res.status}.`);
+            console.error(`waku-memory hook: /brief responded ${res.status} -- no brief.`);
+            return;
+        }
+        const body = (await res.json());
+        if (typeof body.text === 'string' && body.text !== '') {
+            (deps.stdout ?? defaultStdout)(body.text);
+        }
+        else {
+            // A 2xx with missing, non-string, or empty text is a failure like any other.
+            console.error('waku-memory hook: /brief responded with no usable text -- no brief.');
         }
     }
     catch (err) {
-        console.error(`waku-memory hook: POST /ingest/heartbeat failed -- ${errorMessage(err)}.`);
+        // This catch also handles a 2xx response whose body is not valid JSON.
+        console.error(`waku-memory hook: POST /brief failed -- ${errorMessage(err)}.`);
+    }
+    finally {
+        clearTimeout(timer);
     }
 }
+const defaultStdout = (text) => {
+    process.stdout.write(text + '\n');
+};
+const squash = (s) => s.replace(/\s+/g, ' ').trim();
+// spec 011 §2: the text of every assistant: entry after the last user:
+// entry, joined by one space -- what "Claude's final response" (the hooks
+// reference's own words for last_assistant_message) means at record
+// granularity. assistant used tool: entries (role 'tool') are names, not
+// text, and are skipped rather than treated as a boundary. Scoping to the
+// trailing run, instead of searching the whole delta, is deliberate: a
+// short reply like "Done." that also occurred several turns earlier must
+// not be mistaken for the current turn's reply just because the words
+// match.
+export function trailingAssistantText(entries) {
+    let lastUser = -1;
+    entries.forEach((e, i) => {
+        if (e.role === 'user')
+            lastUser = i;
+    });
+    return entries
+        .slice(lastUser + 1)
+        .filter((e) => e.role === 'assistant')
+        .map((e) => e.text)
+        .join(' ');
+}
 async function postDelta(event, deps, source) {
     if (!event.transcript_path) {
         console.error(`waku-memory hook: no transcript_path on this ${event.hook_event_name} event -- skipping.`);
@@ -215,79 +319,126 @@ async function postDelta(event, deps, source) {
     // configDir/state. The same-user trust boundary already limits the blast
     // radius, but this removes the footgun rather than relying on that alone.
     const watermarkPath = join(deps.configDir, 'state', basename(event.session_id));
-    const delta = readDelta(event.transcript_path, watermarkPath);
+    let delta = readDelta(event.transcript_path, watermarkPath);
     if (delta === null) {
-        console.error(`waku-memory hook: nothing new in the transcript for session ${event.session_id} -- skipping.`);
-        return;
-    }
-    const body = {
-        harness: HARNESS,
-        session_id: event.session_id,
-        source,
-        content: delta.content,
-    };
-    if (event.cwd)
-        body.project = basename(event.cwd);
-    // Only session-end is bounded -- see SESSION_END_TIMEOUT_MS's comment.
-    // Stop's controller stays undefined, so its postJson call below gets
-    // `signal: undefined`, identical to not passing one at all.
-    const controller = source === 'session-end' ? new AbortController() : undefined;
-    const timer = controller ? setTimeout(() => controller.abort(), SESSION_END_TIMEOUT_MS) : undefined;
-    let res;
-    try {
-        res = await postJson(deps, config, '/ingest/session', body, controller?.signal);
-    }
-    catch (err) {
-        // Network error, DNS failure, our own SessionEnd timeout firing -- all
-        // reject rather than resolving with a bad status. Leaving the
-        // watermark alone resends exactly this delta next time; the ingest
-        // inbox's (user_id, session_id, content_hash) dedupe recognizes a retry
-        // of byte-identical content as already-seen and no-ops it for free.
-        // That guarantee is specific to retrying *this* unchanged delta -- see
-        // readWatermark's comment for the resend it does NOT cover.
-        console.error(`waku-memory hook: POST /ingest/session failed -- ${errorMessage(err)}.`);
-        return;
-    }
-    finally {
-        // Must run before any of the res.ok handling below, success or not --
-        // an uncleared timer holds the process open for the rest of
-        // SESSION_END_TIMEOUT_MS for no reason once the request has settled.
-        if (timer)
-            clearTimeout(timer);
-    }
-    if (!res.ok && res.status !== 413) {
-        // Covers everything except 2xx and 413 (handled below): 422 (should
-        // not happen -- body shape is fixed here), 5xx, 401/403. Leaving the
-        // watermark unchanged means the next event resends the same bytes; see
-        // the catch block above for exactly what the inbox dedupe does and
-        // does not guarantee about that resend.
-        console.error(`waku-memory hook: /ingest/session responded ${res.status} -- watermark left unchanged.`);
-        return;
-    }
-    if (res.status === 413) {
-        // The endpoint has no server-side chunking (MAX_INGEST_CONTENT_BYTES in
-        // ingest.py, checked before any repository call) -- this exact span can
-        // never succeed as-is. Since the watermark only advances on success and
-        // the transcript only grows, leaving it unchanged here would 413 again
-        // next time with an even larger span, permanently wedging capture for
-        // the rest of this session. Advancing past it loses this one delta but
-        // keeps every later turn capturable -- the strictly better of the two.
-        console.error(`waku-memory hook: /ingest/session responded 413 for session ${event.session_id} -- ` +
-            `dropping this span (too large to ever fit) and advancing past it.`);
+        // spec 011 §2: the transcript can lag the turn past every complete
+        // line it holds. On Stop, a non-empty last_assistant_message is
+        // Claude's own record of what it just said (the hooks reference: "use
+        // this field rather than reading transcript_path" for exactly this
+        // reason) -- when the file has nothing new at all, that reply has not
+        // landed in it yet, and this is the only chance to send it before the
+        // next event finds it in the file for real and skips it (the
+        // trailing-run check below). The piece's `end` is the current
+        // watermark: nothing from the file is being consumed, only the
+        // out-of-band message.
+        if (source === 'stop' && typeof event.last_assistant_message === 'string' && event.last_assistant_message.trim() !== '') {
+            const current = readWatermark(watermarkPath);
+            const entry = { role: 'assistant', text: event.last_assistant_message };
+            delta = { pieces: [{ entries: [entry], text: renderEntries([entry]), end: current }], end: current, offset: current };
+        }
+        else {
+            console.error(`waku-memory hook: nothing new in the transcript for session ${event.session_id} -- skipping.`);
+            return;
+        }
     }
-    // Past this point: res.ok (202 queued / 200 deduped) or 413 (see above)
-    // both advance the watermark the same way.
-    try {
-        atomicWriteText(watermarkPath, String(delta.nextWatermark));
+    // spec 011 §2: append last_assistant_message as one more assistant:
+    // entry unless the trailing run already reads it, on normalised
+    // whitespace -- so a final turn split across two text blocks (joined by
+    // the harness with a newline or a blank line) still matches. This runs
+    // on the structured entries, never on a piece's already-joined text,
+    // because a text can itself contain a blank line and the joined form
+    // cannot be split back to find the boundary between records.
+    if (source === 'stop' && typeof event.last_assistant_message === 'string' && event.last_assistant_message.trim() !== '') {
+        const msg = event.last_assistant_message;
+        const all = delta.pieces.flatMap((p) => p.entries);
+        const present = squash(trailingAssistantText(all)).includes(squash(msg));
+        if (!present) {
+            const entry = { role: 'assistant', text: msg };
+            const last = delta.pieces[delta.pieces.length - 1];
+            if (last) {
+                last.entries.push(entry);
+                last.text = renderEntries(last.entries);
+            }
+            else {
+                delta.pieces.push({ entries: [entry], text: renderEntries([entry]), end: delta.end });
+            }
+        }
     }
-    catch (err) {
-        // The POST outcome is already decided -- the local bookkeeping just
-        // did not keep up. A 202/200 that fails to persist here resends the
-        // same (now server-known) delta next time, same as any other write
-        // failure; a 413 that fails to persist here will simply 413 again on
-        // its own next attempt, same as if this write had never been tried.
-        console.error(`waku-memory hook: could not persist the watermark for session ${event.session_id} -- ${errorMessage(err)}.`);
+    // Only session-end is bounded -- see SESSION_END_TIMEOUT_MS's comment.
+    // One deadline for the whole flush, not one budget per piece: several
+    // pieces each getting the full SESSION_END_TIMEOUT_MS would let a
+    // many-piece session run far longer than the budget the installed hook
+    // entry actually gives the process. Stop's deadline stays undefined, so
+    // every piece's controller below is undefined too -- identical to not
+    // passing a signal at all.
+    const budgetMs = deps.sessionEndTimeoutMs ?? SESSION_END_TIMEOUT_MS;
+    const deadline = source === 'session-end' ? Date.now() + budgetMs : undefined;
+    let previousEnd = delta.offset;
+    for (const piece of delta.pieces) {
+        const controller = deadline !== undefined ? new AbortController() : undefined;
+        const timer = controller ? setTimeout(() => controller.abort(), Math.max(0, deadline - Date.now())) : undefined;
+        let res;
+        try {
+            res = await postJson(deps, config, '/ingest/session', {
+                harness: HARNESS,
+                session_id: event.session_id,
+                source,
+                content: piece.text,
+                content_format: CONTENT_FORMAT,
+                ...(event.cwd ? { project: resolveProject(event.cwd) } : {}),
+            }, controller?.signal);
+        }
+        catch (err) {
+            // Network error, DNS failure, our own SessionEnd timeout firing --
+            // all reject rather than resolving with a bad status. The watermark
+            // stays at the last piece that succeeded; the ingest inbox's
+            // (user_id, session_id, content_hash) dedupe recognizes a retry of
+            // byte-identical content as already-seen and no-ops it for free.
+            // That guarantee is specific to retrying *this* unchanged piece --
+            // see readWatermark's comment for the resend it does NOT cover.
+            console.error(`waku-memory hook: POST /ingest/session failed -- ${errorMessage(err)}.`);
+            return;
+        }
+        finally {
+            // Must run before any of the res.ok handling below, success or not --
+            // an uncleared timer holds the process open for no reason once the
+            // request has settled.
+            if (timer)
+                clearTimeout(timer);
+        }
+        if (res.status === 413) {
+            // The endpoint has no server-side chunking (MAX_INGEST_CONTENT_BYTES
+            // in ingest.py, checked before any repository call) -- a piece is
+            // already cut under MAX_PIECE_BYTES, so this is the backstop for the
+            // one record that is itself over the cap (spec 011 §3), which no
+            // dialogue record should ever be. One span per line, appended -- a
+            // second drop in the same session adds a line, never overwrites the
+            // first, so bootstrap (§8) can see every hole.
+            mkdirSync(dirname(watermarkPath), { recursive: true });
+            appendFileSync(droppedMarkerPath(watermarkPath), `${previousEnd}-${piece.end}\n`);
+            console.error(`waku-memory hook: /ingest/session responded 413 for session ${event.session_id} -- ` +
+                `dropping this piece and advancing past it.`);
+        }
+        else if (!res.ok) {
+            // 422 included (spec 011 §4, deployment order): an API that does not
+            // yet know content_format leaves the watermark where it is, same as
+            // any other non-2xx (5xx, 401/403) -- the next event resends the
+            // whole growing delta rather than losing this piece.
+            console.error(`waku-memory hook: /ingest/session responded ${res.status} -- watermark left unchanged.`);
+            return;
+        }
+        // Past this point: res.ok (202 queued / 200 deduped) or 413 (see
+        // above) both advance the watermark the same way, to this piece's end.
+        writeWatermark(watermarkPath, piece.end);
+        previousEnd = piece.end;
     }
+    // spec 011 §3: a delta that produced zero pieces (every new line was
+    // dropped by the formatting rule) still consumes to `delta.end` --
+    // formatDelta's own contract -- so those lines are never re-read. The
+    // same catches a trailing run of dropped lines after the last real
+    // piece, when that piece's own `end` stops short of the full delta.
+    if (delta.pieces.length === 0 || delta.end > previousEnd)
+        writeWatermark(watermarkPath, delta.end);
 }
 // Entry point cli.ts's run() calls after reading and JSON.parsing stdin --
 // stdin reading deliberately does not live here (see the module comment and
@@ -310,7 +461,7 @@ export async function handleHookEvent(event, deps) {
         }
         switch (event.hook_event_name) {
             case 'SessionStart':
-                await postHeartbeat(deps);
+                await postBrief(event, deps);
                 return;
             case 'Stop':
                 await postDelta(event, deps, 'stop');

package/dist/project.js

@@ -0,0 +1,43 @@
+// Spec 011 §7: the project is the directory name, except that a git
+// worktree names the repository it belongs to. A worktree's `.git` is a
+// file holding `gitdir: <repo>/.git/worktrees/<name>`; a checkout's `.git`
+// is a directory. Read with fs only -- no git binary.
+import { readFileSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+export function resolveProject(cwd, io = { statSync, readFileSync }) {
+    const start = resolve(cwd);
+    let dir = start;
+    for (;;) {
+        const dotGit = join(dir, '.git');
+        let stat;
+        try {
+            stat = io.statSync(dotGit);
+        }
+        catch {
+            stat = undefined;
+        }
+        if (stat?.isDirectory())
+            return basename(start);
+        if (stat?.isFile()) {
+            let content;
+            try {
+                content = io.readFileSync(dotGit, 'utf8');
+            }
+            catch {
+                return basename(start); // unreadable: the checkout's own name, never a throw (§7)
+            }
+            const m = /^gitdir:\s*(.+?)\s*$/m.exec(content);
+            if (m) {
+                const gitdir = isAbsolute(m[1]) ? m[1] : resolve(dir, m[1]);
+                const wt = /^(.*)[\\/]\.git[\\/]worktrees[\\/][^\\/]+$/.exec(gitdir);
+                if (wt)
+                    return basename(wt[1]);
+            }
+            return basename(start);
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return basename(start);
+        dir = parent;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waku-memory",
-  "version": "0.1.0",
+  "version": "0.2.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",