threadit-cli 0.2.0

package/assets/install.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+# Threadit one-paste installer (reference). The server serves a token-injected variant.
+# Usage (server-minted): curl -fsSL https://<server>/install/<token> | sh
+set -eu
+
+: "${THREADIT_SERVER:?set THREADIT_SERVER}"
+: "${THREADIT_TOKEN:?set THREADIT_TOKEN}"
+: "${THREADIT_PROJECT:?set THREADIT_PROJECT}"
+
+# 1. Install the client (pure-JS; no native build).
+npm install -g threadit
+
+# 2. Scaffold this repo. Token rides in via env (never on the command line → not in ps).
+THREADIT_TOKEN="$THREADIT_TOKEN" threadit init "$THREADIT_PROJECT" \
+  --server "$THREADIT_SERVER" --project "$THREADIT_PROJECT"
+# (skills location is prompted from /dev/tty; pass --skills global|repo to skip the prompt)

package/assets/pack/capture-directive.md

@@ -0,0 +1 @@
+Capture discipline: the instant an aside, TODO, loop, or "we should…" surfaces — yours or the user's — run `threadit capture '<text>'` immediately. Don't defer it to wrap-up.

package/assets/skills/threadit-orient/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: threadit-orient
+description: Use at the start of a session in a Threadit repo (a repo with threadit.yml) to orient — load the live work state, surface findings on entry, re-ground stale summaries, and decide what to read first. Triggers on "orient", "where are we", "start of session", "what's the state of this project".
+---
+
+# Threadit — Orient (session start)
+
+The session-start ritual. Ground against ground truth, not your compacted memory.
+
+1. **Load state.** Run `threadit status`. It prints the working slice, findings, and the reading list.
+2. **Surface findings on entry.** Read every finding aloud-to-self. A `unbacked-shipped`, `precondition-violation`, `stale-summary`, or `severity-review` means the record drifted from reality — flag it now, not 25 sessions later. Do not silently proceed past a finding.
+3. **Re-ground stale summaries.** For each `stale-summary` finding, the node's summary predates its latest work. Re-derive it: read the git + linked-doc delta since the summary's `summary_at` sha, then **propose** a rewritten summary to the user (do not auto-apply). This breaks the stale-begets-staler loop.
+4. **Read in order.** Present the reading list and state what to read first. Read those docs before acting.
+
+You author judgment (interpretation + the re-grounded summary prose); the CLI does the mechanics (`threadit status`). Never invent state — if `status` and your memory disagree, `status` wins.

package/assets/skills/threadit-reconcile/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: threadit-reconcile
+description: Use at the end of a session in a Threadit repo (a repo with threadit.yml) to wrap up — triage the inbox, reconcile claimed-vs-committed status, surface un-captured loops, and drain the inbox with forced dispositions. Triggers on "wrap up", "reconcile", "end of session", "before we stop".
+---
+
+# Threadit — Reconcile (wrap-up)
+
+The wrap-up honesty pass. Every surfaced item gets a disposition — no "ignore."
+
+1. **Compute proposals.** Run `threadit reconcile`. It prints a grouped proposal list: inbox dispositions (promote/merge/drop/snooze), status proposals (e.g. resummarize a stale summary, downgrade an unbacked ship), and un-captured loops.
+2. **Batch-approve with per-item veto.** Walk the list with the user. Every inbox item must get promote/merge/drop/snooze — the drain is forced; nothing may be left "open." Veto or adjust any single proposal.
+3. **Author the prose the CLI won't.** The CLI applies prose but never writes it. For an accepted `resummarize`, write the new summary text. For an `accept` (muting a review-class finding), write the rationale and the `until` trigger. Hand these to the apply step.
+4. **Apply atomically.** Build the disposition map and run `threadit reconcile --apply '<json>'`. This executes the two-pass atomic apply and stamps the `reconcile.sha` watermark.
+
+You author judgment + prose; the CLI executes mechanics. This is the step the global wrap-up skill will eventually call instead of hand-maintaining a threads file.

