@indigoai-us/hq-cli 5.274.1 → 5.276.0

package/dist/commands/lanes.js

@@ -27,6 +27,7 @@ import { registerLaneReportCommands } from "./lanes-report.js";
 import { registerLaneRepoMergeHoldCommand } from "./lanes-hold.js";
 import { registerLaneReviewCommand } from "./lanes-review.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { withCliFeatureUsed } from "../utils/cli-telemetry.js";
 import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
 import { isSsmRunCommandProcess } from "../lib/lanes/ssm-command-context.js";
 import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
@@ -1158,7 +1159,7 @@ async function loadClaudeBalanceHostSnapshots(ctx, hqRoot, config) {
         const actualLocalLanes = hostname
             ? localLanes.filter((lane) => lane.host.kind === "local" && lane.host.id === hostname)
             : [];
-        if (actualLocalLanes.length > 0) {
+        if (hostname) {
             snapshots.push({
                 capacity: buildHostCapacitySnapshot({
                     host: actualLocalHost,
@@ -2402,6 +2403,11 @@ async function runCreate(ctx, opts) {
     let placementHostOverride;
     let autoPlacementChoice;
     let autoPlacementSkippedHosts = [];
+    let placementMachineIdentity;
+    const resolvePlacementMachineIdentity = () => {
+        placementMachineIdentity ??= ctx.resolveMachineIdentity();
+        return placementMachineIdentity;
+    };
     let balanceHostLoad;
     let balanceTargetHost;
     let inheritedPlacement;
@@ -2485,23 +2491,39 @@ async function runCreate(ctx, opts) {
                 }
                 throw err;
             }
-            placementHostOverride = autoPlacementChoice.host;
-            if (autoPlacementChoice.host.kind === currentHost.kind &&
-                autoPlacementChoice.host.id === currentHost.id) {
-                outpostId = undefined;
+            const chosenHost = autoPlacementChoice.host;
+            const localHostname = ctx.hostname().trim();
+            if (!localHostname) {
+                throw new LanesError("host_identity_unknown", "Cannot resolve this host for automatic lane placement", {});
+            }
+            const localHost = { kind: "local", id: localHostname };
+            let chosenHostIsCaller = chosenHost.id === currentHost.id ||
+                sanitizeHostComponent(chosenHost.id) === sanitizeHostComponent(localHostname);
+            if (!chosenHostIsCaller && chosenHost.kind === "outpost") {
+                const identity = resolvePlacementMachineIdentity();
+                if (identity.status === "ok") {
+                    const machineIds = [identity.id, identity.imds, identity.hostname]
+                        .filter((id) => typeof id === "string" && id.trim() !== "");
+                    chosenHostIsCaller = machineIds.some((id) => sanitizeHostComponent(chosenHost.id) === sanitizeHostComponent(id.trim()));
+                }
             }
-            else if (autoPlacementChoice.host.kind === "outpost") {
-                outpostId = autoPlacementChoice.host.id;
+            if (chosenHostIsCaller) {
+                // A capacity snapshot can identify this process as an Outpost (or an
+                // alias of its machine). Auto placement must spawn locally so the
+                // Outpost self-target guard is never reached.
+                placementHostOverride = localHost;
+                outpostId = undefined;
             }
             else {
-                outpostId = undefined;
+                placementHostOverride = chosenHost;
+                outpostId = chosenHost.kind === "outpost" ? chosenHost.id : undefined;
             }
         }
     }
     let originHost;
     let originHostSource;
     if (outpostId) {
-        const identity = ctx.resolveMachineIdentity();
+        const identity = resolvePlacementMachineIdentity();
         if (identity.status !== "ok") {
             throw new LanesError("origin_host_unresolvable", "Cannot record origin_host; this machine's identity is unresolvable", { identity });
         }
@@ -6890,7 +6912,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .option("--placement <mode>", "local | auto | outpost:<id>")
         .option("--default-placement <mode>", "Default placement for lanes launched by this lane: local | auto | outpost:<id>")
         .action(wrap(async (opts) => {
-        await runCreate(ctx, opts);
+        await withCliFeatureUsed("lane_create", () => runCreate(ctx, opts));
     }));
     lanes
         .command("approve-target", { hidden: true })
@@ -7194,7 +7216,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .option("--mesh-company <slug>", "Attach Work Mesh attribution after verifying company membership")
         .option("--no-compact", "Skip the resume-time compaction check for this resume")
         .action(wrap(async (laneId, opts) => {
-        await resumeHandlers.runResume(ctx, laneId, opts);
+        await withCliFeatureUsed("lane_resume", () => resumeHandlers.runResume(ctx, laneId, opts));
     }));
     lanes
         .command("reparent")

package/dist/commands/run-feature-telemetry.d.ts

@@ -0,0 +1,3 @@
+/** Attribute hq run's batch secret read to its resolved company UID. */
+export declare function withRunSecretReadTelemetry<T>(companyUid: string, action: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=run-feature-telemetry.d.ts.map

package/dist/commands/run-feature-telemetry.js

@@ -0,0 +1,6 @@
+import { withCliFeatureUsed } from '../utils/cli-telemetry.js';
+/** Attribute hq run's batch secret read to its resolved company UID. */
+export function withRunSecretReadTelemetry(companyUid, action) {
+    return withCliFeatureUsed('secret_read', action, companyUid);
+}
+//# sourceMappingURL=run-feature-telemetry.js.map

package/dist/commands/run.js

@@ -11,6 +11,7 @@ import { discoverSchemas } from '../run/discover-schemas.js';
 import { installHqPlugin, prewarmHqSecrets } from '../run/hq-plugin.js';
 import { assertEnvGraphLoaded, resolveEnvValuesOrThrow, EnvGraphLoadError, EnvResolutionError, } from '../run/env-graph-guard.js';
 import { hadFatalRejection } from '../unhandled-rejection-boundary.js';
+import { withRunSecretReadTelemetry } from './run-feature-telemetry.js';
 const SECRET_LOAD_TIMEOUT_MS = 30_000;
 export async function buildRunUsage(scriptPath, scriptId) {
     if (scriptId && !scriptPath) {
@@ -87,7 +88,7 @@ export function registerRunCommand(program) {
                 allowOfflineScopeFallback: true,
             });
             const usage = await buildRunUsage(opts.script, opts.scriptId);
-            const fetchBatch = async (companyUid, names, requestUsage) => {
+            const fetchBatch = async (companyUid, names, requestUsage) => withRunSecretReadTelemetry(companyUid, async () => {
                 const res = await vaultApiFetch({
                     token,
                     path: `/secrets/${encodeURIComponent(companyUid)}/load`,
@@ -113,7 +114,7 @@ export function registerRunCommand(program) {
                     throw new Error(`Failed to batch-load secrets: ${message}`);
                 }
                 return res.json();
-            };
+            });
             const pluginOpts = {
                 companyOverride: opts.company,
                 principalUid: cognitoCachePrincipalUid(token) ?? undefined,

package/dist/commands/secrets.js

@@ -4,6 +4,7 @@ import { spawn } from "node:child_process";
 import { writeSync } from "node:fs";
 import * as nodePath from "node:path";
 import { cognitoCachePrincipalUid, ensureCognitoToken } from "../utils/cognito-session.js";
+import { withCliFeatureUsed } from "../utils/cli-telemetry.js";
 import { DEFAULT_SECRETS_CACHE_TTL_MS, hasCacheEntry, readCache, writeCache, removeCacheEntry, clearAllCache, } from "../utils/secrets-cache.js";
 import { computeSha256 } from "../utils/integrity.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN } from "./_patterns.js";
@@ -1498,9 +1499,14 @@ export function registerSecretsCommand(program) {
             const companyUid = cred.kind === "api-key"
                 ? "__api_key__"
                 : await getEntityUid(cred.token, scopeOpts(secrets.opts()), { allowOfflineScopeFallback: true });
-            const revealed = await loadRevealedSecrets(cred.token, companyUid, keys, cred.kind === "cognito"
+            const readSecrets = async () => loadRevealedSecrets(cred.token, companyUid, keys, cred.kind === "cognito"
                 ? await buildSecretUsage("exec", _opts.script, _opts.scriptId)
                 : undefined, { allowOfflineFallback: true });
+            // API-key auth has no signed-in person identity for the CLI telemetry
+            // endpoint. Do not attribute that read to an unrelated cached session.
+            const revealed = cred.kind === "cognito"
+                ? await withCliFeatureUsed("secret_read", readSecrets, companyUid)
+                : await readSecrets();
             const secretEnv = {};
             for (const key of keys) {
                 const value = revealed.get(key);

package/dist/commands/whoami.d.ts

@@ -3,6 +3,7 @@
  */
 import { Command } from 'commander';
 import { type PlanLimitStatus } from "../lib/billing/plan-lock.js";
+export declare const CLI_LIMIT_INVITE_TEAMMATE_FLAG = "cli.limit-invite-teammate-v1";
 export interface WhoamiTokenIdentity {
     email?: string;
     sub?: string;
@@ -20,11 +21,8 @@ export interface WhoamiDisplayIdentity {
  * email with the token subject of the delegating machine.
  */
 export declare function resolveWhoamiIdentity(identity: WhoamiTokenIdentity): WhoamiDisplayIdentity;
-/**
- * Human rendering of the plan state: the full over-limit block when the
- * workspace is over its Starter limits, the one-line `Plan: Starter — …`
- * orientation when it is Starter and healthy, and nothing at all otherwise.
- */
-export declare function renderWhoamiPlanBlock(status: PlanLimitStatus): string | null;
+export declare function renderWhoamiPlanBlock(status: PlanLimitStatus, opts?: {
+    inviteTeammateEnabled?: boolean;
+}): string | null;
 export declare function registerWhoamiCommand(program: Command): void;
 //# sourceMappingURL=whoami.d.ts.map

package/dist/commands/whoami.js

@@ -6,6 +6,9 @@ import { loadCachedTokens, isExpiring, loadMachineCreds, } from '@indigoai-us/hq
 import { peekIdToken as decodeIdToken } from "../utils/id-token.js";
 import { ensureCognitoToken, loadMachineCachedTokens, resolveCognitoTokenSource, } from "../utils/cognito-session.js";
 import { colorizePlanLimitNotice, fetchPlanLimitStatus, renderPlanLine, renderPlanLimitNotice, } from "../lib/billing/plan-lock.js";
+import { resolveCompanyFlagGate, } from "../lib/flag-registry.js";
+import { queuePlanLimitInviteTeammateExposure } from "../utils/cli-telemetry.js";
+export const CLI_LIMIT_INVITE_TEAMMATE_FLAG = "cli.limit-invite-teammate-v1";
 /**
  * Resolves the person represented by an ID token without pairing a delegated
  * email with the token subject of the delegating machine.
@@ -62,7 +65,13 @@ async function readPlanLimits(company) {
         // default `interactive: true`, a box with no cached session would launch a
         // browser sign-in and block the caller instead of resolving to UNKNOWN.
         const token = await ensureCognitoToken({ interactive: false });
-        return await fetchPlanLimitStatus(token, slug);
+        const status = await fetchPlanLimitStatus(token, slug);
+        if (!status)
+            return null;
+        return {
+            status,
+            idToken: loadCachedTokens()?.idToken,
+        };
     }
     catch {
         return null;
@@ -73,19 +82,41 @@ async function readPlanLimits(company) {
  * workspace is over its Starter limits, the one-line `Plan: Starter — …`
  * orientation when it is Starter and healthy, and nothing at all otherwise.
  */
-export function renderWhoamiPlanBlock(status) {
+function shouldOfferInviteTeammateSuggestion(status) {
+    if (!status.over ||
+        status.plan !== "free" ||
+        status.members?.used !== 1 ||
+        !status.companyUid) {
+        return false;
+    }
+    return true;
+}
+async function inviteTeammateSuggestionEnabled(status, idToken) {
+    if (!shouldOfferInviteTeammateSuggestion(status) || !status.companyUid) {
+        return false;
+    }
+    return resolveCompanyFlagGate(status.companyUid, idToken ?? "", CLI_LIMIT_INVITE_TEAMMATE_FLAG, { fallback: false }, () => false);
+}
+export function renderWhoamiPlanBlock(status, opts = {}) {
     if (status.over) {
-        return colorizePlanLimitNotice(renderPlanLimitNotice(status));
+        const inviteTeammateEnabled = opts.inviteTeammateEnabled === true;
+        return colorizePlanLimitNotice(renderPlanLimitNotice(status, { inviteTeammateEnabled }));
     }
     return renderPlanLine(status);
 }
 async function printPlanBlock(company) {
-    const status = await readPlanLimits(company);
-    if (!status)
+    const planLimits = await readPlanLimits(company);
+    if (!planLimits)
+        return;
+    const { status, idToken } = planLimits;
+    const inviteTeammateEnabled = await inviteTeammateSuggestionEnabled(status, idToken);
+    const block = renderWhoamiPlanBlock(status, { inviteTeammateEnabled });
+    if (!block)
         return;
-    const block = renderWhoamiPlanBlock(status);
-    if (block)
-        console.log(block);
+    console.log(block);
+    if (inviteTeammateEnabled && status.companyUid) {
+        queuePlanLimitInviteTeammateExposure(status.companyUid);
+    }
 }
 export function registerWhoamiCommand(program) {
     program

package/dist/fast-core.d.ts

@@ -1,16 +1,15 @@
 /**
- * Fast-path dispatcher for relocated scaffold scripts.
+ * Fast-path dispatcher for selected core commands.
  *
  * Reached from the entrypoint BEFORE `main.ts` (and its heavy command graph) is
- * ever imported, so a hot `hq core hq-session` / `hq core checkpoint-stop-gate`
- * dispatches in roughly node's own startup time. It imports only the light root
- * resolver and the bundled-script runner. The slower commander registration in
- * `core.ts` remains the complete path for any invocation this does not match.
+ * ever imported, so hot hook commands avoid the full commander graph. Shell
+ * entries use the bundled-script runner; native entries import their one handler
+ * module. The registration in `core.ts` remains the complete fallback path.
  */
 /**
- * Run the fast-path scaffold script named in `argv` and exit with its code.
+ * Run the fast-path core command named in `argv` and exit with its code.
  * Only call when {@link isFastCoreRequest} is true; a non-match returns without
  * doing anything.
  */
-export declare function runFastCore(argv: readonly string[]): void;
+export declare function runFastCore(argv: readonly string[]): Promise<void>;
 //# sourceMappingURL=fast-core.d.ts.map

package/dist/fast-core.js

@@ -1,21 +1,20 @@
 /**
- * Fast-path dispatcher for relocated scaffold scripts.
+ * Fast-path dispatcher for selected core commands.
  *
  * Reached from the entrypoint BEFORE `main.ts` (and its heavy command graph) is
- * ever imported, so a hot `hq core hq-session` / `hq core checkpoint-stop-gate`
- * dispatches in roughly node's own startup time. It imports only the light root
- * resolver and the bundled-script runner. The slower commander registration in
- * `core.ts` remains the complete path for any invocation this does not match.
+ * ever imported, so hot hook commands avoid the full commander graph. Shell
+ * entries use the bundled-script runner; native entries import their one handler
+ * module. The registration in `core.ts` remains the complete fallback path.
  */
 import { resolveLiveRoot } from "./utils/hq-roots.js";
 import { runBundledScript } from "./utils/run-bundled-script.js";
 import { parseFastCore } from "./fast-scaffold.js";
 /**
- * Run the fast-path scaffold script named in `argv` and exit with its code.
+ * Run the fast-path core command named in `argv` and exit with its code.
  * Only call when {@link isFastCoreRequest} is true; a non-match returns without
  * doing anything.
  */
-export function runFastCore(argv) {
+export async function runFastCore(argv) {
     const parsed = parseFastCore(argv);
     if (!parsed)
         return;
@@ -31,12 +30,27 @@ export function runFastCore(argv) {
     catch {
         hqRoot = undefined;
     }
+    if (parsed.entry.kind === "native") {
+        const handlerModule = await import(parsed.entry.modulePath);
+        const handler = handlerModule[parsed.entry.exportName];
+        if (typeof handler !== "function") {
+            throw new Error(`Native fast handler ${parsed.entry.exportName} was not exported`);
+        }
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        const code = await handler(argv, Buffer.concat(chunks).toString("utf8"), process.cwd(), hqRoot);
+        // Let Node drain handler output before terminating. The timeout guard's
+        // stderr message must survive the native route's process boundary.
+        process.exitCode = code;
+        return;
+    }
     // Keep the CHILD in the caller's cwd, unlike the generic "live" dispatch. The
     // relocated scripts read their data tree from the injected root, not cwd, and
     // hq-session's Work Mesh registration serializes $PWD — so changing directory
     // to the HQ root would mislabel a bind made from inside a project/worktree.
     const { code } = runBundledScript({
-        asset: parsed.asset,
+        asset: parsed.entry.asset,
         args: parsed.args,
         cwd: process.cwd(),
         hqRoot,

package/dist/fast-scaffold.d.ts

@@ -1,27 +1,36 @@
 /**
- * Fast-path manifest for relocated scaffold scripts, kept deliberately
+ * Fast-path manifest for selected core commands, kept deliberately
  * dependency-light.
  *
  * `main.ts` eagerly imports the CLI's entire (~60-module) command graph, so any
  * command routed through it pays seconds of startup — fine for a human typing a
  * command, ruinous for the hot plumbing this hosts: `hq core hq-session` is
  * called several times per skill/hook, and `hq core checkpoint-stop-gate` runs
- * on every turn's Stop. The entrypoint routes those directly to
- * `runBundledScript` instead, and this module holds the tiny parser + table that
- * routing needs WITHOUT importing anything heavy. `core.ts` names the same
- * assets, and a test pins the two lists together so they cannot drift.
+ * on every turn's Stop. The entrypoint routes eligible commands before loading
+ * the graph, and this module holds the parser + table that routing needs.
  */
 export type FastScaffoldScript = {
     /** Direct subcommand name — `hq core <name>`. */
     name: string;
+    kind: "shell";
     /** Path under `assets/scaffold/`, e.g. `core/scripts/foo.sh`. */
     asset: string;
+} | {
+    /** Direct subcommand name — `hq core <name>`. */
+    name: string;
+    kind: "native";
+    /** Relative ESM module specifier, resolved from fast-core.js. */
+    modulePath: string;
+    /** Named export which accepts the native fast-handler contract. */
+    exportName: string;
+    /** Default-off registry flag for this native route. */
+    flagKey: string;
 };
 /** The relocated scripts that qualify for the entrypoint fast path. */
 export declare const FAST_SCAFFOLD_SCRIPTS: readonly FastScaffoldScript[];
 export type ParsedFastCore = {
-    /** The bundled asset to run. */
-    asset: string;
+    /** The manifest entry to run. */
+    entry: FastScaffoldScript;
     /** `--hq-root <path>` value, if the caller passed the group option. */
     hqRootArg?: string;
     /** Everything after the command name, passed to the script verbatim. */

package/dist/fast-scaffold.js

@@ -1,20 +1,25 @@
 /**
- * Fast-path manifest for relocated scaffold scripts, kept deliberately
+ * Fast-path manifest for selected core commands, kept deliberately
  * dependency-light.
  *
  * `main.ts` eagerly imports the CLI's entire (~60-module) command graph, so any
  * command routed through it pays seconds of startup — fine for a human typing a
  * command, ruinous for the hot plumbing this hosts: `hq core hq-session` is
  * called several times per skill/hook, and `hq core checkpoint-stop-gate` runs
- * on every turn's Stop. The entrypoint routes those directly to
- * `runBundledScript` instead, and this module holds the tiny parser + table that
- * routing needs WITHOUT importing anything heavy. `core.ts` names the same
- * assets, and a test pins the two lists together so they cannot drift.
+ * on every turn's Stop. The entrypoint routes eligible commands before loading
+ * the graph, and this module holds the parser + table that routing needs.
  */
 /** The relocated scripts that qualify for the entrypoint fast path. */
 export const FAST_SCAFFOLD_SCRIPTS = [
-    { name: "checkpoint-stop-gate", asset: "core/scripts/checkpoint-stop-gate.sh" },
-    { name: "hq-session", asset: "core/scripts/hq-session.sh" },
+    { name: "checkpoint-stop-gate", kind: "shell", asset: "core/scripts/checkpoint-stop-gate.sh" },
+    { name: "hq-session", kind: "shell", asset: "core/scripts/hq-session.sh" },
+    {
+        name: "timeout-guard",
+        kind: "native",
+        modulePath: "./lib/core-utils/timeout-guard-native.js",
+        exportName: "runTimeoutGuardFast",
+        flagKey: "hq-core-native-fast-route",
+    },
 ];
 /**
  * Parse `hq core [--hq-root <path>] <name> [args...]` when `<name>` is a
@@ -48,7 +53,7 @@ export function parseFastCore(argv) {
     const entry = FAST_SCAFFOLD_SCRIPTS.find((candidate) => candidate.name === name);
     if (!entry)
         return null;
-    return { asset: entry.asset, hqRootArg, args: argv.slice(i + 1) };
+    return { entry, hqRootArg, args: argv.slice(i + 1) };
 }
 /** Whether this invocation is a fast-path scaffold dispatch. */
 export function isFastCoreRequest(argv) {

package/dist/index.js

@@ -6,7 +6,7 @@ import "./node-network-compat.js";
 import { isVersionRequest, wantsLabelledVersionReport } from "./version-request.js";
 // Dependency-light: a pure parser + table, no command graph. Safe to load on
 // every path (including --version) without reintroducing the heavy startup.
-import { isFastCoreRequest } from "./fast-scaffold.js";
+import { isFastCoreRequest, parseFastCore } from "./fast-scaffold.js";
 // Also dependency-light: registers a process-level rejection boundary; its only
 // heavy import (main.js) is lazy and reached only when a rejection fires.
 import { installProcessRejectionBoundary } from "./unhandled-rejection-boundary.js";
@@ -30,6 +30,21 @@ if (isVersionRequest(process.argv)) {
         });
     }
 }
+else if (parseFastCore(process.argv)?.entry.kind === "native") {
+    // Native routes are default-off. Resolve the company-scoped persisted flag
+    // without loading the command graph; a miss or stale snapshot takes the
+    // existing full-graph route.
+    void import("./native-fast-route.js").then(async ({ nativeFastRouteEnabled }) => {
+        if (await nativeFastRouteEnabled(process.argv)) {
+            const { runFastCore } = await import("./fast-core.js");
+            await runFastCore(process.argv);
+        }
+        else {
+            const { runCli } = await import("./main.js");
+            await runCli();
+        }
+    });
+}
 else if (isFastCoreRequest(process.argv)) {
     // Hot relocated plumbing (`hq core hq-session`, `hq core checkpoint-stop-gate`)
     // dispatches straight to the bundled-script runner, so it never pays for the

package/dist/lib/billing/plan-lock.d.ts

@@ -125,7 +125,9 @@ export declare const HARD_STOP_SENTENCE: string;
  * dimension this CLI does not know) renders a generic line rather than a claim
  * about a dimension nobody measured.
  */
-export declare function renderPlanLimitNotice(status: PlanLimitStatus): string;
+export declare function renderPlanLimitNotice(status: PlanLimitStatus, opts?: {
+    inviteTeammateEnabled?: boolean;
+}): string;
 /**
  * The one-line form injected on every turn while the workspace stays over.
  * Kept to a single line on purpose — it repeats each turn.

package/dist/lib/billing/plan-lock.js

@@ -375,7 +375,7 @@ function capitalize(text) {
  * dimension this CLI does not know) renders a generic line rather than a claim
  * about a dimension nobody measured.
  */
-export function renderPlanLimitNotice(status) {
+export function renderPlanLimitNotice(status, opts = {}) {
     const { companySlug, freeMonth } = status;
     const lines = [];
     lines.push(`HQ Starter — ${companySlug} is over its plan limits.`);
@@ -405,6 +405,12 @@ export function renderPlanLimitNotice(status) {
         lines.push(`    2. Upgrade to ${WORKFORCE_PLAN_LABEL}.`);
     }
     lines.push(`  Upgrade: ${status.upgradeUrl}`);
+    if (opts.inviteTeammateEnabled === true &&
+        status.plan === "free" &&
+        status.over &&
+        status.members?.used === 1) {
+        lines.push(`  Invite a teammate with: hq members invite <email> --company ${companySlug} --role member`);
+    }
     return lines.join("\n");
 }
 /**

package/dist/lib/checkpoint-ontology/company.d.ts

@@ -29,10 +29,14 @@ export declare class WriteBoundsError extends Error {
     constructor(message: string);
 }
 /**
- * Write `content` to `target` only when it stays inside one of `roots` with no
- * symlink anywhere between `anchor` (the HQ root) and the file. A root or a
- * directory under it that is a symlink fails closed, and so does a target that
- * is itself a symlink. Missing directories are created only after that check.
+ * Resolve `target` only when it stays inside one of `roots` with no symlink
+ * anywhere between `anchor` (the HQ root) and the file. A root or a directory
+ * under it that is a symlink fails closed, and so does a target that is itself
+ * a symlink. Missing directories are created only after that check.
+ */
+export declare function assertSafeTarget(anchor: string, roots: string[], target: string): string;
+/**
+ * Write `content` to `target` only when {@link assertSafeTarget} accepts it.
  * The file is written to a temporary sibling and renamed, so a reader never
  * sees half a file.
  */

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

@@ -71,14 +71,12 @@ function nearestExisting(target) {
     return current;
 }
 /**
- * Write `content` to `target` only when it stays inside one of `roots` with no
- * symlink anywhere between `anchor` (the HQ root) and the file. A root or a
- * directory under it that is a symlink fails closed, and so does a target that
- * is itself a symlink. Missing directories are created only after that check.
- * The file is written to a temporary sibling and renamed, so a reader never
- * sees half a file.
+ * Resolve `target` only when it stays inside one of `roots` with no symlink
+ * anywhere between `anchor` (the HQ root) and the file. A root or a directory
+ * under it that is a symlink fails closed, and so does a target that is itself
+ * a symlink. Missing directories are created only after that check.
  */
-export function safeWriteFile(anchor, roots, target, content) {
+export function assertSafeTarget(anchor, roots, target) {
     const resolved = path.resolve(target);
     const root = roots.map((candidate) => path.resolve(candidate)).find((candidate) => isInside(candidate, resolved));
     if (!root)
@@ -103,6 +101,16 @@ export function safeWriteFile(anchor, roots, target, content) {
         if (error.code !== "ENOENT")
             throw error;
     }
+    return path.resolve(target);
+}
+/**
+ * Write `content` to `target` only when {@link assertSafeTarget} accepts it.
+ * The file is written to a temporary sibling and renamed, so a reader never
+ * sees half a file.
+ */
+export function safeWriteFile(anchor, roots, target, content) {
+    const resolved = assertSafeTarget(anchor, roots, target);
+    const parent = path.dirname(resolved);
     const tmp = path.join(parent, `.${path.basename(resolved)}.${process.pid}.tmp`);
     fs.writeFileSync(tmp, content);
     fs.renameSync(tmp, resolved);

package/dist/lib/checkpoint-ontology/plan.d.ts

@@ -94,6 +94,15 @@ export declare const CONCEPT_PROJECT_LINK_FLAG = "checkpoint.ontology.concept-pr
  * and lost no gold link.
  */
 export declare 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
+ * company's queued touches to this run's session-touched set, and a run whose
+ * own payload names no company plans the company the parent picked for it
+ * (`ontology_company`), without that run's session text. Off, queued touches
+ * wait on disk and a company-less run skips the ontology step as before.
+ */
+export declare const QUEUED_TOUCHES_FLAG = "checkpoint.ontology.queued-touches";
 export declare const PLAN_FILE = "ontology-plan.json";
 export declare const CANDIDATES_FILE = "ontology-candidates.json";
 export declare const REPORT_FILE = "ontology-report.json";
@@ -183,6 +192,11 @@ export interface OntologyPlan {
 }
 export interface CheckpointPayloadLike {
     company?: unknown;
+    /**
+     * Set by `hq core checkpoint` only when the payload names no company and
+     * another company has queued touches (CO-59). Never scopes anything else.
+     */
+    ontology_company?: unknown;
     /** The sibling backend `hq core checkpoint` spawned for this payload. */
     backend?: unknown;
     files?: unknown;
@@ -234,6 +248,15 @@ export declare function refreshLedger(company: OntologyCompany, existing: Ledger
     ledger: Ledger;
     firstRun: boolean;
 };
+/**
+ * The company this run's ontology step works on: the payload's own company,
+ * or else the `ontology_company` the checkpoint parent picked for queued
+ * touches (`borrowed`).
+ */
+export declare function payloadOntologyCompany(payload: CheckpointPayloadLike): {
+    slug: string | null;
+    borrowed: boolean;
+};
 /** Plan this run. Never throws for a skip; returns the reason instead. */
 export declare function planOntologyRun(options: PlanOptions): Promise<PlanOutcome>;
 /**