threadit-cli 0.2.0

package/dist/commands/serve.js

@@ -0,0 +1,39 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * 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 function resolveServerEntry(explicit) {
+    if (explicit)
+        return resolve(explicit);
+    // From packages/cli/dist/commands/serve.js: 3 levels up (commands→dist→cli→packages) lands at
+    // packages/, then server/build/index.js → packages/server/build/index.js.
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, '../../../server/build/index.js');
+}
+/** Spawn the built server with PORT + THREADIT_DB_PATH in its env. Returns the child process. */
+export function startServer(opts = {}) {
+    const port = opts.port ?? 4317;
+    const dbPath = resolve(opts.dbPath ?? join('.threadit', 'server.sqlite'));
+    mkdirSync(dirname(dbPath), { recursive: true });
+    const entry = resolveServerEntry(opts.serverEntry);
+    if (!existsSync(entry)) {
+        throw new Error(`serve: built server not found at ${entry}. Run \`npm run build --workspace @threadit/server\` first.`);
+    }
+    return spawn(process.execPath, [entry], {
+        stdio: 'inherit',
+        env: { ...process.env, PORT: String(port), THREADIT_DB_PATH: dbPath },
+    });
+}
+/** CLI entry: start the server and keep the process alive until the child exits. */
+export function runServe(opts = {}) {
+    const child = startServer(opts);
+    child.on('error', (err) => { process.stderr.write(`serve: failed to start server: ${err.message}\n`); process.exit(1); });
+    child.on('exit', (code) => process.exit(code ?? 0));
+    return child;
+}

package/dist/commands/ship.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Flip a node to shipped. Courtesy check (warn, never block): set shipped in-memory,
+ * build CommitFacts from git, run the engine; if it raises `unbacked-shipped` for this
+ * node, warn — then save anyway (the two-tier model: ship is a convenience, not a gate;
+ * the server is the real backstop). Returns an optional warning string for the caller to print.
+ */
+export declare function runShip(repoRoot: string, id: string): {
+    warning?: string;
+};

package/dist/commands/ship.js

@@ -0,0 +1,28 @@
+import { engine } from '@threadit/core';
+import { resolveThreaditPath } from '../paths.js';
+import { loadThreadit, saveThreadit } from '../yaml/io.js';
+import { findNode } from '../mutate.js';
+import { buildCommitFacts } from '../git/commitFacts.js';
+/**
+ * Flip a node to shipped. Courtesy check (warn, never block): set shipped in-memory,
+ * build CommitFacts from git, run the engine; if it raises `unbacked-shipped` for this
+ * node, warn — then save anyway (the two-tier model: ship is a convenience, not a gate;
+ * the server is the real backstop). Returns an optional warning string for the caller to print.
+ */
+export function runShip(repoRoot, id) {
+    const path = resolveThreaditPath(repoRoot);
+    const file = loadThreadit(path);
+    const node = findNode(file, id);
+    node.status = 'shipped';
+    const facts = buildCommitFacts(repoRoot, file);
+    const result = engine({ file, commitFacts: facts });
+    const unbacked = result.findings.find((f) => f.kind === 'unbacked-shipped' && f.target === id);
+    saveThreadit(path, file);
+    if (unbacked) {
+        return {
+            warning: `ship: "${id}" has no qualifying backing commit yet — flipped to shipped anyway. ` +
+                `It will surface as an unbacked-shipped finding until a Threadit:${id}-trailered code commit lands.`,
+        };
+    }
+    return {};
+}

package/dist/commands/show.d.ts

@@ -0,0 +1,2 @@
+import type { ValidatedNode } from '@threadit/core';
+export declare function runShow(repoRoot: string, id: string): ValidatedNode;

package/dist/commands/show.js

