@indigoai-us/hq-cli 5.287.0 → 5.289.0

package/dist/lib/checkpoint-ontology/plan.js

@@ -25,99 +25,12 @@ export const ONTOLOGY_FLAG = "checkpoint.ontology";
  * 6.18.7 or later; see ./sync-client.ts.
  */
 export const ONTOLOGY_SYNC_GATED_FLAG = "checkpoint.ontology.sync-gated";
-export const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
-/**
- * Applies only when the payload's sibling backend is grok. On gold-v2, Claude
- * with stripped inputs lost 0.139 recall; Grok with stripped inputs gained
- * precision without losing recall. A machine that falls back from grok keeps
- * the annotated inputs.
- */
-export const IGNORE_ANNOTATIONS_FLAG = "checkpoint.ontology.ignore-annotations";
-/**
- * With `--backend auto`, `hq core checkpoint` tries grok first for this
- * company. Read here, in the detached sibling, and recorded in the company's
- * state directory, so the foreground checkpoint makes no network call.
- */
-export const GROK_BACKEND_FLAG = "checkpoint.ontology.grok-backend";
 /**
  * Several writers in one company vault (design section 20): record written
  * entity bytes in the outbox, merge back set-aside versions, and report
  * duplicate entities.
  */
 export const MULTI_WRITER_FLAG = "checkpoint.ontology.multi-writer";
