@indigoai-us/hq-cli 5.275.0 → 5.277.0

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.d.ts

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import type { Command } from "commander";
 import { writeSync } from "node:fs";
 import { vaultApiFetch, getCompanyUid, getEntityUid } from "../utils/vault-api.js";
 export type { VaultApiOptions } from "../utils/vault-api.js";
@@ -88,5 +88,20 @@ export declare function loadRevealedSecrets(token: string, companyUid: string, k
  * `exit` and `write` are injectable for tests; production uses the real ones.
  */
 export declare function emitEnvExportsAndExit(payload: string, exit?: (code: number) => never, write?: typeof writeSync): never;
+/**
+ * Shared `secrets env` action for Commander and the default-off lightweight
+ * entrypoint. The fast entrypoint still runs the same credential, usage-audit,
+ * server authorization, cache-fallback, redaction, and output code.
+ */
+export declare function runSecretsEnvCommand(opts: {
+    only: string[];
+    script?: string;
+    scriptId?: string;
+}, parentScope: {
+    company?: string;
+    personal?: boolean;
+}, options?: {
+    fallbackOnAuthFailure?: boolean;
+}): Promise<"handled" | "fallback">;
 export declare function registerSecretsCommand(program: Command): void;
 //# sourceMappingURL=secrets.d.ts.map

package/dist/commands/secrets.js

@@ -1,9 +1,8 @@
 import chalk from "chalk";
-import * as readline from "node:readline";
-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 { isAuthError } from "../utils/auth-error.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";
@@ -11,7 +10,6 @@ import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, format
 import { vaultApiFetch, getCompanyUid, getEntityUid, looksLikeCompanyUid, } from "../utils/vault-api.js";
 import { HQ_API_KEY_PREFIX, formatApiKeyCapabilityDenial, requireApiKeyCapability, resolveVaultCredentialForCapability, } from "../utils/resolve-vault-credential.js";
 import { CACHED_SECRETS_SERVER_UNAVAILABLE_MESSAGE, isSecretLoadUnavailable, isUnavailableSecretLoadHttpStatus, SecretLoadUnavailableError, } from "../utils/secret-load-availability.js";
-import { SandboxRunnerClient, } from "../utils/sandbox-runner-client.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
 /**
  * Mirrors `RESOURCE_SURFACES` in hq-pro
@@ -158,14 +156,16 @@ function parseDuration(input) {
     return null;
 }
 function confirmPrompt(message) {
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
-    return new Promise((resolve) => {
-        rl.question(`${message} [y/N] `, (answer) => {
-            rl.close();
-            resolve(answer.trim().toLowerCase() === "y");
+    return import("node:readline").then(({ createInterface }) => {
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        return new Promise((resolve) => {
+            rl.question(`${message} [y/N] `, (answer) => {
+                rl.close();
+                resolve(answer.trim().toLowerCase() === "y");
+            });
         });
     });
 }
@@ -820,6 +820,61 @@ export function emitEnvExportsAndExit(payload, exit = process.exit, write = writ
     }
     return exit(0);
 }
+/**
+ * Shared `secrets env` action for Commander and the default-off lightweight
+ * entrypoint. The fast entrypoint still runs the same credential, usage-audit,
+ * server authorization, cache-fallback, redaction, and output code.
+ */
+export async function runSecretsEnvCommand(opts, parentScope, options = {}) {
+    let secretLoadStarted = false;
+    try {
+        const redact = process.stdout.isTTY;
+        if (redact) {
+            console.error(chalk.yellow("stdout is a terminal — values redacted. Use: source <(hq secrets env --only KEY1,KEY2)"));
+        }
+        const keys = parseSecretNameList(opts.only);
+        const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets env", secretsCredentialOptions());
+        const companyUid = cred.kind === "api-key"
+            ? "__api_key__"
+            : await getEntityUid(cred.token, scopeOpts(parentScope), {
+                allowOfflineScopeFallback: true,
+            });
+        const usage = cred.kind === "cognito"
+            ? await buildSecretUsage("env", opts.script, opts.scriptId)
+            : undefined;
+        secretLoadStarted = true;
+        const revealed = await loadRevealedSecrets(cred.token, companyUid, keys, usage, { allowOfflineFallback: true });
+        let payload = "";
+        for (const key of keys) {
+            const value = revealed.get(key);
+            // loadRevealedSecrets throws on any unresolved key, so a miss here is
+            // unreachable — guard rather than print an `undefined` export line.
+            if (value === undefined) {
+                throw new Error(`Failed to fetch secret '${key}': not returned by vault`);
+            }
+            const out = redact ? "[REDACTED]" : value;
+            payload += `export ${key}=${shellSingleQuote(out)}\n`;
+        }
+        // Write synchronously and exit unconditionally — never depend on the
+        // event loop draining or the stdout write callback firing. See
+        // emitEnvExportsAndExit for the full rationale (orphaned-process leak).
+        emitEnvExportsAndExit(payload);
+        return "handled";
+    }
+    catch (err) {
+        if (options.fallbackOnAuthFailure &&
+            !secretLoadStarted &&
+            (isAuthError(err) ||
+                (err instanceof Error &&
+                    (/^No valid HQ session\b/.test(err.message) ||
+                        /^HQ_API_KEY must start with /.test(err.message))))) {
+            return "fallback";
+        }
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+        return "handled";
+    }
+}
 export function registerSecretsCommand(program) {
     const secrets = program
         .command("secrets")
@@ -1444,6 +1499,7 @@ export function registerSecretsCommand(program) {
             const token = await requireCognitoTokenForSecrets("secrets sandbox", "secrets:read");
             const scope = scopeOpts(mergeScopeOpts(secrets.opts(), opts));
             const companyUid = await getEntityUid(token, scope);
+            const { SandboxRunnerClient } = await import("../utils/sandbox-runner-client.js");
             const client = new SandboxRunnerClient();
             const started = await client.startJob(token, {
                 companyUid,
@@ -1498,9 +1554,19 @@ 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.
+            let revealed;
+            if (cred.kind === "cognito") {
+                const { withCliFeatureUsed } = await import("../utils/cli-telemetry.js");
+                revealed = await withCliFeatureUsed("secret_read", readSecrets, companyUid);
+            }
+            else {
+                revealed = await readSecrets();
+            }
             const secretEnv = {};
             for (const key of keys) {
                 const value = revealed.get(key);
@@ -1512,6 +1578,7 @@ export function registerSecretsCommand(program) {
                 secretEnv[key] = value;
             }
             const [childCmd, ...childCmdArgs] = childArgs;
+            const { spawn } = await import("node:child_process");
             const child = spawn(childCmd, childCmdArgs, {
                 stdio: "inherit",
                 env: { ...process.env, ...secretEnv },
@@ -1539,39 +1606,7 @@ export function registerSecretsCommand(program) {
         .option("--script <path>", "Attach local script identity for script-locked secrets")
         .option("--script-id <id>", "Stable script identifier approved by policy")
         .action(async (opts) => {
-        try {
-            const redact = process.stdout.isTTY;
-            if (redact) {
-                console.error(chalk.yellow("stdout is a terminal — values redacted. Use: source <(hq secrets env --only KEY1,KEY2)"));
-            }
-            const keys = parseSecretNameList(opts.only);
-            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets env", secretsCredentialOptions());
-            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"
-                ? await buildSecretUsage("env", opts.script, opts.scriptId)
-                : undefined, { allowOfflineFallback: true });
-            let payload = "";
-            for (const key of keys) {
-                const value = revealed.get(key);
-                // loadRevealedSecrets throws on any unresolved key, so a miss here is
-                // unreachable — guard rather than print an `undefined` export line.
-                if (value === undefined) {
-                    throw new Error(`Failed to fetch secret '${key}': not returned by vault`);
-                }
-                const out = redact ? "[REDACTED]" : value;
-                payload += `export ${key}=${shellSingleQuote(out)}\n`;
-            }
-            // Write synchronously and exit unconditionally — never depend on the
-            // event loop draining or the stdout write callback firing. See
-            // emitEnvExportsAndExit for the full rationale (orphaned-process leak).
-            emitEnvExportsAndExit(payload);
-        }
-        catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
-            process.exit(1);
-        }
+        await runSecretsEnvCommand(opts, secrets.opts());
     });
     secrets
         .command("generate-link <name>")

package/dist/commands/sync-mode.d.ts

@@ -70,6 +70,15 @@ export interface SetSyncModeResult {
 export interface ShowSyncModesOptions {
     vaultClient: SyncModeVaultClient;
 }
+export interface GetSyncModeOptions {
+    companySlug: string;
+    vaultClient: SyncModeVaultClient;
+}
+export interface GetSyncModeResult {
+    membershipId: string;
+    companySlug: string;
+    config: MembershipSyncConfig;
+}
 export interface ShowSyncModesRow {
     companySlug: string;
     companyName?: string;
@@ -100,6 +109,8 @@ export declare function setSyncMode(options: SetSyncModeOptions): Promise<SetSyn
  * stable table output.
  */
 export declare function showSyncModes(options: ShowSyncModesOptions): Promise<ShowSyncModesRow[]>;
+/** Read one company's effective sync mode without hiding API read failures. */
+export declare function getSyncModeForCompany(options: GetSyncModeOptions): Promise<GetSyncModeResult>;
 /**
  * Render the `--show` table as plain text. No external dep — hq-cli doesn't
  * use cli-table3, so we hand-format columns to match the existing chalk +

package/dist/commands/sync-mode.js

@@ -163,6 +163,36 @@ export async function showSyncModes(options) {
     rows.sort((a, b) => a.companySlug.localeCompare(b.companySlug));
     return rows;
 }
+/** Read one company's effective sync mode without hiding API read failures. */
+export async function getSyncModeForCompany(options) {
+    const { companySlug, vaultClient } = options;
+    const memberships = await vaultClient.listMyMemberships();
+    const enriched = await Promise.all(memberships.map(async (membership) => {
+        try {
+            const entity = await vaultClient.entity.get(membership.companyUid);
+            return { ok: true, membership, slug: entity.slug };
+        }
+        catch (error) {
+            return { ok: false, membership, error };
+        }
+    }));
+    const match = enriched.find((row) => row.ok && row.slug === companySlug);
+    if (!match) {
+        const failedLookup = enriched.find((row) => !row.ok);
+        if (failedLookup && !failedLookup.ok)
+            throw failedLookup.error;
+        throw new Error(`No membership found for company '${companySlug}'.`);
+    }
+    for (const failedLookup of enriched) {
+        if (!failedLookup.ok) {
+            const detail = failedLookup.error instanceof Error ? failedLookup.error.message : String(failedLookup.error);
+            console.error(`getSyncModeForCompany: entity lookup failed for membership ${failedLookup.membership.membershipKey} while resolving '${companySlug}': ${detail}`);
+        }
+    }
+    const membershipId = match.membership.membershipKey;
+    const config = await vaultClient.getMembershipSyncConfig(membershipId);
+    return { membershipId, companySlug, config };
+}
 // ── Table rendering (used by CLI action, separable for tests) ──────────────
 /**
  * Render the `--show` table as plain text. No external dep — hq-cli doesn't

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,32 +1,58 @@
 /**
- * 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. */
     args: string[];
 };
+export type ParsedSecretsEnvFastRequest = {
+    options: {
+        only: string[];
+        script?: string;
+        scriptId?: string;
+    };
+    scope: {
+        company?: string;
+        personal?: boolean;
+    };
+};
+/**
+ * Parse the small, non-ambiguous `hq secrets env` surface for the gated entry
+ * fast path. Anything this parser does not understand stays with Commander in
+ * the full CLI, which remains the source of truth for help and errors.
+ */
+export declare function parseSecretsEnvFastRequest(argv: readonly string[]): ParsedSecretsEnvFastRequest | null;
 /**
  * Parse `hq core [--hq-root <path>] <name> [args...]` when `<name>` is a
  * fast-path script. Returns null for anything else so the caller defers to the