@@ -0,0 +1,16 @@
+import { engine } from '@threadit/core';
+import { resolveThreaditPath } from '../paths.js';
+import { loadThreadit } from '../yaml/io.js';
+import { buildCommitFacts } from '../git/commitFacts.js';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export function runShow(repoRoot, id) {
+    const file = loadThreadit(resolveThreaditPath(repoRoot));
+    // CommitFacts only if this is a git repo; otherwise derive without them.
+    const facts = existsSync(join(repoRoot, '.git')) ? buildCommitFacts(repoRoot, file) : undefined;
+    const { graph } = engine({ file, ...(facts ? { commitFacts: facts } : {}) });
+    const node = graph.nodes.find((n) => n.id === id);
+    if (!node)
+        throw new Error(`No node with id "${id}" in threadit.yml`);
+    return node;
+}

package/dist/commands/snooze.d.ts

@@ -0,0 +1,5 @@
+import type { ParsedInboxFile, UntilPredicate } from '@threadit/core';
+/** Pure core: snooze an inbox item with a wake trigger. */
+export declare function applySnooze(inbox: ParsedInboxFile, itemId: string, until: UntilPredicate): void;
+/** Snooze MUST carry a wake trigger (no park-forever). */
+export declare function runSnooze(repoRoot: string, itemId: string, until: UntilPredicate): void;

package/dist/commands/snooze.js