-/**
- * A candidate that links to an existing entity adds no aliases to it; the plan
- * carries `link_aliases: false` and apply honours it. CO-42: most aliases
- * written through links on the CO-41 runs were other things the text named
- * next to the entity (`Publisher` on indigo, `Stripe Connect` on Stripe), and
- * entity-hints multiplied them (22 aliases on a flag-off run, 45 and 125 on two
- * hinted runs).
- */
-export const NO_LINK_ALIASES_FLAG = "checkpoint.ontology.no-link-aliases";
-/**
- * A person the input and the company's entities give only a first name for is
- * named by that first name instead of being left out. CO-44: on the CO-41
- * grok-4.6 runs the model read "not a first name alone" as "skip them", and
- * dropped people such as Amir and Sebastian, whose own entities carry only a
- * first name. People were 24 of the 138 missed gold entities over three runs.
- * The plan carries `first_name_people: true`, and apply then defers a one-word
- * person whose word starts an existing person's fuller name or alias, since
- * the model cannot see that `John Smith` already exists.
- */
-export const FIRST_NAME_PEOPLE_FLAG = "checkpoint.ontology.first-name-people";
-/**
- * A knowledge input does not link to a concept entity whose canonical name is
- * also the canonical name of an entity of another type (`concept/hq-secrets`
- * beside `project/hq-secrets`). The plan carries
- * `skip_ambiguous_concept_links: true`, and apply rejects the link as
- * `ambiguous_type`. CO-46: 34 of the 73 false positives on the knowledge
- * fixtures were such concept links; skipping them raised precision from 0.733
- * to 0.803 and cost recall 0.023 on a replay of six runs.
- */
-export const SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG = "checkpoint.ontology.skip-ambiguous-concept-links";
-/**
- * A knowledge link to the weaker of two entities that share a canonical name
- * across types is redirected to the sibling other entity files link to
- * (`project/build-your-own-agi` beside `concept/build-your-own-agi`, or
- * `project/hq-core 2` beside `project/hq-core` when a concept also holds the
- * name). The plan carries `dominant_sibling_link: true`, and apply reports
- * the move in `dominant_sibling_redirects` without writing the entity files.
- * CO-60: a replay of six runs raised knowledge precision from 0.725 to 0.754
- * and recall from 0.784 to 0.816, and never changed a create.
- */
-export const DOMINANT_SIBLING_LINK_FLAG = "checkpoint.ontology.dominant-sibling-link";
-/**
- * A knowledge link to a non-person entity that 50 or more
- * other entity files link to is rejected as `hub_under_mentioned` when the
- * input names it fewer than 2 times (whole word, any case, canonical name
- * only). The plan carries `hub_mention_floor: true`. CO-62: a replay of six
- * runs raised knowledge precision from 0.753 to 0.781 at the same recall.
- */
-export const HUB_MENTION_FLOOR_FLAG = "checkpoint.ontology.hub-mention-floor";
-/**
- * A knowledge concept candidate whose name is an alias of more than one
- * entity, and which apply would defer as `ambiguous_alias`, links instead to
- * the one project whose canonical name it is (`HQ` typed as a concept beside
- * `project/HQ` and several concepts aliased `HQ`). The plan carries
- * `concept_project_link: true`. CO-51: over six runs of the shipping config
- * the model typed HQ as a concept in some runs and not others, and the
- * deferral lost 61 gold links; a replay of this rule raised recall from 0.639
- * to 0.709 at precision 0.747 to 0.731 (61 of the 63 added links are HQ).
- */
-export const CONCEPT_PROJECT_LINK_FLAG = "checkpoint.ontology.concept-project-link";
-/**
- * A knowledge link to the company's own company entity, or a
- * concept-project-link redirect, needs evidence that names the entity as a
- * word: the candidate name or one of its aliases, not inside a path, domain,
- * handle, tag or identifier (`indigoai-us/hq`, `getindigo.ai`,
- * `scope: company:indigo`). The plan carries `named_evidence: true`, and apply
- * rejects such a link as `unnamed_in_evidence`. CO-57: on the six CO-52 runs,
- * 67 of 143 false positives were links to company/indigo and project/HQ, most
- * on evidence that only held the name inside an identifier; a replay of this
- * rule raised precision on the concept-project-link arm from 0.705 to 0.750
- * and lost no gold link.
- */
-export const NAMED_EVIDENCE_FLAG = "checkpoint.ontology.named-evidence";
 /**
  * CO-59: consume the files touched by company checkpoints that were queued
  * behind a busy sibling (see queued-touches.ts). On, the plan adds the
@@ -139,7 +52,6 @@ export const BUDGET = {
     chunkTokens: 12_000,
 };
 export const READ_PATH_INSTRUCTION = "When an input has read_path, read that file (relative to the run directory) instead of path, with the same line range. It is the same text with an older annotator's entity lists and entity links removed.";
-export const PERSON_NAME_INSTRUCTION = "Name a person by the full name the input or the company's entities give, not a first name alone.";
 export const FIRST_NAME_PEOPLE_INSTRUCTION = "Name a person by the full name the input or the company's entities give. When neither gives more than a first name, name the person by that first name; do not leave them out.";
 const CANDIDATE_INSTRUCTIONS = [
     `Write ${CANDIDATES_FILE} in the run directory as {"schema":"${CANDIDATES_SCHEMA}","candidates":[...]} and nothing else.`,
@@ -317,17 +229,18 @@ export async function planOntologyRun(options) {
         fs.rmSync(backendPreferencePath(hqRoot, company), { force: true });
         return { status: "skipped", reason: syncClient && !syncClient.ok ? syncClient.reason : "flag off" };
     }
-    const briefOn = await options.readFlag(COMPANY_BRIEF_FLAG, company);
-    const ignoreAnnotations = (await options.readFlag(IGNORE_ANNOTATIONS_FLAG, company)) && payload.backend === "grok";
-    recordBackendPreference(hqRoot, company, await options.readFlag(GROK_BACKEND_FLAG, company));
+    // Was checkpoint.ontology.ignore-annotations, always on since CO-68.
+    // Applies only when the payload's sibling backend is grok. On gold-v2, Claude
+    // with stripped inputs lost 0.139 recall; Grok with stripped inputs gained
+    // precision without losing recall. A machine that falls back from grok keeps
+    // the annotated inputs.
+    const ignoreAnnotations = payload.backend === "grok";
+    // Was checkpoint.ontology.grok-backend, always on since CO-68.
+    // With `--backend auto`, `hq core checkpoint` tries grok first for this
+    // company. Read here, in the detached sibling, and recorded in the company's
+    // state directory, so the foreground checkpoint makes no network call.
+    recordBackendPreference(hqRoot, company, true);
     const multiWriterOn = await options.readFlag(MULTI_WRITER_FLAG, company);
-    const noLinkAliases = await options.readFlag(NO_LINK_ALIASES_FLAG, company);
-    const firstNamePeople = await options.readFlag(FIRST_NAME_PEOPLE_FLAG, company);
-    const skipAmbiguousConceptLinks = await options.readFlag(SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG, company);
-    const dominantSiblingLink = await options.readFlag(DOMINANT_SIBLING_LINK_FLAG, company);
-    const hubMentionFloor = await options.readFlag(HUB_MENTION_FLOOR_FLAG, company);
-    const conceptProjectLink = await options.readFlag(CONCEPT_PROJECT_LINK_FLAG, company);
-    const namedEvidence = await options.readFlag(NAMED_EVIDENCE_FLAG, company);
     const queuedTouchesOn = borrowed || (await options.readFlag(QUEUED_TOUCHES_FLAG, company));
     // A borrowed company's run belongs to another session: its own files and
     // session text are not this company's input.
@@ -343,7 +256,8 @@ export async function planOntologyRun(options) {
     // a plan still merges set-aside versions and records the brief; the brief
     // follows merge-back so its counts include merged entities.
     const multiWriter = multiWriterOn ? startMultiWriterRun(hqRoot, company, options.now ?? new Date()) : undefined;
-    const companyBrief = briefOn ? writeCompanyBrief(hqRoot, company, options.now ?? new Date()) : undefined;
+    // Was checkpoint.ontology.company-brief, always on since CO-68.
+    const companyBrief = writeCompanyBrief(hqRoot, company, options.now ?? new Date());
     const pending = Object.entries(ledger.entries)
         .filter(([, entry]) => entry.state === "pending" && entry.reason === "session-touched")
         .sort(([aRel, a], [bRel, b]) => a.mtime_ms - b.mtime_ms || aRel.localeCompare(bRel));
@@ -446,13 +360,72 @@ export async function planOntologyRun(options) {
             }
             : {}),
         ...(multiWriter ? { multi_writer: multiWriter } : {}),
-        ...(noLinkAliases ? { link_aliases: false } : {}),
-        ...(firstNamePeople ? { first_name_people: true } : {}),
-        ...(skipAmbiguousConceptLinks ? { skip_ambiguous_concept_links: true } : {}),
-        ...(dominantSiblingLink ? { dominant_sibling_link: true } : {}),
-        ...(hubMentionFloor ? { hub_mention_floor: true } : {}),
-        ...(conceptProjectLink ? { concept_project_link: true } : {}),
-        ...(namedEvidence ? { named_evidence: true } : {}),
+        // Was checkpoint.ontology.no-link-aliases, always on since CO-68.
+        // A candidate that links to an existing entity adds no aliases to it; the plan
+        // carries `link_aliases: false` and apply honours it. CO-42: most aliases
+        // written through links on the CO-41 runs were other things the text named
+        // next to the entity (`Publisher` on indigo, `Stripe Connect` on Stripe), and
+        // entity-hints multiplied them (22 aliases on a flag-off run, 45 and 125 on two
+        // hinted runs).
+        link_aliases: false,
+        // Was checkpoint.ontology.first-name-people, always on since CO-68.
+        // A person the input and the company's entities give only a first name for is
+        // named by that first name instead of being left out. CO-44: on the CO-41
+        // grok-4.6 runs the model read "not a first name alone" as "skip them", and
+        // dropped people such as Amir and Sebastian, whose own entities carry only a
+        // first name. People were 24 of the 138 missed gold entities over three runs.
+        // The plan carries `first_name_people: true`, and apply then defers a one-word
+        // person whose word starts an existing person's fuller name or alias, since
+        // the model cannot see that `John Smith` already exists.
+        first_name_people: true,
+        // Was checkpoint.ontology.skip-ambiguous-concept-links, always on since CO-68.
+        // A knowledge input does not link to a concept entity whose canonical name is
+        // also the canonical name of an entity of another type (`concept/hq-secrets`
+        // beside `project/hq-secrets`). The plan carries
+        // `skip_ambiguous_concept_links: true`, and apply rejects the link as
+        // `ambiguous_type`. CO-46: 34 of the 73 false positives on the knowledge
+        // fixtures were such concept links; skipping them raised precision from 0.733
+        // to 0.803 and cost recall 0.023 on a replay of six runs.
+        skip_ambiguous_concept_links: true,
+        // Was checkpoint.ontology.dominant-sibling-link, always on since CO-68.
+        // A knowledge link to the weaker of two entities that share a canonical name
+        // across types is redirected to the sibling other entity files link to
+        // (`project/build-your-own-agi` beside `concept/build-your-own-agi`, or
+        // `project/hq-core 2` beside `project/hq-core` when a concept also holds the
+        // name). The plan carries `dominant_sibling_link: true`, and apply reports
+        // the move in `dominant_sibling_redirects` without writing the entity files.
+        // CO-60: a replay of six runs raised knowledge precision from 0.725 to 0.754
+        // and recall from 0.784 to 0.816, and never changed a create.
+        dominant_sibling_link: true,
+        // Was checkpoint.ontology.hub-mention-floor, always on since CO-68.
+        // A knowledge link to a non-person entity that 50 or more
+        // other entity files link to is rejected as `hub_under_mentioned` when the
+        // input names it fewer than 2 times (whole word, any case, canonical name
+        // only). The plan carries `hub_mention_floor: true`. CO-62: a replay of six
+        // runs raised knowledge precision from 0.753 to 0.781 at the same recall.
+        hub_mention_floor: true,
+        // Was checkpoint.ontology.concept-project-link, always on since CO-68.
+        // A knowledge concept candidate whose name is an alias of more than one
+        // entity, and which apply would defer as `ambiguous_alias`, links instead to
+        // the one project whose canonical name it is (`HQ` typed as a concept beside
+        // `project/HQ` and several concepts aliased `HQ`). The plan carries
+        // `concept_project_link: true`. CO-51: over six runs of the shipping config
+        // the model typed HQ as a concept in some runs and not others, and the
+        // deferral lost 61 gold links; a replay of this rule raised recall from 0.639
+        // to 0.709 at precision 0.747 to 0.731 (61 of the 63 added links are HQ).
+        concept_project_link: true,
+        // Was checkpoint.ontology.named-evidence, always on since CO-68.
+        // A knowledge link to the company's own company entity, or a
+        // concept-project-link redirect, needs evidence that names the entity as a
+        // word: the candidate name or one of its aliases, not inside a path, domain,
+        // handle, tag or identifier (`indigoai-us/hq`, `getindigo.ai`,
+        // `scope: company:indigo`). The plan carries `named_evidence: true`, and apply
+        // rejects such a link as `unnamed_in_evidence`. CO-57: on the six CO-52 runs,
+        // 67 of 143 false positives were links to company/indigo and project/HQ, most
+        // on evidence that only held the name inside an identifier; a replay of this
+        // rule raised precision on the concept-project-link arm from 0.705 to 0.750
+        // and lost no gold link.
+        named_evidence: true,
         inputs,
         session_text: sessionText,
         pending_after_run: remaining,
@@ -466,7 +439,7 @@ export async function planOntologyRun(options) {
         instructions: [
             ...CANDIDATE_INSTRUCTIONS.slice(0, 3),
             ...(inputs.some((input) => input.read_path) ? [READ_PATH_INSTRUCTION] : []),
-            `${CANDIDATE_INSTRUCTIONS[3]} ${firstNamePeople ? FIRST_NAME_PEOPLE_INSTRUCTION : PERSON_NAME_INSTRUCTION}`,
+            `${CANDIDATE_INSTRUCTIONS[3]} ${FIRST_NAME_PEOPLE_INSTRUCTION}`,
             ...CANDIDATE_INSTRUCTIONS.slice(4),
         ],
     };

package/dist/lib/lanes/dropbox.d.ts

@@ -8,7 +8,6 @@
  * overlap.
  */
 import * as fs from "node:fs";