package/dist/assets.d.ts

@@ -0,0 +1,3 @@
+export declare function captureDirectivePath(): string;
+export declare function skillSourceDir(): string;
+export declare function installScriptPath(): string;

package/dist/assets.js

@@ -0,0 +1,16 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+/** Absolute path to the bundled assets dir (package-root `assets/`, shipped via package.json "files"). */
+function assetsRoot() {
+    // dist/assets.js → ../assets
+    return join(dirname(fileURLToPath(import.meta.url)), '..', 'assets');
+}
+export function captureDirectivePath() {
+    return join(assetsRoot(), 'pack', 'capture-directive.md');
+}
+export function skillSourceDir() {
+    return join(assetsRoot(), 'skills');
+}
+export function installScriptPath() {
+    return join(assetsRoot(), 'install.sh');
+}

package/dist/bin.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+/** Build the full commander program. Exported for tests; bin invocation calls parseAsync below. */
+export declare function buildProgram(): Command;
+/**
+ * True iff this module is the process entrypoint. Robust to the npm-bin symlink case:
+ * when installed, the binary is a symlink (e.g. `.../bin/threadit`) whose name is NOT `bin.js`,
+ * so the old `argv[1].endsWith('bin.js')` heuristic silently no-op'd the entire CLI. We resolve
+ * argv[1]'s realpath (following the symlink) and compare it to this module's own path.
+ */
+export declare function isBinInvocation(argv1: string | undefined, moduleHref: string): boolean;

package/dist/bin.js

