threadit-cli 0.2.0

package/dist/commands/capture.js

@@ -0,0 +1,45 @@
+import { resolveInboxPath } from '../paths.js';
+import { mutateInbox } from '../mutate.js';
+import { uniqueInboxId } from '../ids.js';
+import { matchOpenItem } from '../inbox/recurrence.js';
+/**
+ * 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 function applyCapture(inbox, text, opts) {
+    const at = opts.at ?? new Date().toISOString();
+    const existing = matchOpenItem(inbox.items, text);
+    if (existing) {
+        existing.seen_count = (existing.seen_count ?? 1) + 1;
+        existing.seen_at = [...(existing.seen_at ?? [existing.created]), at];
+        return { id: existing.id, recurrence: true };
+    }
+    const item = {
+        id: uniqueInboxId(inbox),
+        text,
+        created: at,
+        source: 'session',
+        status: 'open',
+        seen_count: 1,
+        seen_at: [at],
+    };
+    if (opts.tags?.length)
+        item.tags = opts.tags;
+    if (opts.riskNode !== undefined)
+        item.risk_node = opts.riskNode;
+    inbox.items.push(item);
+    return { id: item.id, recurrence: false };
+}
+/**
+ * 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 function runCapture(repoRoot, text, opts) {
+    let result = { id: '', recurrence: false };
+    mutateInbox(resolveInboxPath(repoRoot), (inbox) => {
+        result = applyCapture(inbox, text, opts);
+    });
+    return result;
+}

package/dist/commands/doc.d.ts

@@ -0,0 +1,7 @@
+import type { DocLink, DocRole } from '@threadit/core';
+export declare const DOC_ROLES: readonly DocRole[];
+export declare function runDocAdd(repoRoot: string, id: string, role: string, ref: string): {
+    warning?: string;
+};
+export declare function runDocRm(repoRoot: string, id: string, ref: string, role?: string): void;
+export declare function runDocList(repoRoot: string, id: string): DocLink[];

package/dist/commands/doc.js

@@ -0,0 +1,56 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { resolveThreaditPath } from '../paths.js';
+import { mutate, findNode } from '../mutate.js';
+import { loadThreadit } from '../yaml/io.js';
+export const DOC_ROLES = ['handoff', 'memory', 'spec', 'plan', 'playbook'];
+function assertRole(role) {
+    if (!DOC_ROLES.includes(role)) {
+        throw new Error(`Unknown doc role "${role}". Expected one of: ${DOC_ROLES.join(', ')}`);
+    }
+}
+/** Heuristic: a ref that looks like a repo path (not a URL scheme, not a bare slug). */
+function isPathLike(ref) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(ref))
+        return false; // URL
+    return ref.includes('/') || /\.[a-z0-9]+$/i.test(ref);
+}
+export function runDocAdd(repoRoot, id, role, ref) {
+    assertRole(role);
+    const r = role; // explicit narrowing so the closure push stays DocRole
+    mutate(resolveThreaditPath(repoRoot), (file) => {
+        const node = findNode(file, id);
+        if (!node.docs)
+            node.docs = [];
+        if (!node.docs.some((d) => d.role === r && d.ref === ref))
+            node.docs.push({ role: r, ref });
+    });
+    if (isPathLike(ref)) {
+        const abs = isAbsolute(ref) ? ref : join(repoRoot, ref);
+        if (!existsSync(abs)) {
+            return { warning: `warning: doc ref "${ref}" does not resolve on disk (forward reference?)` };
+        }
+    }
+    return {};
+}
+export function runDocRm(repoRoot, id, ref, role) {
+    if (role !== undefined)
+        assertRole(role);
+    const matches = (d) => d.ref === ref && (role === undefined || d.role === role);
+    const path = resolveThreaditPath(repoRoot);
+    // Validate BEFORE mutating so a no-match never triggers a (no-op) canonical re-emit / draft-push.
+    const existing = findNode(loadThreadit(path), id).docs ?? [];
+    if (!existing.some(matches)) {
+        throw new Error(`No doc-link with ref "${ref}"${role ? ` and role "${role}"` : ''} on node "${id}"`);
+    }
+    mutate(path, (file) => {
+        const node = findNode(file, id);
+        node.docs = (node.docs ?? []).filter((d) => !matches(d));
+        if (node.docs.length === 0)
+            delete node.docs;
+    });
+}
+export function runDocList(repoRoot, id) {
+    const file = loadThreadit(resolveThreaditPath(repoRoot));
+    return findNode(file, id).docs ?? [];
+}