-import { probeProviderCompactionsSince } from "./compaction.js";
 import { tryReadLane } from "./store.js";
 import { type LaneRecord, type LaneState, type QuestionRecord } from "./types.js";
 export declare const DROPBOX_DIR = "dropbox";
@@ -59,7 +58,7 @@ export interface LaneDrainHookInput {
 }
 export interface RunDrainHookDeps {
     readLane?: typeof tryReadLane;
-    probeCompactionsSince?: typeof probeProviderCompactionsSince;
+    probeCompactionsSince?: typeof import("./compaction.js").probeProviderCompactionsSince;
 }
 export declare function mintClaimId(): string;
 export declare function assertSafeLaneId(laneId: string): void;

package/dist/lib/lanes/dropbox.js

@@ -10,9 +10,8 @@
 import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { probeProviderCompactionsSince, providerTranscriptSize, } from "./compaction.js";
 import { LanesError } from "./errors.js";
-import { MESSAGE_COMPACTION_REPLAY_NOTE, MESSAGE_REPLAY_STATE_NAME, } from "./message-replay.js";
+import { MESSAGE_COMPACTION_REPLAY_NOTE, MESSAGE_REPLAY_STATE_NAME, readMessageReplayState, updateMessageReplayTranscript, writeMessageReplayState, } from "./message-replay.js";
 import { LANES_RUNS_REL, readProcStarttime } from "./spawn.js";
 import { tryReadLane } from "./store.js";
 export const DROPBOX_DIR = "dropbox";
