@indigoai-us/hq-cli 5.345.176 → 5.345.178

package/dist/lib/bot/fleet-local.d.ts

@@ -40,6 +40,7 @@ export interface FleetLocalProfile {
         baseUrl?: string;
         transport?: string;
     };
+    ownerCompanies?: string[];
     hqRoot: string;
     profileDir: string;
     runtime: {
@@ -69,7 +70,27 @@ export interface FleetLocalProfileInput {
     installation: FleetLocalInstallation;
     /** The bot's standing HQ instructions; written as the runtime's SOUL.md persona. */
     systemPrompt?: string;
+    /** Which model login the bot answers with; ChatGPT when omitted. */
+    provider?: FleetLocalProfile["provider"];
+    /** The hello and first task the runtime sends and runs once, on its first start. */
+    firstStart?: {
+        intro?: string;
+        kickoff?: string;
+    };
+    /** Companies the owner's own turns may use; other senders get none of them. */
+    ownerCompanies?: string[];
 }
+/** The model the HQ Fleet Runtime asks for when a Claude bot names none. */
+export declare const FLEET_CLAUDE_DEFAULT_MODEL = "claude-opus-5-5";
+/**
+ * The runtime provider for a bot created from a model CLI choice. Claude uses
+ * the runtime's native Anthropic provider, which reads the owner's Claude Code
+ * login, so it needs no sign-in of its own; ChatGPT and Grok sign in with
+ * `hq bot auth`.
+ */
+export declare function fleetProviderForRuntime(runtime: string, model?: string): FleetLocalProfile["provider"];
+/** True when a bot with this provider still needs `hq bot auth` before it can answer. */
+export declare function fleetProviderNeedsSignIn(provider: FleetLocalProfile["provider"]): boolean;
 type FleetLocalExec = (executable: string, args: string[], options: Record<string, unknown>) => Buffer | string;
 export interface FleetLocalBootstrapDeps {
     fleetHome?: string;
@@ -91,6 +112,7 @@ export interface FleetLocalControlDeps {
     run?: FleetLocalExec;
 }
 export interface FleetLocalAuthInput {
+    installService?: boolean;
     agentUid: string;
     provider: string;
     model?: string;
@@ -128,6 +150,11 @@ export declare function fleetLocalPromotionRuntime(agentUid: string, deps?: Flee
 export declare function removeFleetLocalBot(agentUid: string, deps?: FleetLocalControlDeps): FleetLocalRemovalResult;
 export declare function authenticateFleetLocalBot(input: FleetLocalAuthInput, deps?: FleetLocalControlDeps): FleetLocalAuthResult;
 export declare function writeFleetLocalProfile(input: FleetLocalProfileInput, deps?: Pick<FleetLocalBootstrapDeps, "fleetHome" | "platform">): string;
+/** The runtime's inbox plugin sends the intro and runs the kickoff once, then stamps this file. */
+export declare function writeFleetLocalFirstStart(profileDir: string, firstStart: {
+    intro?: string;
+    kickoff?: string;
+}): string;
 export declare function writeFleetLocalSoul(agentUid: string, systemPrompt: string, deps?: Pick<FleetLocalControlDeps, "fleetHome">): string;
 /**
  * The pinned runtime refuses a persona file that trips its context-file
@@ -137,6 +164,8 @@ export declare function writeFleetLocalSoul(agentUid: string, systemPrompt: stri
 export declare function scanFleetLocalInstructions(agentUid: string, text: string, deps?: FleetLocalControlDeps): string[];
 /** Checks the instructions with the runtime's scanner, then makes them the bot's persona. */
 export declare function refreshFleetLocalInstructions(agentUid: string, systemPrompt: string, deps?: FleetLocalControlDeps): string;
+/** Moves a fresh machine credential into the bot's secure store and deletes the file. */
+export declare function importFleetLocalMachineCredential(agentUid: string, machineCredentials: string, deps?: FleetLocalControlDeps): void;
 export declare function bootstrapFleetLocalBot(input: FleetLocalProfileInput & {
     machineCredentials: string;
 }, deps?: FleetLocalBootstrapDeps): Promise<FleetLocalBootstrapResult>;

package/dist/lib/bot/fleet-local.js

@@ -7,16 +7,42 @@ import { HQ_FLEET_RUNTIME_ENGINE_ID, } from "./config.js";
 import { ensureFleetPython, fleetUvEnv } from "./fleet-python.js";
 import { ensureCognitoToken } from "../../utils/cognito-session.js";
 import { vaultApiFetch } from "../../utils/vault-api.js";
+/** The model the HQ Fleet Runtime asks for when a Claude bot names none. */
+export const FLEET_CLAUDE_DEFAULT_MODEL = "claude-opus-5-5";
+/**
+ * The runtime provider for a bot created from a model CLI choice. Claude uses
+ * the runtime's native Anthropic provider, which reads the owner's Claude Code
+ * login, so it needs no sign-in of its own; ChatGPT and Grok sign in with
+ * `hq bot auth`.
+ */
+export function fleetProviderForRuntime(runtime, model) {
+    if (runtime === "claude") {
+        const requested = model?.trim() ?? "";
+        return { id: "anthropic", model: /^claude-[a-z0-9.-]+$/.test(requested) ? requested : FLEET_CLAUDE_DEFAULT_MODEL };
+    }
+    const preset = providerProfiles[runtime === "grok" ? "grok" : "chatgpt"];
+    return {
+        id: preset.provider,
+        model: model?.trim() || preset.model,
+        credentialProvider: preset.runtimeProvider,
+        baseUrl: preset.baseUrl,
+        transport: preset.transport,
+    };
+}
+/** True when a bot with this provider still needs `hq bot auth` before it can answer. */
+export function fleetProviderNeedsSignIn(provider) {
+    return provider.id !== "anthropic";
+}
 export const HQ_FLEET_LOCAL_RELEASE = {
     repository: "indigoai-us/hq-fleet-local",
-    tag: "v0.4.6",
-    version: "0.4.6",
-    artifact: "hq-fleet-local-0.4.6.zip",
-    artifactSha256: "24e48887dd4450ad63eda11e61f78363b0cc53b3fc87e3fd21bfe97e4a430865",
+    tag: "v0.4.12",
+    version: "0.4.12",
+    artifact: "hq-fleet-local-0.4.12.zip",
+    artifactSha256: "2a07e79b1740e8ef68b19078b73b10cdf9377065a2fd1f53287b7e353099c577",
     runtimeArtifact: "hq-fleet-runtime-abccac13bd9e.tar",
     runtimeArtifactSha256: "29bcfe718ad7fbd3636afd00623772f2a25bc84c4f6f10d8d57f38e549d528d5",
-    manifestSha256: "5cc06b30a724419c22f4ab116db1ae745158d33c4aa46c7be04d29639172af1d",
-    signatureSha256: "b7a6c771dc674423b56db36f58b5a2a2a49eb2e27b33a41206fcc228a11d1def",
+    manifestSha256: "cdac590bdcebea6629de0c164c42c7baf30c025a299ff5829380989dd22a9ff1",
+    signatureSha256: "f07911dd3187393cd325fc8f88ddaa6a7568825aee6d8748a992cea822d5d9b1",
     runtimeCommit: "abccac13bd9ea593b24c8cd9c0ba28d5c6050cc9",
 };
 export const HQ_FLEET_LOCAL_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
@@ -417,7 +443,9 @@ function replaceProfileProvider(profilePath, agentUid, provider) {
     const credentialProviders = Array.isArray(profile.credentialProviders)
         ? profile.credentialProviders.filter((value) => typeof value === "string")
         : [];
-    profile.credentialProviders = [...new Set([...credentialProviders, provider.credentialProvider])];
+    profile.credentialProviders = [
+        ...new Set([...credentialProviders, ...(provider.credentialProvider ? [provider.credentialProvider] : [])]),
+    ];
     const temporary = `${profilePath}.${process.pid}.${crypto.randomUUID()}`;
     fs.writeFileSync(temporary, `${JSON.stringify(profile, null, 2)}\n`, { mode: 0o600 });
     fs.renameSync(temporary, profilePath);
@@ -498,6 +526,16 @@ export function authenticateFleetLocalBot(input, deps = {}) {
     if (!/^[a-z0-9][a-z0-9._:-]*$/.test(requested)) {
         throw expectedError("HQ Fleet provider identifier is invalid.");
     }
+    if ((requested === "claude" || requested === "anthropic") && !input.apiKey) {
+        const files = fleetLocalExecutables(input.agentUid, deps);
+        const run = deps.run ?? execFileSync;
+        const native = fleetProviderForRuntime("claude", input.model);
+        replaceProfileProvider(files.profile, input.agentUid, native);
+        runJson(run, files.helper, ["render-profile", "--spec", files.profile, "--mode", "update"], { stdio: ["ignore", "pipe", "pipe"] }, "profile update");
+        runJson(run, files.helper, ["doctor-profile", "--profile", files.profileDir, "--runtime", files.runtime], { stdio: ["ignore", "pipe", "pipe"] }, "profile validation");
+        const restarted = controlFleetLocalBot(input.agentUid, input.installService ? "install" : "restart", deps).ok === true;
+        return { provider: requested, runtimeProvider: "anthropic", model: native.model, authenticated: true, restarted };
+    }
     const known = providerProfiles[requested];
     const provider = known ?? {
         provider: `custom:personal-${requested}`,
@@ -558,7 +596,7 @@ export function authenticateFleetLocalBot(input, deps = {}) {
     });
     runJson(run, files.helper, ["render-profile", "--spec", files.profile, "--mode", "update"], { stdio: ["ignore", "pipe", "pipe"] }, "profile update");
     runJson(run, files.helper, ["doctor-profile", "--profile", files.profileDir, "--runtime", files.runtime], { stdio: ["ignore", "pipe", "pipe"] }, "profile validation");
-    const restarted = controlFleetLocalBot(input.agentUid, "restart", deps).ok === true;
+    const restarted = controlFleetLocalBot(input.agentUid, input.installService ? "install" : "restart", deps).ok === true;
     return {
         provider: requested,
         runtimeProvider: provider.runtimeProvider,
@@ -583,7 +621,8 @@ export function writeFleetLocalProfile(input, deps = {}) {
         schemaVersion: 1,
         botId: input.agentUid,
         ownerUid: input.ownerUid,
-        provider: { id: "custom:personal-chatgpt", model: "gpt-5.6-sol" },
+        ...(input.ownerCompanies?.length ? { ownerCompanies: [...new Set(input.ownerCompanies)].sort() } : {}),
+        provider: input.provider ?? { id: "custom:personal-chatgpt", model: "gpt-5.6-sol" },
         hqRoot: path.resolve(input.hqRoot),
         profileDir: path.resolve(dir),
         runtime: { commit: input.installation.release.runtimeCommit, path: path.resolve(runtimeDir) },
@@ -599,6 +638,24 @@ export function writeFleetLocalProfile(input, deps = {}) {
     fs.renameSync(temporary, destination);
     if (input.systemPrompt !== undefined)
         writeFleetLocalSoul(input.agentUid, input.systemPrompt, { fleetHome: root });
+    if (input.firstStart && (input.firstStart.intro || input.firstStart.kickoff)) {
+        writeFleetLocalFirstStart(dir, input.firstStart);
+    }
+    return destination;
+}
+/** The runtime's inbox plugin sends the intro and runs the kickoff once, then stamps this file. */
+export function writeFleetLocalFirstStart(profileDir, firstStart) {
+    const destination = path.join(profileDir, "first-start.json");
+    if (fs.existsSync(destination))
+        return destination;
+    const temporary = path.join(profileDir, `.first-start-${process.pid}-${crypto.randomUUID()}`);
+    const record = {
+        schemaVersion: 1,
+        ...(firstStart.intro ? { intro: firstStart.intro } : {}),
+        ...(firstStart.kickoff ? { kickoff: firstStart.kickoff } : {}),
+    };
+    fs.writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, destination);
     return destination;
 }
 export function writeFleetLocalSoul(agentUid, systemPrompt, deps = {}) {
@@ -669,6 +726,24 @@ function checkedRun(run, executable, args, options, label) {
         throw expectedError(`HQ Fleet Local ${label} failed.`);
     }
 }
+/** Moves a fresh machine credential into the bot's secure store and deletes the file. */
+export function importFleetLocalMachineCredential(agentUid, machineCredentials, deps = {}) {
+    const run = deps.run ?? execFileSync;
+    const files = fleetLocalExecutables(agentUid, deps);
+    const machineValue = fs.readFileSync(machineCredentials, "utf8").trim();
+    if (!machineValue) {
+        throw expectedError(`HQ Fleet Local machine credential file is empty: ${machineCredentials}`);
+    }
+    checkedRun(run, files.helper, [
+        "machine-credential",
+        "import",
+        "--profile",
+        files.profileDir,
+        "--bot-id",
+        agentUid,
+    ], { input: machineValue, stdio: ["pipe", "ignore", "pipe"] }, "machine credential import");
+    fs.rmSync(machineCredentials, { force: true });
+}
 export async function bootstrapFleetLocalBot(input, deps = {}) {
     const run = deps.run ?? execFileSync;
     const platform = deps.platform ?? process.platform;
@@ -716,7 +791,7 @@ export async function bootstrapFleetLocalBot(input, deps = {}) {
             "--python",
             runtimePython,
             "--editable",
-            `${runtimeSource}[all,messaging,slack,anthropic]`,
+            `${runtimeSource}[mcp,anthropic]`,
             distributionSource,
         ], { stdio: ["ignore", 2, 2], env: uvEnv }, "package installation");
         fs.writeFileSync(marker, `${JSON.stringify({ schemaVersion: 1, engine: input.installation.engine }, null, 2)}\n`, { mode: 0o600 });

package/dist/lib/bot/index.d.ts

@@ -26,5 +26,6 @@ export * from "./lock.js";
 export * from "./display-name.js";
 export * from "./decisions.js";
 export * from "./fleet-local.js";
+export * from "./fleet-default-flag.js";
 export * from "./fleet-python.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/bot/index.js

@@ -26,5 +26,6 @@ export * from "./lock.js";
 export * from "./display-name.js";
 export * from "./decisions.js";
 export * from "./fleet-local.js";
+export * from "./fleet-default-flag.js";
 export * from "./fleet-python.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/bot/local-config.js

@@ -41,7 +41,7 @@ export function buildBotLocalConfig(config) {
     const companies = effectiveBotCompanies(config);
     const local = {
         v: 1,
-        ...(config.engine ? {} : { runtime: config.runtime }),
+        runtime: config.runtime,
         ...(config.engine ? { engine: config.engine } : {}),
         workerSource: config.workerSource ?? "scaffold",
         ...(config.workerId ? { workerId: config.workerId } : {}),

package/dist/lib/daemon/catalog.d.ts

@@ -21,6 +21,8 @@ export declare function isServiceName(value: unknown): value is ServiceName;
 export declare const SERVICE_DESCRIPTIONS: Record<ServiceName, string>;
 /** The services each machine type runs without being asked. */
 export declare const DEFAULT_SERVICES: Record<MachineType, readonly ServiceName[]>;
+/** Services another enabled service turns on; only an explicit disable keeps them off. */
+export declare const IMPLIED_SERVICES: Partial<Record<ServiceName, ServiceName>>;
 /** Defaults plus this host's overrides, in catalog order. Unknown names are ignored. */
 export declare function enabledServices(machineType: MachineType, overrides: {
     enable: readonly string[];

package/dist/lib/daemon/catalog.js

@@ -80,12 +80,17 @@ export const DEFAULT_SERVICES = {
     "agent-box": ["mesh", "heartbeat", "inbox", "search-index", "updater", "housekeeping"],
     "agent-kit": ["heartbeat", "inbox", "updater", "housekeeping"],
 };
+/** Services another enabled service turns on; only an explicit disable keeps them off. */
+export const IMPLIED_SERVICES = { mesh: "sync-core" };
 /** Defaults plus this host's overrides, in catalog order. Unknown names are ignored. */
 export function enabledServices(machineType, overrides) {
     const defaults = DEFAULT_SERVICES[machineType];
     const wanted = (s) => (defaults.includes(s) || overrides.enable.includes(s)) && !overrides.disable.includes(s);
-    const wakeSubscriber = wanted("sync-core") && !overrides.disable.includes("mesh");
-    return SERVICE_NAMES.filter((s) => wanted(s) || (s === "mesh" && wakeSubscriber));
+    const implied = (s) => {
+        const by = IMPLIED_SERVICES[s];
+        return by !== undefined && wanted(by) && !overrides.disable.includes(s);
+    };
+    return SERVICE_NAMES.filter((s) => wanted(s) || implied(s));
 }
 export const SYNC_CORE_RECONCILE_UNIT = "sync-core";
 export const SYNC_CORE_RECONCILE_INTERVAL_SEC = 600;

package/dist/lib/daemon/config.d.ts

@@ -29,7 +29,8 @@ export declare function readDaemonConfig(file: string): DaemonConfig;
 export declare function writeDaemonConfig(file: string, config: DaemonConfig): void;
 /**
  * Turn services on or off for this host, relative to the machine type's
- * defaults: only differences from the defaults are stored.
+ * defaults: only differences from the defaults are stored. A disable is also
+ * stored for a service another service can turn on, so it stays off.
  */
 export declare function applyServiceToggle(config: DaemonConfig, action: "enable" | "disable", services: readonly string[], defaults: readonly ServiceName[]): DaemonConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/lib/daemon/config.js

@@ -7,7 +7,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { valid as validSemver } from "semver";
-import { isServiceName } from "./catalog.js";
+import { IMPLIED_SERVICES, isServiceName } from "./catalog.js";
 import { isMachineType } from "./machine-type.js";
 import { ensurePrivateDir } from "./paths.js";
 export function effectiveSyncOwner(config, machineType) {
@@ -81,7 +81,8 @@ export function writeDaemonConfig(file, config) {
 }
 /**
  * Turn services on or off for this host, relative to the machine type's
- * defaults: only differences from the defaults are stored.
+ * defaults: only differences from the defaults are stored. A disable is also
+ * stored for a service another service can turn on, so it stays off.
  */
 export function applyServiceToggle(config, action, services, defaults) {
     for (const s of services) {
@@ -99,7 +100,7 @@ export function applyServiceToggle(config, action, services, defaults) {
         }
         else {
             enable.delete(s);
-            if (isDefault)
+            if (isDefault || (isServiceName(s) && IMPLIED_SERVICES[s] !== undefined))
                 disable.add(s);
         }
     }

package/dist/lib/mesh/live/daemon/work-subscribe.d.ts

@@ -17,6 +17,7 @@ export interface WorkCacheSubscriber {
 export { AGENT_INBOX_PUSH_STATE_BASENAME, SYNC_WAKE_STATE_BASENAME } from "../paths.js";
 export type SyncWakeVaults = Record<string, {
     wakeSequence: number;
+    head?: number;
 }>;
 export declare function startWorkCacheSubscriber(opts: {
     meshRoot: string;

package/dist/lib/mesh/live/daemon/work-subscribe.js

@@ -15,6 +15,7 @@ const INBOX_PUSH_HEARTBEAT_MS = 5_000;
 const SYNC_WAKE_KEYS = new Set(["v", "type", "vault", "head", "rootId"]);
 const SYNC_WAKE_VAULT = /^(?:prs|cmp|agt)_[0-9A-Za-z]+$/;
 const SYNC_WAKE_ROOT = /^[0-9a-f]{64}$/i;
+const SYNC_WAKE_MAX_BYTES = 4_096;
 function parseSyncWakeEnvelope(payload) {
     let parsed;
     try {
@@ -38,7 +39,7 @@ function parseSyncWakeEnvelope(payload) {
         Number(message.head) > 0 &&
         (message.rootId === null ||
             (typeof message.rootId === "string" && SYNC_WAKE_ROOT.test(message.rootId)));
-    return valid ? { vault: message.vault } : null;
+    return valid ? { vault: message.vault, head: Number(message.head) } : null;
 }
 function readVaultSequences(raw) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
@@ -47,9 +48,11 @@ function readVaultSequences(raw) {
     for (const [vault, entry] of Object.entries(raw)) {
         if (!SYNC_WAKE_VAULT.test(vault) || !entry || typeof entry !== "object")
             continue;
-        const sequence = entry.wakeSequence;
+        const { wakeSequence: sequence, head } = entry;
         if (Number.isSafeInteger(sequence) && Number(sequence) >= 0) {
-            vaults[vault] = { wakeSequence: Number(sequence) };
+            vaults[vault] = Number.isSafeInteger(head) && Number(head) >= 0
+                ? { wakeSequence: Number(sequence), head: Number(head) }
+                : { wakeSequence: Number(sequence) };
         }
     }
     return vaults;
@@ -85,6 +88,9 @@ function readWakeSequence(meshRoot, basename, label, onInfo) {
         };
     }
 }
+function withoutHeads(vaults) {
+    return Object.fromEntries(Object.entries(vaults).map(([vault, entry]) => [vault, { wakeSequence: entry.wakeSequence }]));
+}
 function writeWakeState(meshRoot, basename, state, durable) {
     fs.mkdirSync(meshRoot, { recursive: true, mode: 0o700 });
     const rootInfo = fs.lstatSync(meshRoot);
@@ -162,15 +168,27 @@ export async function startWorkCacheSubscriber(opts) {
             timers.clearTimeout(heartbeatTimer);
         heartbeatTimer = null;
     };
+    let syncWakeHeadsOmitted = false;
     const persistState = (basename, label, connected, wakeSequence, identity, durable = true, vaults) => {
         try {
-            writeWakeState(opts.meshRoot, basename, {
+            const state = {
                 connected,
                 heartbeatAtMs: now().getTime(),
                 wakeSequence,
                 ...(connected && actorUid && identity ? { [identity]: actorUid } : {}),
                 ...(vaults ? { vaults } : {}),
-            }, durable);
+            };
+            if (vaults) {
+                const oversized = Buffer.byteLength(`${JSON.stringify(state)}\n`) > SYNC_WAKE_MAX_BYTES;
+                if (oversized) {
+                    state.vaults = withoutHeads(vaults);
+                    if (!syncWakeHeadsOmitted) {
+                        opts.onInfo?.(`${label} state over ${SYNC_WAKE_MAX_BYTES} bytes; vault heads omitted`);
+                    }
+                }
+                syncWakeHeadsOmitted = oversized;
+            }
+            writeWakeState(opts.meshRoot, basename, state, durable);
         }
         catch (error) {
             const name = error instanceof Error ? error.name : "UnknownError";
@@ -318,8 +336,10 @@ export async function startWorkCacheSubscriber(opts) {
                     return;
                 }
                 syncWakeSequence += 1;
+                const previous = syncWakeVaults[envelope.vault];
                 syncWakeVaults[envelope.vault] = {
-                    wakeSequence: (syncWakeVaults[envelope.vault]?.wakeSequence ?? 0) + 1,
+                    wakeSequence: (previous?.wakeSequence ?? 0) + 1,
+                    head: Math.max(previous?.head ?? 0, envelope.head),
                 };
                 persistSyncState(true);
                 return;

package/dist/lib/sync-core/release.d.ts

@@ -1,4 +1,4 @@
-export declare const SYNC_CORE_RELEASE = "v0.1.20";
+export declare const SYNC_CORE_RELEASE = "v0.1.21";
 export declare const SYNC_CORE_COMPANY_FULL_RELEASE: string | null;
 export declare function compareSyncCoreReleases(a: string, b: string): number;
 export declare function companyFullModeAllowed(release: string): boolean;

package/dist/lib/sync-core/release.js

@@ -3,8 +3,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { execFileSync } from "node:child_process";
-export const SYNC_CORE_RELEASE = "v0.1.20";
-export const SYNC_CORE_COMPANY_FULL_RELEASE = "v0.1.20";
+export const SYNC_CORE_RELEASE = "v0.1.21";
+export const SYNC_CORE_COMPANY_FULL_RELEASE = "v0.1.21";
 export function compareSyncCoreReleases(a, b) {
     const parse = (release) => release.replace(/^v/, "").split(".").map((part) => Number.parseInt(part, 10) || 0);
     const [x, y] = [parse(a), parse(b)];

package/dist/run/hq-plugin.d.ts

@@ -18,6 +18,9 @@ export interface PluginState {
     }>;
     loadedSecretsByName: Map<string, string>;
 }
+/** True when the varlock item has an `# @optional` decorator. */
+export declare function itemIsOptional(item: unknown): boolean;
+export declare function isSkippableOptionalSecretError(code: string | undefined): boolean;
 export declare function installHqPlugin(graph: any, opts: InstallHqPluginOpts): PluginState;
 export declare function prewarmHqSecrets(graph: any, opts: InstallHqPluginOpts, state: PluginState): Promise<void>;
 //# sourceMappingURL=hq-plugin.d.ts.map

package/dist/run/hq-plugin.js

@@ -16,6 +16,15 @@ function normalizeCacheTtlMs(secret) {
         ? secret.cacheTtlMs
         : 0;
 }
+const SKIPPABLE_OPTIONAL_CODES = new Set(['forbidden', 'not_found', 'not_returned']);
+/** True when the varlock item has an `# @optional` decorator. */
+export function itemIsOptional(item) {
+    const decorators = item?.effectiveDecorators;
+    return Boolean(decorators && Object.prototype.hasOwnProperty.call(decorators, 'optional'));
+}
+export function isSkippableOptionalSecretError(code) {
+    return Boolean(code && SKIPPABLE_OPTIONAL_CODES.has(code));
+}
 export function installHqPlugin(graph /* EnvGraph */, opts) {
     const pluginState = {
         schemaCompanySlug: null,
@@ -63,6 +72,10 @@ export function installHqPlugin(graph /* EnvGraph */, opts) {
                 }
                 const err = pluginState.errorsByName.get(secretName);
                 if (err) {
+                    // `# @optional`: missing ACL or a missing secret leaves the var unset.
+                    if (itemIsOptional(this._ownerItem) && isSkippableOptionalSecretError(err.code)) {
+                        return undefined;
+                    }
                     if (err.code === 'forbidden') {
                         throw new ResolutionError(`No read permission for secret "${secretName}" — ask an admin to share it via \`hq secrets share ${secretName} --with <you> --permission read\``);
                     }
@@ -85,13 +98,18 @@ export function installHqPlugin(graph /* EnvGraph */, opts) {
                 if (inMemory != null) {
                     return inMemory;
                 }
+                if (itemIsOptional(this._ownerItem)) {
+                    return undefined;
+                }
                 throw new ResolutionError(`Secret "${secretName}" was not returned by vault after server authorization`);
             },
         };
         // Captured during process(parent); used by resolve() to fall back to the var key.
         _ownerKey;
+        _ownerItem;
         process(parent) {
             super.process(parent);
+            this._ownerItem = parent;
             if (parent != null && typeof parent.key === 'string') {
                 this._ownerKey = parent.key;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.176",
+  "version": "5.345.178",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -114,11 +114,11 @@
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   },
   "optionalDependencies": {
-    "@indigoai-us/hq-hook-win32-x64": "5.345.176",
-    "@indigoai-us/hq-hook-win32-arm64": "5.345.176",
-    "@indigoai-us/hq-hook-darwin-x64": "5.345.176",
-    "@indigoai-us/hq-hook-darwin-arm64": "5.345.176",
-    "@indigoai-us/hq-hook-linux-x64": "5.345.176",
-    "@indigoai-us/hq-hook-linux-arm64": "5.345.176"
+    "@indigoai-us/hq-hook-win32-x64": "5.345.178",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.178",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.178",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.178",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.178",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.178"
   }
 }