@@ -0,0 +1,472 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolveRepoRoot } from './paths.js';
+import { shouldPushAfter, maybePushDraft, defaultDraftPushDeps, shouldPushInboxAfter, maybePushInbox, defaultInboxPushDeps } from './draft.js';
+import { PACK_VERSION } from './version.js';
+function parseIntOpt(v) { return Number.parseInt(v, 10); }
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return '';
+    const chunks = [];
+    for await (const c of process.stdin)
+        chunks.push(c);
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** Build the full commander program. Exported for tests; bin invocation calls parseAsync below. */
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name('threadit')
+        .description('Threadit — repo-side CLI for the work-structure visualizer')
+        .version(PACK_VERSION, '-v, --version', 'print the Threadit CLI version')
+        .option('--repo <dir>', 'repo root (default: walk up from cwd to find threadit.yml or .git)')
+        .option('--json', 'machine-readable JSON output where supported');
+    // --- integrity ---
+    program
+        .command('validate')
+        .argument('[path]', 'path to threadit.yml (default: resolved threadit.yml)')
+        .description('structural gate — exit non-zero on structural errors')
+        .action(async (path) => {
+        const { runValidateCommand } = await import('./commands/validate.js');
+        const { code, output } = await runValidateCommand(program.opts(), path);
+        if (output)
+            (code === 0 ? process.stdout : process.stderr).write(output + '\n');
+        process.exit(code);
+    });
+    const hookCmd = program.command('hook').description('internal hook entrypoints (called from .claude/settings.json)');
+    hookCmd
+        .command('capture-directive')
+        .description('emit the SessionStart capture directive as additionalContext')
+        .action(async () => {
+        const { runHookCaptureDirective } = await import('./commands/hook.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        process.stdout.write(runHookCaptureDirective(resolveRepoRoot(process.cwd(), program.opts().repo)) + '\n');
+    });
+    hookCmd
+        .command('validate')
+        .description('PostToolUse: validate threadit.yml after an edit (warn-only; reads payload on stdin)')
+        .action(async () => {
+        const { runHookValidate } = await import('./commands/hook.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const stdin = await readStdin();
+        const { code, stderr } = await runHookValidate(resolveRepoRoot(process.cwd(), program.opts().repo), stdin);
+        if (stderr)
+            process.stderr.write(stderr + '\n');
+        process.exit(code);
+    });
+    const packCmd = program.command('pack').description('manage the installed discipline pack');
+    packCmd
+        .command('sync')
+        .description('re-install the bundled skills + directive at the current pack version (clears the stale nudge)')
+        .action(async () => {
+        const { runPackSync } = await import('./commands/pack.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const { location } = runPackSync(resolveRepoRoot(process.cwd(), program.opts().repo));
+        process.stdout.write(`pack synced (${location})\n`);
+    });
+    // Every other verb is registered with the same shape; actions are filled in by later tasks.
+    // Each registration below mirrors the verb's flags exactly so the surface is frozen now.
+    program
+        .command('init')
+        .argument('[projectId]', 'project slug (default: repo dir name)')
+        .option('--name <name>', 'display name (default: projectId)')
+        .option('--server <url>', 'Threadit server endpoint')
+        .option('--token <tok>', 'ingest token (prefer THREADIT_TOKEN env)')
+        .option('--project <id>', 'project id (overrides the positional)')
+        .option('--skills <loc>', 'skills install location: global|repo (default: prompt, then global)')
+        .option('--yes', 'non-interactive: accept defaults (skills=global)')
+        .description('install the Threadit pack into this repo (config + hooks + skills)')
+        .action(async (projectId, opts) => {
+        const { runInit } = await import('./commands/init.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const root = resolveRepoRoot(process.cwd(), program.opts().repo);
+        const id = opts.project ?? projectId ?? root.split('/').filter(Boolean).pop();
+        const resolvedToken = opts.token ?? process.env.THREADIT_TOKEN;
+        const { skillsLocation, warnings } = runInit(root, id, {
+            ...(opts.name ? { name: opts.name } : {}),
+            ...(opts.server ? { server: opts.server } : {}),
+            ...(resolvedToken ? { token: resolvedToken } : {}),
+            ...(opts.skills === 'global' || opts.skills === 'repo' ? { skills: opts.skills } : {}),
+            ...(opts.yes ? { yes: true } : {}),
+        });
+        for (const w of warnings)
+            process.stderr.write(w + '\n');
+        process.stdout.write(`Initialized threadit project "${id}" in ${root} (skills: ${skillsLocation})\n`);
+    });
+    program
+        .command('session')
+        .option('--bump', 'increment the session counter (run once per session, e.g. from a SessionStart hook)')
+        .description('print the current session number, or bump it')
+        .action(async (opts) => {
+        const { readSession, bumpSession } = await import('./session.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const repoRoot = resolveRepoRoot(process.cwd(), program.opts().repo);
+        const n = opts.bump ? bumpSession(repoRoot) : readSession(repoRoot);
+        process.stdout.write(`s${n}\n`);
+    });
+    program
+        .command('wrapup')
+        .description('stamp the wrap-up watermark (wrapup.session = current session) — called by the wrap-up skill at clean session end')
+        .action(async () => {
+        const { runWrapup } = await import('./commands/wrapup.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const n = runWrapup(resolveRepoRoot(process.cwd(), program.opts().repo));
+        process.stdout.write(`wrapped through s${n}\n`);
+    });
+    program
+        .command('sync')
+        .option('--draft', 'push the uncommitted working file as a draft overlay')
+        .option('--session <key>', 'session key for the draft overlay')
+        .description('push committed history (or the draft) to the server')
+        .action(async (opts) => {
+        const { runSync } = await import('./commands/sync.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const syncOpts = {
+            ...(opts.draft ? { draft: true } : {}),
+            ...(opts.session !== undefined ? { sessionKey: opts.session } : {}),
+        };
+        await runSync(resolveRepoRoot(process.cwd(), program.opts().repo), syncOpts);
+        process.stdout.write(opts.draft ? 'draft synced\n' : 'synced\n');
+    });
+    program
+        .command('status')
+        .description('orient: working slice + findings + sha self-heal')
+        .action(async () => {
+        const { runStatus, formatReadingList } = await import('./commands/status.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const report = runStatus(resolveRepoRoot(process.cwd(), program.opts().repo));
+        if (program.opts().json) {
+            process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+            return;
+        }
+        const lines = [];
+        lines.push(`Working slice (${report.workingSlice.length}): ${report.workingSlice.join(', ') || '(empty)'}`);
+        if (report.findings.length) {
+            lines.push('Findings:');
+            for (const f of report.findings)
+                lines.push(`  [${f.severityClass}] ${f.kind} @ ${f.target}${f.muted ? ' (muted)' : ''}: ${f.message}`);
+        }
+        else {
+            lines.push('Findings: none');
+        }
+        lines.push('');
+        lines.push(...formatReadingList(report.readingList));
+        if (report.unsynced)
+            lines.push(`⚠ HEAD ${report.head ?? '(none)'} differs from last-synced ${report.lastSha ?? '(none)'} — run threadit sync`);
+        if (report.priorSessionUnwrapped) {
+            const from = (report.wrappedThrough ?? 0) + 1;
+            const to = report.currentSession - 1;
+            const label = from === to ? `session ${from}` : `sessions ${from}…${to}`;
+            lines.push(`⚠ ${label} ended without wrap-up — re-scan for uncaptured loops`);
+        }
+        lines.push('(working slice omits the "recently-closed" window — deferred to Phase 3 server data)');
+        process.stdout.write(lines.join('\n') + '\n');
+    });
+    program
+        .command('show')
+        .argument('<id>', 'node id')
+        .description('print one node in full')
+        .action(async (id) => {
+        const { runShow } = await import('./commands/show.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const node = runShow(resolveRepoRoot(process.cwd(), program.opts().repo), id);
+        process.stdout.write(JSON.stringify(node, null, 2) + '\n');
+    });
+    program
+        .command('ls')
+        .description('list nodes')
+        .action(async () => {
+        const { runLs } = await import('./commands/ls.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const rows = runLs(resolveRepoRoot(process.cwd(), program.opts().repo));
+        if (program.opts().json) {
+            process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
+            return;
+        }
+        for (const r of rows)
+            process.stdout.write(`${'  '.repeat(r.depth)}${r.id} [${r.status}] ${r.title}\n`);
+    });
+    program
+        .command('add')
+        .argument('<title>', 'node title')
+        .option('--id <id>').option('--parent <id>').option('--order <n>', 'order', parseIntOpt)
+        .option('--status <s>', 'status', 'planned').option('--flow <f>')
+        .description('add a node')
+        .action(async (title, opts) => {
+        const { runAdd } = await import('./commands/add.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        runAdd(resolveRepoRoot(process.cwd(), program.opts().repo), title, opts);
+        process.stdout.write('added\n');
+    });
+    program
+        .command('move')
+        .argument('<id>', 'node id')
+        .option('--parent <id>').option('--order <n>', 'order', parseIntOpt)
+        .description('move a node (parent/order, with sibling rebalance)')
+        .action(async (id, opts) => {
+        const { runMove } = await import('./commands/move.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        runMove(resolveRepoRoot(process.cwd(), program.opts().repo), id, opts);
+        process.stdout.write('moved\n');
+    });
+    program
+        .command('update <id>')
+        .option('--status <s>').option('--title <t>').option('--summary <s>')
+        .option('--summary-at <sha>').option('--detail <d>').option('--flow <f>')
+        .option('--milestone <bool>', 'milestone', (v) => v === 'true')
+        .description('update node fields')
+        .action(async (id, opts) => {
+        const { runUpdate } = await import('./commands/update.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        runUpdate(resolveRepoRoot(process.cwd(), program.opts().repo), id, opts);
+        process.stdout.write('updated\n');
+    });
+    const docCmd = program.command('doc').description("manage a node's governing doc-links");
+    docCmd
+        .command('add <id>')
+        .requiredOption('--role <role>', 'handoff|memory|spec|plan|playbook')
+        .requiredOption('--ref <ref>', 'path, URL, or memory slug')
+        .description('add a doc-link to a node')
+        .action(async (id, opts) => {
+        const { runDocAdd } = await import('./commands/doc.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const { warning } = runDocAdd(resolveRepoRoot(process.cwd(), program.opts().repo), id, opts.role, opts.ref);
+        if (warning)
+            process.stderr.write(warning + '\n');
+        process.stdout.write('added\n');
+    });
+    docCmd
+        .command('rm <id>')
+        .requiredOption('--ref <ref>', 'the ref to remove')
+        .option('--role <role>', 'narrow removal to one role')
+        .description('remove a doc-link from a node')
+        .action(async (id, opts) => {
+        const { runDocRm } = await import('./commands/doc.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        runDocRm(resolveRepoRoot(process.cwd(), program.opts().repo), id, opts.ref, opts.role);
+        process.stdout.write('removed\n');
+    });
+    docCmd
+        .command('ls <id>')
+        .option('--json', 'output as JSON')
+        .description("list a node's doc-links")
+        .action(async (id, opts) => {
+        const { runDocList } = await import('./commands/doc.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const docs = runDocList(resolveRepoRoot(process.cwd(), program.opts().repo), id);
+        // `--json` may land on the root program (Commander attributes a trailing flag after the
+        // positional to the parent); the local --option declaration above just prevents an
+        // "unknown option" error, while program.opts().json carries the value.
+        if (opts.json || program.opts().json) {
+            process.stdout.write(JSON.stringify(docs, null, 2) + '\n');
+            return;
+        }
+        for (const d of docs)
+            process.stdout.write(`${d.role}\t${d.ref}\n`);
+    });
+    program
+        .command('ship')
+        .argument('<id>', 'node id')
+        .description('flip to shipped (commit-binding courtesy check)')
+        .action(async (id) => {
+        const { runShip } = await import('./commands/ship.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const { warning } = runShip(resolveRepoRoot(process.cwd(), program.opts().repo), id);
+        if (warning)
+            process.stderr.write(warning + '\n');
+        process.stdout.write(`shipped ${id}\n`);
+    });
+    program
+        .command('park')
+        .argument('<id>', 'node id')
+        .option('--until <json>', 'until predicate as JSON')
+        .description('park a node')
+        .action(async (id, opts) => {
+        const { runPark } = await import('./commands/park.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const until = opts.until !== undefined ? JSON.parse(opts.until) : undefined;
+        runPark(resolveRepoRoot(process.cwd(), program.opts().repo), id, until);
+        process.stdout.write('parked\n');
+    });
+    program
+        .command('supersede')
+        .argument('<id>', 'node id')
+        .requiredOption('--by <id>', 'the successor node')
+        .description('supersede a node')
+        .action(async (id, opts) => {
+        const { runSupersede } = await import('./commands/supersede.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        runSupersede(resolveRepoRoot(process.cwd(), program.opts().repo), id, opts.by);
+        process.stdout.write('superseded\n');
+    });
+    program
+        .command('fold')
+        .argument('<id>', 'node id')
+        .requiredOption('--into <id>', 'the absorbing node')
+        .description('fold a node into another')
+        .action(async (id, opts) => {
+        const { runFold } = await import('./commands/fold.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        runFold(resolveRepoRoot(process.cwd(), program.opts().repo), id, opts.into);
+        process.stdout.write('folded\n');
+    });
+    program
+        .command('capture')
+        .argument('<text...>', 'the capture text')
+        .option('--at <label>', 'time label (session number or ISO date)')
+        .option('--tags <csv>', 'comma-separated tags')
+        .option('--risk-node <id>', 'glow anchor for a live-risk item')
+        .description('capture an inbox item')
+        .action(async (textParts, opts) => {
+        const { runCapture } = await import('./commands/capture.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const text = textParts.join(' ');
+        const at = opts.at === undefined ? undefined : (/^\d+$/.test(opts.at) ? Number(opts.at) : opts.at);
+        const captureOpts = {
+            ...(at !== undefined ? { at } : {}),
+            ...(opts.tags ? { tags: opts.tags.split(',').map((s) => s.trim()).filter(Boolean) } : {}),
+            ...(opts.riskNode !== undefined ? { riskNode: opts.riskNode } : {}),
+        };
+        const { id, recurrence } = runCapture(resolveRepoRoot(process.cwd(), program.opts().repo), text, captureOpts);
+        process.stdout.write(`${recurrence ? 'recurrence on' : 'captured'} ${id}\n`);
+    });
+    program
+        .command('promote')
+        .argument('<itemId>', 'inbox item id')
+        .requiredOption('--under <parentId>', 'parent node')
+        .option('--id <id>').option('--status <s>', 'status', 'planned').option('--title <t>')
+        .description('promote an inbox item to a node')
+        .action(async (itemId, opts) => {
+        const { runPromote } = await import('./commands/promote.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const nodeId = runPromote(resolveRepoRoot(process.cwd(), program.opts().repo), itemId, opts);
+        process.stdout.write(`promoted ${itemId} -> ${nodeId}\n`);
+    });
+    program
+        .command('merge')
+        .argument('<itemId>', 'inbox item id')
+        .requiredOption('--into <itemId>', 'the sibling item')
+        .description('merge an inbox item into a recurring sibling')
+        .action(async (itemId, opts) => {
+        const { runMerge } = await import('./commands/merge.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        runMerge(resolveRepoRoot(process.cwd(), program.opts().repo), itemId, opts.into);
+        process.stdout.write(`merged ${itemId} -> ${opts.into}\n`);
+    });
+    program
+        .command('drop')
+        .argument('<itemId>', 'inbox item id')
+        .description('drop an inbox item')
+        .action(async (itemId) => {
+        const { runDrop } = await import('./commands/drop.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        runDrop(resolveRepoRoot(process.cwd(), program.opts().repo), itemId);
+        process.stdout.write(`dropped ${itemId}\n`);
+    });
+    program
+        .command('accept <nodeId>')
+        .requiredOption('--kind <kind>', 'finding kind to accept')
+        .requiredOption('--target <id>', 'finding target (node or edge id)')
+        .requiredOption('--until <json>', 'until-predicate as JSON')
+        .requiredOption('--text <prose>', 'rationale (authored by the caller)')
+        .option('--id <id>', 'decision id (default: accept-<kind>-<target>)')
+        .option('--at <label>', 'time label')
+        .description('mute a review-class finding via a decisions: record')
+        .action(async (nodeId, opts) => {
+        const { runAccept } = await import('./commands/accept.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const root = resolveRepoRoot(process.cwd(), program.opts().repo);
+        runAccept(root, nodeId, {
+            kind: opts.kind, target: opts.target, until: JSON.parse(opts.until), text: opts.text,
+            ...(opts.id ? { id: opts.id } : {}), ...(opts.at ? { at: opts.at } : {}),
+        });
+        process.stdout.write(`accepted ${opts.kind} on ${opts.target}\n`);
+    });
+    program
+        .command('snooze')
+        .argument('<itemId>', 'inbox item id')
+        .requiredOption('--until <json>', 'until predicate as JSON')
+        .description('snooze an inbox item (requires a wake trigger)')
+        .action(async (itemId, opts) => {
+        const { runSnooze } = await import('./commands/snooze.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        runSnooze(resolveRepoRoot(process.cwd(), program.opts().repo), itemId, JSON.parse(opts.until));
+        process.stdout.write(`snoozed ${itemId}\n`);
+    });
+    program
+        .command('reconcile')
+        .option('--apply <json>', 'disposition map as JSON')
+        .description('wrap-up: triage the inbox + reconcile claimed-vs-committed status + surface un-captured loops')
+        .action(async (opts) => {
+        const { runReconcile } = await import('./commands/reconcile.js');
+        const { resolveRepoRoot } = await import('./paths.js');
+        const root = resolveRepoRoot(process.cwd(), program.opts().repo);
+        const applyArg = opts.apply !== undefined ? { apply: JSON.parse(opts.apply) } : {};
+        const { proposals } = runReconcile(root, applyArg);
+        if (opts.apply === undefined) {
+            if (program.opts().json) {
+                process.stdout.write(JSON.stringify(proposals, null, 2) + '\n');
+                return;
+            }
+            const { formatProposals } = await import('./reconcileFormat.js');
+            process.stdout.write(formatProposals(proposals));
+        }
+        else {
+            process.stdout.write('reconciled\n');
+        }
+    });
+    program
+        .command('serve')
+        .option('--port <n>', 'port', parseIntOpt)
+        .option('--db <path>', 'SQLite db path (default: ./.threadit/server.sqlite)')
+        .description('boot the Threadit server on localhost (spawns the built SvelteKit server)')
+        .action(async (opts) => {
+        const { runServe } = await import('./commands/serve.js');
+        const serveOpts = {
+            ...(opts.port !== undefined ? { port: opts.port } : {}),
+            ...(opts.db !== undefined ? { dbPath: opts.db } : {}),
+        };
+        runServe(serveOpts);
+        process.stdout.write(`Threadit server spawning on port ${opts.port ?? 4317}\n`);
+    });
+    // Post-action best-effort pushes — never fail the user's command.
+    // Draft: stream threadit.yml as a session-keyed overlay if it diverged from HEAD.
+    // Inbox: re-push the inbox after any inbox-mutating verb.
+    program.hook('postAction', async (_thisCommand, actionCommand) => {
+        const name = actionCommand.name();
+        try {
+            const repoRoot = resolveRepoRoot(process.cwd(), program.opts().repo);
+            if (shouldPushAfter(name))
+                await maybePushDraft(repoRoot, defaultDraftPushDeps(repoRoot));
+            if (shouldPushInboxAfter(name))
+                await maybePushInbox(repoRoot, defaultInboxPushDeps(repoRoot));
+        }
+        catch { /* best-effort — never fail the user's command */ }
+    });
+    return program;
+}
+/**
+ * True iff this module is the process entrypoint. Robust to the npm-bin symlink case:
+ * when installed, the binary is a symlink (e.g. `.../bin/threadit`) whose name is NOT `bin.js`,
+ * so the old `argv[1].endsWith('bin.js')` heuristic silently no-op'd the entire CLI. We resolve
+ * argv[1]'s realpath (following the symlink) and compare it to this module's own path.
+ */
+export function isBinInvocation(argv1, moduleHref) {
+    if (!argv1)
+        return false;
+    try {
+        return realpathSync(argv1) === fileURLToPath(moduleHref);
+    }
+    catch {
+        return false;
+    }
+}
+// Invocation guard: only parse argv when run as the bin, not when imported by tests.
+if (isBinInvocation(process.argv[1], import.meta.url)) {
+    buildProgram().parseAsync(process.argv).catch((err) => {
+        process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(2);
+    });
+}

package/dist/commands/accept.d.ts

@@ -0,0 +1,12 @@
+import type { ParsedThreaditFile, FindingKind, UntilPredicate } from '@threadit/core';
+export interface AcceptOpts {
+    kind: FindingKind;
+    target: string;
+    until: UntilPredicate;
+    text: string;
+    id?: string;
+    at?: string | number;
+}
+/** Pure core: mutate a parsed threadit file in-place. */
+export declare function applyAccept(file: ParsedThreaditFile, nodeId: string, opts: AcceptOpts): void;
+export declare function runAccept(repoRoot: string, nodeId: string, opts: AcceptOpts): void;

package/dist/commands/accept.js

@@ -0,0 +1,21 @@
+import { resolveThreaditPath } from '../paths.js';
+import { mutate, findNode } from '../mutate.js';
+/** Pure core: mutate a parsed threadit file in-place. */
+export function applyAccept(file, nodeId, opts) {
+    const id = opts.id ?? `accept-${opts.kind}-${opts.target}`;
+    const node = findNode(file, nodeId);
+    const record = {
+        id, status: 'executed', text: opts.text,
+        accepts: { kind: opts.kind, target: opts.target }, until: opts.until,
+        ...(opts.at !== undefined ? { at: opts.at } : {}),
+    };
+    node.decisions ??= [];
+    const existing = node.decisions.findIndex((d) => d.id === id);
+    if (existing >= 0)
+        node.decisions[existing] = record;
+    else
+        node.decisions.push(record);
+}
+export function runAccept(repoRoot, nodeId, opts) {
+    mutate(resolveThreaditPath(repoRoot), (file) => applyAccept(file, nodeId, opts));
+}

package/dist/commands/add.d.ts

@@ -0,0 +1,11 @@
+import type { ParsedThreaditFile, Status, Flow } from '@threadit/core';
+export interface AddOpts {
+    id?: string;
+    parent?: string;
+    order?: number;
+    status?: Status;
+    flow?: Flow;
+}
+/** Pure core: mutate a parsed threadit file in-place; returns the created node id. */
+export declare function applyAddNode(file: ParsedThreaditFile, title: string, opts: AddOpts): string;
+export declare function runAdd(repoRoot: string, title: string, opts: AddOpts): void;

package/dist/commands/add.js

@@ -0,0 +1,19 @@
+import { resolveThreaditPath } from '../paths.js';
+import { mutate } from '../mutate.js';
+import { slugify, uniqueNodeId } from '../ids.js';
+/** Pure core: mutate a parsed threadit file in-place; returns the created node id. */
+export function applyAddNode(file, title, opts) {
+    const id = uniqueNodeId(file, opts.id ?? slugify(title));
+    const siblings = file.nodes.filter((n) => (n.parent ?? null) === (opts.parent ?? null));
+    const order = opts.order ?? (siblings.length ? Math.max(...siblings.map((s) => s.order)) + 10 : 10);
+    const node = { id, order, title, status: opts.status ?? 'planned' };
+    if (opts.parent !== undefined)
+        node.parent = opts.parent;
+    if (opts.flow !== undefined)
+        node.flow = opts.flow;
+    file.nodes.push(node);
+    return id;
+}
+export function runAdd(repoRoot, title, opts) {
+    mutate(resolveThreaditPath(repoRoot), (file) => { applyAddNode(file, title, opts); });
+}

package/dist/commands/capture.d.ts

@@ -0,0 +1,24 @@
+import type { ParsedInboxFile, TimeLabel } from '@threadit/core';
+export interface CaptureOpts {
+    at?: TimeLabel;
+    tags?: string[];
+    riskNode?: string;
+}
+/**
+ * Pure core: capture an inbox item into a parsed inbox object. If it fuzzy-matches an existing
+ * OPEN item, record a recurrence (seen_count++ / append seen_at) instead of duplicating.
+ * The `at` default (new Date().toISOString()) lives here so Task 9 can call applyCapture
+ * with an empty opts and still get a timestamp. Returns the affected item id + recurrence flag.
+ */
+export declare function applyCapture(inbox: ParsedInboxFile, text: string, opts: CaptureOpts): {
+    id: string;
+    recurrence: boolean;
+};
+/**
+ * Capture an inbox item. If it fuzzy-matches an existing OPEN item, record a recurrence
+ * (seen_count++ / append seen_at) instead of duplicating. Returns the affected item id.
+ */
+export declare function runCapture(repoRoot: string, text: string, opts: CaptureOpts): {
+    id: string;
+    recurrence: boolean;
+};