@indigoai-us/hq-cli 5.275.0 → 5.276.0

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>;
 /**

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

@@ -13,6 +13,7 @@ import * as path from "node:path";
 import { writeCompanyBrief } from "./company-brief.js";
 import { resolveOntologyCompany, safeWriteFile, stateRoot } from "./company.js";
 import { startMultiWriterRun } from "./multi-writer.js";
+import { claimQueuedTouches, recordQueuedTouches } from "./queued-touches.js";
 import { checkSyncClient, readSyncClientVersions } from "./sync-client.js";
 import { buildEntityIndex, listKnowledgeFiles, listSignalFiles, readSignal } from "./tree.js";
 export const ONTOLOGY_FLAG = "checkpoint.ontology";
@@ -98,6 +99,15 @@ export const CONCEPT_PROJECT_LINK_FLAG = "checkpoint.ontology.concept-project-li
  * 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
+ * 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 const QUEUED_TOUCHES_FLAG = "checkpoint.ontology.queued-touches";
 export const PLAN_FILE = "ontology-plan.json";
 export const CANDIDATES_FILE = "ontology-candidates.json";
 export const REPORT_FILE = "ontology-report.json";
@@ -255,13 +265,32 @@ export function refreshLedger(company, existing, touched) {
     }
     return { ledger: { schema: LEDGER_SCHEMA, company: company.slug, boundary, entries }, firstRun };
 }
+/**
+ * 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 function payloadOntologyCompany(payload) {
+    if (typeof payload.company === "string" && payload.company)
+        return { slug: payload.company, borrowed: false };
+    if (typeof payload.ontology_company === "string" && payload.ontology_company) {
+        return { slug: payload.ontology_company, borrowed: true };
+    }
+    return { slug: null, borrowed: false };
+}
 /** Plan this run. Never throws for a skip; returns the reason instead. */
 export async function planOntologyRun(options) {
     const { hqRoot, runDir, payload } = options;
-    const resolution = resolveOntologyCompany(hqRoot, typeof payload.company === "string" ? payload.company : null);
+    const { slug, borrowed } = payloadOntologyCompany(payload);
+    const resolution = resolveOntologyCompany(hqRoot, slug);
     if (!resolution.ok)
         return { status: "skipped", reason: resolution.reason };
     const company = resolution.company;
+    // A borrowed company exists only for queued touches, so its run needs the
+    // queued-touches flag before anything else is read or written.
+    if (borrowed && !(await options.readFlag(QUEUED_TOUCHES_FLAG, company))) {
+        return { status: "skipped", reason: "flag off" };
+    }
     const ontologyOn = (await options.readFlag(ONTOLOGY_FLAG, company)) || (await options.readFlag(ONTOLOGY_SYNC_GATED_FLAG, company));
     const syncClient = ontologyOn ? checkSyncClient((options.syncClientVersions ?? readSyncClientVersions)()) : null;
     if (!ontologyOn || !syncClient?.ok) {
@@ -278,7 +307,14 @@ export async function planOntologyRun(options) {
     const skipAmbiguousConceptLinks = await options.readFlag(SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG, company);
     const conceptProjectLink = await options.readFlag(CONCEPT_PROJECT_LINK_FLAG, company);
     const namedEvidence = await options.readFlag(NAMED_EVIDENCE_FLAG, company);
-    const touched = sessionTouched(hqRoot, company, payload.files);
+    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.
+    const touched = sessionTouched(hqRoot, company, borrowed ? [] : payload.files);
+    if (queuedTouchesOn) {
+        for (const rel of sessionTouched(hqRoot, company, claimQueuedTouches(hqRoot, company, runDir)))
+            touched.add(rel);
+    }
     // A first run takes its boundary from the entity tree, so the ledger is
     // refreshed before merge-back moves any `last_updated` forward.
     const { ledger, firstRun } = refreshLedger(company, readLedger(hqRoot, company), touched);
@@ -293,9 +329,11 @@ export async function planOntologyRun(options) {
     const inputs = [];
     let tokens = 0;
     let remaining = 0;
+    const leftover = [];
     for (const [rel, entry] of pending) {
         if (inputs.length >= BUDGET.maxInputs || tokens >= BUDGET.maxTokens) {
             remaining += 1;
+            leftover.push(rel);
             continue;
         }
         const text = fs.readFileSync(path.join(company.dir, rel), "utf8");
@@ -329,10 +367,21 @@ export async function planOntologyRun(options) {
             });
             tokens += cost;
         }
-        if (index < chunks.length)
+        if (index < chunks.length) {
             remaining += 1;
+            leftover.push(rel);
+        }
     }
     writeLedger(hqRoot, company, ledger);
+    // The leftover files stay queued so a later company-less run can borrow this company again.
+    if (queuedTouchesOn && leftover.length > 0) {
+        try {
+            recordQueuedTouches(hqRoot, company.slug, leftover.map((rel) => path.relative(hqRoot, path.join(company.dir, rel))), options.now ?? new Date());
+        }
+        catch {
+            // Re-queueing leftovers must not fail the plan.
+        }
+    }
     if (inputs.length === 0) {
         const reason = pending.length > 0 ? "over budget" : "nothing changed";
         return {
@@ -345,7 +394,7 @@ export async function planOntologyRun(options) {
     // Session content is scoped to the session's user (design section 6, D2).
     // v1 records the existing entities it names as links in the report and
     // writes nothing from it, so it rides along only when files changed.
-    const sessionText = sessionContent(payload);
+    const sessionText = borrowed ? null : sessionContent(payload);
     if (sessionText) {
         const cost = estTokens(Buffer.byteLength(sessionText, "utf8"));
         inputs.unshift({

package/dist/lib/checkpoint-ontology/queued-touches.d.ts

@@ -0,0 +1,32 @@
+import { type OntologyCompany } from "./company.js";
+export declare const QUEUED_TOUCHES_FILE = "queued-touches.jsonl";
+export declare const QUEUED_TOUCHES_CLAIM_FILE = "queued-touches-claimed.jsonl";
+export declare const QUEUED_TOUCHES_BORROWED_FILE = "queued-touches-borrowed-at";
+export declare const MAX_QUEUED_TOUCHES = 200;
+export declare function queuedTouchesPath(hqRoot: string, slug: string): string;
+/**
+ * Record the files a queued checkpoint touched inside its company. Files
+ * outside `companies/<slug>/` are dropped. Returns the number of files
+ * recorded; 0 when the company is not a manifest company or nothing is inside
+ * it. The queue keeps its newest {@link MAX_QUEUED_TOUCHES} lines.
+ */
+export declare function recordQueuedTouches(hqRoot: string, slug: string | null, files: string[], now: Date): number;
+/**
+ * Record that a company-less run borrowed `slug`, so the next such run prefers
+ * a company that has waited longer.
+ */
+export declare function markBorrowed(hqRoot: string, slug: string, now: Date): void;
+/**
+ * The manifest company whose queued touches have waited longest, or null.
+ * The order key is the later of the first queued record and the last borrow,
+ * so a company a company-less run just borrowed goes to the back. A run whose
+ * own payload names no company uses it for its ontology step.
+ */
+export declare function oldestQueuedCompany(hqRoot: string): string | null;
+/**
+ * Take the company's queued touches by renaming the file into the run
+ * directory, then return the HQ-relative paths it lists. Renaming is atomic,
+ * so a touch recorded during the claim lands in a fresh file for a later run.
+ */
+export declare function claimQueuedTouches(hqRoot: string, company: OntologyCompany, runDir: string): string[];
+//# sourceMappingURL=queued-touches.d.ts.map