@indigoai-us/hq-cli 5.345.127 → 5.345.129

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

@@ -437,6 +437,13 @@ export interface LaneAccountsHandlerDeps {
     readClaudeAccountBalanceSignalsEnabled(ctx: Ctx): Promise<boolean>;
     reconcileHostFromCtx(ctx: Ctx): ReconcileHost;
     resolveCallerPath(callerCwd: string, filePath: string): string;
+    /** Admit queued lanes in-process after capacity changes; returns admitted lanes. */
+    admitQueuedFromCtx(ctx: Ctx): Promise<Array<{
+        id: string;
+        from?: string;
+        to?: string;
+        reason?: string;
+    }>>;
 }
 export interface LaneQuestionsHandlerDeps {
     CAPACITY_PROBE_TIMEOUT_MS: number;

package/dist/commands/lanes.js

@@ -24,6 +24,7 @@ export { resolveAnswerChoice } from "./lanes-questions.js";
 import { registerOutpostPrunerCommand } from "./outpost-pruner.js";
 import { registerLaneKpisCommand } from "./lanes-kpis.js";
 import { registerLaneKeepAliveAuditCommand } from "./lanes-keep-alive-audit.js";
+import { finishReconcilePass } from "../lib/lanes/reconcile-result.js";
 import { registerLaneAutopilotReportCommand } from "./lanes-autopilot.js";
 import { registerLaneChecksCommand } from "./lanes-checks.js";
 import { registerLaneDropboxRepairCommand } from "./lanes-dropbox-repair.js";
@@ -41,11 +42,12 @@ import { runResidentCommandWithPackageLease } from "../utils/resident-package-pr
 import { codexEnvEvidence, grokEnvEvidence } from "../lib/doctor/platform.js";
 import { readLanesFlagLocalOverride, readLanesRegistryFlag, readLanesRegistryFlagFailOff, readLanesRegistryFlagFailOpen } from "../lib/lanes/registry-flag.js";
 import { readLaneStatusRowFields } from "../lib/lanes/status-fields.js";
+import { registerDaemonLanesReconcileHandler } from "../lib/lanes/daemon-reconcile.js";
 import { appendProjectFocusOverride, readProjectStoryFocusData, removeProjectFocusOverride } from "../lib/lanes/story-ledger.js";
 import { appendLaneFocusOverride, assertFocusGuardAllows, makeFocusOverride } from "../lib/lanes/focus-guard.js";
 import { LANE_FOCUS_GUARD_FLAG, LANE_FOCUS_DASHBOARD_FLAG, LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_LIST_SKIP_REMOTE_REFRESH_FLAG, LANE_MESSAGE_ROUTE_OWNER_HOST_FLAG, LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG, LANE_PROFILE_PIN_EXHAUSTED_FALLBACK_FLAG, LANE_STATUS_ROW_FIELDS_FLAG, LANE_REAP_STOP_FLAG, LANE_REUSE_REFRESHES_PROFILE_FLAG, LANE_WORKER_CONTINUITY_FLAG, LANE_CONDUCT_LOOP_FLAG, LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG, } from "../lib/lanes/flag-keys.js";
 import { findWorkerContinuityLane, sameLaneHost, workerContinuityPrompt } from "../lib/lanes/worker-continuity.js";
-import { enqueueLoopEnvelope, interruptLoopQueue, interruptLoopQueueForStory, loopControllerIsAlive, loopStatus, validateLoopEnvelope } from "../lib/lanes/loop.js";
+import { commitIdleLoopStop, enqueueLoopEnvelope, interruptLoopQueue, interruptLoopQueueForStory, loopControllerIsAlive, loopStatus, validateLoopEnvelope } from "../lib/lanes/loop.js";
 import { runLaneLoopController, startLaneLoopController } from "./lanes-loop.js";
 import { configuredCodexRolloutHomes, retainCodexRollouts } from "../lib/lanes/disk-guard.js";
 import { isControllerAliasOutpostId } from "../lib/lanes/admission-host.js";
@@ -76,6 +78,7 @@ import { listLaneReviews } from "../lib/lanes/reviews.js";
 import { effectiveAccountHome } from "../lib/lanes/account-home.js";
 import { remoteControlSelectionConfig, remoteControlSessionHome } from "../lib/lanes/remote-control-lane.js";
 import { AccountResolutionError, compareLaneQueueOrder, LANE_PROVIDERS, LANE_STATES, QUESTION_STATUSES, SENIOR_KINDS, accountStatus, appendCappedHistory, canonicalizeHome, createLane, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, isFinishedResumableHireChild, childrenHoldingHireGrantCarve, laneHoldsHireGrantCarve, assignedChildHireGrants, hireGrantCapacityError, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, laneStoryLedgerEnabled, syncLaneToProjectStoryLedger, removeLaneFromProjectStoryLedger, validateProjectStories, buildLaneStatusSnapshot, formatLaneStatusHuman, listLaneIds, listQuestionIds, loadLanesConfig, laneRunsHere, MAX_LANE_DEPTH, MONITOR_ERROR_EXIT_CODE, readLiveMonitorEvidence, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, isLaneProvider, parseLaneRecord, parseLaneState, parseQuestionRecord, parseSeniorKind, readAllLanes, readLane, sanitizeHostComponent, retryUpdateLane, syncLaneRecordFromOwner, readQuestion, resolveAccount, resolveLaneWorker, ignoredWorkerProfileFields, loadWorkerProfile, loadWorkerProfileWithRegistry, registryWorkerRecord, runReconcilePass, DEAD_HOST_MS, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, dropboxDir, laneDeliveryMechanism, hasActiveAdmissionReservation, hasActivePendingResume, hasRecordedSessionId, hasEarlierEligibleQueuedLane, laneAdmissionCapReason, providerSupportsSessionResume, providerSessionPortable, isFailedQuotaKeepAliveLane, sessionNotPortableMessage, withLaneAdmissionLock, withAllLaneAdmissionLocks, readWorkerRunResult, resumeCommandRefusal, withLaneHireLocks, raiseLaneQuestion, sha256Text, } from "../lib/lanes/index.js";
+import { admitQueuedNow } from "../lib/lanes/reconcile.js";
 import { laneStories, storyWarning, } from "../lib/lanes/stories.js";
 import { resolveLaneKeepAlive } from "../lib/lanes/profile.js";
 import { laneCompanyUidSource, resolveLaneCompany } from "../lib/lanes/lane-company.js";
@@ -490,6 +493,82 @@ function livenessDepsFromCtx(ctx) {
         hostname: ctx.hostname,
     };
 }
