@indigoai-us/hq-cli 5.345.160 → 5.345.162

package/dist/commands/lanes-loop.js

@@ -7,7 +7,7 @@ import { readLatestEnvelopeRecord } from "../lib/lanes/watcher.js";
 import { spawnLaneWorker } from "../lib/lanes/spawn.js";
 import { raiseLaneQuestion } from "../lib/lanes/questions.js";
 import { isTerminalLaneState } from "../lib/lanes/types.js";
-import { clearLoopControllerPid, loopAdmissionPath, runLoopLane, setLoopControllerPid } from "../lib/lanes/loop.js";
+import { HANDOFF_HOLD_CHOICES, clearLoopControllerPid, loopAdmissionPath, runLoopLane, setLoopControllerPid } from "../lib/lanes/loop.js";
 import { laneStories } from "../lib/lanes/stories.js";
 import { readLanesRegistryFlagFailOpen } from "../lib/lanes/registry-flag.js";
 import { LANE_LOOP_HANDOFF_REPAIR_FLAG } from "../lib/lanes/flag-keys.js";
@@ -255,7 +255,7 @@ export async function runLaneLoopController(ctx, laneId, deps) {
                     signal.removeEventListener("abort", abortPhase);
                 }
             },
-            raiseQuestion: ({ envelope, envelopeId, attempt, error, questionId }) => {
+            raiseQuestion: ({ envelope, envelopeId, attempt, error, questionId, reason }) => {
                 const current = readLane(hqRoot, laneId);
                 const data = envelope;
                 raiseLaneQuestion({
@@ -265,11 +265,11 @@ export async function runLaneLoopController(ctx, laneId, deps) {
                     raisedVia: "cli",
                     at: ctx.now().toISOString(),
                     body: {
-                        question: `Loop phase ${String(data.phase ?? envelopeId)} stalled twice. How should it proceed?`,
-                        context: `${error}\nThe phase is parked; later envelopes remain queued. Stall attempt: ${attempt}.`,
-                        options: ["Retry with a longer deadline", "Reroute to another worker", "Drop this phase and block the story"],
-                        recommended: "Retry with a longer deadline",
-                        loop_stall: { lane_id: laneId, envelope_id: envelopeId, attempt },
+                        question: reason === "handoff_needs_repair" ? `Loop phase ${String(data.phase ?? envelopeId)} has an invalid handoff. How should it proceed?` : `Loop phase ${String(data.phase ?? envelopeId)} stalled twice. How should it proceed?`,
+                        context: reason === "handoff_needs_repair" ? `${error}\nThe worker file is preserved and the phase is parked; later envelopes remain queued. Repair the handoff file before accepting it. Retrying can repeat external effects.` : `${error}\nThe phase is parked; later envelopes remain queued. Stall attempt: ${attempt}.`,
+                        options: reason === "handoff_needs_repair" ? [...HANDOFF_HOLD_CHOICES] : ["Retry with a longer deadline", "Reroute to another worker", "Drop this phase and block the story"],
+                        recommended: reason === "handoff_needs_repair" ? HANDOFF_HOLD_CHOICES[0] : "Retry with a longer deadline",
+                        loop_stall: { lane_id: laneId, envelope_id: envelopeId, attempt, ...(reason ? { reason } : {}) },
                     },
                 });
             },

package/dist/commands/lanes-questions.js

@@ -1,4 +1,5 @@
 import * as path from "node:path";
+import { readSessionCompanyLock } from "../lib/session-company-lock.js";
 import { isQuestionImported } from "../lib/lanes/imported-question.js";
 import { buildOutpostQuestionAnswerCommand, buildOutpostQuestionCancelCommand, buildOutpostQuestionShowCommand, dispatchErrorMessage } from "../lib/lanes/outpost-dispatch.js";
 import { assertNoSecretText } from "../lib/lanes/text-scan.js";
@@ -6,7 +7,7 @@ import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
 import { appendCappedHistory, createQuestion, expandLocalLaneIdPrefix, isLanesError, listSessionLiveness, parseLivenessState, parseQuestionRecord, parseQuestionStatus, readDaemonPresenceConnected, readLane, readQuestion, wakeAnsweredLaneNow, sessionLiveness, appendDropboxMessage, answerDropboxMessage, laneAcceptsDropboxDelivery, laneIdForAnswerDelivery, writeQuestionBody } from "../lib/lanes/index.js";
 import { resolveQuestionCompanyWithFallback } from "../lib/lanes/questions.js";
 import { LanesError } from "../lib/lanes/errors.js";
-import { applyLoopStallAnswer, findLoopStallResult } from "../lib/lanes/loop.js";
+import { HANDOFF_HOLD_CHOICES, applyLoopStallAnswer, findLoopStallResult, loopHandoffHoldIdentity } from "../lib/lanes/loop.js";
 export function resolveAnswerChoice(choice, options, freeform) {
     const trimmed = choice.trim();
     if (/^[0-9]+$/.test(trimmed)) {
@@ -847,11 +848,48 @@ export function createLaneQuestionsHandlers(deps) {
         const retryingSameLoopAnswer = isLoopStallQuestion && question.status === "answered" && question.answer?.choice === choice &&
             question.answer.answer_kind === incomingAnswerKind && incomingNotesMatch &&
             deps.sameQuestionAnswer(question.answer, { ...question.answer });
-        if (question.status !== "pending" && !retryingSameLoopAnswer)
-            throwIfQuestionNotPending(question);
         const loopStallResult = isLoopStallQuestion
             ? findLoopStallResult(path.join(hqRoot, "workspace", "lanes-runs", askingLane.lane_id), questionId)
             : undefined;
+        if (loopStallResult?.hold_reason === "handoff_needs_repair" && !HANDOFF_HOLD_CHOICES.includes(choice)) {
+            throw new LanesError("invalid_handoff_disposition", "Choose an explicit handoff repair disposition", { question_id: questionId });
+        }
+        const handoffIdentity = askingLane.loop_mode ? loopHandoffHoldIdentity(path.join(hqRoot, "workspace", "lanes-runs", askingLane.lane_id)) : undefined;
+        const changingHeldAnswer = body.loop_stall?.reason === "handoff_needs_repair" && isLoopStallQuestion &&
+            question.status === "answered" && question.answer?.choice === HANDOFF_HOLD_CHOICES[2] &&
+            choice !== HANDOFF_HOLD_CHOICES[2] && handoffIdentity?.unresolved === true &&
+            handoffIdentity.question_id === questionId && handoffIdentity.envelope_id === body.loop_stall.envelope_id &&
+            loopStallResult?.hold_reason === "handoff_needs_repair";
+        if (question.status !== "pending" && !retryingSameLoopAnswer && !changingHeldAnswer)
+            throwIfQuestionNotPending(question);
+        const isHandoffQuestion = body.loop_stall?.reason === "handoff_needs_repair" || loopStallResult?.hold_reason === "handoff_needs_repair" || handoffIdentity !== undefined;
+        if (isHandoffQuestion) {
+            assertQuestionAnswerAuthorized(ctx, askingLane);
+            assertLaneRunsHereForOperatorMutation(ctx, askingLane, "resolve a handoff repair hold on");
+            const targetCompany = questionCompanyForLane(question, askingLane, hqRoot);
+            const lock = readSessionCompanyLock({ ...ctx.env, HQ_ROOT: hqRoot });
+            const actorLaneId = ctx.env.HQ_LANE_ID?.trim();
+            if (actorLaneId) {
+                const actorLane = readLane(hqRoot, actorLaneId);
+                const actorCompany = actorLane.company ?? actorLane.mesh_company;
+                if (!targetCompany || !actorCompany || !sameQuestionCompany(actorCompany, targetCompany))
+                    throw new LanesError("handoff_answer_company_mismatch", "Caller lane does not own this handoff company", { question_id: questionId });
+            }
+            // Lane-only callers may use their owned lane identity; a present session lock
+            // always constrains that identity and may never be widened by HQ_LANE_ID.
+            if ((lock || !actorLaneId) && (!lock || !targetCompany || !lock.companies.includes(targetCompany.slug))) {
+                throw new LanesError("handoff_answer_company_mismatch", "The current session is not bound to this handoff company", { question_id: questionId });
+            }
+            if (!isLoopStallQuestion || body.loop_stall?.reason !== "handoff_needs_repair" ||
+                (handoffIdentity && (handoffIdentity.question_id !== questionId || handoffIdentity.envelope_id !== body.loop_stall.envelope_id)) ||
+                (loopStallResult && loopStallResult.envelope_id !== body.loop_stall.envelope_id)) {
+                throw new LanesError("handoff_question_identity_mismatch", "The persisted handoff question and hold identities do not match", { question_id: questionId });
+            }
+            if (!HANDOFF_HOLD_CHOICES.includes(choice))
+                throw new LanesError("invalid_handoff_disposition", "Choose an explicit handoff repair disposition", { question_id: questionId });
+            if (!loopStallResult && question.status === "pending")
+                throw new LanesError("handoff_result_missing", "The handoff hold result is missing; no disposition was applied", { question_id: questionId });
+        }
         const at = ctx.now().toISOString();
         const answeredBy = sessionIdFromEnv(ctx.env)
             ? `session:${sessionIdFromEnv(ctx.env)}`
@@ -860,7 +898,14 @@ export function createLaneQuestionsHandlers(deps) {
             if (retryingSameLoopAnswer && current.status === "answered" && current.answer?.choice === choice &&
                 deps.sameQuestionAnswer(current.answer, question.answer))
                 return current;
-            throwIfQuestionNotPending(current);
+            const currentHold = changingHeldAnswer ? loopHandoffHoldIdentity(path.join(hqRoot, "workspace", "lanes-runs", askingLane.lane_id)) : undefined;
+            const stillHeld = changingHeldAnswer && current.status === "answered" &&
+                current.answer?.choice === HANDOFF_HOLD_CHOICES[2] &&
+                deps.sameQuestionAnswer(current.answer, question.answer) &&
+                currentHold?.unresolved === true && currentHold.question_id === questionId &&
+                currentHold.envelope_id === body.loop_stall?.envelope_id;
+            if (!stillHeld)
+                throwIfQuestionNotPending(current);
             assertQuestionCompanyAccess(current, askingLane, requestedCompany, hqRoot);
             const recordedCompany = current.company ?? questionCompany;
             const currentForBody = current.company === null
@@ -882,6 +927,7 @@ export function createLaneQuestionsHandlers(deps) {
                 body: nextBody,
                 status: "answered",
                 delivered_at: null,
+                ...(stillHeld && current.answer ? { answer_history: [...(current.answer_history ?? []), current.answer] } : {}),
                 answer: {
                     choice,
                     answer_kind: freeform ? "freeform" : "option",
@@ -911,6 +957,10 @@ export function createLaneQuestionsHandlers(deps) {
                 printJson({ ok: true, action: "questions.answer", lane_id: askingLane.lane_id, question: updated, loop_action: resolved.action });
                 return;
             }
+            if (isHandoffQuestion && resolved.action === "parked") {
+                printJson({ ok: true, action: "questions.answer", lane_id: askingLane.lane_id, question: updated, loop_action: "parked" });
+                return;
+            }
             const controllerPid = await deps.restartLoopController(ctx, askingLane.lane_id);
             printJson({ ok: true, action: "questions.answer", lane_id: askingLane.lane_id, question: updated, loop_action: resolved.action, controller_pid: controllerPid });
             return;

package/dist/commands/lanes-session-start.d.ts

@@ -8,9 +8,21 @@ export interface SessionStartOptions {
     stderr?: Pick<NodeJS.WriteStream, "write">;
     resolveRoot?: (env: NodeJS.ProcessEnv, cwd?: string) => string;
     startSweep?: (root: string, env: NodeJS.ProcessEnv) => void;
+    /** Starts the off-hot-path registry read when an offline flag value is missing or old. */
+    refreshFlags?: (env: NodeJS.ProcessEnv) => void;
 }
+/** Offline flag values older than this trigger one background registry read. */
+export declare const SESSION_START_FLAG_REFRESH_AFTER_MS: number;
 /** Starts the CL-4 read-only orphan report once per host, without holding SessionStart open. */
 export declare function startSessionStartOrphanSweep(root: string, env?: NodeJS.ProcessEnv, spawnDetached?: typeof spawn, rootScoped?: boolean): void;
+/**
+ * Start a detached `hq lanes session-start --refresh-flags` so the registry
+ * read never runs inside the SessionStart hook. A short lease keeps a burst of
+ * session starts to one refresh. An env without a state dir never spawns.
+ */
+export declare function startSessionStartFlagRefresh(env: NodeJS.ProcessEnv, spawnDetached?: typeof spawn, now?: number): boolean;
+/** Read the session-start flags from the registry, refreshing the offline cache. */
+export declare function refreshSessionStartFlags(env?: NodeJS.ProcessEnv): Promise<void>;
 /** SessionStart-compatible, fail-open conduct bootstrap. */
 export declare function runLaneSessionStart(options?: SessionStartOptions): Promise<void>;
 export declare function registerLaneSessionStartCommand(lanes: Command): void;

package/dist/commands/lanes-session-start.js

@@ -4,8 +4,17 @@ import os from "node:os";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
-import { readLanesRegistryFlagFailOpen } from "../lib/lanes/registry-flag.js";
+import { readLanesRegistryFlagOffline, readLanesRegistryFlagResult } from "../lib/lanes/registry-flag.js";
 import { LANE_CONDUCT_SESSION_START_FLAG, LANE_ORPHAN_SWEEP_CONTEXT_FLAG, LANE_ORPHAN_SWEEP_ROOT_KEYING_FLAG } from "../lib/lanes/flag-keys.js";
+const SESSION_START_FLAGS = [
+    LANE_CONDUCT_SESSION_START_FLAG,
+    LANE_ORPHAN_SWEEP_ROOT_KEYING_FLAG,
+    LANE_ORPHAN_SWEEP_CONTEXT_FLAG,
+];
+/** Offline flag values older than this trigger one background registry read. */
+export const SESSION_START_FLAG_REFRESH_AFTER_MS = 10 * 60 * 1000;
+const SESSION_START_FLAG_REFRESH_LEASE_MS = 60 * 1000;
+const SESSION_START_FLAG_REFRESH_LEASE = "lanes-session-start-flag-refresh.lock";
 const CODEX_DEFAULT_KEYS = ["conduct_engine", "conduct_child_model", "conduct_child_effort", "conduct_default_source"];
 function readSessionMetaValue(text, key) {
     const line = text.split(/\r?\n/).find((entry) => new RegExp(`^\\s*${key}:`).test(entry));
@@ -247,6 +256,58 @@ export function startSessionStartOrphanSweep(root, env = process.env, spawnDetac
         // SessionStart's orphan report is advisory and must never block startup.
     }
 }
+function flagRefreshLeaseDir(env) {
+    const stateDir = env.HQ_STATE_DIR?.trim();
+    if (stateDir)
+        return stateDir;
+    const home = env.HOME?.trim() || env.USERPROFILE?.trim();
+    return home ? path.join(home, ".hq") : null;
+}
+/**
+ * Start a detached `hq lanes session-start --refresh-flags` so the registry
+ * read never runs inside the SessionStart hook. A short lease keeps a burst of
+ * session starts to one refresh. An env without a state dir never spawns.
+ */
+export function startSessionStartFlagRefresh(env, spawnDetached = spawn, now = Date.now()) {
+    const dir = flagRefreshLeaseDir(env);
+    const cli = process.argv[1];
+    if (!dir || !cli)
+        return false;
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const lease = path.join(dir, SESSION_START_FLAG_REFRESH_LEASE);
+        try {
+            if (now - fs.statSync(lease).mtimeMs < SESSION_START_FLAG_REFRESH_LEASE_MS)
+                return false;
+            fs.rmSync(lease, { force: true });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return false;
+        }
+        try {
+            fs.closeSync(fs.openSync(lease, "wx", 0o600));
+        }
+        catch {
+            return false;
+        }
+        const child = spawnDetached(process.execPath, [cli, "lanes", "session-start", "--refresh-flags"], {
+            detached: true,
+            stdio: "ignore",
+            env: { ...env, HQ_NO_UPDATE_CHECK: "1" },
+        });
+        child.on("error", () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read the session-start flags from the registry, refreshing the offline cache. */
+export async function refreshSessionStartFlags(env = process.env) {
+    await Promise.all(SESSION_START_FLAGS.map((flag) => readLanesRegistryFlagResult(flag, { env, defaultValue: true, reportFailure: () => undefined }).catch(() => undefined)));
+}
 /** SessionStart-compatible, fail-open conduct bootstrap. */
 export async function runLaneSessionStart(options = {}) {
     const env = options.env ?? process.env;
@@ -278,19 +339,33 @@ export async function runLaneSessionStart(options = {}) {
         if (/(^|,)auto-conduct(,|$)/.test(disabledHooks))
             return;
         const root = (options.resolveRoot ?? ((e, cwd) => resolveLanesHqRoot({ env: e, cwd })))(env, options.cwd);
-        const flagEnabled = await readLanesRegistryFlagFailOpen(LANE_CONDUCT_SESSION_START_FLAG, {
-            env,
-            defaultValue: true,
-            reportFailure: (error) => {
-                const kind = error instanceof Error ? error.name : "Error";
-                debug(`hq lanes session-start: flag read failed (${kind})`);
-            },
-        });
+        // Flags come from offline state only. A missing or old value fails open and
+        // schedules one background registry read for the next session start.
+        let refreshNeeded = false;
+        const readFlag = (flag) => {
+            let read = null;
+            try {
+                read = readLanesRegistryFlagOffline(flag, { env, defaultValue: true });
+            }
+            catch {
+                read = null;
+            }
+            if (!read || (read.source !== "local-override" && read.ageMs > SESSION_START_FLAG_REFRESH_AFTER_MS))
+                refreshNeeded = true;
+            return read?.value ?? true;
+        };
+        const flagEnabled = readFlag(LANE_CONDUCT_SESSION_START_FLAG);
+        const rootScoped = readFlag(LANE_ORPHAN_SWEEP_ROOT_KEYING_FLAG);
+        const contextEnabled = readFlag(LANE_ORPHAN_SWEEP_CONTEXT_FLAG);
+        if (refreshNeeded) {
+            try {
+                (options.refreshFlags ?? ((e) => { startSessionStartFlagRefresh(e); }))(env);
+            }
+            catch { /* advisory */ }
+        }
         if (!flagEnabled)
             return;
-        const rootScoped = await readLanesRegistryFlagFailOpen(LANE_ORPHAN_SWEEP_ROOT_KEYING_FLAG, { env, defaultValue: true });
         (options.startSweep ?? ((r, e) => startSessionStartOrphanSweep(r, e, spawn, rootScoped)))(root, env);
-        const contextEnabled = await readLanesRegistryFlagFailOpen(LANE_ORPHAN_SWEEP_CONTEXT_FLAG, { env, defaultValue: true });
         if (contextEnabled) {
             const count = readOrphanCount(root, env, rootScoped, (error) => debug(`hq lanes session-start: orphan report read failed (${error instanceof Error ? error.name : "Error"})`));
             if (count > 0)
@@ -324,6 +399,12 @@ export async function runLaneSessionStart(options = {}) {
 export function registerLaneSessionStartCommand(lanes) {
     lanes.command("session-start", { hidden: true })
         .description("Internal SessionStart bootstrap")
-        .action(async () => runLaneSessionStart());
+        .option("--refresh-flags", "Refresh the offline session-start flag values from the registry")
+        .action(async (opts) => {
+        if (opts.refreshFlags)
+            await refreshSessionStartFlags();
+        else
+            await runLaneSessionStart();
+    });
 }
 //# sourceMappingURL=lanes-session-start.js.map

package/dist/commands/lanes.js

@@ -717,7 +717,8 @@ export function parseQuestionBody(raw) {
         typeof obj.loop_stall.envelope_id !== "string" ||
         typeof obj.loop_stall.attempt !== "number" ||
         !Number.isSafeInteger(obj.loop_stall.attempt) ||
-        obj.loop_stall.attempt < 1))
+        obj.loop_stall.attempt < 1 ||
+        (obj.loop_stall.reason !== undefined && obj.loop_stall.reason !== "handoff_needs_repair")))
         return null;
     const options = obj.options.filter((item) => typeof item === "string");
     const body = {

package/dist/commands/meetings.d.ts

@@ -9,5 +9,16 @@ export declare const SHORT_ID_MAX_PAGES = 50;
  * names no plan: the flat plans are closed.
  */
 export declare function meetingPaymentRequiredLines(body: Record<string, unknown>, resolvePlan?: () => Promise<PricingPlan | null>): Promise<string[]>;
+/**
+ * The company a `hq meetings` call is about: the explicit `--company` value,
+ * otherwise the company an explicitly named HQ session is bound to (the session's company
+ * lock, from `scope-capability.json` or `meta.yaml`). A session bound to
+ * Personal, an unbound session, or an unreadable lock gives undefined so the
+ * server's own default applies. Before this, every subcommand sent no
+ * company at all without `--company`, so the list, get, transcript and
+ * search views silently showed only the caller's personal recordings.
+ * Feedback 04771691-fcbc-4847-899a-6c966c561b52.
+ */
+export declare function sessionCompanySlug(env?: NodeJS.ProcessEnv): string | undefined;
 export declare function registerMeetingsCommand(program: Command): void;
 //# sourceMappingURL=meetings.d.ts.map

package/dist/commands/meetings.js

@@ -1,6 +1,8 @@
 import chalk from "chalk";
 import { readFile } from "node:fs/promises";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { readSessionCompanyLock } from "../lib/session-company-lock.js";
+import { sessionIdFromEnv } from "../lib/core-utils/session-id.js";
 import { vaultApiFetch, getCompanyUid, resolveCallerPersonUid, } from "../utils/vault-api.js";
 import { isPlanGateError, planGateErrorFromPayload, } from "../utils/plan-gate-error.js";
 import { mapWithConcurrency } from "./sync-manifest.js";
@@ -434,11 +436,39 @@ function printMeetingTable(meetings) {
         ].join("  "));
     }
 }
+/**
+ * The company a `hq meetings` call is about: the explicit `--company` value,
+ * otherwise the company an explicitly named HQ session is bound to (the session's company
+ * lock, from `scope-capability.json` or `meta.yaml`). A session bound to
+ * Personal, an unbound session, or an unreadable lock gives undefined so the
+ * server's own default applies. Before this, every subcommand sent no
+ * company at all without `--company`, so the list, get, transcript and
+ * search views silently showed only the caller's personal recordings.
+ * Feedback 04771691-fcbc-4847-899a-6c966c561b52.
+ */
+export function sessionCompanySlug(env = process.env) {
+    // The shared reader also supports the last-writer-wins .current pointer.
+    // It cannot identify a plain terminal or cron caller's session.
+    if (!sessionIdFromEnv(env))
+        return undefined;
+    let lock;
+    try {
+        lock = readSessionCompanyLock(env);
+    }
+    catch (err) {
+        // Fall through to the server default, but say why so an unbound call is
+        // never mistaken for a working company scope.
+        console.error(chalk.dim(`  (session company not applied: ${err instanceof Error ? err.message : String(err)})`));
+        return undefined;
+    }
+    const primary = lock?.companies[0];
+    return primary && primary !== "personal" ? primary : undefined;
+}
 export function registerMeetingsCommand(program) {
     const meetings = program
         .command("meetings")
         .description("View and search meeting recordings, transcripts, and notes")
-        .option("--company <slug>", "Company slug (for multi-company users)")
+        .option("--company <slug>", "Company slug (defaults to the company this HQ session is bound to)")
         .option("--json", "Output raw JSON instead of formatted text");
     // ── hq meetings list ──────────────────────────────────────────────
     meetings
@@ -450,7 +480,7 @@ export function registerMeetingsCommand(program) {
         try {
             const token = await ensureCognitoToken();
             const query = {};
-            const companySlug = meetings.opts().company;
+            const companySlug = meetings.opts().company ?? sessionCompanySlug();
             if (opts.limit)
                 query.limit = opts.limit;
             if (opts.next)
@@ -488,9 +518,9 @@ export function registerMeetingsCommand(program) {
         .action(async (recallBotId, opts) => {
         try {
             const token = await ensureCognitoToken();
-            const companySlug = meetings.opts().company;
+            const companySlug = meetings.opts().company ?? sessionCompanySlug();
             if (!companySlug)
-                throw new Error("--company <slug|uid> is required for live transcripts");
+                throw new Error("--company <slug|uid> is required for live transcripts (this session is not bound to a company)");
             const companyId = companySlug.startsWith("cmp_") ? companySlug : await getCompanyUid(token, companySlug);
             if (!recallBotId) {
                 if (opts.follow || opts.since)
@@ -610,9 +640,9 @@ export function registerMeetingsCommand(program) {
         .description("Import a normalized historical transcript JSON file")
         .action(async (file) => {
         try {
-            const companySlug = meetings.opts().company;
+            const companySlug = meetings.opts().company ?? sessionCompanySlug();
             if (!companySlug) {
-                throw new Error("--company <slug> is required for historical imports");
+                throw new Error("--company <slug> is required for historical imports (this session is not bound to a company)");
             }
             const bytes = await readFile(file);
             if (bytes.byteLength > 5 * 1024 * 1024) {
@@ -666,7 +696,7 @@ export function registerMeetingsCommand(program) {
         .action(async (meetingUrl) => {
         try {
             const token = await ensureCognitoToken();
-            const companySlug = meetings.opts().company;
+            const companySlug = meetings.opts().company ?? sessionCompanySlug();
             // Always name a company. With no companyId the backend files the bot
             // under Personal, which can never record, so an entitled user would
             // get the payment-required refusal. Without --company this uses the
@@ -707,7 +737,7 @@ export function registerMeetingsCommand(program) {
         try {
             const token = await ensureCognitoToken();
             const query = {};
-            const companySlug = meetings.opts().company;
+            const companySlug = meetings.opts().company ?? sessionCompanySlug();
             if (companySlug)
                 query.companyId = await getCompanyUid(token, companySlug);
             const meetingId = await resolveShortId(token, rawId, query);
@@ -832,7 +862,7 @@ export function registerMeetingsCommand(program) {
         try {
             const token = await ensureCognitoToken();
             const params = { q: query };
-            const companySlug = meetings.opts().company;
+            const companySlug = meetings.opts().company ?? sessionCompanySlug();
             if (companySlug)
                 params.companyId = await getCompanyUid(token, companySlug);
             const res = await vaultApiFetch({
@@ -863,7 +893,7 @@ export function registerMeetingsCommand(program) {
         try {
             const token = await ensureCognitoToken();
             const query = {};
-            const companySlug = meetings.opts().company;
+            const companySlug = meetings.opts().company ?? sessionCompanySlug();
             if (companySlug)
                 query.companyId = await getCompanyUid(token, companySlug);
             const meetingId = await resolveShortId(token, rawId, query);
@@ -932,7 +962,7 @@ export function registerMeetingsCommand(program) {
         try {
             const token = await ensureCognitoToken();
             const query = {};
-            const companySlug = meetings.opts().company;
+            const companySlug = meetings.opts().company ?? sessionCompanySlug();
             if (companySlug)
                 query.companyId = await getCompanyUid(token, companySlug);
             const meetingId = await resolveShortId(token, rawId, query);

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

@@ -0,0 +1,87 @@
+/**
+ * `hq sync held` and `hq sync release-held` (feedback_3bf773c5).
+ *
+ * After a different person signs in on the same computer, hq-cloud holds every
+ * upload and cloud delete for each sync scope (the personal vault and each
+ * company) until the signed-in person reviews what is held and releases it.
+ * These commands are the person's way to see the hold and make that decision.
+ *
+ * The hq-cloud exports (`listPushIdentityFences`, `releasePushIdentityFences`)
+ * ship after the hq-cloud version this CLI pins, so they are feature-detected
+ * on the module namespace, the same way `lib/hq-cloud-manifest.ts` does it. A
+ * static named import of a missing ESM export would stop every command that
+ * loads this file.
+ */
+import { Command } from "commander";
+export interface HeldScope {
+    slug: string;
+    uid: string;
+    sinceMs: number;
+    held?: {
+        count: number;
+        samplePaths: string[];
+        at: string;
+    };
+}
+interface FenceExports {
+    listPushIdentityFences: (stateDir: string) => HeldScope[];
+    releasePushIdentityFences: (stateDir: string, identities: readonly string[], slugs?: readonly string[]) => string[];
+}
+export declare const HELD_UNAVAILABLE_MESSAGE = "this HQ build cannot list or release held uploads yet; update HQ and try again";
+export declare function fenceExports(mod?: Record<string, unknown>): FenceExports | undefined;
+/**
+ * One authenticated snapshot of who is signed in: the Cognito sub of the
+ * session token and, when asked for, the personal vault uid resolved with that
+ * same token. The sub never comes from the upload-author label, which needs an
+ * email; hq-cloud#1040 identifies email-less sessions by sub alone.
+ */
+export interface HeldIdentity {
+    sub: string;
+    personalUid?: string;
+}
+export interface SyncHeldDeps {
+    exports: FenceExports | undefined;
+    stateDir: string;
+    /**
+     * Resolve the signed-in identity from one token. `interactive` allows a
+     * sign-in or refresh; the result is taken after it, never mixed with an
+     * identity read before it.
+     */
+    identity: (options: {
+        needPersonal: boolean;
+        interactive: boolean;
+    }) => Promise<HeldIdentity>;
+    confirm: (question: string) => Promise<boolean>;
+    log: (line: string) => void;
+}
+export declare function scopeLabel(slug: string): string;
+export declare function runSyncHeld(deps: SyncHeldDeps, json?: boolean): Promise<number>;
+export interface ReleaseHeldOptions {
+    company?: string;
+    personal?: boolean;
+    yes?: boolean;
+    json?: boolean;
+}
+export declare function runReleaseHeld(deps: SyncHeldDeps, options: ReleaseHeldOptions): Promise<number>;
+/**
+ * The signed-in identity from the session token `ensureCognitoToken` selects
+ * (person or machine, the same choice every vault call makes). The personal
+ * vault uid is resolved with that same token: an agent principal uses its own
+ * entity uid, as the sync runner does; a person uses the canonical person
+ * entity.
+ */
+export declare function resolveHeldIdentity(options: {
+    needPersonal: boolean;
+    interactive: boolean;
+}, io: {
+    ensureToken: (interactive: boolean) => Promise<string>;
+    listPersons: (token: string) => Promise<Array<{
+        uid: string;
+        type: string;
+        createdAt: string;
+    }>>;
+}): Promise<HeldIdentity>;
+export declare function createDefaultSyncHeldDeps(): SyncHeldDeps;
+export declare function registerSyncHeldCommands(syncCmd: Command): void;
+export {};
+//# sourceMappingURL=sync-held.d.ts.map