package/dist/commands/drop.d.ts

@@ -0,0 +1,4 @@
+import type { ParsedInboxFile } from '@threadit/core';
+/** Pure core: flip an inbox item's status to dropped. */
+export declare function applyDrop(inbox: ParsedInboxFile, itemId: string): void;
+export declare function runDrop(repoRoot: string, itemId: string): void;

package/dist/commands/drop.js

@@ -0,0 +1,12 @@
+import { resolveInboxPath } from '../paths.js';
+import { mutateInbox } from '../mutate.js';
+/** Pure core: flip an inbox item's status to dropped. */
+export function applyDrop(inbox, itemId) {
+    const item = inbox.items.find((i) => i.id === itemId);
+    if (!item)
+        throw new Error(`No inbox item "${itemId}"`);
+    item.status = 'dropped';
+}
+export function runDrop(repoRoot, itemId) {
+    mutateInbox(resolveInboxPath(repoRoot), (inbox) => applyDrop(inbox, itemId));
+}

package/dist/commands/fold.d.ts

@@ -0,0 +1 @@
+export declare function runFold(repoRoot: string, id: string, into: string): void;

package/dist/commands/fold.js

@@ -0,0 +1,9 @@
+import { resolveThreaditPath } from '../paths.js';
+import { mutate, findNode } from '../mutate.js';
+export function runFold(repoRoot, id, into) {
+    mutate(resolveThreaditPath(repoRoot), (file) => {
+        const node = findNode(file, id);
+        node.status = 'superseded'; // closed-lineage; folded_into satisfies the successor requirement (Task 1)
+        node.folded_into = into;
+    });
+}

package/dist/commands/hook.d.ts

@@ -0,0 +1,24 @@
+export interface CaptureDirectiveOpts {
+    skillsDirOverride?: string;
+    currentVersion?: string;
+}
+/**
+ * Emit the SessionStart hook output: the capture directive (pack-owned prose) as
+ * additionalContext, plus a stale-pack nudge appended when the installed pack is older
+ * than the current pack version. The CLI is a courier for the pack asset — it does not author the prose.
+ * `opts` exists for hermetic tests (override the install dir + current version).
+ */
+export declare function runHookCaptureDirective(repoRoot: string, opts?: CaptureDirectiveOpts): string;
+export interface HookValidateResult {
+    code: number;
+    stderr: string;
+}
+/**
+ * PostToolUse validate. Reads the tool payload; acts ONLY when the edited file is the repo's
+ * threadit.yml (exact match — naturally excludes threadit-inbox.yml and everything else).
+ * Warn-only (Claude hook, not a git hook):
+ *   exit 0 — no-op (non-matching / unparseable stdin), OR valid, OR an IO/parse-IO error
+ *            (runValidate code 2 — don't masquerade an internal error as a structural finding)
+ *   exit 2 — structural-invalid (runValidate code 1; PostToolUse exit-2 feeds stderr to the model)
+ */
+export declare function runHookValidate(repoRoot: string, stdin: string): Promise<HookValidateResult>;

