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

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.4. 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.4`. 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. |
 

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,70 @@
+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."
+            };
+        }
+        return {
+            identity: harnessIdentity,
+            source: "harness_cli_exported_detection",
+            detail: "Resolved as harness CLI because TT_HARNESS_EXPORT enabled harness-aware detection."
+        };
+    }
+    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);
+}

package/dist/cli/output.js

@@ -0,0 +1,147 @@
+import { SUPPORTED_HARNESSES } from "../install.js";
+import { hasOption } from "./parser.js";
+export function printResult(parsed, result, renderText) {
+    if (shouldUseJson(parsed)) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`${renderText()}\n`);
+}
+export function shouldUseJson(parsed, env = process.env) {
+    if (hasOption(parsed, "json"))
+        return true;
+    if (hasOption(parsed, "text"))
+        return false;
+    // Auto-JSON when invoked from a harness, using the same opt-in gate as
+    // identity resolution.
+    const exportFlag = env.TT_HARNESS_EXPORT;
+    if (exportFlag === "1" || exportFlag?.toLowerCase() === "true")
+        return true;
+    if (env.TT_HARNESS_AGENT_ID?.trim())
+        return true;
+    return false;
+}
+export function formatRelativeTime(iso, now = new Date()) {
+    if (!iso)
+        return "—";
+    const target = Date.parse(iso);
+    if (Number.isNaN(target))
+        return iso;
+    const deltaMs = target - now.getTime();
+    const absMs = Math.abs(deltaMs);
+    const minute = 60_000;
+    const hour = 60 * minute;
+    const day = 24 * hour;
+    let value;
+    if (absMs < minute)
+        value = `${Math.max(1, Math.round(absMs / 1000))}s`;
+    else if (absMs < hour)
+        value = `${Math.round(absMs / minute)}m`;
+    else if (absMs < day)
+        value = `${Math.round(absMs / hour)}h`;
+    else
+        value = `${Math.round(absMs / day)}d`;
+    return deltaMs >= 0 ? `in ${value}` : `${value} ago`;
+}
+export function formatWaitResult(result) {
+    switch (result.status) {
+        case "not_yet": {
+            if (result.current_owner) {
+                const deadline = result.lease_expires_at
+                    ? ` (lease expires ${formatRelativeTime(result.lease_expires_at)})`
+                    : "";
+                return `Not your turn — ${result.current_owner} holds turn ${result.turn_id ?? "?"}${deadline}.`;
+            }
+            if (result.reserved_for) {
+                const deadline = result.claim_expires_at
+                    ? ` (claim expires ${formatRelativeTime(result.claim_expires_at)})`
+                    : "";
+                return `Not your turn — turn ${result.turn_id ?? "?"} is reserved for ${result.reserved_for}${deadline}.`;
+            }
+            return "Not your turn yet.";
+        }
+        case "closed":
+            return "The room is closed.";
+        case "takeover_available":
+            return `Takeover available: ${result.reason ?? "unknown"}.`;
+        case "your_turn": {
+            if (result.reason === "already_owner") {
+                return "Already holding the stick.";
+            }
+            const header = result.from_agent_id != null
+                ? `Your turn (turn ${result.turn_id ?? "?"}, ${result.reason ?? "claim"} from ${result.from_agent_id}).`
+                : `Your turn (turn ${result.turn_id ?? "?"}, ${result.reason ?? "claim"}).`;
+            const handoffBlock = result.handoff ? formatHandoff(result.handoff) : "";
+            return handoffBlock ? `${header}\n\n${handoffBlock}` : header;
+        }
+        default:
+            return result.status;
+    }
+}
+export function formatHandoff(handoff) {
+    const sections = [];
+    if (handoff.status?.trim()) {
+        sections.push(`Status:\n${indent(handoff.status.trim())}`);
+    }
+    if (handoff.next_action?.trim()) {
+        sections.push(`Next action:\n${indent(handoff.next_action.trim())}`);
+    }
+    if (handoff.artifacts && handoff.artifacts.length > 0) {
+        const lines = handoff.artifacts.map((artifact) => {
+            const range = artifact.lines
+                ? `:${artifact.lines[0]}-${artifact.lines[1]}`
+                : "";
+            const note = artifact.note ? ` — ${artifact.note}` : "";
+            return `- ${artifact.path}${range} (${artifact.role})${note}`;
+        });
+        sections.push(`Artifacts:\n${lines.join("\n")}`);
+    }
+    if (handoff.open_questions && handoff.open_questions.length > 0) {
+        const lines = handoff.open_questions.map((q) => `- ${q}`);
+        sections.push(`Open questions:\n${lines.join("\n")}`);
+    }
+    if (handoff.do_not && handoff.do_not.length > 0) {
+        const lines = handoff.do_not.map((q) => `- ${q}`);
+        sections.push(`Do not:\n${lines.join("\n")}`);
+    }
+    return sections.join("\n\n");
+}
+export function indent(text, prefix = "  ") {
+    return text
+        .split("\n")
+        .map((line) => (line.length > 0 ? `${prefix}${line}` : line))
+        .join("\n");
+}
+export function printHelp() {
+    process.stdout.write(`Usage: tt <command> [options]
+
+Commands:
+  tt whoami [--explain]
+  tt list [path]
+  tt join [path] [--force-new]
+  tt wait [path] [--timeout 30s]
+  tt try [path]
+  tt state [path]
+  tt events [path] [--after N] [--limit N]
+  tt release [path] (--status TEXT --next-action TEXT | --stdin)
+  tt pass [path] (--status TEXT --next-action TEXT | --stdin)
+  tt assign <target|next> [path] (--status TEXT --next-action TEXT | --stdin)
+  tt take [path] [--reason TEXT] [--operator-requested]
+  tt takeover [path] [--reason TEXT] [--operator-requested]
+  tt notes add <body> [--turn N] [--path DIR] [--stdin]
+  tt notes list [--all] [--after NOTE_ID] [--limit N] [--path DIR]
+  tt mcp
+  tt install <harness...> | --all [--print]
+  tt uninstall <harness...> | --all [--print]
+  tt install-skill <harness...> | --all [--print] [--copy] [--link]
+  tt uninstall-skill <harness...> | --all [--print]
+  tt self-update [--print] [--manager npm|pnpm|yarn|bun]
+
+Harnesses: ${SUPPORTED_HARNESSES.join(", ")}
+
+Common options:
+  --agent ID   Override the default human identity
+  --json       Force JSON output (also default when invoked from a harness)
+  --text       Force human-readable text even when invoked from a harness
+`);
+}