@@ -430,83 +429,6 @@ export function hookAdditionalContextJson(messages, hookEventName = "PreToolUse"
 function replayStatePath(hqRoot, laneId) {
     return path.join(dropboxDir(hqRoot, laneId), MESSAGE_REPLAY_STATE_NAME);
 }
-function safeProviderTranscriptPath(transcriptPath, provider, env) {
-    if (provider === "grok")
-        return transcriptPath;
-    const home = provider === "claude" ? env.CLAUDE_CONFIG_DIR : env.CODEX_HOME;
-    if (!home) {
-        throw new LanesError("message_replay_provider_home_missing", `Cannot validate ${provider} transcript without its provider home`);
-    }
-    if (!path.isAbsolute(transcriptPath) || path.extname(transcriptPath) !== ".jsonl") {
-        throw new LanesError("message_replay_transcript_path_invalid", `The ${provider} hook transcript path must be an absolute JSONL path`);
-    }
-    const configuredHomePath = path.resolve(home);
-    const homePath = fs.realpathSync(home);
-    const candidate = path.resolve(transcriptPath);
-    const expectedRoot = provider === "claude" ? "projects" : "sessions";
-    const assertWithinProviderHome = (root, resolvedTranscript, message) => {
-        const relative = path.relative(root, resolvedTranscript);
-        if (relative === "" ||
-            relative === ".." ||
-            relative.startsWith(`..${path.sep}`) ||
-            path.isAbsolute(relative) ||
-            relative.split(path.sep)[0] !== expectedRoot) {
-            throw new LanesError("message_replay_transcript_outside_provider_home", message);
-        }
-    };
-    try {
-        const realTranscript = fs.realpathSync(candidate);
-        assertWithinProviderHome(homePath, realTranscript, `The ${provider} hook transcript resolves outside its ${expectedRoot} directory`);
-        return realTranscript;
-    }
-    catch (err) {
-        if (err.code === "ENOENT") {
-            assertWithinProviderHome(configuredHomePath, candidate, `The ${provider} hook transcript is outside its configured ${expectedRoot} directory`);
-            return candidate;
-        }
-        throw err;
-    }
-}
-function readReplayState(filePath, turnId) {
-    const text = fs.readFileSync(filePath, "utf8");
-    let parsed;
-    try {
-        parsed = JSON.parse(text);
-    }
-    catch (err) {
-        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} is invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} is not an object`);
-    }
-    const state = parsed;
-    if (state.schema_version !== 1 ||
-        state.turn_id !== turnId ||
-        (state.last_compaction_marker !== null &&
-            (!Number.isSafeInteger(state.last_compaction_marker) || Number(state.last_compaction_marker) < 0)) ||
-        (state.transcript_offset !== undefined &&
-            (!Number.isSafeInteger(state.transcript_offset) || Number(state.transcript_offset) < 0)) ||
-        (state.transcript_path !== undefined && typeof state.transcript_path !== "string") ||
-        (state.flag_enabled !== undefined && typeof state.flag_enabled !== "boolean")) {
-        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} does not match the current provider turn`);
-    }
-    // Older state files persisted the removed per-turn flag. Accept it, but
-    // remove it before the next write so the stale cache does not live on.
-    delete state.flag_enabled;
-    return state;
-}
-function writeReplayState(filePath, state) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    const tempPath = `${filePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
-    fs.writeFileSync(tempPath, `${JSON.stringify(state)}\n`, { mode: 0o600 });
-    try {
-        fs.renameSync(tempPath, filePath);
-    }
-    catch (err) {
-        fs.rmSync(tempPath, { force: true });
-        throw err;
-    }
-}
 function deliveredMessagesForTurn(hqRoot, laneId, turnId) {
     const delivered = path.join(dropboxDir(hqRoot, laneId), DELIVERED_DIR);
     let names;
@@ -522,7 +444,8 @@ function deliveredMessagesForTurn(hqRoot, laneId, turnId) {
     return names.flatMap((name) => readClaimedFile(path.join(delivered, name), defaultDrainDeps()));
 }
 function reportReplayFailure(err) {
-    return `hq-lanes-drain: message compaction replay failed: ${err instanceof Error ? err.message : String(err)}\n`;
+    const code = err instanceof LanesError ? `${err.error}: ` : "";
+    return `hq-lanes-drain: message compaction replay failed: ${code}${err instanceof Error ? err.message : String(err)}\n`;
 }
 /**
  * Hook protocol. HQ_LANE_ID absent or empty → exit 0, empty stdout, empty stderr.
@@ -564,7 +487,7 @@ export async function runDrainHook(env, input = {}, deps = {}) {
                 const statePath = replayStatePath(hqRoot, laneId);
                 let state;
                 try {
-                    state = readReplayState(statePath, turnId);
+                    state = readMessageReplayState(statePath, turnId);
                 }
                 catch (err) {
                     if (err.code !== "ENOENT")
@@ -576,38 +499,14 @@ export async function runDrainHook(env, input = {}, deps = {}) {
                     if (!lane) {
                         throw new LanesError("message_replay_lane_missing", `Lane ${laneId} could not be read for compaction replay`);
                     }
-                    if (lane.provider === "grok") {
-                        state.last_compaction_marker = 0;
-                    }
-                    else {
-                        const transcriptPath = safeProviderTranscriptPath(input.transcript_path, lane.provider, env);
-                        if (state.last_compaction_marker === null ||
-                            state.transcript_path !== transcriptPath ||
-                            state.transcript_offset === undefined) {
-                            // Existing transcript history belongs to the turn's resume
-                            // prompt. Start watching only records appended from this point.
-                            state.last_compaction_marker = 0;
-                            state.transcript_path = transcriptPath;
-                            state.transcript_offset = providerTranscriptSize(transcriptPath);
-                        }
-                        else {
-                            const delta = (deps.probeCompactionsSince ?? probeProviderCompactionsSince)(transcriptPath, lane.provider, state.transcript_offset);
-                            state.transcript_offset = delta.next_offset;
-                            if (delta.replaced) {
-                                // A replaced or truncated transcript establishes a new
-                                // baseline; it is not evidence of a fresh compaction.
-                                state.last_compaction_marker = 0;
-                            }
-                            else if (delta.count > 0) {
-                                state.last_compaction_marker += delta.count;
-                                replayed = deliveredMessagesForTurn(hqRoot, laneId, turnId);
-                                if (replayed.length > 0)
-                                    replayNote = MESSAGE_COMPACTION_REPLAY_NOTE;
-                            }
-                        }
+                    const update = updateMessageReplayTranscript(state, input.transcript_path, lane.provider, env, deps.probeCompactionsSince);
+                    if (update === "compacted") {
+                        replayed = deliveredMessagesForTurn(hqRoot, laneId, turnId);
+                        if (replayed.length > 0)
+                            replayNote = MESSAGE_COMPACTION_REPLAY_NOTE;
                     }
                 }
-                writeReplayState(statePath, state);
+                writeMessageReplayState(statePath, state);
             }
             catch (err) {
                 // Replay is advisory hook context. Report failures but let the provider

package/dist/lib/lanes/message-replay.d.ts

@@ -1,3 +1,5 @@
+import { probeProviderCompactionsSince } from "./compaction.js";
+import type { LaneProvider } from "./types.js";
 export declare const MESSAGE_REPLAY_STATE_NAME = "message-compaction-replay.json";
 export declare const MESSAGE_COMPACTION_REPLAY_NOTE = "These messages were delivered before a context compaction and still apply.";
 export interface MessageReplayState {
@@ -9,5 +11,11 @@ export interface MessageReplayState {
     transcript_offset?: number;
     /** Canonical transcript path for this provider turn. */
     transcript_path?: string;
+    /** Provider needed to inspect appended transcript records without loading the lane store. */
+    provider?: LaneProvider;
 }
+export type ReplayTranscriptUpdate = "baseline" | "unchanged" | "replaced" | "compacted";
+export declare function readMessageReplayState(filePath: string, turnId: string, onLegacyFlag?: () => void): MessageReplayState;
+export declare function writeMessageReplayState(filePath: string, state: MessageReplayState): void;
+export declare function updateMessageReplayTranscript(state: MessageReplayState, transcriptPath: string, provider: LaneProvider, env: NodeJS.ProcessEnv, probe?: typeof probeProviderCompactionsSince): ReplayTranscriptUpdate;
 //# sourceMappingURL=message-replay.d.ts.map

package/dist/lib/lanes/message-replay.js

@@ -1,3 +1,122 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { probeProviderCompactionsSince, providerTranscriptSize, } from "./compaction.js";
+import { LanesError } from "./errors.js";
 export const MESSAGE_REPLAY_STATE_NAME = "message-compaction-replay.json";
 export const MESSAGE_COMPACTION_REPLAY_NOTE = "These messages were delivered before a context compaction and still apply.";
+export function readMessageReplayState(filePath, turnId, onLegacyFlag) {
+    const text = fs.readFileSync(filePath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} is invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} is not an object`);
+    }
+    const state = parsed;
+    if (state.schema_version !== 1 ||
+        state.turn_id !== turnId ||
+        (state.last_compaction_marker !== null &&
+            (!Number.isSafeInteger(state.last_compaction_marker) || Number(state.last_compaction_marker) < 0)) ||
+        (state.transcript_offset !== undefined &&
+            (!Number.isSafeInteger(state.transcript_offset) || Number(state.transcript_offset) < 0)) ||
+        (state.transcript_path !== undefined && typeof state.transcript_path !== "string") ||
+        (state.provider !== undefined && !isLaneProvider(state.provider)) ||
+        (state.flag_enabled !== undefined && typeof state.flag_enabled !== "boolean")) {
+        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} does not match the current provider turn`);
+    }
+    // Older state files persisted the removed per-turn flag. Accept it, but
+    // remove it before the next write so the stale cache does not live on.
+    if (state.flag_enabled !== undefined) {
+        delete state.flag_enabled;
+        onLegacyFlag?.();
+    }
+    return state;
+}
+function isLaneProvider(value) {
+    return value === "claude" || value === "codex" || value === "grok";
+}
+export function writeMessageReplayState(filePath, state) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    fs.writeFileSync(tempPath, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+    try {
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (err) {
+        fs.rmSync(tempPath, { force: true });
+        throw err;
+    }
+}
+function safeProviderTranscriptPath(transcriptPath, provider, env) {
+    if (provider === "grok")
+        return transcriptPath;
+    const home = provider === "claude" ? env.CLAUDE_CONFIG_DIR : env.CODEX_HOME;
+    if (!home) {
+        throw new LanesError("message_replay_provider_home_missing", `Cannot validate ${provider} transcript without its provider home`);
+    }
+    if (!path.isAbsolute(transcriptPath) || path.extname(transcriptPath) !== ".jsonl") {
+        throw new LanesError("message_replay_transcript_path_invalid", `The ${provider} hook transcript path must be an absolute JSONL path`);
+    }
+    const configuredHomePath = path.resolve(home);
+    const homePath = fs.realpathSync(home);
+    const candidate = path.resolve(transcriptPath);
+    const expectedRoot = provider === "claude" ? "projects" : "sessions";
+    const assertWithinProviderHome = (root, resolvedTranscript, message) => {
+        const relative = path.relative(root, resolvedTranscript);
+        if (relative === "" ||
+            relative === ".." ||
+            relative.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relative) ||
+            relative.split(path.sep)[0] !== expectedRoot) {
+            throw new LanesError("message_replay_transcript_outside_provider_home", message);
+        }
+    };
+    try {
+        const realTranscript = fs.realpathSync(candidate);
+        assertWithinProviderHome(homePath, realTranscript, `The ${provider} hook transcript resolves outside its ${expectedRoot} directory`);
+        return realTranscript;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            assertWithinProviderHome(configuredHomePath, candidate, `The ${provider} hook transcript is outside its configured ${expectedRoot} directory`);
+            return candidate;
+        }
+        throw err;
+    }
+}
+export function updateMessageReplayTranscript(state, transcriptPath, provider, env, probe = probeProviderCompactionsSince) {
+    if (provider === "grok") {
+        state.provider = provider;
+        state.last_compaction_marker = 0;
+        return "unchanged";
+    }
+    const canonicalPath = safeProviderTranscriptPath(transcriptPath, provider, env);
+    const providerChanged = state.provider !== undefined && state.provider !== provider;
+    state.provider = provider;
+    if (providerChanged ||
+        state.last_compaction_marker === null ||
+        state.transcript_path !== canonicalPath ||
+        state.transcript_offset === undefined) {
+        state.last_compaction_marker = 0;
+        state.transcript_path = canonicalPath;
+        state.transcript_offset = providerTranscriptSize(canonicalPath);
+        return "baseline";
+    }
+    const delta = probe(canonicalPath, provider, state.transcript_offset);
+    state.transcript_offset = delta.next_offset;
+    if (delta.replaced) {
+        state.last_compaction_marker = 0;
+        return "replaced";
+    }
+    if (delta.count > 0) {
+        state.last_compaction_marker += delta.count;
+        return "compacted";
+    }
+    return "unchanged";
+}
 //# sourceMappingURL=message-replay.js.map

package/dist/lib/lanes/store.js

@@ -532,26 +532,44 @@ export function parseLaneRecord(raw, filePath) {
         const details = raw.queued_details;
         if (details === null || typeof details !== "object" || Array.isArray(details) ||
             typeof details.reason !== "string") {
-            throw new LaneSchemaError("queued_details must describe a worker_profile_changed queue reason", {
+            throw new LaneSchemaError("queued_details must describe a supported queue condition", {
                 path: filePath,
                 field: "queued_details",
             });
         }
         const detailsRecord = details;
-        if (detailsRecord.reason !== "worker_profile_changed" ||
-            (detailsRecord.expected_hash !== null && typeof detailsRecord.expected_hash !== "string") ||
-            typeof detailsRecord.actual_hash !== "string" || detailsRecord.actual_hash === "" ||
-            typeof detailsRecord.recovery_command !== "string" || detailsRecord.recovery_command.trim() === "") {
-            throw new LaneSchemaError("queued_details must describe a worker_profile_changed queue reason", {
-                path: filePath,
-                field: "queued_details",
-            });
+        if (detailsRecord.reason === "worker_profile_changed") {
+            if ((detailsRecord.expected_hash !== null && typeof detailsRecord.expected_hash !== "string") ||
+                typeof detailsRecord.actual_hash !== "string" || detailsRecord.actual_hash === "" ||
+                typeof detailsRecord.recovery_command !== "string" || detailsRecord.recovery_command.trim() === "") {
+                throw new LaneSchemaError("queued_details must describe a worker_profile_changed queue reason", {
+                    path: filePath,
+                    field: "queued_details",
+                });
+            }
+            if (raw.queued_reason !== "worker_profile_changed") {
+                throw new LaneSchemaError("queued_details requires queued_reason worker_profile_changed", {
+                    path: filePath,
+                    field: "queued_details",
+                    queued_reason: raw.queued_reason,
+                });
+            }
+        }
+        else if (detailsRecord.reason === "outpost_dispatch_unknown") {
+            if (raw.state !== "queued" ||
+                detailsRecord.outcome_unknown !== true ||
+                (detailsRecord.command_id !== null &&
+                    (typeof detailsRecord.command_id !== "string" || detailsRecord.command_id.trim() === ""))) {
+                throw new LaneSchemaError("queued_details must describe an unknown Outpost dispatch on a queued lane", {
+                    path: filePath,
+                    field: "queued_details",
+                });
+            }
         }
-        if (raw.queued_reason !== "worker_profile_changed") {
-            throw new LaneSchemaError("queued_details requires queued_reason worker_profile_changed", {
+        else {
+            throw new LaneSchemaError("queued_details must describe a supported queue condition", {
                 path: filePath,
                 field: "queued_details",
-                queued_reason: raw.queued_reason,
             });
         }
     }

package/dist/lib/lanes/types.d.ts

@@ -175,12 +175,16 @@ export declare const LANE_PROVIDERS: readonly ["claude", "codex", "grok"];
 export type LaneProvider = (typeof LANE_PROVIDERS)[number];
 export declare const QUEUED_REASONS: readonly ["cap", "provider_cap", "account_cap", "profile_cap", "queue_position", "throttle", "provider_binary_missing", "account_retry", "worker_profile_changed"];
 export type QueuedReason = (typeof QUEUED_REASONS)[number];
-export interface QueuedDetails {
+export type QueuedDetails = {
     reason: "worker_profile_changed";
     expected_hash: string | null;
     actual_hash: string;
     recovery_command: string;
-}
+} | {
+    reason: "outpost_dispatch_unknown";
+    outcome_unknown: true;
+    command_id: string | null;
+};
 export declare function isQueuedReason(value: unknown): value is QueuedReason;
 export declare const HOST_KINDS: readonly ["local", "outpost"];
 export type HostKind = (typeof HOST_KINDS)[number];

package/dist/lib/lanes/types.js

@@ -231,7 +231,7 @@ export const LANE_FIELD_WRITERS = {
     last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn", "command"], model_source: ["creator", "spawn", "command"], effort: ["creator", "spawn", "command"], effort_source: ["creator", "spawn", "command"], fast_mode: ["spawn"],
     last_message_at: ["command"], status_gate: ["spawn", "watcher"], status_gate_history: ["watcher"], blocker_freshness_state: ["watcher"], kr_freshness_state: ["watcher"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],
     overdue: ["reconcile"], overdue_at: ["reconcile"], last_host_report_at: ["watcher", "spawn", "reconcile"], stalled: ["watcher"], stalled_at: ["watcher"], stalled_reason: ["watcher"],
-    admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], stop_history: ["command"], settings_history: ["command"], pending_settings: ["command", "spawn"], interrupted_at: ["command", "watcher", "reconcile"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
+    admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], stop_history: ["command", "reconcile"], settings_history: ["command"], pending_settings: ["command", "spawn"], interrupted_at: ["command", "watcher", "reconcile"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
     quota_reset_at: ["watcher", "reconcile"], model_quota_marker: ["watcher", "reconcile"], outpost_command_id: ["command"],
     provider_session_id: ["watcher", "command", "spawn"], provider_session_id_absent: ["watcher", "command"], provider_home_at_spawn: ["spawn"], last_resume: ["spawn"], last_run_usage: ["watcher"], last_run_usage_at: ["watcher"], envelope_repair: ["watcher", "reconcile"], envelope_validation_errors: ["watcher"], last_progress_event_at: ["watcher"],
 };