@indigoai-us/hq-cli 5.287.0 → 5.288.0

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.288.0] — 2026-09-29
+
 ## [5.287.0] — 2026-09-29
 - Group hook-timeout events by script while preserving triage diagnostics.
 - Preserve safe slow-child script basenames in hook-timeout diagnostics.
@@ -16,6 +18,40 @@
   directories are cloud-backed, and points to `hq sync pull --all` and
   `hq sync status` for cloud-backed companies.
 
+### Fixed
+
+- Confirm primary-dispatched Outpost profile recovery when it is queued for
+  reconcile, and sync the cleared recovery state to the primary lane mirror.
+- Cache-first `hq lanes list` now allows one detached Outpost summary refresh
+  per HQ root at a time, avoiding duplicate work from overlapping list calls.
+
+### Fixed
+
+- The lanes hook reads only transcript bytes appended since its last check.
+  It still replays compaction messages and resets the offset when a transcript
+  is replaced or truncated.
+
+### Added
+
+- `hq core ontology merge-copies --only <file>` handles only the copy -> original pairs listed in a JSON file and reports every other found pair as skipped (`not_listed`).
+
+### Changed
+
+- The checkpoint ontology step always applies its ten quality rules (company
+  brief, annotation stripping on grok, grok-first backend, no link aliases,
+  first-name people, ambiguous concept links, dominant sibling link, hub
+  mention floor, concept-project link, named evidence). Their
+  `checkpoint.ontology.*` flags, on for everyone since 2026-09-29, are no
+  longer read.
+
+### Added
+
+- Record company-scoped exposure for printed CLI plan-limit notices when the default-off `billing.limit-at-action-prompt` flag is enabled; count an upgrade engagement only after the user confirms opening the link.
+
+### Fixed
+
+- `hq secrets` and other noninteractive person-token callers reuse a fresh same-principal session written by another process while a stale refresh is rejected.
+
 ## [5.286.0] — 2026-09-29
 
 ### Changed
@@ -27,11 +63,6 @@
   it, and output the old daemon had not read reaches the new one. Other
   platforms keep the anonymous pipe.
 
-### Fixed
-
-- Cache-first `hq lanes list` now allows one detached Outpost summary refresh
-  per HQ root at a time, avoiding duplicate work from overlapping list calls.
-
 ## [5.285.0] — 2026-09-29
 
 - Route eligible Linux CI jobs onto ARM runners while retaining existing test and platform gates.
@@ -42,6 +73,13 @@
 
 ### Fixed
 
+- Recover a queued Outpost lane held for `worker_profile_changed` with its
+  printed `hq lanes resume <id> --worker <profile>` command. The lane owner's
+  profile copy is authoritative: the command records an authorized re-pin in
+  history, leaves the lane queued for normal reconcile admission, and syncs the
+  cleared recovery state back to the primary mirror. Other queued lanes still
+  require `hq lanes admit`.
+
 - A remote `hq lanes list` read no longer dispatches owner hire summaries,
   capacity probes, or mirror snapshots to other Outposts. Two Outposts that
   each held a lane placed on the other ran `hq lanes list --json` on each other

package/dist/command-catalog.generated.d.ts

