@indigoai-us/hq-cli 5.108.1 → 5.108.2

package/dist/lib/mesh/live/daemon/run.js

@@ -0,0 +1,400 @@
+/**
+ * hq mesh daemon run — single-instance resident process.
+ *
+ * - pid lock at ~/.hq/work-mesh/daemon/pid
+ * - fs.watch spool + 2s debounce; flush at least every 10s (US-008 path)
+ * - replay context outbox
+ * - board.md refresh for bound sessions ≤ every 60s
+ * - MQTT presence (contract-3)
+ * - SIGTERM/SIGINT: flush once more, MQTT DISCONNECT (server derives offline), exit
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createWorkSessionDeliverer } from "../../client.js";
+import { meshJson, resolveActiveMembershipCompany } from "../../api.js";
+import { ensureCognitoToken } from "../../../../utils/cognito-session.js";
+import { replayOutbox } from "../../../work-context/outbox.js";
+import { workContextRoot } from "../../../work-context/paths.js";
+import { createSessionEventsPoster, resolveVaultApiBase, } from "../session-events-client.js";
+import { flushSessionEvents } from "../flush.js";
+import { workMeshRoot, workMeshSpoolPath } from "../paths.js";
+import { createVaultBoardReader, refreshBoundSessionBoards, BOARD_REFRESH_INTERVAL_MS, } from "./board-refresh.js";
+import { createContract3Fetcher, realTimerHost, } from "./credentials.js";
+import { appendDaemonLog, daemonLogLine, ensureDaemonLog } from "./log.js";
+import { acquirePidLock, defaultPidLockDeps, releasePidLock, } from "./pid-lock.js";
+import { daemonDir } from "./paths.js";
+import { PresenceClient, } from "./presence.js";
+import { defaultDaemonState, patchDaemonState, writeDaemonState, } from "./state.js";
+import { workMeshHeldPath } from "../paths.js";
+import { noteHookSessionsFromSpoolFile, TRANSCRIPT_WATCH_INTERVAL_MS, TranscriptWatcher, } from "./transcript-watch.js";
+export const SPOOL_DEBOUNCE_MS = 2_000;
+export const FLUSH_INTERVAL_MS = 10_000;
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Start the daemon. Resolves once the process is running (lock held, loops armed).
+ * Call handle.stop() or send SIGTERM for graceful shutdown.
+ */
+export async function runMeshDaemon(deps = {}) {
+    const home = deps.home ?? os.homedir();
+    const env = deps.env ?? process.env;
+    const meshRoot = deps.meshRoot ?? workMeshRoot(home, env);
+    const ctxRoot = deps.workContextRoot ?? workContextRoot(home, env);
+    const dir = daemonDir(meshRoot, home, env);
+    const timers = deps.timers ?? realTimerHost;
+    const now = deps.now ?? (() => new Date());
+    const log = deps.log ??
+        ((d, line) => appendDaemonLog(d, daemonLogLine("info", line, now)));
+    const processEvents = deps.processEvents ?? process;
+    const exit = deps.exit ?? ((code) => process.exit(code));
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    ensureDaemonLog(dir);
+    const lockDeps = deps.pidLock ?? defaultPidLockDeps({ isProcessAlive: alive });
+    const lock = acquirePidLock(dir, lockDeps);
+    if (!lock.ok) {
+        throw new Error(`daemon already running (pid ${lock.owner.pid}); refuse second instance`);
+    }
+    writeDaemonState(dir, defaultDaemonState(lockDeps.pid, now));
+    log(dir, `daemon started pid=${lockDeps.pid}`);
+    let token;
+    // Opt into machine-credential minting when the box has creds (systemd exports
+    // HQ_MACHINE_CREDS_FILE). On a person laptop with no machine creds this falls
+    // through to the person login cache inside ensureCognitoToken.
+    const defaultGetToken = async () => ensureCognitoToken({ interactive: false, tokenSource: "machine" });
+    const getToken = deps.getToken ??
+        (async () => {
+            if (!token)
+                token = await defaultGetToken();
+            return token;
+        });
+    const flushFn = deps.flush ??
+        (async () => {
+            const t = await getToken();
+            const poster = createSessionEventsPoster({
+                token: t,
+                baseUrl: resolveVaultApiBase(env),
+            });
+            return flushSessionEvents({
+                workMeshRoot: meshRoot,
+                workContextRoot: ctxRoot,
+                poster,
+            });
+        });
+    const replayFn = deps.replayOutbox ??
+        (async () => {
+            const t = await getToken();
+            const deliver = createWorkSessionDeliverer({ token: t });
+            return replayOutbox(ctxRoot, deliver);
+        });
+    const boardLast = new Map();
+    const refreshFn = deps.refreshBoards ??
+        (async () => {
+            const t = await getToken();
+            const reader = createVaultBoardReader({
+                getJson: (p) => meshJson(t, p),
+            });
+            return refreshBoundSessionBoards({
+                workContextRoot: ctxRoot,
+                readBoard: reader,
+                lastRefresh: boardLast,
+                intervalMs: BOARD_REFRESH_INTERVAL_MS,
+                now: () => timers.now(),
+            });
+        });
+    let presence = null;
+    if (deps.enablePresence !== false) {
+        const fetchCredentials = deps.fetchCredentials ??
+            (async () => {
+                const t = await getToken();
+                return createContract3Fetcher({
+                    token: t,
+                    baseUrl: resolveVaultApiBase(env),
+                    env,
+                })();
+            });
+        const presenceOpts = {
+            fetchCredentials,
+            mqttConnect: deps.mqttConnect,
+            timers,
+            random: deps.random,
+            now,
+            onState: (state) => {
+                patchDaemonState(dir, { mqttState: state }, now);
+            },
+            onOnline: (companies) => {
+                patchDaemonState(dir, {
+                    mqttState: "connected",
+                    companiesOnline: companies,
+                    actorUid: presence?.getBundle()?.actorUid,
+                }, now);
+                log(dir, `presence online companies=${companies.length}`);
+            },
+            onError: (err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                patchDaemonState(dir, { lastErrorCode: msg.slice(0, 120) }, now);
+                log(dir, `presence error: ${msg.slice(0, 200)}`);
+            },
+        };
+        presence = new PresenceClient(presenceOpts);
+        try {
+            await presence.start();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log(dir, `presence start failed: ${msg.slice(0, 200)}`);
+            // Continue draining spool even if MQTT is down.
+        }
+    }
+    let stopped = false;
+    let flushInFlight = null;
+    let debounceHandle = null;
+    let flushIntervalHandle = null;
+    let boardIntervalHandle = null;
+    let transcriptIntervalHandle = null;
+    let watcher = null;
+    /** Shared with transcript watcher: sessionIds seen on the hook/spool path. */
+    const lastHookEventAt = new Map();
+    let transcriptWatcher = null;
+    if (deps.enableTranscriptWatch !== false) {
+        const hqRoot = deps.hqRoot ?? env.HQ_ROOT?.trim() ?? undefined;
+        const getToken = deps.getToken ?? defaultGetToken;
+        transcriptWatcher = new TranscriptWatcher({
+            home,
+            env,
+            workContextRoot: ctxRoot,
+            workMeshRoot: meshRoot,
+            hqRoot: hqRoot || undefined,
+            fs: deps.transcriptFs,
+            now: () => now().getTime(),
+            lastHookEventAt,
+            validateMembership: async (slug) => {
+                try {
+                    const token = await getToken();
+                    const membership = await resolveActiveMembershipCompany(token, slug);
+                    if (!membership)
+                        return false;
+                    return { uid: membership.companyUid };
+                }
+                catch {
+                    return false;
+                }
+            },
+            deliver: async (op) => {
+                try {
+                    const token = await getToken();
+                    return createWorkSessionDeliverer({ token })(op);
+                }
+                catch (err) {
+                    return {
+                        ok: false,
+                        retryable: true,
+                        code: err instanceof Error ? err.message : "DELIVER_FAILED",
+                    };
+                }
+            },
+        });
+    }
+    const doFlushCycle = async (reason, opts = {}) => {
+        // Refuse new cycles after stop, except the forced shutdown flush.
+        if (stopped && !opts.force)
+            return;
+        if (flushInFlight) {
+            await flushInFlight;
+            if (stopped && !opts.force)
+                return;
+        }
+        flushInFlight = (async () => {
+            try {
+                // Record hook-emitted session ids from spool/held before claim/rename.
+                const at = now().getTime();
+                noteHookSessionsFromSpoolFile(workMeshSpoolPath(meshRoot), lastHookEventAt, at);
+                noteHookSessionsFromSpoolFile(workMeshHeldPath(meshRoot), lastHookEventAt, at);
+                const summary = await flushFn();
+                try {
+                    await replayFn();
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    log(dir, `outbox replay error: ${msg.slice(0, 200)}`);
+                }
+                patchDaemonState(dir, {
+                    lastFlushAt: now().toISOString(),
+                    lastFlushResult: { ...summary, ok: true },
+                }, now);
+                if (summary.claimed > 0 || summary.posted > 0 || summary.held > 0) {
+                    log(dir, `flush(${reason}): claimed=${summary.claimed} posted=${summary.posted} held=${summary.held}`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                patchDaemonState(dir, {
+                    lastFlushAt: now().toISOString(),
+                    lastFlushResult: {
+                        ok: false,
+                        claimed: 0,
+                        posted: 0,
+                        held: 0,
+                        dropped: 0,
+                        deadLettered: 0,
+                        restored: 0,
+                        batches: 0,
+                    },
+                    lastErrorCode: msg.slice(0, 120),
+                }, now);
+                log(dir, `flush(${reason}) error: ${msg.slice(0, 200)}`);
+            }
+            finally {
+                flushInFlight = null;
+            }
+        })();
+        await flushInFlight;
+    };
+    const scheduleDebouncedFlush = () => {
+        if (stopped)
+            return;
+        if (debounceHandle !== null) {
+            timers.clearTimeout(debounceHandle);
+        }
+        debounceHandle = timers.setTimeout(() => {
+            debounceHandle = null;
+            void doFlushCycle("watch");
+        }, SPOOL_DEBOUNCE_MS);
+    };
+    // Watch spool directory (and file) for changes.
+    const spoolPath = workMeshSpoolPath(meshRoot);
+    try {
+        fs.mkdirSync(path.dirname(spoolPath), { recursive: true, mode: 0o700 });
+        if (!fs.existsSync(spoolPath)) {
+            fs.writeFileSync(spoolPath, "", { mode: 0o600 });
+        }
+        watcher = fs.watch(path.dirname(spoolPath), { persistent: true }, (_event, filename) => {
+            if (stopped)
+                return;
+            if (!filename ||
+                filename === "spool.jsonl" ||
+                filename === "held.jsonl" ||
+                String(filename).startsWith("spool.") ||
+                String(filename).startsWith("held.")) {
+                scheduleDebouncedFlush();
+            }
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log(dir, `fs.watch failed (interval flush still active): ${msg.slice(0, 120)}`);
+    }
+    flushIntervalHandle = timers.setTimeout(function tick() {
+        if (stopped)
+            return;
+        void doFlushCycle("interval").finally(() => {
+            if (stopped)
+                return;
+            flushIntervalHandle = timers.setTimeout(tick, FLUSH_INTERVAL_MS);
+        });
+    }, FLUSH_INTERVAL_MS);
+    boardIntervalHandle = timers.setTimeout(function boardTick() {
+        if (stopped)
+            return;
+        void refreshFn()
+            .catch(() => undefined)
+            .finally(() => {
+            if (stopped)
+                return;
+            boardIntervalHandle = timers.setTimeout(boardTick, BOARD_REFRESH_INTERVAL_MS);
+        });
+    }, BOARD_REFRESH_INTERVAL_MS);
+    const runTranscriptTick = async () => {
+        if (!transcriptWatcher || stopped)
+            return;
+        try {
+            const summary = await transcriptWatcher.tick();
+            if (summary.started > 0 ||
+                summary.turns > 0 ||
+                summary.ended > 0) {
+                log(dir, `transcript-watch: started=${summary.started} turns=${summary.turns} ended=${summary.ended} skippedHook=${summary.skippedHookCovered}`);
+                scheduleDebouncedFlush();
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log(dir, `transcript-watch error: ${msg.slice(0, 200)}`);
+        }
+    };
+    if (transcriptWatcher) {
+        transcriptIntervalHandle = timers.setTimeout(function transcriptTick() {
+            if (stopped)
+                return;
+            void runTranscriptTick().finally(() => {
+                if (stopped)
+                    return;
+                transcriptIntervalHandle = timers.setTimeout(transcriptTick, TRANSCRIPT_WATCH_INTERVAL_MS);
+            });
+        }, TRANSCRIPT_WATCH_INTERVAL_MS);
+    }
+    // Initial flush + board pass + transcript scan.
+    void doFlushCycle("start");
+    void refreshFn().catch(() => undefined);
+    void runTranscriptTick();
+    const stop = async () => {
+        if (stopped)
+            return;
+        stopped = true;
+        log(dir, "daemon stopping");
+        if (debounceHandle !== null)
+            timers.clearTimeout(debounceHandle);
+        if (flushIntervalHandle !== null)
+            timers.clearTimeout(flushIntervalHandle);
+        if (boardIntervalHandle !== null)
+            timers.clearTimeout(boardIntervalHandle);
+        if (transcriptIntervalHandle !== null) {
+            timers.clearTimeout(transcriptIntervalHandle);
+        }
+        try {
+            watcher?.close();
+        }
+        catch {
+            /* ignore */
+        }
+        // Final flush, then clean MQTT DISCONNECT so the broker emits the
+        // lifecycle event; offline is published server-side only.
+        await doFlushCycle("shutdown", { force: true });
+        if (presence) {
+            try {
+                await presence.stop();
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log(dir, `presence stop error: ${msg.slice(0, 120)}`);
+            }
+        }
+        patchDaemonState(dir, { mqttState: "closed", companiesOnline: [] }, now);
+        releasePidLock(dir, lockDeps);
+        log(dir, "daemon stopped");
+    };
+    const onSignal = () => {
+        void stop().finally(() => exit(0));
+    };
+    processEvents.once("SIGTERM", onSignal);
+    processEvents.once("SIGINT", onSignal);
+    if (deps.runForMs !== undefined) {
+        timers.setTimeout(() => {
+            void stop();
+        }, deps.runForMs);
+    }
+    return {
+        stop,
+        dir,
+        presence,
+        lastHookEventAt,
+        transcriptWatcher,
+    };
+}
+//# sourceMappingURL=run.js.map

package/dist/lib/mesh/live/daemon/state.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Daemon state.json under ~/.hq/work-mesh/daemon/ (0600, metadata-only).
+ */
+import type { MqttConnectionState } from "./presence.js";
+import type { FlushSummary } from "../flush.js";
+export interface DaemonStateFile {
+    v: 1;
+    pid: number;
+    startedAt: string;
+    mqttState: MqttConnectionState;
+    companiesOnline: string[];
+    actorUid?: string;
+    lastFlushAt?: string;
+    lastFlushResult?: FlushSummary & {
+        ok: boolean;
+    };
+    lastErrorCode?: string;
+    updatedAt: string;
+}
+export declare function defaultDaemonState(pid: number, now?: () => Date): DaemonStateFile;
+export declare function readDaemonState(dir: string): DaemonStateFile | null;
+export declare function writeDaemonState(dir: string, state: DaemonStateFile): void;
+export declare function patchDaemonState(dir: string, patch: Partial<DaemonStateFile>, now?: () => Date): DaemonStateFile;
+//# sourceMappingURL=state.d.ts.map

package/dist/lib/mesh/live/daemon/state.js

@@ -0,0 +1,57 @@
+/**
+ * Daemon state.json under ~/.hq/work-mesh/daemon/ (0600, metadata-only).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { daemonStatePath } from "./paths.js";
+export function defaultDaemonState(pid, now = () => new Date()) {
+    const at = now().toISOString();
+    return {
+        v: 1,
+        pid,
+        startedAt: at,
+        mqttState: "idle",
+        companiesOnline: [],
+        updatedAt: at,
+    };
+}
+export function readDaemonState(dir) {
+    const p = daemonStatePath(dir);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+        if (raw.v !== 1 || typeof raw.pid !== "number")
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeDaemonState(dir, state) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const dest = daemonStatePath(dir);
+    const tmp = path.join(dir, `.state.tmp.${process.pid}.${Date.now()}`);
+    const body = `${JSON.stringify(state, null, 2)}\n`;
+    fs.writeFileSync(tmp, body, { mode: 0o600 });
+    fs.renameSync(tmp, dest);
+    try {
+        fs.chmodSync(dest, 0o600);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+export function patchDaemonState(dir, patch, now = () => new Date()) {
+    const current = readDaemonState(dir) ?? defaultDaemonState(process.pid, now);
+    const next = {
+        ...current,
+        ...patch,
+        v: 1,
+        updatedAt: now().toISOString(),
+    };
+    writeDaemonState(dir, next);
+    return next;
+}
+//# sourceMappingURL=state.js.map

package/dist/lib/mesh/live/daemon/transcript-watch.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Transcript-watch fallback for hookless hosts (US-018 / AMEND-001).
+ *
+ * Enumerates ~/.claude/projects/ (recursive *.jsonl) and ~/.codex/sessions/
+ * every 15s using only readdir + stat (mtime). Never opens or reads transcript bytes.
+ *
+ * Session identity (deterministic):
+ * - Claude: ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl
+ *   sessionId = basename without .jsonl. Paths under /subagents/ are skipped.
+ *   cwd is decoded from the project dir name ("/" replaced by "-" encoding).
+ * - Codex: ~/.codex/sessions/.../rollout-*-<sessionId>.jsonl
+ *   sessionId = trailing UUID in the filename, else basename without .jsonl.
+ *   cwd is not recoverable from the path (mtime-only); left unset.
+ *
+ * Network: harness claude-desktop | codex, source "transcript" on every event.
+ * Local state keeps transcriptMarker for channel-card / Atlas before network sync;
+ * localHarness is no longer written (harness carries claude-desktop on the wire).
+ */
+import * as fs from "node:fs";
+import type { MembershipValidationResult } from "../../../work-context/config.js";
+import { reconcileObservation, type ReconcileDeps } from "../../../work-context/reconcile.js";
+import { readSessionState, writeSessionState, type SessionStateFile } from "../../../work-context/state.js";
+import { enqueueSessionEvent } from "../enqueue.js";
+import type { SessionEventHarness } from "../format-spool-line.js";
+export declare const TRANSCRIPT_WATCH_INTERVAL_MS = 15000;
+export declare const TRANSCRIPT_TURN_QUIET_MS = 5000;
+export declare const TRANSCRIPT_SESSION_END_MS: number;
+export declare const TRANSCRIPT_HOOK_COVER_MS = 60000;
+/** Ignore cold transcripts whose mtime is older than this on first sight. */
+export declare const TRANSCRIPT_FRESH_MS: number;
+export declare const TRANSCRIPT_MARKER: "from transcript";
+export declare const TRANSCRIPT_ADAPTER_VERSION: string;
+/** Network `source` stamped on every synthesized event (AMEND-001). */
+export declare const TRANSCRIPT_EVENT_SOURCE: "transcript";
+/** Fs surface used by the watcher — intentionally no open/readFile. */
+export interface TranscriptFs {
+    readdirSync: (dir: string, opts?: {
+        withFileTypes: true;
+    }) => fs.Dirent[] | string[];
+    statSync: (p: string) => {
+        mtimeMs: number;
+        isFile(): boolean;
+        isDirectory(): boolean;
+    };
+    existsSync: (p: string) => boolean;
+}
+export declare const defaultTranscriptFs: TranscriptFs;
+export type TranscriptKind = "claude" | "codex";
+export interface DiscoveredTranscript {
+    path: string;
+    sessionId: string;
+    kind: TranscriptKind;
+    /** Best-effort cwd (Claude project-dir decode only). */
+    cwd?: string;
+    mtimeMs: number;
+    /** Network harness (schema enum): claude-desktop | codex. */
+    harness: SessionEventHarness;
+}
+export interface TranscriptWatchDeps {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    workContextRoot: string;
+    workMeshRoot?: string;
+    hqRoot?: string;
+    fs?: TranscriptFs;
+    now?: () => number;
+    /**
+     * Last hook-emitted activity per sessionId (epoch ms). Daemon updates this
+     * when spool flush sees hook events. Sessions active within
+     * TRANSCRIPT_HOOK_COVER_MS are not synthesized.
+     */
+    lastHookEventAt?: Map<string, number>;
+    /** Injectable enqueue (tests). */
+    enqueue?: typeof enqueueSessionEvent;
+    /** Injectable state read/write (tests). */
+    readState?: typeof readSessionState;
+    writeState?: typeof writeSessionState;
+    /**
+     * Membership-validated slug→uid for reconcile (flush needs companyUid).
+     * Injectable for tests; daemon wires resolveActiveMembershipCompany.
+     */
+    validateMembership?: (slug: string) => Promise<MembershipValidationResult> | MembershipValidationResult;
+    /** Optional outbox deliverer (daemon); offline when omitted. */
+    deliver?: ReconcileDeps["deliver"];
+    /** Injectable reconcile (tests). */
+    reconcile?: typeof reconcileObservation;
+    claudeProjectsDir?: string;
+    codexSessionsDir?: string;
+}
+export interface TranscriptWatchTickResult {
+    discovered: number;
+    started: number;
+    turns: number;
+    ended: number;
+    skippedHookCovered: number;
+    skippedStale: number;
+}
+/**
+ * Claude Code encodes an absolute cwd as a directory name by replacing every
+ * "/" with "-". Decoding is best-effort (hyphenated path segments are ambiguous).
+ */
+export declare function decodeClaudeProjectDirName(encoded: string): string | undefined;
+/**
+ * Derive session id from a Claude transcript path.
+ * Rule: basename without .jsonl; skip anything under /subagents/.
+ */
+export declare function sessionIdFromClaudeTranscriptPath(filePath: string): string | null;
+/**
+ * Derive session id from a Codex transcript path.
+ * Rule: trailing UUID in basename, else basename without extension.
+ */
+export declare function sessionIdFromCodexTranscriptPath(filePath: string): string | null;
+/**
+ * Enumerate transcript files with mtime only (no content read).
+ */
+export declare function discoverTranscripts(opts: {
+    home?: string;
+    fs?: TranscriptFs;
+    claudeProjectsDir?: string;
+    codexSessionsDir?: string;
+}): DiscoveredTranscript[];
+/**
+ * Whether hooks already cover this session: durable hook-written state, or a
+ * hook event observed within the last TRANSCRIPT_HOOK_COVER_MS.
+ */
+export declare function isTranscriptHookCovered(sessionId: string, opts: {
+    workContextRoot: string;
+    nowMs: number;
+    lastHookEventAt?: Map<string, number>;
+    readState?: typeof readSessionState;
+    coverMs?: number;
+}): boolean;
+/**
+ * Resolve local registration for a transcript session. Never asks, never
+ * creates a project. Uses deterministic cwd/remote mapping only.
+ */
+export declare function resolveTranscriptRegistration(input: {
+    sessionId: string;
+    cwd?: string;
+    hqRoot?: string;
+    workContextRoot: string;
+    now?: () => Date;
+}): SessionStateFile;
+/**
+ * Scan a spool/held jsonl for hook-emitted session ids (not transcript-watch).
+ * Reads spool metadata only — never a transcript file.
+ */
+export declare function noteHookSessionsFromSpoolFile(spoolPath: string, lastHookEventAt: Map<string, number>, atMs: number, tfs?: Pick<TranscriptFs, "existsSync"> & {
+    readFileSync?: (p: string, enc: "utf8") => string;
+}): string[];
+export declare class TranscriptWatcher {
+    private readonly tracked;
+    private readonly deps;
+    private readonly tfs;
+    private readonly enqueueFn;
+    private readonly readState;
+    private readonly writeState;
+    private readonly reconcileFn;
+    constructor(deps: TranscriptWatchDeps);
+    /** Record that a hook path emitted an event for sessionId (daemon flush). */
+    noteHookEvent(sessionId: string, atMs?: number): void;
+    tick(): Promise<TranscriptWatchTickResult>;
+    /**
+     * Register via reconcileObservation (membership-validated slug→uid), then
+     * enqueue session_start. Never overwrites a hook-written state.
+     */
+    private emitStart;
+    private emitKind;
+}
+//# sourceMappingURL=transcript-watch.d.ts.map