talking-stick 0.1.0-alpha.3 → 0.1.0-alpha.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Talking Stick contributors
+
+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/README.md

@@ -2,7 +2,7 @@
 
 An MCP coordination server that lets multiple AI coding agents share a single workspace without stepping on each other. One agent holds the stick at a time; handoffs carry structured context so the next agent doesn't have to re-derive it.
 
-**Version:** 0.1.0-alpha.3. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
+**Version:** 0.1.0-alpha.5. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
 
 ## Quickstart
 
@@ -27,7 +27,7 @@ That's it. The next time two agents `cd` into the same repo, they see each other
 
 | Method | Command | Notes |
 |---|---|---|
-| **From npm** | `npm i -g talking-stick` | Published as `0.1.0-alpha.3`. Requires Node ≥ 22. |
+| **From npm** | `npm i -g talking-stick` | Published as `0.1.0-alpha.5`. Requires Node ≥ 22. |
 | **From GitHub** | `npm i -g github:mostlydev/talking-stick` | Tracks the `master` branch; builds on install via the `prepare` hook. |
 | **From source** | `git clone … && npm install && npm link` | For contributors. |
 
@@ -65,6 +65,7 @@ Once installed, each agent harness sees these tools:
 ```
 list_rooms         — which rooms exist under a path
 join_path          — join the room for this workspace
+leave_room         — explicitly leave a room; deletes it when no active members remain
 wait_for_turn      — block until the stick is available, with takeover signals
 heartbeat          — prove liveness while holding the stick
 release_stick      — normal handoff to the next fair waiter, with structured Handoff
@@ -127,6 +128,7 @@ The same `tt` binary also works as a human CLI, useful for watching or participa
 tt whoami [--explain]                                      # show the resolved CLI identity
 tt list [path]                                            # list rooms
 tt join [path] [--force-new]                              # join the room for path
+tt leave [path]                                           # leave the room for path
 tt wait [path] [--timeout 30s]                            # block until your turn
 tt try [path]                                             # non-blocking claim attempt
 tt state [path]                                           # full room state
@@ -152,14 +154,15 @@ Human CLI commands use a stable identity like `human:<username>`. When `tt wait`
 
 ### CLI identity
 
-By default, `tt` behaves like a human CLI and resolves to `human:<username>`, even when you run it from a shell embedded inside Claude Code, Codex, Gemini, or OpenCode.
+By default, `tt` behaves like a human CLI and resolves to `human:<username>` only when no harness environment is detected.
 
-Harness-aware CLI identity is now explicit:
+Harness-aware CLI identity is resolved before the human fallback:
 
-- Set `TT_HARNESS_EXPORT=1` if you want `tt` to derive a harness-style identity from the current environment and process ancestry.
+- Known harness environment markers such as `CLAUDECODE=1`, `CODEX_THREAD_ID`, `GEMINI_CLI=1`, or `OPENCODE=1` make `tt` derive a harness-style identity automatically.
 - Set `TT_HARNESS_AGENT_ID=<agent-id>` if the harness wants to export the exact agent id directly.
+- Set `TT_HARNESS_EXPORT=1` only when you need ancestry-based harness detection without a known harness environment marker.
 
-If neither variable is set, `tt` stays on the human CLI path. That keeps ordinary shell usage predictable and avoids silently turning a human terminal into a harness participant.
+If no harness signal is present, `tt` stays on the human CLI path. That keeps ordinary shell usage predictable while preventing harness-launched shells from silently joining rooms as `human:<username>`.
 
 Use `tt whoami --explain` to see which identity path the CLI chose.
 
@@ -168,6 +171,8 @@ Use `tt whoami --explain` to see which identity path the CLI chose.
 - **Workspace-root room resolution.** An agent at any depth under `/repo/` joins the `/repo/` room automatically. Nested rooms require explicit `force_new`.
 - **Structured handoffs.** `release_stick` and `pass_stick` carry a typed `Handoff` with required `status` / `next_action` and optional `artifacts[]` pointing at specific files and line ranges.
 - **Fair handoff selection.** Normal release prefers a recent waiter that is new or has gone longest without holding the stick; if the best-known candidate is between wait polls, a short grace window prevents immediate recycling to a less-fair claimant.
+- **No immediate take-backs.** If release leaves a handoff idle, the prior owner waits through the short grace window before reclaiming while another member exists.
+- **Ephemeral rooms.** `leave_room`/`tt leave` removes membership, rooms with no active members are physically deleted, and long-idle rooms are purged opportunistically on later invocations.
 - **Fencing tokens.** `lease_id` + `turn_id` make stale writes impossible — an agent who lost their turn cannot commit anything under the room's name.
 - **Liveness-aware recovery.** Dead or crashed holders are detected with OS-level process checks; claim-timeout takeover skips the prior owner when another active member is waiting.
 - **Multi-process safe.** Shared SQLite with WAL mode, `BEGIN IMMEDIATE` writes, 250 ms polling for `wait_for_turn`. No daemon required.
@@ -204,4 +209,4 @@ See [`CHANGELOG.md`](CHANGELOG.md) for a per-version summary; full release notes
 
 ## License
 
-Unlicensed WIP. To be decided before the first release.
+MIT. See [LICENSE](LICENSE).

package/dist/cli/guardian.js

@@ -0,0 +1,151 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createSystemProcessInspector, deriveHumanCliIdentity, isProtocolError, terminateKnownProcess } from "../index.js";
+import { parseRequiredInteger, requireStringOption } from "./parser.js";
+import { createRuntime } from "./runtime.js";
+const GUARD_READY = "READY";
+const GUARD_READY_TIMEOUT_MS = 10_000;
+const STALE_GUARD_ERRORS = new Set(["stale_lease", "turn_mismatch", "room_not_found"]);
+export async function runGuardCommand(parsed) {
+    const identity = deriveHumanCliIdentity({
+        agentId: requireStringOption(parsed, "agent"),
+        displayName: requireStringOption(parsed, "agent").replace(/^human:/, ""),
+        sessionKind: "human_guardian"
+    });
+    const runtime = createRuntime();
+    try {
+        const joined = runtime.commands.joinPath(identity, {
+            context_path: requireStringOption(parsed, "context-path")
+        });
+        const heartbeatInput = {
+            room_id: requireStringOption(parsed, "room-id"),
+            lease_id: requireStringOption(parsed, "lease-id"),
+            expected_turn_id: parseRequiredInteger(parsed, "turn-id")
+        };
+        const intervalMs = joined.policy.heartbeatIntervalMs;
+        process.stdout.write(`${GUARD_READY}\n`);
+        const timer = setInterval(() => {
+            try {
+                runtime.commands.heartbeat(identity, heartbeatInput);
+            }
+            catch (error) {
+                if (isProtocolError(error) && STALE_GUARD_ERRORS.has(error.code)) {
+                    process.exit(0);
+                }
+                process.exit(1);
+            }
+        }, intervalMs);
+        const exit = () => {
+            clearInterval(timer);
+            process.exit(0);
+        };
+        process.on("SIGINT", exit);
+        process.on("SIGTERM", exit);
+        await new Promise(() => undefined);
+    }
+    finally {
+        runtime.close();
+    }
+}
+export async function spawnGuardian(input) {
+    const self = resolveSelfSpawn(input.cliEntryUrl);
+    const child = spawn(self.command, [
+        ...self.args,
+        "guard",
+        "--agent",
+        input.agentId,
+        "--context-path",
+        input.canonicalPath,
+        "--room-id",
+        input.roomId,
+        "--lease-id",
+        input.leaseId,
+        "--turn-id",
+        String(input.turnId)
+    ], {
+        detached: true,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: process.env
+    });
+    return await new Promise((resolve, reject) => {
+        const inspector = createSystemProcessInspector();
+        let stdout = "";
+        let stderr = "";
+        const timeout = setTimeout(() => {
+            reject(new Error("Guardian did not signal readiness in time."));
+        }, GUARD_READY_TIMEOUT_MS);
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+            if (!stdout.includes(GUARD_READY)) {
+                return;
+            }
+            clearTimeout(timeout);
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            child.unref();
+            if (!child.pid) {
+                reject(new Error("Guardian started without a PID."));
+                return;
+            }
+            resolve({
+                pid: child.pid,
+                process_started_at: inspector.inspect(child.pid)?.startTime ?? null
+            });
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("exit", (code) => {
+            clearTimeout(timeout);
+            reject(new Error(`Guardian exited before readiness (code ${code ?? "unknown"}): ${stderr.trim()}`));
+        });
+    });
+}
+function resolveSelfSpawn(cliEntryUrl) {
+    const scriptPath = fileURLToPath(cliEntryUrl);
+    if (scriptPath.endsWith(".ts")) {
+        const tsxBin = path.join(process.cwd(), "node_modules", ".bin", "tsx");
+        if (fs.existsSync(tsxBin)) {
+            return { command: tsxBin, args: [scriptPath] };
+        }
+    }
+    return { command: process.execPath, args: [scriptPath] };
+}
+export function stopGuardian(guardianPid, guardianProcessStartedAt) {
+    if (!guardianPid) {
+        return;
+    }
+    terminateKnownProcess({
+        pid: guardianPid,
+        process_started_at: guardianProcessStartedAt ?? null
+    }, {
+        inspector: createSystemProcessInspector()
+    });
+}
+export function checkGuardianLiveness(ref, inspector, platform = process.platform) {
+    if (ref.pid === null ||
+        ref.pid === undefined ||
+        !ref.process_started_at ||
+        ref.process_started_at.trim() === "") {
+        return "unknown";
+    }
+    if (platform === "win32") {
+        return "unknown";
+    }
+    const inspection = inspector.inspect(ref.pid);
+    if (inspection === undefined) {
+        return "unknown";
+    }
+    if (inspection === null || !inspection.startTime) {
+        return "gone";
+    }
+    // Trim-normalized match mirrors the service-layer liveness checker: a live
+    // pid with startTime drift is more likely the original process than a reuse.
+    return inspection.startTime.trim() === ref.process_started_at.trim()
+        ? "alive"
+        : "unknown";
+}

package/dist/cli/handoff.js

@@ -0,0 +1,45 @@
+import { getStringOption, hasOption } from "./parser.js";
+const DEFAULT_CLI_HANDOFF_STATUS = "(human handoff — no structured status provided)";
+const DEFAULT_CLI_HANDOFF_NEXT_ACTION = "(no explicit guidance — proceed as previously established)";
+export async function resolveHandoff(parsed) {
+    if (hasOption(parsed, "stdin")) {
+        const raw = (await readAllStdin()).trim();
+        if (!raw) {
+            throw new Error("--stdin specified but no input received. Pipe a JSON Handoff or omit --stdin.");
+        }
+        let value;
+        try {
+            value = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`Invalid JSON on stdin: ${error.message}`);
+        }
+        return parseHandoffJson(value);
+    }
+    return {
+        status: getStringOption(parsed, "status") ?? DEFAULT_CLI_HANDOFF_STATUS,
+        next_action: getStringOption(parsed, "next-action") ?? DEFAULT_CLI_HANDOFF_NEXT_ACTION
+    };
+}
+export function parseHandoffJson(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Handoff JSON must be an object.");
+    }
+    const obj = value;
+    if (typeof obj.status !== "string" || obj.status.trim() === "") {
+        throw new Error("Handoff JSON requires a non-empty `status` string.");
+    }
+    if (typeof obj.next_action !== "string" || obj.next_action.trim() === "") {
+        throw new Error("Handoff JSON requires a non-empty `next_action` string.");
+    }
+    // Pass optional fields through; the service layer's validateHandoff does
+    // final structural validation on artifacts/open_questions/do_not.
+    return obj;
+}
+export async function readAllStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}

package/dist/cli/identity.js

@@ -0,0 +1,77 @@
+import { deriveHarnessCliIdentity, deriveHumanCliIdentity } from "../index.js";
+import { getStringOption, hasOption } from "./parser.js";
+export function deriveCliIdentity(parsed) {
+    return resolveCliIdentity(parsed).identity;
+}
+export function resolveCliIdentity(parsed, env = process.env) {
+    const agentIdOption = getStringOption(parsed, "agent");
+    if (agentIdOption) {
+        const displayName = agentIdOption.replace(/^[^:]+:/, "");
+        return {
+            identity: deriveHumanCliIdentity({
+                agentId: agentIdOption,
+                displayName
+            }),
+            source: "agent_override",
+            detail: "Resolved from explicit --agent override."
+        };
+    }
+    const harnessIdentity = deriveHarnessCliIdentity({ env });
+    if (harnessIdentity) {
+        if (env.TT_HARNESS_AGENT_ID?.trim()) {
+            return {
+                identity: harnessIdentity,
+                source: "harness_cli_exported_agent_id",
+                detail: "Resolved from explicit TT_HARNESS_AGENT_ID export."
+            };
+        }
+        if (env.TT_HARNESS_EXPORT === "1" || env.TT_HARNESS_EXPORT?.toLowerCase() === "true") {
+            return {
+                identity: harnessIdentity,
+                source: "harness_cli_exported_detection",
+                detail: "Resolved as harness CLI because TT_HARNESS_EXPORT enabled harness-aware detection."
+            };
+        }
+        return {
+            identity: harnessIdentity,
+            source: "harness_cli_env_detection",
+            detail: "Resolved as harness CLI from known harness environment variables."
+        };
+    }
+    if (env.TT_HARNESS_EXPORT?.trim()) {
+        return {
+            identity: deriveHumanCliIdentity(),
+            source: "human_cli_default",
+            detail: "TT_HARNESS_EXPORT was set, but no harness signal matched; defaulted to human CLI identity."
+        };
+    }
+    return {
+        identity: deriveHumanCliIdentity(),
+        source: "human_cli_default",
+        detail: "Defaulted to stable human CLI identity."
+    };
+}
+export function resolveTakeoverReason(parsed, env = process.env) {
+    const explicitReason = getStringOption(parsed, "reason");
+    if (explicitReason) {
+        return explicitReason;
+    }
+    if (hasOption(parsed, "operator-requested")) {
+        return "operator requested takeover";
+    }
+    if (isKnownHarnessCliEnv(env)) {
+        throw new Error("Missing required option --reason. Harness CLI takeovers must explain why, unless --operator-requested is set.");
+    }
+    return "operator takeover";
+}
+export function shouldUseOperatorOverride(parsed, env = process.env) {
+    return (!isKnownHarnessCliEnv(env) ||
+        hasOption(parsed, "operator-requested") ||
+        hasOption(parsed, "force"));
+}
+export function isKnownHarnessCliEnv(env = process.env) {
+    if (env.TT_HARNESS_AGENT_ID?.trim()) {
+        return true;
+    }
+    return deriveHarnessCliIdentity({ env }) !== null;
+}

package/dist/cli/install-commands.js

@@ -0,0 +1,156 @@
+import { spawn } from "node:child_process";
+import { SUPPORTED_HARNESSES, detectHarness, parseHarnessList, planInstall, planUninstall, runAction } from "../install.js";
+import { planSkillInstall, planSkillUninstall } from "../skill-install.js";
+import { detectInstallSource, isPackageManager, planSelfUpdate, resolveCurrentBinaryPath } from "../self-update.js";
+import { getStringOption, hasOption, normalizeBooleanFlag } from "./parser.js";
+export async function runInstallCommand(parsed) {
+    normalizeBooleanFlag(parsed, "print");
+    const harnesses = selectHarnesses(parsed);
+    const dryRun = hasOption(parsed, "print");
+    const installOptions = { skipMissing: true };
+    const actions = harnesses.map((harness) => planInstall(harness, installOptions));
+    if (dryRun) {
+        for (const action of actions) {
+            printActionPlan(action);
+        }
+        return;
+    }
+    const results = await Promise.all(actions.map((action) => runAction(action, installOptions)));
+    reportInstallResults(results, "install");
+}
+export async function runUninstallCommand(parsed) {
+    normalizeBooleanFlag(parsed, "print");
+    const harnesses = selectHarnesses(parsed);
+    const dryRun = hasOption(parsed, "print");
+    const installOptions = { skipMissing: true };
+    const actions = harnesses.map((harness) => planUninstall(harness, installOptions));
+    if (dryRun) {
+        for (const action of actions) {
+            printActionPlan(action);
+        }
+        return;
+    }
+    const results = await Promise.all(actions.map((action) => runAction(action, installOptions)));
+    reportInstallResults(results, "uninstall");
+}
+export async function runInstallSkillCommand(parsed) {
+    normalizeBooleanFlag(parsed, "print");
+    normalizeBooleanFlag(parsed, "copy");
+    normalizeBooleanFlag(parsed, "link");
+    const harnesses = selectHarnesses(parsed);
+    const dryRun = hasOption(parsed, "print");
+    const link = resolveSkillInstallLinkMode(parsed);
+    const installOptions = { link, skipMissing: true };
+    const actions = harnesses.map((harness) => planSkillInstall(harness, installOptions));
+    if (dryRun) {
+        for (const action of actions) {
+            printActionPlan(action);
+        }
+        return;
+    }
+    const results = await Promise.all(actions.map((action) => runAction(action, installOptions)));
+    reportInstallResults(results, "install");
+}
+export async function runUninstallSkillCommand(parsed) {
+    normalizeBooleanFlag(parsed, "print");
+    const harnesses = selectHarnesses(parsed);
+    const dryRun = hasOption(parsed, "print");
+    const installOptions = { skipMissing: true };
+    const actions = harnesses.map((harness) => planSkillUninstall(harness, installOptions));
+    if (dryRun) {
+        for (const action of actions) {
+            printActionPlan(action);
+        }
+        return;
+    }
+    const results = await Promise.all(actions.map((action) => runAction(action, installOptions)));
+    reportInstallResults(results, "uninstall");
+}
+export async function runSelfUpdateCommand(parsed, cliEntryUrl) {
+    normalizeBooleanFlag(parsed, "print");
+    const dryRun = hasOption(parsed, "print");
+    const managerOverride = getStringOption(parsed, "manager");
+    let source;
+    if (managerOverride) {
+        if (!isPackageManager(managerOverride)) {
+            throw new Error(`--manager must be one of npm | pnpm | yarn | bun (got ${managerOverride}).`);
+        }
+        source = managerOverride;
+    }
+    else {
+        const binaryPath = resolveCurrentBinaryPath(cliEntryUrl);
+        source = detectInstallSource({ binaryPath });
+    }
+    const plan = planSelfUpdate(source);
+    if (!plan) {
+        if (source === "dev") {
+            throw new Error("tt is running from a development checkout. Use `git pull && npm install && npm run build` instead of `tt self-update`, or pass `--manager npm|pnpm|yarn|bun` if this is wrong.");
+        }
+        throw new Error(`Could not determine how tt was installed. Pass --manager npm|pnpm|yarn|bun to override.`);
+    }
+    if (dryRun) {
+        process.stdout.write(`${plan.description}\n`);
+        return;
+    }
+    process.stdout.write(`Updating via: ${plan.description}\n`);
+    await runInheritIo(plan.command, plan.args);
+    process.stdout.write("Done. Restart your harness MCP subprocess to pick up the new dist.\n");
+}
+function resolveSkillInstallLinkMode(parsed) {
+    const wantsCopy = hasOption(parsed, "copy");
+    const wantsLink = hasOption(parsed, "link");
+    if (wantsCopy && wantsLink) {
+        throw new Error("Pass only one of --copy or --link.");
+    }
+    if (wantsCopy) {
+        return false;
+    }
+    return true;
+}
+function selectHarnesses(parsed) {
+    if (hasOption(parsed, "all")) {
+        const detected = SUPPORTED_HARNESSES.filter((harness) => detectHarness(harness).detected);
+        return [...detected];
+    }
+    if (parsed.positionals.length === 0) {
+        throw new Error(`Specify at least one harness (${SUPPORTED_HARNESSES.join(", ")}) or pass --all to target every detected one.`);
+    }
+    return parseHarnessList(parsed.positionals);
+}
+function printActionPlan(action) {
+    if (action.kind === "skip") {
+        return;
+    }
+    if (action.kind === "exec") {
+        process.stdout.write(`[${action.harness}] ${action.description}\n`);
+        return;
+    }
+    process.stdout.write(`[${action.harness}] ${action.description}\n`);
+}
+function runInheritIo(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: "inherit", shell: false });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`${command} exited with code ${code}.`));
+        });
+    });
+}
+function reportInstallResults(results, mode) {
+    let anyFailed = false;
+    for (const result of results) {
+        if (result.skipped)
+            continue;
+        const status = result.ok ? "ok" : "FAIL";
+        process.stdout.write(`[${result.harness}] ${status}: ${result.message}\n`);
+        if (!result.ok)
+            anyFailed = true;
+    }
+    if (anyFailed) {
+        throw new Error(`${mode} completed with failures.`);
+    }
+}

package/dist/cli/notes-commands.js

@@ -0,0 +1,70 @@
+import { deriveCliIdentity } from "./identity.js";
+import { readAllStdin } from "./handoff.js";
+import { getStringOption, hasOption, parseOptionalInteger } from "./parser.js";
+import { formatRelativeTime, printResult } from "./output.js";
+import { resolveSessionForNotes } from "./session.js";
+export async function handleNotesCommand(runtime, parsed) {
+    const [subcommand, ...rest] = parsed.positionals;
+    if (!subcommand) {
+        throw new Error("Usage: tt notes <add|list> [...]. See `tt --help` for details.");
+    }
+    const subParsed = {
+        name: `notes ${subcommand}`,
+        positionals: rest,
+        options: parsed.options
+    };
+    switch (subcommand) {
+        case "add":
+            await handleNotesAddCommand(runtime, subParsed);
+            return;
+        case "list":
+            handleNotesListCommand(runtime, subParsed);
+            return;
+        default:
+            throw new Error(`Unknown notes subcommand: ${subcommand}`);
+    }
+}
+async function handleNotesAddCommand(runtime, parsed) {
+    const identity = deriveCliIdentity(parsed);
+    const session = resolveSessionForNotes(runtime, parsed, identity);
+    const positionalBody = parsed.positionals.join(" ").trim();
+    const body = positionalBody ||
+        (hasOption(parsed, "stdin") ? (await readAllStdin()).trim() : "");
+    if (!body) {
+        throw new Error("Note body is required (pass as a positional or use --stdin to read from stdin).");
+    }
+    const turnId = parseOptionalInteger(parsed, "turn");
+    const result = runtime.commands.addNote(identity, {
+        room_id: session.room_id,
+        body,
+        turn_id: turnId
+    });
+    printResult(parsed, result, () => `Added note ${shortNoteId(result.note_id)} (turn=${result.turn_id ?? "-"}).`);
+}
+function handleNotesListCommand(runtime, parsed) {
+    const identity = deriveCliIdentity(parsed);
+    const session = resolveSessionForNotes(runtime, parsed, identity);
+    const includeResolved = hasOption(parsed, "all");
+    const result = runtime.commands.listNotes(identity, {
+        room_id: session.room_id,
+        include_resolved: includeResolved,
+        after_note_id: getStringOption(parsed, "after"),
+        limit: parseOptionalInteger(parsed, "limit")
+    });
+    printResult(parsed, result, () => {
+        if (result.notes.length === 0) {
+            return "No notes.";
+        }
+        const header = `${result.notes.length} note${result.notes.length === 1 ? "" : "s"} in this room:`;
+        const lines = result.notes.map((note) => {
+            const scope = note.turn_id !== null ? `turn ${note.turn_id}` : "room-scoped";
+            const firstLine = note.body.split("\n")[0] ?? "";
+            const preview = firstLine.length > 80 ? `${firstLine.slice(0, 77)}...` : firstLine;
+            return `- ${shortNoteId(note.note_id)} ${note.author_agent_id} · ${formatRelativeTime(note.created_at)} · ${scope}\n  ${preview}`;
+        });
+        return [header, ...lines].join("\n");
+    });
+}
+function shortNoteId(noteId) {
+    return noteId.slice(0, 8);
+}