@indigoai-us/hq-cli 5.108.0 → 5.108.2

package/dist/lib/mesh/live/daemon/transcript-watch.js

@@ -0,0 +1,520 @@
+/**
+ * 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 * as os from "node:os";
+import * as path from "node:path";
+import { CLI_VERSION } from "../../../../cli-version.js";
+import { companySlugFromCwd, projectIdFromCwd, resolveDeterministicCompany, } from "../../../work-context/company.js";
+import { getDefaultCompany } from "../../../work-context/config.js";
+import { WORK_CONTEXT_CONTRACT_VERSION } from "../../../work-context/contract.js";
+import { reconcileObservation, } from "../../../work-context/reconcile.js";
+import { deriveRemoteOwnerSlug } from "../../../work-context/repo-remote.js";
+import { isHookWrittenSessionState, readSessionState, writeSessionState, } from "../../../work-context/state.js";
+import { enqueueSessionEvent } from "../enqueue.js";
+import { isValidSessionId } from "../session-identity.js";
+export const TRANSCRIPT_WATCH_INTERVAL_MS = 15_000;
+export const TRANSCRIPT_TURN_QUIET_MS = 5_000;
+export const TRANSCRIPT_SESSION_END_MS = 10 * 60_000;
+export const TRANSCRIPT_HOOK_COVER_MS = 60_000;
+/** Ignore cold transcripts whose mtime is older than this on first sight. */
+export const TRANSCRIPT_FRESH_MS = TRANSCRIPT_SESSION_END_MS;
+export const TRANSCRIPT_MARKER = "from transcript";
+export const TRANSCRIPT_ADAPTER_VERSION = CLI_VERSION;
+/** Network `source` stamped on every synthesized event (AMEND-001). */
+export const TRANSCRIPT_EVENT_SOURCE = "transcript";
+export const defaultTranscriptFs = {
+    readdirSync: (dir, opts) => opts?.withFileTypes
+        ? fs.readdirSync(dir, { withFileTypes: true })
+        : fs.readdirSync(dir),
+    statSync: (p) => fs.statSync(p),
+    existsSync: (p) => fs.existsSync(p),
+};
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+/**
+ * Claude Code encodes an absolute cwd as a directory name by replacing every
+ * "/" with "-". Decoding is best-effort (hyphenated path segments are ambiguous).
+ */
+export function decodeClaudeProjectDirName(encoded) {
+    const name = encoded.trim();
+    if (!name.startsWith("-") || name.length < 2)
+        return undefined;
+    return name.replace(/-/g, "/");
+}
+/**
+ * Derive session id from a Claude transcript path.
+ * Rule: basename without .jsonl; skip anything under /subagents/.
+ */
+export function sessionIdFromClaudeTranscriptPath(filePath) {
+    const normalized = filePath.replace(/\\/g, "/");
+    if (normalized.includes("/subagents/"))
+        return null;
+    const base = path.basename(filePath);
+    if (!base.endsWith(".jsonl"))
+        return null;
+    const id = base.slice(0, -".jsonl".length);
+    if (!isValidSessionId(id))
+        return null;
+    return id;
+}
+/**
+ * Derive session id from a Codex transcript path.
+ * Rule: trailing UUID in basename, else basename without extension.
+ */
+export function sessionIdFromCodexTranscriptPath(filePath) {
+    const base = path.basename(filePath);
+    const stem = base.endsWith(".jsonl")
+        ? base.slice(0, -".jsonl".length)
+        : base.includes(".")
+            ? base.slice(0, base.lastIndexOf("."))
+            : base;
+    const matches = stem.match(new RegExp(UUID_RE.source, "gi"));
+    const id = matches?.[matches.length - 1] ?? stem;
+    if (!isValidSessionId(id))
+        return null;
+    return id;
+}
+function listJsonlFiles(root, tfs) {
+    if (!tfs.existsSync(root))
+        return [];
+    const out = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = tfs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const name = typeof entry === "string" ? entry : entry.name;
+            const full = path.join(dir, name);
+            let isDir;
+            let isFile;
+            if (typeof entry !== "string" && typeof entry.isDirectory === "function") {
+                isDir = entry.isDirectory();
+                isFile = entry.isFile();
+            }
+            else {
+                try {
+                    const st = tfs.statSync(full);
+                    isDir = st.isDirectory();
+                    isFile = st.isFile();
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (isDir) {
+                stack.push(full);
+            }
+            else if (isFile && name.endsWith(".jsonl")) {
+                out.push(full);
+            }
+        }
+    }
+    return out;
+}
+function listCodexSessionFiles(root, tfs) {
+    if (!tfs.existsSync(root))
+        return [];
+    const out = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = tfs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const name = typeof entry === "string" ? entry : entry.name;
+            const full = path.join(dir, name);
+            let isDir;
+            let isFile;
+            if (typeof entry !== "string" && typeof entry.isDirectory === "function") {
+                isDir = entry.isDirectory();
+                isFile = entry.isFile();
+            }
+            else {
+                try {
+                    const st = tfs.statSync(full);
+                    isDir = st.isDirectory();
+                    isFile = st.isFile();
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (isDir) {
+                stack.push(full);
+            }
+            else if (isFile) {
+                // Codex stores rollout-*.jsonl (and occasionally other session files).
+                out.push(full);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Enumerate transcript files with mtime only (no content read).
+ */
+export function discoverTranscripts(opts) {
+    const home = opts.home ?? os.homedir();
+    const tfs = opts.fs ?? defaultTranscriptFs;
+    const claudeRoot = opts.claudeProjectsDir ?? path.join(home, ".claude", "projects");
+    const codexRoot = opts.codexSessionsDir ?? path.join(home, ".codex", "sessions");
+    const found = [];
+    for (const filePath of listJsonlFiles(claudeRoot, tfs)) {
+        const sessionId = sessionIdFromClaudeTranscriptPath(filePath);
+        if (!sessionId)
+            continue;
+        let mtimeMs;
+        try {
+            const st = tfs.statSync(filePath);
+            if (!st.isFile())
+                continue;
+            mtimeMs = st.mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        const projectDir = path.basename(path.dirname(filePath));
+        const cwd = decodeClaudeProjectDirName(projectDir);
+        found.push({
+            path: filePath,
+            sessionId,
+            kind: "claude",
+            cwd,
+            mtimeMs,
+            harness: "claude-desktop",
+        });
+    }
+    for (const filePath of listCodexSessionFiles(codexRoot, tfs)) {
+        if (!filePath.endsWith(".jsonl") && !path.basename(filePath).startsWith("rollout-")) {
+            // Prefer jsonl; still accept rollout-* without extension edge cases via id parse.
+            if (!path.basename(filePath).startsWith("rollout-"))
+                continue;
+        }
+        const sessionId = sessionIdFromCodexTranscriptPath(filePath);
+        if (!sessionId)
+            continue;
+        let mtimeMs;
+        try {
+            const st = tfs.statSync(filePath);
+            if (!st.isFile())
+                continue;
+            mtimeMs = st.mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        found.push({
+            path: filePath,
+            sessionId,
+            kind: "codex",
+            mtimeMs,
+            harness: "codex",
+        });
+    }
+    return found;
+}
+/**
+ * Whether hooks already cover this session: durable hook-written state, or a
+ * hook event observed within the last TRANSCRIPT_HOOK_COVER_MS.
+ */
+export function isTranscriptHookCovered(sessionId, opts) {
+    const read = opts.readState ?? readSessionState;
+    const state = read(sessionId, opts.workContextRoot);
+    if (isHookWrittenSessionState(state))
+        return true;
+    const last = opts.lastHookEventAt?.get(sessionId);
+    if (last === undefined)
+        return false;
+    return opts.nowMs - last < (opts.coverMs ?? TRANSCRIPT_HOOK_COVER_MS);
+}
+/**
+ * Resolve local registration for a transcript session. Never asks, never
+ * creates a project. Uses deterministic cwd/remote mapping only.
+ */
+export function resolveTranscriptRegistration(input) {
+    const now = input.now ?? (() => new Date());
+    const updatedAt = now().toISOString();
+    const remoteOwnerSlug = input.cwd
+        ? deriveRemoteOwnerSlug({ cwd: input.cwd, hqRoot: input.hqRoot })
+        : null;
+    const deterministic = resolveDeterministicCompany({
+        cwd: input.cwd,
+        hqRoot: input.hqRoot,
+        remoteOwnerSlug,
+    });
+    const projectId = projectIdFromCwd(input.cwd, input.hqRoot);
+    // Prefer company slug from deterministic evidence; optionally adopt uid when
+    // the enabled device default names the same slug (no conflict ask).
+    const companySlug = deterministic?.slug ?? companySlugFromCwd(input.cwd, input.hqRoot);
+    let companyUid;
+    const device = getDefaultCompany({ root: input.workContextRoot });
+    if (companySlug &&
+        device?.enabled &&
+        device.slug &&
+        device.slug.toLowerCase() === companySlug.toLowerCase()) {
+        companyUid = device.uid;
+    }
+    let contextStatus;
+    if (!companySlug) {
+        contextStatus = "needs_company";
+    }
+    else if (projectId) {
+        contextStatus = "needs_task";
+    }
+    else {
+        contextStatus = "unresolved";
+    }
+    const state = {
+        contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+        sessionId: input.sessionId,
+        contextStatus,
+        updatedAt,
+        source: "transcript",
+        // Keep local marker for channel-card / Atlas before SESSION_STATE sync.
+        transcriptMarker: TRANSCRIPT_MARKER,
+    };
+    if (companySlug)
+        state.companySlug = companySlug;
+    if (companyUid)
+        state.companyUid = companyUid;
+    if (projectId && companySlug)
+        state.projectId = projectId;
+    return state;
+}
+/**
+ * Scan a spool/held jsonl for hook-emitted session ids (not transcript-watch).
+ * Reads spool metadata only — never a transcript file.
+ */
+export function noteHookSessionsFromSpoolFile(spoolPath, lastHookEventAt, atMs, tfs = defaultTranscriptFs) {
+    if (!tfs.existsSync(spoolPath))
+        return [];
+    const readFile = tfs.readFileSync ?? ((p, enc) => fs.readFileSync(p, enc));
+    let text;
+    try {
+        text = readFile(spoolPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const noted = [];
+    for (const line of text.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            const ev = JSON.parse(line);
+            if (typeof ev.sessionId !== "string" || !ev.sessionId)
+                continue;
+            // Synthesized transcript events carry source=transcript — not hooks.
+            if (ev.source === TRANSCRIPT_EVENT_SOURCE)
+                continue;
+            lastHookEventAt.set(ev.sessionId, atMs);
+            noted.push(ev.sessionId);
+        }
+        catch {
+            /* ignore malformed */
+        }
+    }
+    return noted;
+}
+export class TranscriptWatcher {
+    tracked = new Map();
+    deps;
+    tfs;
+    enqueueFn;
+    readState;
+    writeState;
+    reconcileFn;
+    constructor(deps) {
+        this.deps = deps;
+        this.tfs = deps.fs ?? defaultTranscriptFs;
+        this.enqueueFn = deps.enqueue ?? enqueueSessionEvent;
+        this.readState = deps.readState ?? readSessionState;
+        this.writeState = deps.writeState ?? writeSessionState;
+        this.reconcileFn = deps.reconcile ?? reconcileObservation;
+    }
+    /** Record that a hook path emitted an event for sessionId (daemon flush). */
+    noteHookEvent(sessionId, atMs) {
+        const map = this.deps.lastHookEventAt;
+        if (!map)
+            return;
+        map.set(sessionId, atMs ?? (this.deps.now?.() ?? Date.now()));
+    }
+    async tick() {
+        const nowMs = this.deps.now?.() ?? Date.now();
+        const home = this.deps.home ?? os.homedir();
+        const result = {
+            discovered: 0,
+            started: 0,
+            turns: 0,
+            ended: 0,
+            skippedHookCovered: 0,
+            skippedStale: 0,
+        };
+        const discovered = discoverTranscripts({
+            home,
+            fs: this.tfs,
+            claudeProjectsDir: this.deps.claudeProjectsDir,
+            codexSessionsDir: this.deps.codexSessionsDir,
+        });
+        result.discovered = discovered.length;
+        const seenPaths = new Set();
+        for (const d of discovered) {
+            seenPaths.add(d.path);
+            if (isTranscriptHookCovered(d.sessionId, {
+                workContextRoot: this.deps.workContextRoot,
+                nowMs,
+                lastHookEventAt: this.deps.lastHookEventAt,
+                readState: this.readState,
+            })) {
+                result.skippedHookCovered += 1;
+                this.tracked.delete(d.path);
+                continue;
+            }
+            let track = this.tracked.get(d.path);
+            if (!track) {
+                // First sight: only adopt fresh or actively-written transcripts.
+                if (nowMs - d.mtimeMs > TRANSCRIPT_FRESH_MS) {
+                    result.skippedStale += 1;
+                    continue;
+                }
+                track = {
+                    path: d.path,
+                    sessionId: d.sessionId,
+                    kind: d.kind,
+                    cwd: d.cwd,
+                    harness: d.harness,
+                    lastMtimeMs: d.mtimeMs,
+                    lastChangeAtMs: d.mtimeMs,
+                    started: false,
+                    ended: false,
+                    pendingTurn: false,
+                    seq: 0,
+                };
+                this.tracked.set(d.path, track);
+                const started = await this.emitStart(track, nowMs);
+                if (started)
+                    result.started += 1;
+                continue;
+            }
+            if (track.ended)
+                continue;
+            if (d.mtimeMs > track.lastMtimeMs) {
+                track.lastMtimeMs = d.mtimeMs;
+                track.lastChangeAtMs = nowMs;
+                if (track.started) {
+                    track.pendingTurn = true;
+                }
+            }
+            if (track.pendingTurn &&
+                nowMs - track.lastChangeAtMs >= TRANSCRIPT_TURN_QUIET_MS) {
+                this.emitKind(track, "turn_end", nowMs);
+                track.pendingTurn = false;
+                result.turns += 1;
+            }
+            if (track.started &&
+                !track.ended &&
+                nowMs - track.lastChangeAtMs >= TRANSCRIPT_SESSION_END_MS) {
+                this.emitKind(track, "session_end", nowMs);
+                track.ended = true;
+                result.ended += 1;
+            }
+        }
+        // Sessions that disappeared from disk: end if still open.
+        for (const [p, track] of [...this.tracked.entries()]) {
+            if (seenPaths.has(p))
+                continue;
+            if (track.started && !track.ended) {
+                this.emitKind(track, "session_end", nowMs);
+                track.ended = true;
+                result.ended += 1;
+            }
+            this.tracked.delete(p);
+        }
+        return result;
+    }
+    /**
+     * Register via reconcileObservation (membership-validated slug→uid), then
+     * enqueue session_start. Never overwrites a hook-written state.
+     */
+    async emitStart(track, nowMs) {
+        const prior = this.readState(track.sessionId, this.deps.workContextRoot);
+        if (isHookWrittenSessionState(prior)) {
+            track.ended = true;
+            return false;
+        }
+        const observation = {
+            contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+            identity: {
+                sessionId: track.sessionId,
+                harness: track.harness,
+                adapterVersion: TRANSCRIPT_ADAPTER_VERSION,
+            },
+            clientOperationId: `transcript_start_${track.sessionId}`,
+            cwd: track.cwd,
+            hqRoot: this.deps.hqRoot,
+            source: "transcript",
+        };
+        await this.reconcileFn(observation, {
+            root: this.deps.workContextRoot,
+            env: this.deps.env,
+            now: () => new Date(nowMs),
+            validateMembership: this.deps.validateMembership,
+            deliver: this.deps.deliver,
+            offline: !this.deps.deliver,
+        });
+        // Re-check: a hook may have raced us during reconcile.
+        const after = this.readState(track.sessionId, this.deps.workContextRoot);
+        if (isHookWrittenSessionState(after)) {
+            track.ended = true;
+            return false;
+        }
+        this.emitKind(track, "session_start", nowMs);
+        track.started = true;
+        return true;
+    }
+    emitKind(track, kind, nowMs) {
+        track.seq += 1;
+        const opts = {
+            kind,
+            sessionId: track.sessionId,
+            harness: track.harness,
+            adapterVersion: TRANSCRIPT_ADAPTER_VERSION,
+            source: TRANSCRIPT_EVENT_SOURCE,
+            at: new Date(nowMs).toISOString(),
+            seq: track.seq,
+            cwd: track.cwd,
+            hqRoot: this.deps.hqRoot,
+            root: this.deps.workMeshRoot,
+            env: this.deps.env,
+            now: () => new Date(nowMs),
+        };
+        this.enqueueFn(opts);
+    }
+}
+//# sourceMappingURL=transcript-watch.js.map

package/dist/lib/mesh/live/enqueue.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Local session-event enqueue (US-008): validate + append one spool line.
+ * No network. Shared line format with work-mesh-enqueue.sh.
+ */
+import { type SessionEventHarness, type SessionEventKind, type SessionEventSource, type SpoolEventInput } from "./format-spool-line.js";
+export declare class EnqueueValidationError extends Error {
+    readonly code: "ENQUEUE_VALIDATION";
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+export declare const CLI_KIND_TO_SCHEMA: Record<string, SessionEventKind>;
+export interface EnqueueOptions {
+    kind: SessionEventKind;
+    sessionId?: string;
+    harness: SessionEventHarness;
+    adapterVersion: string;
+    runtimeVersion?: string;
+    source?: SessionEventSource;
+    at?: string;
+    seq: number;
+    eventId?: string;
+    taskId?: string;
+    status?: "queued" | "in_progress" | "review" | "done";
+    reason?: string;
+    summary?: string;
+    cwd?: string;
+    hqRoot?: string;
+    companySlug?: string;
+    project?: string;
+    task?: string;
+    toolWrites?: number;
+    /** Work-mesh root override (tests). */
+    root?: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => Date;
+}
+export interface EnqueueResult {
+    line: string;
+    spoolPath: string;
+    event: SpoolEventInput;
+}
+export declare function resolveEnqueueSessionId(explicit: string | undefined, env: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Validate and append one schema-valid spool line. Throws EnqueueValidationError
+ * (nothing written) when the event is invalid — including a missing sessionId.
+ */
+export declare function enqueueSessionEvent(opts: EnqueueOptions): EnqueueResult;
+//# sourceMappingURL=enqueue.d.ts.map

package/dist/lib/mesh/live/enqueue.js

@@ -0,0 +1,100 @@
+/**
+ * Local session-event enqueue (US-008): validate + append one spool line.
+ * No network. Shared line format with work-mesh-enqueue.sh.
+ */
+import { validateSessionEvent } from "./validate-session-event.js";
+import { formatSpoolLine, } from "./format-spool-line.js";
+import { generateUlid } from "./ulid.js";
+import { appendSpoolLine, SpoolWriteError } from "./spool.js";
+import { workMeshRoot } from "./paths.js";
+import { sessionIdFromEnv } from "./session-identity.js";
+export class EnqueueValidationError extends Error {
+    code = "ENQUEUE_VALIDATION";
+    errors;
+    constructor(errors) {
+        super(errors.join("; ") || "Session event failed schema validation");
+        this.name = "EnqueueValidationError";
+        this.errors = errors;
+    }
+}
+export const CLI_KIND_TO_SCHEMA = {
+    start: "session_start",
+    "turn-start": "turn_start",
+    "turn-end": "turn_end",
+    end: "session_end",
+    "task-status": "task_status",
+    blocked: "blocked",
+    note: "note",
+};
+export function resolveEnqueueSessionId(explicit, env) {
+    const trimmed = explicit?.trim();
+    if (trimmed)
+        return trimmed;
+    return sessionIdFromEnv(env);
+}
+/**
+ * Validate and append one schema-valid spool line. Throws EnqueueValidationError
+ * (nothing written) when the event is invalid — including a missing sessionId.
+ */
+export function enqueueSessionEvent(opts) {
+    const env = opts.env ?? process.env;
+    const sessionId = resolveEnqueueSessionId(opts.sessionId, env);
+    if (!sessionId) {
+        throw new EnqueueValidationError(["sessionId: required"]);
+    }
+    const now = opts.now ?? (() => new Date());
+    const event = {
+        v: 1,
+        eventId: opts.eventId?.trim() || generateUlid(now().getTime()),
+        kind: opts.kind,
+        sessionId,
+        harness: opts.harness,
+        adapterVersion: opts.adapterVersion,
+        at: opts.at ?? now().toISOString(),
+        seq: opts.seq,
+    };
+    if (opts.runtimeVersion)
+        event.runtimeVersion = opts.runtimeVersion;
+    if (opts.source)
+        event.source = opts.source;
+    if (opts.taskId)
+        event.taskId = opts.taskId;
+    if (opts.status)
+        event.status = opts.status;
+    if (opts.reason)
+        event.reason = opts.reason;
+    if (opts.summary)
+        event.summary = opts.summary;
+    if (opts.cwd)
+        event.cwd = opts.cwd;
+    if (opts.hqRoot)
+        event.hqRoot = opts.hqRoot;
+    if (opts.companySlug)
+        event.companySlug = opts.companySlug;
+    if (opts.project)
+        event.project = opts.project;
+    if (opts.task)
+        event.task = opts.task;
+    if (opts.toolWrites !== undefined)
+        event.toolWrites = opts.toolWrites;
+    const candidate = {
+        ...event,
+        v: 1,
+    };
+    const validation = validateSessionEvent(candidate);
+    if (!validation.ok) {
+        throw new EnqueueValidationError(validation.errors);
+    }
+    const line = formatSpoolLine(event);
+    const root = opts.root ?? workMeshRoot(undefined, env);
+    try {
+        const spoolPath = appendSpoolLine(line, root);
+        return { line, spoolPath, event };
+    }
+    catch (err) {
+        if (err instanceof SpoolWriteError)
+            throw err;
+        throw new SpoolWriteError(err instanceof Error ? err.message : String(err));
+    }
+}
+//# sourceMappingURL=enqueue.js.map