package/dist/commands/hook.js

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs';
+import { relative, resolve, join as pjoin } from 'node:path';
+import { captureDirectivePath } from '../assets.js';
+import { readInstalledPackVersion } from '../install/skills.js';
+import { THREADIT_FILE } from '../paths.js';
+import { PACK_VERSION, isOlder, isDevVersion } from '../version.js';
+import { runValidate } from './validate.js';
+/**
+ * Emit the SessionStart hook output: the capture directive (pack-owned prose) as
+ * additionalContext, plus a stale-pack nudge appended when the installed pack is older
+ * than the current pack version. The CLI is a courier for the pack asset — it does not author the prose.
+ * `opts` exists for hermetic tests (override the install dir + current version).
+ */
+export function runHookCaptureDirective(repoRoot, opts = {}) {
+    const current = opts.currentVersion ?? PACK_VERSION;
+    let prose = readFileSync(captureDirectivePath(), 'utf8').trim();
+    const installed = readInstalledPackVersion(repoRoot, opts.skillsDirOverride);
+    if (installed && !isDevVersion(current) && isOlder(installed, current)) {
+        prose += `\n\nThreadit pack is stale (installed ${installed}, available ${current}) — run \`threadit pack sync\`.`;
+    }
+    return JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: prose },
+    });
+}
+/**
+ * PostToolUse validate. Reads the tool payload; acts ONLY when the edited file is the repo's
+ * threadit.yml (exact match — naturally excludes threadit-inbox.yml and everything else).
+ * Warn-only (Claude hook, not a git hook):
+ *   exit 0 — no-op (non-matching / unparseable stdin), OR valid, OR an IO/parse-IO error
+ *            (runValidate code 2 — don't masquerade an internal error as a structural finding)
+ *   exit 2 — structural-invalid (runValidate code 1; PostToolUse exit-2 feeds stderr to the model)
+ */
+export async function runHookValidate(repoRoot, stdin) {
+    let filePath;
+    try {
+        const payload = JSON.parse(stdin);
+        filePath = payload.tool_input?.file_path ?? payload.file_path;
+    }
+    catch {
+        return { code: 0, stderr: '' };
+    }
+    if (!filePath)
+        return { code: 0, stderr: '' };
+    if (relative(repoRoot, resolve(repoRoot, filePath)) !== THREADIT_FILE)
+        return { code: 0, stderr: '' };
+    const { code, output } = await runValidate(pjoin(repoRoot, THREADIT_FILE));
+    if (code === 0)
+        return { code: 0, stderr: '' };
+    if (code === 2)
+        return { code: 0, stderr: `threadit hook validate: internal error — ${output}` }; // IO → don't masquerade as structural
+    return { code: 2, stderr: `threadit validate failed after a threadit.yml edit — fix the structure:\n${output}` };
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,18 @@
+export interface InitOptions {
+    name?: string;
+    server?: string;
+    token?: string;
+    skills?: 'global' | 'repo';
+    yes?: boolean;
+    packVersion?: string;
+}
+/**
+ * Idempotent, resumable installer. Seeds files if absent; always (re)writes pointers/hooks/skills.
+ * If `.claude/settings.json` is malformed, `mergeSettings` throws AFTER yml/inbox/.gitignore/config
+ * are written — but `.threadit/` is already gitignored (step 2 precedes config), so the token is safe,
+ * and re-running after fixing the JSON converges.
+ */
+export declare function runInit(repoRoot: string, projectId: string, opts?: InitOptions): {
+    skillsLocation: 'global' | 'repo';
+    warnings: string[];
+};

package/dist/commands/init.js

@@ -0,0 +1,55 @@
+import { existsSync } from 'node:fs';
+import { resolveThreaditPath, resolveInboxPath } from '../paths.js';
+import { saveThreadit, saveInbox } from '../yaml/io.js';
+import { readConfig, writeConfig } from '../config.js';
+import { ensureGitignore, verifyIgnored } from '../install/gitignore.js';
+import { mergeSettings } from '../install/settings.js';
+import { installGitHooks } from '../install/gitHooks.js';
+import { installSkills } from '../install/skills.js';
+import { promptChoice } from '../install/tty.js';
+import { PACK_VERSION } from '../version.js';
+/**
+ * Idempotent, resumable installer. Seeds files if absent; always (re)writes pointers/hooks/skills.
+ * If `.claude/settings.json` is malformed, `mergeSettings` throws AFTER yml/inbox/.gitignore/config
+ * are written — but `.threadit/` is already gitignored (step 2 precedes config), so the token is safe,
+ * and re-running after fixing the JSON converges.
+ */
+export function runInit(repoRoot, projectId, opts = {}) {
+    const warnings = [];
+    const version = opts.packVersion ?? PACK_VERSION;
+    // 1. Seed yml/inbox ONLY if absent (never clobber an existing graph).
+    const ymlPath = resolveThreaditPath(repoRoot);
+    if (!existsSync(ymlPath)) {
+        const file = { threadit: 1, project: { id: projectId, name: opts.name ?? projectId }, nodes: [] };
+        saveThreadit(ymlPath, file);
+    }
+    const inboxPath = resolveInboxPath(repoRoot);
+    if (!existsSync(inboxPath)) {
+        const inbox = { threadit_inbox: 1, project: projectId, items: [] };
+        saveInbox(inboxPath, inbox);
+    }
+    // 2. .gitignore BEFORE config (close the token-leak window), then verify.
+    ensureGitignore(repoRoot);
+    if (!verifyIgnored(repoRoot, '.threadit/config.json')) {
+        warnings.push('⚠ .threadit/config.json is not git-ignored — the ingest token could be committed. Check .gitignore for a negation pattern.');
+    }
+    // 3. Config (preserve existing fields; fill the new ones).
+    const prev = readConfig(repoRoot);
+    writeConfig(repoRoot, {
+        ...prev,
+        projectId,
+        session: prev.session ?? 1,
+        packVersion: version,
+        ...(opts.server ? { server: opts.server } : {}),
+        ...(opts.token ? { ingestToken: opts.token } : {}),
+    });
+    // 4. Claude hooks (merge) + git hooks (chain).
+    mergeSettings(repoRoot);
+    const { skipped } = installGitHooks(repoRoot);
+    for (const h of skipped)
+        warnings.push(`⚠ git hook ${h} is a non-shell script — left untouched; sync won't auto-fire from it (SessionStart sync still covers you).`);
+    // 5. Skills — location: flag → /dev/tty prompt → default global.
+    const skillsLocation = opts.skills ?? (opts.yes ? 'global' : promptChoice('Install Threadit skills globally or in this repo?', ['global', 'repo'], 'global'));
+    installSkills(repoRoot, skillsLocation, version);
+    return { skillsLocation, warnings };
+}

package/dist/commands/ls.d.ts

@@ -0,0 +1,8 @@
+import type { Status } from '@threadit/core';
+export interface LsRow {
+    id: string;
+    title: string;
+    status: Status;
+    depth: number;
+}
+export declare function runLs(repoRoot: string): LsRow[];

package/dist/commands/ls.js

@@ -0,0 +1,27 @@
+import { resolveThreaditPath } from '../paths.js';
+import { loadThreadit } from '../yaml/io.js';
+export function runLs(repoRoot) {
+    const file = loadThreadit(resolveThreaditPath(repoRoot));
+    const byId = new Map(file.nodes.map((n) => [n.id, n]));
+    const depthOf = (id) => {
+        let depth = 0;
+        let cur = byId.get(id)?.parent ?? null;
+        const guard = new Set();
+        while (cur && !guard.has(cur)) {
+            guard.add(cur);
+            depth++;
+            cur = byId.get(cur)?.parent ?? null;
+        }
+        return depth;
+    };
+    const childrenOf = (parent) => file.nodes.filter((n) => (n.parent ?? null) === parent).sort((a, b) => a.order - b.order);
+    const rows = [];
+    const walk = (parent) => {
+        for (const n of childrenOf(parent)) {
+            rows.push({ id: n.id, title: n.title, status: n.status, depth: depthOf(n.id) });
+            walk(n.id);
+        }
+    };
+    walk(null);
+    return rows;
+}

package/dist/commands/merge.d.ts

@@ -0,0 +1,4 @@
+import type { ParsedInboxFile } from '@threadit/core';
+/** Pure core: merge `itemId` into sibling `intoId` (recurrence rolls up; merged item dropped + linked). */
+export declare function applyMerge(inbox: ParsedInboxFile, itemId: string, intoId: string): void;
+export declare function runMerge(repoRoot: string, itemId: string, intoId: string): void;

package/dist/commands/merge.js

@@ -0,0 +1,18 @@
+import { resolveInboxPath } from '../paths.js';
+import { mutateInbox } from '../mutate.js';
+/** Pure core: merge `itemId` into sibling `intoId` (recurrence rolls up; merged item dropped + linked). */
+export function applyMerge(inbox, itemId, intoId) {
+    const item = inbox.items.find((i) => i.id === itemId);
+    const into = inbox.items.find((i) => i.id === intoId);
+    if (!item)
+        throw new Error(`No inbox item "${itemId}"`);
+    if (!into)
+        throw new Error(`No inbox item "${intoId}"`);
+    into.seen_count = (into.seen_count ?? 1) + (item.seen_count ?? 1);
+    into.seen_at = [...(into.seen_at ?? []), ...(item.seen_at ?? [])];
+    item.status = 'dropped';
+    item.related = [...(item.related ?? []), intoId];
+}
+export function runMerge(repoRoot, itemId, intoId) {
+    mutateInbox(resolveInboxPath(repoRoot), (inbox) => applyMerge(inbox, itemId, intoId));
+}

package/dist/commands/move.d.ts

@@ -0,0 +1,11 @@
+export interface MoveOpts {
+    parent?: string | null;
+    order?: number;
+}
+/**
+ * Move a node: change parent and/or order. If the requested order would collide with
+ * a sibling and there is no integer gap to slot into, rebalance the whole sibling set
+ * to gaps of 10 (the one sanctioned multi-line structural diff), preserving the intended
+ * relative position of the moved node.
+ */
+export declare function runMove(repoRoot: string, id: string, opts: MoveOpts): void;

package/dist/commands/move.js

@@ -0,0 +1,45 @@
+import { resolveThreaditPath } from '../paths.js';
+import { mutate, findNode } from '../mutate.js';
+/**
+ * Move a node: change parent and/or order. If the requested order would collide with
+ * a sibling and there is no integer gap to slot into, rebalance the whole sibling set
+ * to gaps of 10 (the one sanctioned multi-line structural diff), preserving the intended
+ * relative position of the moved node.
+ */
+export function runMove(repoRoot, id, opts) {
+    mutate(resolveThreaditPath(repoRoot), (file) => {
+        const node = findNode(file, id);
+        const newParent = opts.parent !== undefined ? opts.parent : (node.parent ?? null);
+        node.parent = newParent;
+        if (opts.order !== undefined)
+            node.order = opts.order;
+        const siblings = file.nodes.filter((n) => (n.parent ?? null) === (newParent ?? null));
+        if (hasOrderCollision(siblings))
+            rebalance(siblings, node);
+    });
+}
+function hasOrderCollision(siblings) {
+    const seen = new Set();
+    for (const s of siblings) {
+        if (seen.has(s.order))
+            return true;
+        seen.add(s.order);
+    }
+    return false;
+}
+/**
+ * Reassign orders to 10,20,30,... over the sibling set sorted by (order, then the moved
+ * node first on a tie so it keeps the slot it asked for), then by id for stability.
+ */
+function rebalance(siblings, moved) {
+    const sorted = [...siblings].sort((a, b) => {
+        if (a.order !== b.order)
+            return a.order - b.order;
+        if (a.id === moved.id)
+            return -1;
+        if (b.id === moved.id)
+            return 1;
+        return a.id < b.id ? -1 : 1;
+    });
+    sorted.forEach((n, i) => { n.order = (i + 1) * 10; });
+}

package/dist/commands/pack.d.ts

@@ -0,0 +1,5 @@
+/** Re-copy the skills + directive to wherever they're installed (repo if a repo marker is present,
+ *  else global) and re-stamp the version. `globalOverride` redirects the global dest (tests). */
+export declare function runPackSync(repoRoot: string, version?: string, globalOverride?: string): {
+    location: 'global' | 'repo';
+};

package/dist/commands/pack.js

@@ -0,0 +1,12 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { installSkills } from '../install/skills.js';
+import { PACK_VERSION } from '../version.js';
+/** Re-copy the skills + directive to wherever they're installed (repo if a repo marker is present,
+ *  else global) and re-stamp the version. `globalOverride` redirects the global dest (tests). */
+export function runPackSync(repoRoot, version = PACK_VERSION, globalOverride) {
+    const repoMarker = join(repoRoot, '.claude', 'skills', '.threadit-pack-version');
+    const location = existsSync(repoMarker) ? 'repo' : 'global';
+    installSkills(repoRoot, location, version, globalOverride);
+    return { location };
+}

package/dist/commands/park.d.ts

@@ -0,0 +1,2 @@
+import type { UntilPredicate } from '@threadit/core';
+export declare function runPark(repoRoot: string, id: string, until?: UntilPredicate): void;

package/dist/commands/park.js

@@ -0,0 +1,10 @@
+import { resolveThreaditPath } from '../paths.js';
+import { mutate, findNode } from '../mutate.js';
+export function runPark(repoRoot, id, until) {
+    mutate(resolveThreaditPath(repoRoot), (file) => {
+        const node = findNode(file, id);
+        node.status = 'parked';
+        if (until !== undefined)
+            node.until = until;
+    });
+}

package/dist/commands/promote.d.ts

@@ -0,0 +1,11 @@
+import type { ParsedInboxFile, Status } from '@threadit/core';
+export interface PromoteOpts {
+    under: string;
+    id?: string;
+    status?: Status;
+    title?: string;
+}
+/** Pure core: mark an inbox item as promoted, linking to the given nodeId. */
+export declare function applyPromoteMark(inbox: ParsedInboxFile, itemId: string, nodeId: string): void;
+/** Promote an inbox item to a node under `--under`; flip the item to promoted + link. */
+export declare function runPromote(repoRoot: string, itemId: string, opts: PromoteOpts): string;

package/dist/commands/promote.js

@@ -0,0 +1,33 @@
+import { resolveThreaditPath, resolveInboxPath } from '../paths.js';
+import { loadInbox } from '../yaml/io.js';
+import { mutate, mutateInbox } from '../mutate.js';
+import { applyAddNode } from './add.js';
+/** Pure core: mark an inbox item as promoted, linking to the given nodeId. */
+export function applyPromoteMark(inbox, itemId, nodeId) {
+    const item = inbox.items.find((i) => i.id === itemId);
+    if (!item)
+        throw new Error(`No inbox item "${itemId}"`);
+    if (item.status !== 'open')
+        throw new Error(`Item "${itemId}" is ${item.status}, not open`);
+    item.status = 'promoted';
+    item.promoted_to = nodeId;
+}
+/** Promote an inbox item to a node under `--under`; flip the item to promoted + link. */
+export function runPromote(repoRoot, itemId, opts) {
+    const inbox = loadInbox(resolveInboxPath(repoRoot));
+    const item = inbox.items.find((i) => i.id === itemId);
+    if (!item)
+        throw new Error(`No inbox item "${itemId}"`);
+    if (item.status !== 'open')
+        throw new Error(`Item "${itemId}" is ${item.status}, not open`);
+    const title = opts.title ?? item.text;
+    let createdId = '';
+    mutate(resolveThreaditPath(repoRoot), (file) => {
+        createdId = applyAddNode(file, title, {
+            ...(opts.id !== undefined ? { id: opts.id } : {}),
+            parent: opts.under, status: opts.status ?? 'planned',
+        });
+    });
+    mutateInbox(resolveInboxPath(repoRoot), (ibx) => applyPromoteMark(ibx, itemId, createdId));
+    return createdId;
+}

package/dist/commands/reconcile.d.ts

@@ -0,0 +1,12 @@
+import type { Disposition, Proposal } from '@threadit/core';
+/**
+ * Working-set = OPEN items (Phase 2; "this-session items + now-due snoozes" needs session
+ * tracking + clock = Phase-5 hook context). Without `apply`: return a suggested disposition
+ * per open item. With `apply`: every open item MUST have a disposition (forced drain — no ignore);
+ * execute them.
+ */
+export declare function runReconcile(repoRoot: string, opts: {
+    apply?: Record<string, Disposition>;
+}): {
+    proposals: Proposal[];
+};

package/dist/commands/reconcile.js

@@ -0,0 +1,97 @@
+import { engine, deriveReconcile } from '@threadit/core';
+import { resolveInboxPath, resolveThreaditPath } from '../paths.js';
+import { loadInbox, loadThreadit } from '../yaml/io.js';
+import { buildCommitFacts } from '../git/commitFacts.js';
+import { gatherReconcileCommits } from '../git/reconcileCommits.js';
+import { matchOpenItem } from '../inbox/recurrence.js';
+import { firstParentChain } from '../git/log.js';
+import { mutate, mutateInbox } from '../mutate.js';
+import { applyAddNode } from './add.js';
+import { applyUpdate } from './update.js';
+import { applyAccept } from './accept.js';
+import { applyPromoteMark } from './promote.js';
+import { applyMerge } from './merge.js';
+import { applyDrop } from './drop.js';
+import { applySnooze } from './snooze.js';
+import { applyCapture } from './capture.js';
+/**
+ * Working-set = OPEN items (Phase 2; "this-session items + now-due snoozes" needs session
+ * tracking + clock = Phase-5 hook context). Without `apply`: return a suggested disposition
+ * per open item. With `apply`: every open item MUST have a disposition (forced drain — no ignore);
+ * execute them.
+ */
+export function runReconcile(repoRoot, opts) {
+    const inboxFile = loadInbox(resolveInboxPath(repoRoot));
+    const open = inboxFile.items.filter((i) => i.status === 'open');
+    // Inbox proposals (existing heuristic).
+    const proposals = open.map((item) => ({
+        class: 'inbox',
+        itemId: item.id,
+        text: item.text,
+        seenCount: item.seen_count ?? 1,
+        suggested: suggest(item, open),
+    }));
+    // Status + loop proposals (engine findings + un-captured-loop scan).
+    const file = loadThreadit(resolveThreaditPath(repoRoot));
+    const facts = buildCommitFacts(repoRoot, file);
+    const commits = gatherReconcileCommits(repoRoot, file, file.reconcile?.sha);
+    const { findings } = engine({ file, commitFacts: facts, inbox: inboxFile });
+    const { statusProposals, loopProposals } = deriveReconcile({ findings, commits });
+    if (!opts.apply) {
+        return { proposals: [...proposals, ...statusProposals, ...loopProposals] };
+    }
+    // opts.apply is set below this point.
+    const apply = opts.apply;
+    // Forced-drain check (BEFORE any write): open inbox items + loops + forced (stale-summary) status.
+    const forcedLoopShas = loopProposals.map((l) => l.sha);
+    const forcedStatusIds = statusProposals.filter((s) => s.forced).map((s) => s.nodeId);
+    const required = [...open.map((i) => i.id), ...forcedLoopShas, ...forcedStatusIds];
+    const missing = required.filter((key) => !(key in apply));
+    if (missing.length)
+        throw new Error(`forced disposition: ${missing.length} item(s) have no disposition: ${missing.join(', ')}`);
+    // Resolve promote default titles from the inbox BEFORE Pass 1 (Pass 1 writes threadit.yml before Pass 2 reads/writes the inbox).
+    const itemTextById = new Map(inboxFile.items.map((i) => [i.id, i.text]));
+    const head = firstParentChain(repoRoot)[0]?.sha;
+    // Pass 1: threadit.yml — node mutations + promote node-creation + watermark — ONE atomic mutate.
+    const createdIds = {};
+    mutate(resolveThreaditPath(repoRoot), (file) => {
+        for (const [key, d] of Object.entries(apply)) {
+            if (d.kind === 'downgrade')
+                applyUpdate(file, d.nodeId, { status: d.to });
+            else if (d.kind === 'resummarize')
+                applyUpdate(file, d.nodeId, { summary: d.summary, summaryAt: d.summaryAt });
+            else if (d.kind === 'accept')
+                applyAccept(file, d.nodeId, { kind: d.finding, target: d.target, until: d.until, text: d.text, ...(d.id ? { id: d.id } : {}), ...(d.at !== undefined ? { at: d.at } : {}) });
+            else if (d.kind === 'promote')
+                createdIds[key] = applyAddNode(file, d.title ?? itemTextById.get(key) ?? key, { ...(d.id ? { id: d.id } : {}), parent: d.under, status: d.status ?? 'planned' });
+        }
+        if (head !== undefined)
+            file.reconcile = { sha: head };
+    });
+    // Pass 2: threadit-inbox.yml — promote marks + merge/drop/snooze/capture — ONE atomic mutate.
+    mutateInbox(resolveInboxPath(repoRoot), (inbox) => {
+        for (const [key, d] of Object.entries(apply)) {
+            if (d.kind === 'promote')
+                applyPromoteMark(inbox, key, createdIds[key]);
+            else if (d.kind === 'merge')
+                applyMerge(inbox, key, d.into);
+            else if (d.kind === 'drop')
+                applyDrop(inbox, key);
+            else if (d.kind === 'snooze')
+                applySnooze(inbox, key, d.until);
+            else if (d.kind === 'capture')
+                applyCapture(inbox, d.text, {});
+            // 'dismiss': no-op — watermark advance (Pass 1) means it won't re-surface.
+        }
+    });
+    return { proposals: [] };
+}
+/** Heuristic suggestion: recurring (≥3) → promote; fuzzy sibling exists → merge; else drop. */
+function suggest(item, open) {
+    if ((item.seen_count ?? 1) >= 3)
+        return 'promote';
+    const others = open.filter((o) => o.id !== item.id);
+    if (matchOpenItem(others, item.text))
+        return 'merge';
+    return 'drop';
+}

package/dist/commands/serve.d.ts

@@ -0,0 +1,17 @@
+import { type ChildProcess } from 'node:child_process';
+export interface ServeOpts {
+    port?: number;
+    dbPath?: string;
+    serverEntry?: string;
+}
+/**
+ * Resolve the built SvelteKit adapter-node entry. The server package sits next to the cli package
+ * in the monorepo; its build output is packages/server/build/index.js. Overridable via opts for
+ * tests / non-standard layouts. The CLI does NOT import the server — it only spawns it (strict
+ * dep direction, index §1).
+ */
+export declare function resolveServerEntry(explicit?: string): string;
+/** Spawn the built server with PORT + THREADIT_DB_PATH in its env. Returns the child process. */
+export declare function startServer(opts?: ServeOpts): ChildProcess;
+/** CLI entry: start the server and keep the process alive until the child exits. */
+export declare function runServe(opts?: ServeOpts): ChildProcess;