@@ -5205,6 +5205,9 @@ export declare const COMMAND_CATALOG: readonly [{
             }, {
                 readonly flags: "--limit <n>";
                 readonly description: "handle at most this many copies";
+            }, {
+                readonly flags: "--only <file>";
+                readonly description: "handle only the copy -> original pairs listed in this JSON file";
             }, {
                 readonly flags: "--json";
                 readonly description: "print JSON";

package/dist/command-catalog.generated.js

@@ -6730,6 +6730,10 @@ export const COMMAND_CATALOG = [
                                 "flags": "--limit <n>",
                                 "description": "handle at most this many copies"
                             },
+                            {
+                                "flags": "--only <file>",
+                                "description": "handle only the copy -> original pairs listed in this JSON file"
+                            },
                             {
                                 "flags": "--json",
                                 "description": "print JSON"

package/dist/commands/agent-enroll.js

@@ -20,6 +20,7 @@ import * as os from "node:os";
 import { CLI_VERSION } from "../cli-version.js";
 import { DEFAULT_VAULT_API_URL, personTokenCacheFile, } from "../utils/cognito-session.js";
 import { HQ_CLIENT_NAME } from "../utils/vault-api.js";
+import { queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, } from "../utils/cli-telemetry.js";
 import { networkTransportErrorCode } from "../utils/network-transport-error.js";
 import { canOfferTeamUpgrade, formatUpgradeRefusal, isPlanGateError, offerUpgradeLink, planGateErrorFromPayload, } from "../utils/plan-gate-error.js";
 import { generateHostKeyPair, machineCredsFileExists, readExternalMachineCreds, writeHostKeyPair, writeMachineCreds, } from "../lib/agent-kit/creds.js";
@@ -373,9 +374,14 @@ export function registerAgentEnrollCommand(agent) {
             else if (err instanceof EnrollError && err.upgradeUrl) {
                 const interactive = canOfferTeamUpgrade();
                 console.error(chalk.red(formatEnrollFailureMessage(err, { urlOnly: !interactive })));
+                const exposure = err.code === "billing_required"
+                    ? queueCliLimitNoticeExposure("agents", "refusal")
+                    : null;
                 if (interactive) {
                     try {
-                        await offerUpgradeLink(err.upgradeUrl, { interactive: true });
+                        const opened = await offerUpgradeLink(err.upgradeUrl, { interactive: true });
+                        if (opened)
+                            queueCliLimitNoticeEngagement(exposure);
                     }
                     catch (openErr) {
                         const message = openErr instanceof Error ? openErr.message : String(openErr);
@@ -386,7 +392,9 @@ export function registerAgentEnrollCommand(agent) {
             else {
                 console.error(chalk.red(err instanceof Error ? err.message : String(err)));
             }
-            process.exit(1);
+            // Let the CLI's bounded finalization flush the best-effort prompt
+            // telemetry before the process exits with the same failure status.
+            process.exitCode = 1;
         }
     });
 }

package/dist/commands/agents.d.ts

@@ -62,6 +62,7 @@ export declare function agentCreatePlanLimitFromPayload(status: number, body: un
 /** Print a server-priced plan block without minting or rewriting its URL. */
 export declare function surfaceAgentCreatePlanLimit(planLimit: AgentCreatePlanLimit, opts?: {
     json?: boolean;
+    companyUid?: string;
 }): Promise<void>;
 /**
  * Resolve a closed-set option value, or exit(1) with a message naming the

package/dist/commands/agents.js

@@ -34,6 +34,7 @@ import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { maxLength } from "../utils/table-width.js";
 import { DEFAULT_VAULT_API_URL } from "../utils/cognito-session.js";
 import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
+import { queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, } from "../utils/cli-telemetry.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 import { consoleOrigin } from "./integrations-connect.js";
 import { launchSessionManagerPlugin, SessionManagerPluginLaunchError, TerminalSessionTimeoutError, waitForTerminalSession, } from "@indigoai-us/hq-cloud/outposts/node";
@@ -128,13 +129,14 @@ function formatServerPrice(amountMinor, currency) {
 async function offerAgentCheckout(url) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
     try {
-        await offerUpgradeLink(url, {
+        return await offerUpgradeLink(url, {
             interactive: true,
             ask: (question) => new Promise((resolve) => rl.question(question, resolve)),
         });
     }
     catch {
         console.error("Could not open the upgrade page automatically. Use the URL above.");
+        return false;
     }
     finally {
         rl.close();
@@ -149,11 +151,14 @@ export async function surfaceAgentCreatePlanLimit(planLimit, opts = {}) {
     if (!planLimit.checkoutUrl) {
         console.error(reason);
         console.error("Ask a company owner to upgrade before creating an agent.");
+        queueCliLimitNoticeExposure("agents", "refusal", opts.companyUid);
         return;
     }
     console.error(formatUpgradeRefusal(reason, planLimit.checkoutUrl, { urlOnly: !interactive }));
-    if (interactive)
-        await offerAgentCheckout(planLimit.checkoutUrl);
+    const exposure = queueCliLimitNoticeExposure("agents", "refusal", opts.companyUid);
+    if (interactive && await offerAgentCheckout(planLimit.checkoutUrl)) {
+        queueCliLimitNoticeEngagement(exposure);
+    }
 }
 /**
  * Resolve a closed-set option value, or exit(1) with a message naming the
@@ -1548,7 +1553,10 @@ export function registerAgentsCommand(program) {
                     if (!err.agentCreatePlanLimit) {
                         throw new Error("HQ Pro returned an unrecognized agent payment-required response.");
                     }
-                    await surfaceAgentCreatePlanLimit(err.agentCreatePlanLimit, opts);
+                    await surfaceAgentCreatePlanLimit(err.agentCreatePlanLimit, {
+                        ...opts,
+                        companyUid,
+                    });
                     // Keep the payment-required status through normal CLI teardown.
                     // Unlike process.exit(), this is testable and cannot be caught by
                     // this action's outer error boundary as a generic failure.

package/dist/commands/core-ontology.d.ts

@@ -9,7 +9,7 @@
  */
 import { Command } from "commander";
 import { type FlagReader } from "../lib/checkpoint-ontology/plan.js";
-import { type DeleteVaultKey } from "../lib/checkpoint-ontology/merge-copies.js";
+import { type DeleteVaultKey, type ListedPair } from "../lib/checkpoint-ontology/merge-copies.js";
 export declare const ONTOLOGY_PAYLOAD_FILE = "payload.json";
 /** The hq-flags read, scoped to the payload company. */
 export declare const registryFlagReader: FlagReader;
@@ -32,8 +32,11 @@ export interface MergeCopiesCommandOptions {
     delete?: boolean;
     variants?: boolean;
     limit?: number;
+    only?: string;
     json?: boolean;
 }
+/** Reads a `--only` file: a JSON array of `{ copy, original }` company-relative paths. */
+export declare function readListedPairs(file: string): ListedPair[];
 /**
  * `hq core ontology merge-copies`: merge `<slug> <n>.md` copies into their
  * original (`--apply`), then delete merged copies from the vault

package/dist/commands/core-ontology.js

@@ -153,8 +153,31 @@ function mergeCopiesSummary(report) {
         lines.push(`  held ${plan.copy}: ${plan.held}`);
     for (const error of report.errors)
         lines.push(`  error ${error.path}: ${error.error}`);
+    for (const entry of report.only_unmatched ?? [])
+        lines.push(`  not found ${entry.copy} -> ${entry.original}`);
     return lines.join("\n");
 }
+/** Reads a `--only` file: a JSON array of `{ copy, original }` company-relative paths. */
+export function readListedPairs(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new OntologyUsageError(`ontology: --only file ${file} is not readable JSON: ${error.message}`);
+    }
+    if (!Array.isArray(parsed) ||
+        parsed.length === 0 ||
+        !parsed.every((entry) => {
+            if (!entry || typeof entry !== "object")
+                return false;
+            const record = entry;
+            return typeof record.copy === "string" && typeof record.original === "string";
+        })) {
+        throw new OntologyUsageError("ontology: --only must be a non-empty JSON array of { copy, original } paths");
+    }
+    return parsed.map((entry) => ({ copy: entry.copy, original: entry.original }));
+}
 /**
  * `hq core ontology merge-copies`: merge `<slug> <n>.md` copies into their
  * original (`--apply`), then delete merged copies from the vault
@@ -171,6 +194,7 @@ export async function runOntologyMergeCopies(hqRoot, slug, options, deps = {}) {
     if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1)) {
         throw new OntologyUsageError("ontology: --limit must be a positive whole number");
     }
+    const only = options.only !== undefined ? readListedPairs(options.only) : undefined;
     const resolution = resolveOntologyCompany(hqRoot, slug);
     if (!resolution.ok)
         throw new OntologyUsageError(`ontology: company rejected: ${resolution.reason}`);
@@ -195,6 +219,7 @@ export async function runOntologyMergeCopies(hqRoot, slug, options, deps = {}) {
         now: deps.now?.() ?? new Date(),
         ...(options.variants ? { pairKind: "variants" } : {}),
         ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        ...(only ? { only } : {}),
         ...(deleteVaultKey ? { deleteVaultKey } : {}),
     });
     return options.json ? JSON.stringify(report, null, 2) : mergeCopiesSummary(report);
@@ -248,6 +273,7 @@ export function registerCoreOntologyCommand(core) {
         .option("--delete", "delete fully merged copies from the vault by exact key (after sync pushed the merge)")
         .option("--variants", "merge two-file duplicate groups whose names differ only in case, spacing or punctuation (checkpoint.ontology.merge-variants)")
         .option("--limit <n>", "handle at most this many copies", (value) => Number(value))
+        .option("--only <file>", "handle only the copy -> original pairs listed in this JSON file")
         .option("--json", "print JSON")
         .option("--hq-root <path>", "HQ installation to operate on")
         .action(async (options) => {

package/dist/commands/lanes-resume.js

@@ -153,10 +153,27 @@ export function createLaneResumeHandlers(deps) {
         if (opts.account !== undefined && !providerSessionPortable(lane.provider)) {
             throw new LanesError("provider_session_not_portable", sessionNotPortableMessage(lane.provider), { lane_id: laneId, provider: lane.provider });
         }
-        if (lane.state === "queued") {
+        if (lane.state === "queued" &&
+            (lane.queued_reason !== "worker_profile_changed" || opts.worker === undefined)) {
             throw new LanesError("lane_not_resumable", `Lane ${laneId} is queued; use hq lanes admit ${laneId} to request admission`, { lane_id: laneId, state: lane.state, admission_command: `hq lanes admit ${laneId}` });
         }
-        const refusal = resumeCommandRefusal(lane, { allowFailed: opts.fromFailed === true });
+        const queuedProfileRecovery = lane.state === "queued" &&
+            lane.queued_reason === "worker_profile_changed" &&
+            opts.worker !== undefined;
+        if (queuedProfileRecovery && (opts.text !== undefined ||
+            opts.project !== undefined ||
+            opts.story !== undefined ||
+            opts.account !== undefined ||
+            opts.model !== undefined ||
+            opts.effort !== undefined ||
+            opts.keepAlive !== undefined ||
+            opts.meshCompany !== undefined ||
+            opts.compact === false)) {
+            throw new LanesError("worker_profile_recovery_options_invalid", "Queued worker-profile recovery accepts only --worker; rerun hq lanes resume after reconcile admits the lane", { lane_id: laneId });
+        }
+        const refusal = queuedProfileRecovery
+            ? null
+            : resumeCommandRefusal(lane, { allowFailed: opts.fromFailed === true });
         if (refusal !== null) {
             throw new LanesError(refusal.error, refusal.message, {
                 lane_id: laneId,
@@ -206,6 +223,28 @@ export function createLaneResumeHandlers(deps) {
         if (resumeProfile !== undefined && (opts.account === undefined || keepCurrentAccount)) {
             validateResumeProfileModel(ctx, lane, resumeProfile.profile);
         }
+        if (lane.state === "queued" && lane.queued_reason === "worker_profile_changed") {
+            if (resumeProfile === undefined) {
+                throw new LanesError("worker_profile_required", `Lane ${laneId} needs --worker ${lane.worker_profile ?? "<profile>"} to recover its queued profile`, { lane_id: laneId, worker: lane.worker_profile ?? null });
+            }
+            const recovered = recordResumeSetup(ctx, lane, {
+                profile: resumeProfile,
+                ...(profileRepin !== undefined ? { profileRepin } : {}),
+                clearWorkerProfileChangedQueue: true,
+            });
+            printJson({
+                ok: true,
+                action: "resume",
+                lane_id: laneId,
+                delivery: "profile_repin",
+                delivery_status: "queued_for_reconcile",
+                profile_repin: profileRepin !== undefined
+                    ? recovered.worker_profile_repin_history?.at(-1) ?? null
+                    : null,
+                lane: recovered,
+            });
+            return;
+        }
         const automaticAccountSelection = opts.account === undefined
             ? await selectAutomaticClaudeResumeAccount(ctx, lane, resumeProfile, { repairUnavailableAccount: true })
             : undefined;

package/dist/commands/lanes-shared.d.ts

@@ -113,6 +113,8 @@ export interface RecordResumeSetupInput {
     meshCompany?: LaneCompanyRef;
     threadId?: string;
     profileRepin?: ResumeProfileRepinAuthorization;
+    /** Clear only the recoverable worker_profile_changed queue after its profile is revalidated. */
+    clearWorkerProfileChangedQueue?: boolean;
 }
 export declare function accountRequestKeepsCurrentLane(lane: LaneRecord, rawAccount: string): boolean;
 export declare function assertCurrentResumeAccountAvailable(ctx: Ctx, lane: LaneRecord): void;

package/dist/commands/lanes.js

@@ -3792,6 +3792,29 @@ function authorizeResumeProfileRepin(ctx, lane, profile, encodedContext) {
                 : workerProfileHashMismatch(lane, profile);
         }
     }
+    if (lane.state === "queued" && lane.queued_reason === "worker_profile_changed" && profile !== undefined) {
+        // The hash is for the executing Outpost's profile copy, not the primary
+        // host's copy. Only the lane senior (or its authorized owner dispatch) may
+        // clear this hold after resolving that local copy.
+        if (lane.host.kind !== "outpost" || lane.worker_profile !== profile.id) {
+            throw new LanesError("worker_profile_hash_mismatch", `Queued profile recovery for lane ${lane.lane_id} must use its original Outpost worker profile`, {
+                lane_id: lane.lane_id,
+                worker: profile.id,
+                lane_worker: lane.worker_profile ?? null,
+                outpost: lane.host.kind === "outpost" ? lane.host.id : null,
+            });
+        }
+        if (ssmOwnerDispatch) {
+            if (context === undefined)
+                throw workerProfileHashMismatch(lane, profile);
+        }
+        else {
+            const callerAuthorization = callerSeniorAuthorization(ctx, lane.senior);
+            if (!callerAuthorization.authorized) {
+                throw workerProfileHashMismatch(lane, profile, callerAuthorization);
+            }
+        }
+    }
     if (profile === undefined ||
         (lane.host.kind !== "outpost" && !(ssmOwnerDispatch && laneGrantTargetHostedHere(ctx, lane))) ||
         lane.worker_profile_hash === profile.profile.contentHash) {
@@ -4059,7 +4082,13 @@ async function dispatchOutpostLaneCommand(ctx, lane, action, options, behavior =
                                 remote.lane !== null &&
                                 typeof remote.lane === "object" &&
                                 !Array.isArray(remote.lane) &&
-                                remote.lane.state === "queued")));
+                                remote.lane.state === "queued") ||
+                            (remote.delivery_status === "queued_for_reconcile" &&
+                                remote.lane !== null &&
+                                typeof remote.lane === "object" &&
+                                !Array.isArray(remote.lane) &&
+                                remote.lane.state === "queued" &&
+                                remote.lane.queued_reason !== "worker_profile_changed")));
     if (!resultConfirmed) {
         throw new LanesError("outpost_delivery_unconfirmed", `Outpost ${outpostId} completed exec without a confirmed ${action} result for lane ${lane.lane_id}`, {
             lane_id: lane.lane_id,
@@ -5853,6 +5882,7 @@ function recordResumeSetup(ctx, lane, input) {
         input.keepAlive === undefined &&
         input.cliModel === undefined &&
         input.meshCompany === undefined &&
+        input.clearWorkerProfileChangedQueue !== true &&
         lane.keep_alive_blocked_reason !== "terminal_state")
         return lane;
     return casUpdateLane(ctx.hqRoot(), lane.lane_id, (current) => {
@@ -5862,12 +5892,28 @@ function recordResumeSetup(ctx, lane, input) {
         if (input.profileRepin !== undefined) {
             assertResumeProfileRepinStillAuthorized(ctx, current, input.profileRepin);
         }
+        if (input.clearWorkerProfileChangedQueue === true && (current.state !== "queued" ||
+            current.queued_reason !== "worker_profile_changed" ||
+            input.profile === undefined ||
+            current.worker_profile !== input.profile.id ||
+            (current.worker_profile_hash !== input.profile.profile.contentHash && input.profileRepin === undefined))) {
+            throw new LanesError("lane_resume_setup_conflict", `Lane ${lane.lane_id} is no longer eligible for worker-profile recovery; run the recovery command again`, {
+                lane_id: lane.lane_id,
+                state: current.state,
+                queued_reason: current.queued_reason ?? null,
+            });
+        }
         const next = { ...current };
         // An operator resume takes the lane out of the terminal state reconcile
         // recorded, so keep-alive may continue it again after this turn.
         if (next.keep_alive_blocked_reason === "terminal_state")
             next.keep_alive_blocked_reason = undefined;
         applyResumeProfileAndEffort(current, next, { ...input, at: ctx.now().toISOString() });
+        if (input.clearWorkerProfileChangedQueue === true) {
+            next.queued_reason = undefined;
+            next.queued_details = undefined;
+            next.admission_reserved_at = undefined;
+        }
         if (input.cliModel !== undefined) {
             next.model = input.cliModel.trim();
             next.model_source = "cli";

package/dist/lanes-drain-hook.d.ts

@@ -1,2 +1,14 @@
+import type { LaneDrainHookInput } from "./lib/lanes/dropbox.js";
+interface DrainHookResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+type DropboxModule = typeof import("./lib/lanes/dropbox.js");
+export interface DrainHookRunnerDeps {
+    /** Test seam for proving the steady-state path does not load the drainer. */
+    loadDropbox?: () => Promise<Pick<DropboxModule, "runDrainHook">>;
+}
+export declare function runLaneDrainHook(env: NodeJS.ProcessEnv, input?: LaneDrainHookInput, inputError?: string, deps?: DrainHookRunnerDeps): Promise<DrainHookResult>;
 export {};
 //# sourceMappingURL=lanes-drain-hook.d.ts.map

package/dist/lanes-drain-hook.js

@@ -1,6 +1,8 @@
 import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MESSAGE_REPLAY_STATE_NAME, readMessageReplayState, updateMessageReplayTranscript, writeMessageReplayState, } from "./lib/lanes/message-replay.js";
 function parseHookInput(text) {
     if (text.trim() === "")
         return {};
@@ -72,38 +74,34 @@ function dropboxMayNeedDrain(box) {
     }
     return false;
 }
-function replayMayNeedWork(box, turnId, input) {
+function replayMayNeedWork(box, turnId, input, env) {
     if (!/^[A-Za-z0-9-]{1,80}$/.test(turnId))
         return false;
-    if (input.transcript_path)
-        return true;
-    let text;
-    const statePath = path.join(box, "message-compaction-replay.json");
+    const statePath = path.join(box, MESSAGE_REPLAY_STATE_NAME);
+    let state;
+    let hasLegacyFlag = false;
     try {
-        text = fs.readFileSync(statePath, "utf8");
+        state = readMessageReplayState(statePath, turnId, () => {
+            hasLegacyFlag = true;
+        });
     }
     catch {
         // Keep the existing named replay error behavior for missing or unreadable state.
         return true;
     }
+    if (hasLegacyFlag || !input.transcript_path)
+        return hasLegacyFlag;
+    if (!state.provider)
+        return true;
     try {
-        const parsed = JSON.parse(text);
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        const update = updateMessageReplayTranscript(state, input.transcript_path, state.provider, env);
+        if (update === "compacted")
             return true;
-        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) {
-            return true;
-        }
+        writeMessageReplayState(statePath, state);
         return false;
     }
     catch {
+        // The full path preserves the existing named replay error reporting.
         return true;
     }
 }
@@ -125,52 +123,42 @@ function recordToolActivity(hqRoot, laneId) {
         return `hq-lanes-drain: failed to record tool activity: ${err instanceof Error ? err.message : String(err)}\n`;
     }
 }
-function finish(result, inputError) {
+function finish(result) {
     if (result.stdout)
         process.stdout.write(result.stdout);
-    if (inputError || result.stderr)
-        process.stderr.write(`${inputError}${result.stderr}`);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
     process.exitCode = result.exitCode;
 }
-async function runFullPath(input, inputError) {
-    const { runDrainHook } = await import("./lib/lanes/dropbox.js");
-    finish(await runDrainHook(process.env, input), inputError);
+async function runFullPath(env, input, deps) {
+    const loadDropbox = deps.loadDropbox ?? (() => import("./lib/lanes/dropbox.js"));
+    const { runDrainHook } = await loadDropbox();
+    return runDrainHook(env, input);
 }
-async function main() {
-    const chunks = [];
-    for await (const chunk of process.stdin)
-        chunks.push(Buffer.from(chunk));
-    const text = Buffer.concat(chunks).toString("utf8");
-    let input = {};
-    let inputError = "";
-    try {
-        input = parseHookInput(text);
-    }
-    catch (err) {
-        inputError = `hq-lanes-drain: ${err instanceof Error ? err.message : String(err)}\n`;
-    }
-    const laneId = process.env.HQ_LANE_ID ?? "";
+export async function runLaneDrainHook(env, input = {}, inputError = "", deps = {}) {
+    const withInputError = (result) => ({
+        ...result,
+        stderr: `${inputError}${result.stderr}`,
+    });
+    const laneId = env.HQ_LANE_ID ?? "";
     if (laneId === "") {
-        finish({ exitCode: 0, stdout: "", stderr: "" }, inputError);
-        return;
+        return withInputError({ exitCode: 0, stdout: "", stderr: "" });
     }
-    const hqRoot = process.env.HQ_ROOT ?? "";
+    const hqRoot = env.HQ_ROOT ?? "";
     if (hqRoot === "" || !laneIdIsSafe(laneId)) {
-        await runFullPath(input, inputError);
-        return;
+        return withInputError(await runFullPath(env, input, deps));
     }
     const box = path.join(hqRoot, "workspace", "lanes-runs", laneId, "dropbox");
     let noWork = false;
     try {
         noWork = !dropboxMayNeedDrain(box) &&
-            !replayMayNeedWork(box, process.env.HQ_LANE_TURN_ID ?? "", input);
+            !replayMayNeedWork(box, env.HQ_LANE_TURN_ID ?? "", input, env);
     }
     catch {
         // Filesystem uncertainty must use the full path so it retains its named errors.
     }
     if (!noWork) {
-        await runFullPath(input, inputError);
-        return;
+        return withInputError(await runFullPath(env, input, deps));
     }
     let stderr = recordToolActivity(hqRoot, laneId);
     const directories = [
@@ -186,14 +174,30 @@ async function main() {
     catch (err) {
         const message = `Failed to open drop box ${box}: ${err instanceof Error ? err.message : String(err)}`;
         stderr += `hq-lanes-drain: ${message}\n`;
-        finish({ exitCode: 1, stdout: "", stderr }, inputError);
-        return;
+        return withInputError({ exitCode: 1, stdout: "", stderr });
+    }
+    return withInputError({ exitCode: 0, stdout: "", stderr });
+}
+async function main() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    const text = Buffer.concat(chunks).toString("utf8");
+    let input = {};
+    let inputError = "";
+    try {
+        input = parseHookInput(text);
     }
-    finish({ exitCode: 0, stdout: "", stderr }, inputError);
+    catch (err) {
+        inputError = `hq-lanes-drain: ${err instanceof Error ? err.message : String(err)}\n`;
+    }
+    finish(await runLaneDrainHook(process.env, input, inputError));
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main().catch((err) => {
+        process.stderr.write(`hq-lanes-drain: hook_runner_failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        // A hook runner failure must not stop the provider's requested tool call.
+        process.exitCode = 0;
+    });
 }
-main().catch((err) => {
-    process.stderr.write(`hq-lanes-drain: hook_runner_failed: ${err instanceof Error ? err.message : String(err)}\n`);
-    // A hook runner failure must not stop the provider's requested tool call.
-    process.exitCode = 0;
-});
 //# sourceMappingURL=lanes-drain-hook.js.map

package/dist/lib/checkpoint-ontology/merge-copies.d.ts

@@ -42,7 +42,7 @@ export declare const MERGE_COPIES_FLAG = "checkpoint.ontology.merge-copies";
  * names differ only in spacing, case or punctuation (CO-65).
  */
 export declare const MERGE_VARIANTS_FLAG = "checkpoint.ontology.merge-variants";
-export type CopySkipReason = "no_original" | "original_invalid" | "identity_differs" | "not_in_duplicate_group" | "group_size" | "type_differs" | "names_differ" | "numbered_copy";
+export type CopySkipReason = "no_original" | "original_invalid" | "identity_differs" | "not_in_duplicate_group" | "group_size" | "type_differs" | "names_differ" | "numbered_copy" | "not_listed";
 export type PairKind = "numbered" | "variants";
 export interface CopySkip {
     copy: string;
@@ -55,6 +55,11 @@ export interface CopyPair {
     /** Company-relative path of the original it merges into. */
     original: string;
 }
+/** One entry of a `--only` list: an exact copy -> original pair. */
+export interface ListedPair {
+    copy: string;
+    original: string;
+}
 export interface CopyPlan extends CopyPair {
     add_aliases: string[];
     /** Copy names the original lacks that another entity already holds, so they do not move. */
@@ -98,6 +103,8 @@ export interface MergeCopiesReport {
         path: string;
         error: string;
     }[];
+    /** Listed entries the finder did not produce. Absent unless `--only` was set. */
+    only_unmatched?: ListedPair[];
     /** Entity-file links whose target file does not exist. */
     broken_links_before: number;
     broken_links_after: number;
@@ -114,6 +121,8 @@ export interface MergeCopiesOptions {
     pairKind?: PairKind;
     /** Handle at most this many copies (sorted by path). */
     limit?: number;
+    /** Handle only these exact pairs; every other found pair is skipped as `not_listed`. */
+    only?: ListedPair[];
     now: Date;
     deleteVaultKey?: DeleteVaultKey;
 }