@@ -0,0 +1,16 @@
+import { resolveInboxPath } from '../paths.js';
+import { mutateInbox } from '../mutate.js';
+/** Pure core: snooze an inbox item with a wake trigger. */
+export function applySnooze(inbox, itemId, until) {
+    if (!until || Object.keys(until).length === 0)
+        throw new Error('snooze requires an --until wake trigger');
+    const item = inbox.items.find((i) => i.id === itemId);
+    if (!item)
+        throw new Error(`No inbox item "${itemId}"`);
+    item.status = 'snoozed';
+    item.snooze_until = until;
+}
+/** Snooze MUST carry a wake trigger (no park-forever). */
+export function runSnooze(repoRoot, itemId, until) {
+    mutateInbox(resolveInboxPath(repoRoot), (inbox) => applySnooze(inbox, itemId, until));
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,14 @@
+import type { Finding, NodeId, ReadingListEntry } from '@threadit/core';
+export interface StatusReport {
+    head: string | null;
+    lastSha: string | undefined;
+    unsynced: boolean;
+    currentSession: number;
+    wrappedThrough: number | undefined;
+    priorSessionUnwrapped: boolean;
+    workingSlice: NodeId[];
+    findings: Finding[];
+    readingList: ReadingListEntry[];
+}
+export declare function runStatus(repoRoot: string): StatusReport;
+export declare function formatReadingList(entries: ReadingListEntry[]): string[];

package/dist/commands/status.js

@@ -0,0 +1,47 @@
+import { engine, computeWorkingSlice, deriveReadingList } from '@threadit/core';
+import { resolveThreaditPath, resolveInboxPath } from '../paths.js';
+import { loadThreadit, loadInbox } from '../yaml/io.js';
+import { buildCommitFacts } from '../git/commitFacts.js';
+import { readConfig } from '../config.js';
+import { firstParentChain } from '../git/log.js';
+import { existsSync } from 'node:fs';
+export function runStatus(repoRoot) {
+    const file = loadThreadit(resolveThreaditPath(repoRoot));
+    const inboxPath = resolveInboxPath(repoRoot);
+    const inbox = existsSync(inboxPath) ? loadInbox(inboxPath) : undefined;
+    const facts = buildCommitFacts(repoRoot, file);
+    const result = engine({ file, commitFacts: facts, ...(inbox ? { inbox } : {}) });
+    const slice = computeWorkingSlice(result.graph);
+    const chain = firstParentChain(repoRoot);
+    const head = chain[0]?.sha ?? null;
+    const cfg = readConfig(repoRoot);
+    const unsynced = head !== null && head !== cfg.lastSha;
+    const currentSession = cfg.session ?? 0;
+    const wrappedThrough = file.wrapup?.session;
+    // `> 0` guards the degenerate case: `readSession` returns 0 pre-bump, so a `wrapup` stamped before
+    // any SessionStart records session 0 — "set but not meaningfully wrapped" → don't warn.
+    const priorSessionUnwrapped = wrappedThrough !== undefined && wrappedThrough > 0 && wrappedThrough < currentSession - 1;
+    return {
+        head,
+        lastSha: cfg.lastSha,
+        unsynced,
+        currentSession,
+        wrappedThrough,
+        priorSessionUnwrapped,
+        workingSlice: [...slice],
+        findings: result.findings,
+        readingList: deriveReadingList(result.graph),
+    };
+}
+export function formatReadingList(entries) {
+    if (entries.length === 0)
+        return ['READ NEXT: none'];
+    const lines = ['READ NEXT:'];
+    for (const e of entries) {
+        lines.push('');
+        lines.push(`${e.nodeId} [${e.status}${e.relevance === 'context' ? ' · context' : ''}]`);
+        for (const d of e.docs)
+            lines.push(`  ${d.role.padEnd(9)} ${d.ref}`);
+    }
+    return lines;
+}

package/dist/commands/supersede.d.ts

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

package/dist/commands/supersede.js

@@ -0,0 +1,9 @@
+import { resolveThreaditPath } from '../paths.js';
+import { mutate, findNode } from '../mutate.js';
+export function runSupersede(repoRoot, id, by) {
+    mutate(resolveThreaditPath(repoRoot), (file) => {
+        const node = findNode(file, id);
+        node.status = 'superseded';
+        node.superseded_by = by;
+    });
+}

package/dist/commands/sync.d.ts

@@ -0,0 +1,16 @@
+import { type SyncDeps } from '../transport/sync.js';
+export interface SyncOpts {
+    draft?: boolean;
+    sessionKey?: string;
+}
+export interface DriftAdvisory {
+    kind: 'client-older' | 'server-older';
+    clientV: string;
+    serverV: string;
+}
+export declare function driftAdvisory(clientV: string, serverV: string): DriftAdvisory | null;
+/** Push committed history (or the uncommitted draft) to the server. Transport is injected for tests. */
+export declare function runSync(repoRoot: string, opts: SyncOpts, deps?: SyncDeps): Promise<void>;
+/** Best-effort post of the current on-disk inbox (current-state, not per-commit). Exported so the
+ *  postAction inbox-push and runSync share one definition. */
+export declare function pushInbox(repoRoot: string, projectId: string, server: string, token: string, deps: SyncDeps): Promise<void>;

package/dist/commands/sync.js

@@ -0,0 +1,66 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolveThreaditPath, resolveInboxPath, THREADIT_FILE } from '../paths.js';
+import { readConfig, updateConfig } from '../config.js';
+import { firstParentChain, fileBlobAt, trailersFor, touchedPaths, isAncestor } from '../git/log.js';
+import { buildRevisionPayloads, postIngest, postDraft, postInbox, postManifest } from '../transport/sync.js';
+import { PACK_VERSION, isOlder, isDevVersion } from '../version.js';
+export function driftAdvisory(clientV, serverV) {
+    if (isDevVersion(clientV) || isDevVersion(serverV) || clientV === serverV)
+        return null;
+    return isOlder(clientV, serverV) ? { kind: 'client-older', clientV, serverV } : { kind: 'server-older', clientV, serverV };
+}
+/** Push committed history (or the uncommitted draft) to the server. Transport is injected for tests. */
+export async function runSync(repoRoot, opts, deps = { fetch: globalThis.fetch }) {
+    const cfg = readConfig(repoRoot);
+    if (!cfg.server || !cfg.ingestToken)
+        throw new Error('sync: config missing server/ingestToken (run threadit init + set them)');
+    if (opts.draft) {
+        const fileBlob = readFileSync(resolveThreaditPath(repoRoot), 'utf8');
+        await postDraft(cfg.server, cfg.ingestToken, {
+            projectId: cfg.projectId,
+            sessionKey: opts.sessionKey ?? 'local',
+            fileBlob,
+        }, deps);
+        return; // draft never advances the cursor
+    }
+    // Detect a history REWRITE: the server's last-synced sha is no longer an ancestor of HEAD
+    // (rebase / amend / force-push moved or dropped it). On a rewrite we purge orphans server-side
+    // (via the manifest) and re-backfill the WHOLE chain; idempotent ingest makes surviving shas no-ops.
+    const rewrite = cfg.lastSha !== undefined && !isAncestor(repoRoot, cfg.lastSha, 'HEAD');
+    // On a rewrite, walk the full chain (sinceSha = undefined). Otherwise, incremental since lastSha.
+    const sinceSha = rewrite ? undefined : cfg.lastSha;
+    const chain = firstParentChain(repoRoot, sinceSha);
+    if (rewrite) {
+        // FIRST tell the server the full current sha set so it purges anything no longer reachable,
+        // THEN re-ingest. Order matters: purge-before-reingest, so an orphaned sha can't survive.
+        const fullChain = firstParentChain(repoRoot, undefined);
+        await postManifest(cfg.server, cfg.ingestToken, { projectId: cfg.projectId, shas: fullChain.map((c) => c.sha) }, deps);
+    }
+    if (chain.length === 0) {
+        // No new commits — still sync the inbox if present (its content may have changed).
+        await pushInbox(repoRoot, cfg.projectId, cfg.server, cfg.ingestToken, deps);
+        return;
+    }
+    const payloads = buildRevisionPayloads(cfg.projectId, chain, (sha) => fileBlobAt(repoRoot, sha, THREADIT_FILE), (sha) => trailersFor(repoRoot, sha), (sha) => touchedPaths(repoRoot, sha));
+    let lastInfo;
+    for (const p of payloads)
+        lastInfo = await postIngest(cfg.server, cfg.ingestToken, p, deps);
+    await pushInbox(repoRoot, cfg.projectId, cfg.server, cfg.ingestToken, deps);
+    const newest = chain[0].sha;
+    updateConfig(repoRoot, { lastSha: newest });
+    if (lastInfo) {
+        const adv = driftAdvisory(PACK_VERSION, lastInfo.serverVersion);
+        if (adv)
+            process.stderr.write(`threadit: ${adv.kind === 'client-older'
+                ? `server is newer (${adv.serverV} > ${adv.clientV}) — update the client`
+                : `server is older (${adv.serverV} < ${adv.clientV}) — consider updating the server`}\n`);
+    }
+}
+/** Best-effort post of the current on-disk inbox (current-state, not per-commit). Exported so the
+ *  postAction inbox-push and runSync share one definition. */
+export async function pushInbox(repoRoot, projectId, server, token, deps) {
+    const inboxPath = resolveInboxPath(repoRoot);
+    if (!existsSync(inboxPath))
+        return;
+    await postInbox(server, token, { projectId, fileBlob: readFileSync(inboxPath, 'utf8') }, deps);
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,13 @@
+import type { ParsedThreaditFile, Status, Flow } from '@threadit/core';
+export interface UpdateOpts {
+    status?: Status;
+    title?: string;
+    summary?: string;
+    summaryAt?: string;
+    detail?: string;
+    flow?: Flow;
+    milestone?: boolean;
+}
+/** Pure core: mutate a parsed threadit file in-place. */
+export declare function applyUpdate(file: ParsedThreaditFile, id: string, opts: UpdateOpts): void;
+export declare function runUpdate(repoRoot: string, id: string, opts: UpdateOpts): void;

package/dist/commands/update.js

@@ -0,0 +1,23 @@
+import { resolveThreaditPath } from '../paths.js';
+import { mutate, findNode } from '../mutate.js';
+/** Pure core: mutate a parsed threadit file in-place. */
+export function applyUpdate(file, id, opts) {
+    const node = findNode(file, id);
+    if (opts.status !== undefined)
+        node.status = opts.status;
+    if (opts.title !== undefined)
+        node.title = opts.title;
+    if (opts.summary !== undefined)
+        node.summary = opts.summary;
+    if (opts.summaryAt !== undefined)
+        node.summary_at = opts.summaryAt;
+    if (opts.detail !== undefined)
+        node.detail = opts.detail;
+    if (opts.flow !== undefined)
+        node.flow = opts.flow;
+    if (opts.milestone !== undefined)
+        node.milestone = opts.milestone;
+}
+export function runUpdate(repoRoot, id, opts) {
+    mutate(resolveThreaditPath(repoRoot), (file) => applyUpdate(file, id, opts));
+}

package/dist/commands/validate.d.ts

@@ -0,0 +1,18 @@
+export interface ValidateResult {
+    code: number;
+    output: string;
+}
+/**
+ * Run structural validation on the file at `filePath`.
+ * Returns { code, output } without printing — bin.ts prints + exits.
+ *
+ * Exit codes:
+ *   0 — file is structurally valid
+ *   1 — structural errors found (dangling edge, cycle, etc.) OR parse failure
+ *   2 — IO error (file cannot be read) or usage error (wrong args)
+ */
+export declare function runValidate(filePath: string): Promise<ValidateResult>;
+/** Command wrapper: resolves the threadit.yml path from global opts, then runs validation. */
+export declare function runValidateCommand(globalOpts: {
+    repo?: string;
+}, explicitPath?: string): Promise<ValidateResult>;

package/dist/commands/validate.js

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs';
+import { engine, parseThreaditFile, ThreaditParseError } from '@threadit/core';
+import { resolveThreaditPath } from '../paths.js';
+/**
+ * Run structural validation on the file at `filePath`.
+ * Returns { code, output } without printing — bin.ts prints + exits.
+ *
+ * Exit codes:
+ *   0 — file is structurally valid
+ *   1 — structural errors found (dangling edge, cycle, etc.) OR parse failure
+ *   2 — IO error (file cannot be read) or usage error (wrong args)
+ */
+export async function runValidate(filePath) {
+    // --- 1. Read file from disk ---
+    let text;
+    try {
+        text = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { code: 2, output: `Cannot read file "${filePath}": ${msg}` };
+    }
+    // --- 2. Parse YAML + schema ---
+    let file;
+    try {
+        file = parseThreaditFile(text);
+    }
+    catch (err) {
+        if (err instanceof ThreaditParseError) {
+            return { code: 1, output: `Parse error in "${filePath}": ${err.message}` };
+        }
+        // unexpected error — treat as IO/usage
+        const msg = err instanceof Error ? err.message : String(err);
+        return { code: 2, output: `Unexpected error parsing "${filePath}": ${msg}` };
+    }
+    // --- 3. Run engine (structural validation only; no commitFacts in Phase 1) ---
+    const result = engine({ file });
+    if (result.structuralErrors.length === 0) {
+        return {
+            code: 0,
+            output: `OK: "${filePath}" is structurally valid (${result.graph.nodes.length} nodes)`,
+        };
+    }
+    // Format one line per structural error: "<kind> at <at>: <message>"
+    const lines = result.structuralErrors.map((e) => `${e.kind} at ${e.at}: ${e.message}`);
+    return { code: 1, output: lines.join('\n') };
+}
+/** Command wrapper: resolves the threadit.yml path from global opts, then runs validation. */
+export async function runValidateCommand(globalOpts, explicitPath) {
+    const path = explicitPath ?? resolveThreaditPath(globalOpts.repo);
+    return runValidate(path);
+}

package/dist/commands/wrapup.d.ts

@@ -0,0 +1,3 @@
+/** Stamp the wrap-up watermark = the current session counter. Purely mechanical
+ *  (the first stub of Threadit subsuming the wrap-up skill). Returns the stamped session. */
+export declare function runWrapup(repoRoot: string): number;

package/dist/commands/wrapup.js

@@ -0,0 +1,10 @@
+import { resolveThreaditPath } from '../paths.js';
+import { mutate } from '../mutate.js';
+import { readSession } from '../session.js';
+/** Stamp the wrap-up watermark = the current session counter. Purely mechanical
+ *  (the first stub of Threadit subsuming the wrap-up skill). Returns the stamped session. */
+export function runWrapup(repoRoot) {
+    const session = readSession(repoRoot);
+    mutate(resolveThreaditPath(repoRoot), (file) => { file.wrapup = { session }; });
+    return session;
+}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export interface ThreaditConfig {
+    projectId: string;
+    server?: string;
+    ingestToken?: string;
+    lastSha?: string;
+    session?: number;
+    packVersion?: string;
+}
+export declare function readConfig(repoRoot: string): ThreaditConfig;
+export declare function writeConfig(repoRoot: string, cfg: ThreaditConfig): void;
+export declare function updateConfig(repoRoot: string, patch: Partial<ThreaditConfig>): ThreaditConfig;

package/dist/config.js

@@ -0,0 +1,20 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+function configPath(repoRoot) {
+    return join(repoRoot, '.threadit', 'config.json');
+}
+export function readConfig(repoRoot) {
+    const p = configPath(repoRoot);
+    if (!existsSync(p))
+        return { projectId: '' };
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+export function writeConfig(repoRoot, cfg) {
+    mkdirSync(join(repoRoot, '.threadit'), { recursive: true });
+    writeFileSync(configPath(repoRoot), JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+}
+export function updateConfig(repoRoot, patch) {
+    const merged = { ...readConfig(repoRoot), ...patch };
+    writeConfig(repoRoot, merged);
+    return merged;
+}

package/dist/draft.d.ts

@@ -0,0 +1,29 @@
+import { type SyncOpts } from './commands/sync.js';
+/** The working file is an in-flight draft worth streaming iff it exists AND differs from committed HEAD. */
+export declare function draftDiverged(workingBlob: string | null, headBlob: string | null): boolean;
+/** Which commands get a post-action draft push. `sync` already pushes; `serve` is long-running.
+ *  Everything else relies on the divergence gate (read commands simply never diverge). */
+export declare function shouldPushAfter(commandName: string): boolean;
+export interface DraftPushDeps {
+    readWorking: () => string | null;
+    readHead: () => string | null;
+    readSession: () => number;
+    serverConfigured: () => boolean;
+    sync: (repoRoot: string, opts: SyncOpts) => Promise<void>;
+}
+export declare function defaultDraftPushDeps(repoRoot: string): DraftPushDeps;
+/** Best-effort: push the working file as a session-keyed draft overlay iff it diverged from HEAD
+ *  and a server is configured. Returns whether it pushed. Caller owns error swallowing. */
+export declare function maybePushDraft(repoRoot: string, deps: DraftPushDeps): Promise<{
+    pushed: boolean;
+}>;
+export declare function shouldPushInboxAfter(commandName: string): boolean;
+export interface InboxPushDeps {
+    serverConfigured: () => boolean;
+    push: (repoRoot: string) => Promise<void>;
+}
+export declare function defaultInboxPushDeps(repoRoot: string): InboxPushDeps;
+/** Best-effort: push the current inbox iff a server is configured. Caller owns error swallowing. */
+export declare function maybePushInbox(repoRoot: string, deps: InboxPushDeps): Promise<{
+    pushed: boolean;
+}>;

package/dist/draft.js

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import { resolveThreaditPath, THREADIT_FILE } from './paths.js';
+import { fileBlobAt } from './git/log.js';
+import { readConfig } from './config.js';
+import { readSession } from './session.js';
+import { runSync, pushInbox } from './commands/sync.js';
+/** The working file is an in-flight draft worth streaming iff it exists AND differs from committed HEAD. */
+export function draftDiverged(workingBlob, headBlob) {
+    return workingBlob !== null && workingBlob !== headBlob;
+}
+/** Which commands get a post-action draft push. `sync` already pushes; `serve` is long-running.
+ *  Everything else relies on the divergence gate (read commands simply never diverge). */
+export function shouldPushAfter(commandName) {
+    return commandName !== 'sync' && commandName !== 'serve';
+}
+export function defaultDraftPushDeps(repoRoot) {
+    return {
+        readWorking: () => { try {
+            return readFileSync(resolveThreaditPath(repoRoot), 'utf8');
+        }
+        catch {
+            return null;
+        } },
+        readHead: () => fileBlobAt(repoRoot, 'HEAD', THREADIT_FILE),
+        readSession: () => readSession(repoRoot),
+        serverConfigured: () => { const c = readConfig(repoRoot); return !!c.server && !!c.ingestToken; },
+        sync: runSync,
+    };
+}
+/** Best-effort: push the working file as a session-keyed draft overlay iff it diverged from HEAD
+ *  and a server is configured. Returns whether it pushed. Caller owns error swallowing. */
+export async function maybePushDraft(repoRoot, deps) {
+    if (!deps.serverConfigured())
+        return { pushed: false };
+    if (!draftDiverged(deps.readWorking(), deps.readHead()))
+        return { pushed: false };
+    await deps.sync(repoRoot, { draft: true, sessionKey: `s${deps.readSession()}` });
+    return { pushed: true };
+}
+/** Which commands mutate the inbox file and so warrant a post-action inbox push.
+ *  These five are the inbox-mutating verbs; everything else leaves the inbox untouched. */
+const INBOX_VERBS = new Set(['capture', 'promote', 'merge', 'drop', 'snooze', 'reconcile']);
+export function shouldPushInboxAfter(commandName) { return INBOX_VERBS.has(commandName); }
+export function defaultInboxPushDeps(repoRoot) {
+    return {
+        serverConfigured: () => { const c = readConfig(repoRoot); return !!c.server && !!c.ingestToken; },
+        push: async (root) => {
+            const c = readConfig(root);
+            await pushInbox(root, c.projectId, c.server, c.ingestToken, { fetch: globalThis.fetch });
+        },
+    };
+}
+/** Best-effort: push the current inbox iff a server is configured. Caller owns error swallowing. */
+export async function maybePushInbox(repoRoot, deps) {
+    if (!deps.serverConfigured())
+        return { pushed: false };
+    await deps.push(repoRoot);
+    return { pushed: true };
+}

package/dist/git/commitFacts.d.ts

@@ -0,0 +1,6 @@
+import type { ParsedThreaditFile, CommitFacts } from '@threadit/core';
+/**
+ * Build the CommitFacts struct from live git. Same shape the Phase-3 server
+ * builds from stored commit rows — the engine computes identical findings either way.
+ */
+export declare function buildCommitFacts(repoDir: string, file: ParsedThreaditFile, sinceSha?: string): CommitFacts;

package/dist/git/commitFacts.js

@@ -0,0 +1,56 @@
+import picomatch from 'picomatch';
+import { firstParentChain, trailerCommits, touchedPaths } from './log.js';
+import { isOwnedPath } from '../paths.js';
+/**
+ * Build the CommitFacts struct from live git. Same shape the Phase-3 server
+ * builds from stored commit rows — the engine computes identical findings either way.
+ */
+export function buildCommitFacts(repoDir, file, sinceSha) {
+    const chain = firstParentChain(repoDir, sinceSha);
+    const nodeById = new Map(file.nodes.map((n) => [n.id, n]));
+    const trailerCommitsByNode = {};
+    // Single pass over trailered commits — reused for both trailerCommitsByNode and trailersBySha below.
+    const allTrailerCommits = trailerCommits(repoDir, sinceSha);
+    const trailersBySha = new Map(allTrailerCommits.map((tc) => [tc.sha, tc.trailers]));
+    for (const tc of allTrailerCommits) {
+        const paths = touchedPaths(repoDir, tc.sha);
+        const touchesCodePath = paths.some((p) => !isOwnedPath(p, file));
+        for (const nodeId of tc.trailers) {
+            const node = nodeById.get(nodeId);
+            const globs = node?.paths;
+            const touchesNodePaths = globs !== undefined && globs.length > 0
+                ? paths.some((p) => globs.some((g) => picomatch.isMatch(p, g.startsWith('./') ? g.slice(2) : g)))
+                : false;
+            (trailerCommitsByNode[nodeId] ??= []).push({
+                sha: tc.sha,
+                authorDate: tc.authorDate,
+                touchesCodePath,
+                touchesNodePaths,
+            });
+        }
+    }
+    // nodeLatestWorkSha: newest first-parent commit that carries the node's trailer OR touches its paths.
+    // Iterate chain newest-first; first match per node wins. Mirrors server's buildServerCommitFacts exactly.
+    const nodeLatestWorkSha = {};
+    for (const commit of chain) {
+        const commitTrailers = trailersBySha.get(commit.sha) ?? [];
+        // Lazily compute touched paths only when a node with globs still needs evaluation.
+        let paths;
+        const getPaths = () => { paths ??= touchedPaths(repoDir, commit.sha); return paths; };
+        for (const node of file.nodes) {
+            if (nodeLatestWorkSha[node.id] !== undefined)
+                continue;
+            const byTrailer = commitTrailers.includes(node.id);
+            const globs = node.paths ?? [];
+            const byPath = globs.length > 0 && getPaths().some((p) => globs.some((g) => picomatch.isMatch(p, g.startsWith('./') ? g.slice(2) : g)));
+            if (byTrailer || byPath)
+                nodeLatestWorkSha[node.id] = commit.sha;
+        }
+    }
+    return {
+        trailerCommits: trailerCommitsByNode,
+        firstParentChain: chain.map((c) => ({ sha: c.sha, authorDate: c.authorDate, parent: c.parent })),
+        knownShas: chain.map((c) => c.sha),
+        ...(Object.keys(nodeLatestWorkSha).length > 0 ? { nodeLatestWorkSha } : {}),
+    };
+}

package/dist/git/log.d.ts

@@ -0,0 +1,41 @@
+export interface ChainEntry {
+    sha: string;
+    authorDate: string;
+    parent: string | null;
+}
+/** main's first-parent chain, newest-first. `sinceSha` (exclusive) bounds the bottom. */
+export declare function firstParentChain(repoDir: string, sinceSha?: string): ChainEntry[];
+/** File content at a revision, or null if the file did not exist there. */
+export declare function fileBlobAt(repoDir: string, sha: string, relPath: string): string | null;
+export interface TrailerCommit {
+    sha: string;
+    authorDate: string;
+    trailers: string[];
+}
+/**
+ * All commits on main's first-parent chain that carry ≥1 `Threadit: <id>` trailer.
+ * Uses git's trailer formatting (exact values, no regex fragility).
+ */
+export declare function trailerCommits(repoDir: string, sinceSha?: string): TrailerCommit[];
+/**
+ * The `Threadit: <id>` trailer values on ONE commit (by sha). Mirrors trailerCommits' git-trailer
+ * formatter (no regex). Returns [] when the commit carries none.
+ */
+export declare function trailersFor(repoDir: string, sha: string): string[];
+/**
+ * True iff `maybeAncestor` is an ancestor of `descendant` on the current history. Uses
+ * `git merge-base --is-ancestor` (exit 0 = ancestor, exit 1 = NOT ancestor). `descendant` is always
+ * a valid ref here ('HEAD'), so a 128 means `maybeAncestor` itself is unresolvable — the stored sha
+ * was rewritten away AND pruned/gc'd (or this is a fresh clone). That is itself a divergence signal,
+ * so we treat 1 AND 128 as "not an ancestor" rather than crashing sync (the resulting full re-sync is
+ * idempotent — safe to over-trigger). A spawn failure (no numeric status) or any other code rethrows,
+ * mirroring the gitProcessExited discipline (distinguish a clean answer from a real error).
+ *
+ * Used by `sync` to detect a history REWRITE: if the server's last-synced sha is NO LONGER an
+ * ancestor of HEAD, the chain was rebased/amended/force-pushed and the server must purge + re-ingest.
+ */
+export declare function isAncestor(repoDir: string, maybeAncestor: string, descendant: string): boolean;
+/** sha → subject line for main's first-parent chain. `sinceSha` (exclusive) bounds the bottom. */
+export declare function firstParentSubjects(repoDir: string, sinceSha?: string): Map<string, string>;
+/** Paths a single commit touched (root commit handled via --root; -z = NUL-terminated, quoting-safe). */
+export declare function touchedPaths(repoDir: string, sha: string): string[];