+/**
+ * Admit queued lanes in-process after a command frees or adds capacity, so
+ * the queue drains without `hq daemon`. Best effort: an admission failure is
+ * reported on stderr and never fails the command that freed the slot.
+ */
+async function admitQueuedFromCtx(ctx) {
+    try {
+        const result = await admitQueuedNow(ctx.hqRoot(), {
+            now: ctx.now,
+            host: reconcileHostFromCtx(ctx),
+            dryRun: false,
+            spawnLaneDeps: {
+                env: ctx.env,
+                existsSync: ctx.existsSync,
+                spawnProcess: ctx.spawnProcess,
+                proveDetached: ctx.proveDetached,
+                killProcess: ctx.killProcess,
+                now: ctx.now,
+                resolveMachineIdentity: ctx.resolveMachineIdentity,
+                runCompaction: ctx.runCompaction,
+                locateTranscript: ctx.locateTranscript,
+            },
+            throttleDeps: ctx.throttleDeps,
+            livenessDeps: livenessDepsFromCtx(ctx),
+            presenceConnected: ctx.presenceConnected,
+            mesh: ctx.mesh,
+            env: ctx.env,
+        });
+        for (const error of result.errors) {
+            process.stderr.write(`hq lanes: queue admission: ${error.message}\n`);
+        }
+        return result.admitted;
+    }
+    catch (err) {
+        process.stderr.write(`hq lanes: queue admission failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return [];
+    }
+}
+/**
+ * End a queued loop lane whose queue holds only a stop envelope and whose
+ * controller is not running. Without this the lane waits for admission just
+ * to read the stop, and counts as busy for its worker until then.
+ */
+async function finalizeIdleLoopStop(ctx, lane) {
+    if (lane.loop_mode !== true || lane.state !== "queued")
+        return undefined;
+    const hqRoot = ctx.hqRoot();
+    const runDirPath = runDir(hqRoot, lane.lane_id);
+    if (loopControllerIsAlive(runDirPath))
+        return undefined;
+    if (!commitIdleLoopStop(runDirPath, lane.lane_id, ctx.now))
+        return undefined;
+    let stopped;
+    try {
+        stopped = casUpdateLane(hqRoot, lane.lane_id, (current) => {
+            if (current.state !== "queued") {
+                throw new LanesError("lane_state_changed", `Lane ${lane.lane_id} left the queue while its stop was committed`, { lane_id: lane.lane_id, state: current.state });
+            }
+            return {
+                ...current,
+                state: "done",
+                queued_reason: undefined,
+                queued_details: undefined,
+                admission_reserved_at: undefined,
+                terminal_reason: "loop_stopped",
+            };
+        });
+    }
+    catch (err) {
+        if (err instanceof LanesError && err.error === "lane_state_changed")
+            return undefined;
+        throw err;
+    }
+    await emitLaneTerminalStateSoft(ctx, stopped);
+    return stopped;
+}
 function reconcileHostFromCtx(ctx) {
     return resolveAdmissionHost({
         hostname: ctx.hostname,
@@ -3522,6 +3601,17 @@ async function runCreate(ctx, opts) {
         throw new LanesError("lane_title_requires_remote_control", "--title is only supported with --remote-control", {});
     }
     const continuityEnabled = opts.remoteControl !== true && opts.worker !== undefined && await readLanesRegistryFlagFailOpen(LANE_WORKER_CONTINUITY_FLAG, { company: company ?? meshCompany, env: ctx.env, defaultValue: true });
+    // A lane that waits only on the admitter (a queued loop lane holding just a
+    // stop, or a queued lane with free capacity) is not busy: finish it here.
+    const preCreateAdmitted = [];
+    if (continuityEnabled) {
+        const workerId = resolvedWorker?.id ?? opts.worker;
+        const waiting = loadAllLanes(hqRoot).filter((lane) => lane.worker === workerId && lane.provider === provider && lane.state === "queued");
+        for (const lane of waiting)
+            await finalizeIdleLoopStop(ctx, lane);
+        if (waiting.length > 0)
+            preCreateAdmitted.push(...await admitQueuedFromCtx(ctx));
+    }
     let workerContinuity = continuityEnabled
         ? findWorkerContinuityLane(loadAllLanes(hqRoot), {
             senior,
@@ -4337,10 +4427,19 @@ async function runCreate(ctx, opts) {
                 : undefined,
         });
     }
+    // Admit queued lanes (older ones first) now that this create has settled.
+    // Outpost lanes are admitted on their Outpost.
+    const admitted = [...preCreateAdmitted];
+    if (!outpostId) {
+        admitted.push(...await admitQueuedFromCtx(ctx));
+        if (admitted.some((entry) => entry.id === started.lane_id))
+            started = readLane(hqRoot, started.lane_id);
+    }
     if (!opts.quiet)
         printJson({
             ok: true,
             action: "create",
+            admitted,
             lane_id: started.lane_id,
             state: started.state,
             queued_reason: started.queued_reason ?? null,
@@ -7410,7 +7509,7 @@ async function prepareAccountMove(ctx, lane, input) {
     });
     const block = quotaBlockFor(loadQuotaState(hqRoot), lane.provider, target, model, now);
     if (block.blocked) {
-        throw new LanesError("account_quota_held", `Account ${target} for ${lane.provider} is held${block.quota_reset_at ? ` until ${block.quota_reset_at}` : ""}${block.marker ? ` (${block.marker})` : ""}. Clear the hold with: hq lanes accounts clear-quota ${lane.provider} ${target}`, { provider: lane.provider, account: target, quota_reset_at: block.quota_reset_at ?? null, marker: block.marker ?? null, model: model ?? null, clear_command: `hq lanes accounts clear-quota ${lane.provider} ${target}` });
+        throw new LanesError("account_quota_held", `Account ${target} for ${lane.provider} cannot run model ${model ?? "(default)"}: the account's model needs credits${block.marker ? ` (${block.marker})` : ""}. Once credits are added, clear the marker with: hq lanes accounts clear-quota ${lane.provider} ${target}`, { provider: lane.provider, account: target, quota_reset_at: block.quota_reset_at ?? null, marker: block.marker ?? null, model: model ?? null, clear_command: `hq lanes accounts clear-quota ${lane.provider} ${target}` });
     }
     if (model !== undefined) {
         validateLaneModel(lane.provider, model, targetHome, {
@@ -8705,8 +8804,18 @@ async function runStop(ctx, laneId, reason, quiet = false) {
         const queued = enqueueLoopEnvelope({ runDir: runDirPath, laneId: lane.lane_id, envelope: { kind: "stop" }, now: ctx.now });
         if (!controllerAlive && lane.state !== "queued")
             startLaneLoopController(ctx, lane.lane_id);
+        const finalized = !controllerAlive ? await finalizeIdleLoopStop(ctx, readLane(hqRoot, lane.lane_id)) : undefined;
+        const admitted = await admitQueuedFromCtx(ctx);
         if (!quiet)
-            printJson({ ok: true, action: "stop", lane_id: lane.lane_id, terminal: false, queued_stop: queued });
+            printJson({
+                ok: true,
+                action: "stop",
+                lane_id: lane.lane_id,
+                terminal: finalized !== undefined,
+                queued_stop: queued,
+                ...(finalized ? { lane: finalized } : {}),
+                admitted,
+            });
         return;
     }
     if (isTerminalLaneState(lane.state)) {
@@ -8744,6 +8853,7 @@ async function runStop(ctx, laneId, reason, quiet = false) {
     }
     await emitLaneTerminalStateSoft(ctx, updated);
     const cancelled = cancelPendingQuestionsForLane(hqRoot, laneId, at);
+    const admitted = await admitQueuedFromCtx(ctx);
     if (!quiet)
         printJson({
             ok: true,
@@ -8752,6 +8862,7 @@ async function runStop(ctx, laneId, reason, quiet = false) {
             terminal: true,
             resumable: false,
             cancelled_questions: cancelled.map((q) => q.question_id),
+            admitted,
         });
 }
 /** Stderr notice that `stop` ends a lane for good, naming the resumable path. */
@@ -9429,21 +9540,21 @@ async function runReconcile(ctx, opts, recoverQueuedMessages) {
         summary.errors.push({ code: error instanceof LanesError ? error.error : "lead_autopilot_failed", message });
         process.stderr.write(`hq lanes autopilot: ${message}\n`);
     }
-    printJson({
-        ...summary,
-        ...(autopilotRegistrySync ? { autopilot_registry_sync: autopilotRegistrySync } : {}),
-        ...(autopilot ? { autopilot } : {}),
-        ...(remoteLost.length > 0 ? { remote_lost: remoteLost } : {}),
-        ...(mirrorRefresh.unverifiedRemote.size > 0
-            ? {
-                unverified_remote_lanes: [...mirrorRefresh.unverifiedRemote.keys()]
-                    .filter((id) => !terminalizedRemoteIds.has(id)),
-            }
-            : {}),
-    });
-    if (!summary.ok) {
-        process.exit(1);
+    if (!opts.inProcess) {
+        printJson({
+            ...summary,
+            ...(autopilotRegistrySync ? { autopilot_registry_sync: autopilotRegistrySync } : {}),
+            ...(autopilot ? { autopilot } : {}),
+            ...(remoteLost.length > 0 ? { remote_lost: remoteLost } : {}),
+            ...(mirrorRefresh.unverifiedRemote.size > 0
+                ? {
+                    unverified_remote_lanes: [...mirrorRefresh.unverifiedRemote.keys()]
+                        .filter((id) => !terminalizedRemoteIds.has(id)),
+                }
+                : {}),
+        });
     }
+    finishReconcilePass(summary, opts.inProcess ? "daemon" : "cli");
 }
 async function runReconcileInstall(ctx, opts) {
     // `hq daemon` runs lanes-reconcile on this machine; a separate timer would run it twice.
@@ -9540,6 +9651,7 @@ export function registerLanesCommand(parent, deps = {}) {
         readClaudeAccountBalanceSignalsEnabled,
         reconcileHostFromCtx,
         resolveCallerPath,
+        admitQueuedFromCtx,
     });
     const questionHandlers = createLaneQuestionsHandlers({
         CAPACITY_PROBE_TIMEOUT_MS,
@@ -9647,6 +9759,16 @@ export function registerLanesCommand(parent, deps = {}) {
         withResumeHireAdmission,
     };
     const messageHandlers = createLaneMessageHandlers(messageHandlerDeps);
+    const daemonReconcileCtx = { ...ctx, env: { ...ctx.env } };
+    registerDaemonLanesReconcileHandler(async () => {
+        const hqRoot = daemonReconcileCtx.hqRoot();
+        daemonReconcileCtx.env.HQ_ROOT = hqRoot;
+        daemonReconcileCtx.cwd = () => hqRoot;
+        daemonReconcileCtx.callerCwd = () => hqRoot;
+        await runReconcile(daemonReconcileCtx, { inProcess: true }, async (lane) => {
+            await messageHandlers.recoverQueuedMessages(daemonReconcileCtx, lane.lane_id);
+        });
+    });
     monitorLaneMessageApis.set(parent, (laneId, payload) => messageHandlers.deliverMonitorLaneMessage(ctx, laneId, payload));
     const resumeHandlers = createLaneResumeHandlers({
         onLaneWorkerStarted: deps.onLaneWorkerStarted,

package/dist/commands/mesh.js

@@ -307,16 +307,21 @@ function parseProjectReposJson(raw, source) {
         throw err;
     }
 }
-function projectStoriesFromJson(value, source) {
+function projectStoriesFromJson(value, source, options = {}) {
     const plan = Array.isArray(value) ? null : record(value);
-    const rawStories = Array.isArray(value)
-        ? value
-        : Array.isArray(plan?.userStories)
-            ? plan.userStories
-            : Array.isArray(plan?.stories)
-                ? plan.stories
-                : null;
-    if (!rawStories) {
+    if (options.requireUserStories && (!plan || !Array.isArray(plan.userStories))) {
+        fail(`${source} must be a PRD object with a userStories array.`);
+    }
+    const rawStories = options.requireUserStories
+        ? plan?.userStories ?? null
+        : Array.isArray(value)
+            ? value
+            : Array.isArray(plan?.userStories)
+                ? plan.userStories
+                : Array.isArray(plan?.stories)
+                    ? plan.stories
+                    : null;
+    if (!Array.isArray(rawStories)) {
         fail(`${source} must be a JSON story array or an object with userStories.`);
     }
     const rejectedStories = [];
@@ -398,7 +403,7 @@ function failProjectStoryStates(rejected, json) {
 }
 function parseProjectPlan(raw, source, options = {}) {
     try {
-        const plan = projectStoriesFromJson(JSON.parse(raw), source);
+        const plan = projectStoriesFromJson(JSON.parse(raw), source, options);
         if (plan.rejectedStories.length && !options.allowRejectedStories) {
             throw new RejectedProjectStoryStatesError(plan.rejectedStories);
         }
@@ -431,7 +436,7 @@ async function runProjectSet(projectId, opts) {
         fail("Pass only one of --repos-json or --repo.");
     }
     const source = opts.storiesFile
-        ? parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile)
+        ? parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { requireUserStories: true })
         : opts.storiesJson
             ? parseProjectPlan(opts.storiesJson, "--stories-json")
             : undefined;
@@ -588,12 +593,17 @@ async function runProjectMemberAdd(projectId, personUid, opts) {
 async function runProjectEnsure(projectId, opts) {
     if (!opts.storiesFile?.trim())
         fail("`--stories-file <prd.json>` is required.");
-    const source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { allowRejectedStories: true });
-    const { token, company } = await withCompany(opts);
-    if (source.rejectedStories.length && source.stories.length === 0) {
-        failProjectStoryStates(source.rejectedStories, Boolean(opts.json));
+    let source;
+    try {
+        source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { requireUserStories: true });
+    }
+    catch (err) {
+        if (!(err instanceof RejectedProjectStoryStatesError) || !opts.json)
+            throw err;
+        failProjectStoryStates(err.rejected, true);
         return;
     }
+    const { token, company } = await withCompany(opts);
     let current;
     try {
         current = await getProjectView(token, company.companyUid, projectId);
@@ -738,7 +748,10 @@ async function runProjectEnsure(projectId, opts) {
 async function runProjectReconcile(projectId, opts) {
     if (!opts.storiesFile?.trim())
         fail("`--stories-file <prd.json>` is required.");
-    const source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { allowRejectedStories: true });
+    const source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, {
+        requireUserStories: true,
+        allowRejectedStories: true,
+    });
     const { token, company } = await withCompany(opts);
     let current;
     try {
@@ -852,7 +865,7 @@ async function runPrdSync(opts) {
             return;
         }
         try {
-            const source = parseProjectPlan(readFileSync(file, "utf8"), file);
+            const source = parseProjectPlan(readFileSync(file, "utf8"), file, { requireUserStories: true });
             await ensureMissingBoardStories({
                 token,
                 company: {
@@ -1091,7 +1104,7 @@ async function runBindProject(target, opts) {
         }
         if (!current.companyUid)
             fail(`Session ${sessionId} has no company. Bind a company first.`);
-        const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath);
+        const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath, { requireUserStories: true });
         const { token, company } = await withCompany({ company: opts.company ?? current.companySlug });
         await ensureProjectBoard({
             token,
@@ -1234,7 +1247,7 @@ async function runContextReconcile(opts) {
         validateMembership,
         ensureProjectBoard: token
             ? async ({ companyUid, projectId, prdPath }) => {
-                const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath);
+                const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath, { requireUserStories: true });
                 await ensureProjectBoard({
                     token,
                     company: { companyUid, companySlug: companyUid },

package/dist/commands/skill.js

@@ -190,16 +190,21 @@ function displayNameFromSlug(slug) {
         .join(" ");
 }
 export function makeSkillTemplate(input) {
-    const name = input.name?.trim() || displayNameFromSlug(input.slug);
+    // Frontmatter `name` is the slash-command name in Claude Code and Codex, so it
+    // must be the slug. A spaced display title there breaks command entry in the
+    // Claude desktop app. The display title goes in frontmatter `title` (which
+    // HQ Pro shows in the console) and in the heading.
+    const title = input.name?.trim() || displayNameFromSlug(input.slug);
     const description = input.description?.trim() ?? "";
     return [
         "---",
-        `name: ${JSON.stringify(name)}`,
+        `name: ${JSON.stringify(input.slug)}`,
+        `title: ${JSON.stringify(title)}`,
         `description: ${JSON.stringify(description)}`,
         "tags: []",
         "---",
         "",
-        `# ${name}`,
+        `# ${title}`,
         "",
         "Describe when and how to use this skill.",
         "",
@@ -466,7 +471,7 @@ export function registerSkillCommand(program, deps = {}) {
     skill
         .command("create <slug>")
         .description("Register, stamp, surface, and sync a company skill")
-        .option("--name <name>", "Display name when creating a new template")
+        .option("--name <name>", "Display title for a new template, written as frontmatter title (frontmatter name is always the slug)")
         .option("--description <text>", "Description when creating a new template")
         .option("--no-sync", "Register locally without uploading the stamped file")
         .option("--surface-only", "Refresh local skill discovery without registration or sync")

package/dist/fast-scaffold.js

@@ -160,6 +160,30 @@ export function isDefaultOnFastFamily(flagKey) {
 }
 /** The relocated scripts that qualify for the entrypoint fast path. */
 export const FAST_SCAFFOLD_SCRIPTS = [
+    {
+        name: "hq-detach",
+        kind: "native",
+        modulePath: "./commands/core-bucket-c-hq-detach-fast.js",
+        exportName: "runHqDetachFast",
+        flagKey: "hq-core-native-fast-route",
+        familyFlagKey: "core-native-bucket-c",
+        asset: "core/scripts/hq-detach.sh",
+        root: "cwd",
+        shellCwd: "caller",
+        shellHqRoot: "none",
+    },
+    {
+        name: "handoff-knowledge-commit",
+        kind: "native",
+        modulePath: "./commands/core-bucket-c-handoff-knowledge-fast.js",
+        exportName: "runHandoffKnowledgeCommitFast",
+        flagKey: "hq-core-native-fast-route",
+        familyFlagKey: "core-native-bucket-c",
+        asset: "core/scripts/handoff-knowledge-commit.sh",
+        root: "cwd",
+        shellCwd: "caller",
+        shellHqRoot: "none",
+    },
     {
         name: "work-mesh-project-registration-offer",
         kind: "native",
@@ -897,6 +921,10 @@ export function isFastCoreRequest(argv) {
 }
 /** Metadata-only help can render without importing the selected command graph. */
 export function isCommandHelpRequest(argv) {
+    // `core` owns the argument parser even when global options appear before
+    // its subcommand; its child commands pass --help through to their handlers.
+    if (argv[2] === "core" || argv[2] === "run")
+        return false;
     const args = argv.slice(2);
     const delimiter = args.indexOf("--");
     const beforeDelimiter = delimiter === -1 ? args : args.slice(0, delimiter);

package/dist/lib/bot/inbox-poll-backoff-flag.d.ts

@@ -2,6 +2,8 @@ import { type FlagClient, type FlagClientOptions } from "@indigoai-us/hq-flags-c
 import { type BotConfig } from "./config.js";
 export declare const INBOX_POLL_BACKOFF_FLAG = "agents.inbox-poll-backoff-local-cli";
 export declare const INBOX_POLL_BACKOFF_FLAG_FALLBACK = false;
+export declare const INBOX_MQTT_WAKE_FLAG = "agents.bot-inbox-mqtt-wake";
+export declare const INBOX_MQTT_WAKE_FLAG_FALLBACK = true;
 export declare const INBOX_POLL_BACKOFF_FLAG_TIMEOUT_MS = 2000;
 export declare const INBOX_POLL_BACKOFF_FLAG_CACHE_MS: number;
 type InboxPollBackoffFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
@@ -14,11 +16,7 @@ export interface InboxPollBackoffFlagReaderDependencies {
     reportFailure?: (error: unknown) => void;
 }
 export declare function safeErrorClass(error: unknown): string;
-/**
- * Create a per-bot reader. The flag client is opened at most once per three
- * minutes; a missing identity, failed request, or malformed snapshot keeps
- * idle polling at its existing two-second interval.
- */
 export declare function createInboxPollBackoffFlagReader(config: Pick<BotConfig, "kind" | "workerId" | "companies" | "companySlug" | "hqRoot">, dependencies?: InboxPollBackoffFlagReaderDependencies): () => Promise<boolean>;
+export declare function createInboxMqttWakeFlagReader(config: Pick<BotConfig, "kind" | "workerId" | "companies" | "companySlug" | "hqRoot">, dependencies?: InboxPollBackoffFlagReaderDependencies): () => Promise<boolean>;
 export {};
 //# sourceMappingURL=inbox-poll-backoff-flag.d.ts.map

package/dist/lib/bot/inbox-poll-backoff-flag.js

@@ -5,6 +5,8 @@ import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
 import { effectiveBotCompanies, effectiveBotKind } from "./config.js";
 export const INBOX_POLL_BACKOFF_FLAG = "agents.inbox-poll-backoff-local-cli";
 export const INBOX_POLL_BACKOFF_FLAG_FALLBACK = false;
+export const INBOX_MQTT_WAKE_FLAG = "agents.bot-inbox-mqtt-wake";
+export const INBOX_MQTT_WAKE_FLAG_FALLBACK = true;
 // One read every three minutes on a fresh connection. From a home network the
 // TCP and TLS handshakes plus the resolve call take about 250-400 ms, so a
 // 150 ms budget timed out on every read and kept the gate off.
@@ -15,8 +17,8 @@ export function safeErrorClass(error) {
     const name = error instanceof Error ? error.name : "UnknownError";
     return /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(name) ? name : "UnknownError";
 }
-function reportFlagFailure(error) {
-    process.stderr.write(`HQ local bot inbox poll backoff flag lookup failed (${safeErrorClass(error)}); using default off.\n`);
+function reportFlagFailure(error, fallback) {
+    process.stderr.write(`HQ local bot inbox flag lookup failed (${safeErrorClass(error)}); using default ${fallback ? "on" : "off"}.\n`);
 }
 function companyContexts(config, env) {
     if (effectiveBotKind(config) !== "company")
@@ -44,9 +46,9 @@ function companyContexts(config, env) {
 /**
  * Create a per-bot reader. The flag client is opened at most once per three
  * minutes; a missing identity, failed request, or malformed snapshot keeps
- * idle polling at its existing two-second interval.
+ * registered fallback.
  */
-export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
+function createInboxFlagReader(config, flagKey, fallback, dependencies = {}) {
     const env = dependencies.env ?? process.env;
     const contexts = companyContexts(config, env);
     const endpoint = resolveFlagRegistryEndpoint(undefined, env);
@@ -54,15 +56,15 @@ export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
     const createClient = dependencies.createClient ?? createFlagClient;
     const getToken = dependencies.getToken ?? (() => loadCachedTokens()?.idToken ?? "");
     const doFetch = dependencies.fetch ?? globalThis.fetch;
-    const report = dependencies.reportFailure ?? reportFlagFailure;
-    let cachedValue = INBOX_POLL_BACKOFF_FLAG_FALLBACK;
+    const report = dependencies.reportFailure ?? ((error) => reportFlagFailure(error, fallback));
+    let cachedValue = fallback;
     let lastReadAt = Number.NEGATIVE_INFINITY;
     let pending = null;
     const readContext = async (context) => {
         let client;
         let failed = false;
         let failureReported = false;
-        let enabled = INBOX_POLL_BACKOFF_FLAG_FALLBACK;
+        let enabled = fallback;
         const reportFailureOnce = (error) => {
             failed = true;
             if (failureReported)
@@ -84,7 +86,7 @@ export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
             });
             await client.ready();
             if (!failed) {
-                enabled = resolveFlagGate(client, INBOX_POLL_BACKOFF_FLAG, { fallback: INBOX_POLL_BACKOFF_FLAG_FALLBACK }, () => INBOX_POLL_BACKOFF_FLAG_FALLBACK);
+                enabled = resolveFlagGate(client, flagKey, { fallback }, () => fallback);
             }
         }
         catch (error) {
@@ -98,12 +100,12 @@ export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
                 reportFailureOnce(error);
             }
         }
-        return failed ? INBOX_POLL_BACKOFF_FLAG_FALLBACK : enabled;
+        return failed ? fallback : enabled;
     };
     const read = async () => {
         if (!contexts || contexts.length === 0) {
-            report(new Error("local bot inbox poll backoff flag has no resolvable company identity"));
-            return INBOX_POLL_BACKOFF_FLAG_FALLBACK;
+            report(new Error("local bot inbox flag has no resolvable company identity"));
+            return fallback;
         }
         const values = await Promise.all(contexts.map(readContext));
         return values.every(Boolean);
@@ -123,7 +125,7 @@ export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
         })
             .catch((error) => {
             report(error);
-            cachedValue = INBOX_POLL_BACKOFF_FLAG_FALLBACK;
+            cachedValue = fallback;
             return cachedValue;
         })
             .finally(() => {
@@ -132,4 +134,10 @@ export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
         return pending;
     };
 }
+export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
+    return createInboxFlagReader(config, INBOX_POLL_BACKOFF_FLAG, INBOX_POLL_BACKOFF_FLAG_FALLBACK, dependencies);
+}
+export function createInboxMqttWakeFlagReader(config, dependencies = {}) {
+    return createInboxFlagReader(config, INBOX_MQTT_WAKE_FLAG, INBOX_MQTT_WAKE_FLAG_FALLBACK, dependencies);
+}
 //# sourceMappingURL=inbox-poll-backoff-flag.js.map

package/dist/lib/bot/inbox-wake.d.ts

@@ -0,0 +1,18 @@
+import * as fs from "node:fs";
+export { AGENT_INBOX_PUSH_STATE_BASENAME } from "../mesh/live/paths.js";
+type WakeEvent = "wake" | "timeout" | "aborted";
+type Watcher = Pick<fs.FSWatcher, "close"> & {
+    on?: (event: "error", listener: (error: Error) => void) => unknown;
+};
+export interface InboxWakeWatcher {
+    wait(delayMs: number, signal?: AbortSignal): Promise<WakeEvent>;
+    isLiveFor?(agentUid: string): boolean;
+    close(): void;
+}
+/** Watches the content-free Work Mesh inbox sequence, with a bounded poll fallback. */
+export declare function createInboxWakeWatcher(root: string, options?: {
+    watch?: (root: string, listener: (event: string, filename: string | Buffer | null) => void) => Watcher;
+    onError?: (error: unknown) => void;
+    now?: () => number;
+}): InboxWakeWatcher;
+//# sourceMappingURL=inbox-wake.d.ts.map