@indigoai-us/hq-cli 5.274.1 → 5.276.0

package/dist/commands/core-checkpoint-gate-setting.js

@@ -0,0 +1,163 @@
+/**
+ * `hq core checkpoint-gate-setting` — keeps the local cache that lets a
+ * company owner turn the checkpoint Stop gate off for their company (CO-58).
+ *
+ * The owner sets `companySettings.checkpointGateEnabled` on hq-pro
+ * (`hq company settings set --checkpoint-gate-enabled false`, or the console
+ * Settings page). The Stop gate script never calls the network: it reads
+ * `~/.hq/cache/checkpoint-gate/<slug>.json` and, when that is missing or older
+ * than ten minutes, starts this command detached with `--refresh`.
+ *
+ * `--refresh` reads the setting through the member-readable
+ * `GET /company-settings/checkpoint-gate` route and writes the cache only while
+ * the hq-flag `checkpoint.gate.company-setting` is on for the company. With the
+ * flag off it removes the cache, so the gate keeps today's behaviour. Any
+ * failure (no login, API unreachable, timeout) leaves the cache as it was: the
+ * gate then uses the last known value, or today's behaviour when there is none.
+ * Only the named company's setting is ever read.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { getEntityUid, vaultApiFetch } from "../utils/vault-api.js";
+import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
+import { describeCoreCommand } from "./core-command-catalog.js";
+export const CHECKPOINT_GATE_SETTING_FLAG = "checkpoint.gate.company-setting";
+/** The refresh gives up after this long; the gate keeps the cached value. */
+export const CHECKPOINT_GATE_REFRESH_TIMEOUT_MS = 3_000;
+/** Same character set the gate script accepts; anything else is refused. */
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+export function assertCompanySlug(slug) {
+    if (!SLUG_RE.test(slug) || slug === "personal") {
+        throw new Error(`checkpoint-gate-setting: '${slug}' is not a company slug`);
+    }
+}
+export function checkpointGateCacheDir(home = os.homedir()) {
+    return path.join(home, ".hq", "cache", "checkpoint-gate");
+}
+export function checkpointGateCachePath(slug, home = os.homedir()) {
+    return path.join(checkpointGateCacheDir(home), `${slug}.json`);
+}
+/**
+ * `readLanesRegistryFlag` resolves a failed registry read to `false`. The
+ * refresh must not treat that as "flag off" and delete a valid cache, so a
+ * reported failure becomes null (unknown).
+ */
+export async function readCheckpointGateSettingFlag(slug, companyUid) {
+    let failed = false;
+    const enabled = await readLanesRegistryFlag(CHECKPOINT_GATE_SETTING_FLAG, {
+        company: { slug, uid: companyUid },
+        reportFailure: () => {
+            failed = true;
+        },
+    });
+    return failed ? null : enabled;
+}
+async function defaultFetchSetting(token, companyUid, signal) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/company-settings/checkpoint-gate",
+        query: { companyUid },
+        signal,
+    });
+    if (!res.ok)
+        throw new Error(`GET /company-settings/checkpoint-gate returned ${res.status}`);
+    const body = (await res.json());
+    if (typeof body.checkpointGateEnabled !== "boolean") {
+        throw new Error("GET /company-settings/checkpoint-gate returned no boolean checkpointGateEnabled");
+    }
+    return body.checkpointGateEnabled;
+}
+function writeCacheAtomic(file, entry) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+function withTimeout(work, ms) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new Error(`timed out after ${ms} ms`));
+        }, ms);
+    });
+    return Promise.race([work(controller.signal), timeout]).finally(() => clearTimeout(timer));
+}
+/**
+ * Refresh one company's cache entry. Never throws for a network or auth
+ * failure: those return `kept` and leave the cache untouched.
+ */
+export async function refreshCheckpointGateSetting(slug, deps = {}) {
+    assertCompanySlug(slug);
+    const file = checkpointGateCachePath(slug, deps.home);
+    // Never interactive: a detached refresh must not open a browser login.
+    const getToken = deps.getToken ?? (() => ensureCognitoToken({ interactive: false }));
+    const resolveCompanyUid = deps.resolveCompanyUid ?? ((token, companySlug) => getEntityUid(token, { companySlug }));
+    const fetchSetting = deps.fetchSetting ?? defaultFetchSetting;
+    const readFlag = deps.readFlag ?? readCheckpointGateSettingFlag;
+    // One timeout covers every network step, the flag read included.
+    let fetched;
+    try {
+        fetched = await withTimeout(async (signal) => {
+            const token = await getToken();
+            const uid = await resolveCompanyUid(token, slug);
+            const enabled = await fetchSetting(token, uid, signal);
+            return { enabled, flag: await readFlag(slug, uid) };
+        }, deps.timeoutMs ?? CHECKPOINT_GATE_REFRESH_TIMEOUT_MS);
+    }
+    catch (error) {
+        return { status: "kept", company: slug, reason: error instanceof Error ? error.message : String(error) };
+    }
+    if (fetched.flag === null) {
+        return { status: "kept", company: slug, reason: `could not read ${CHECKPOINT_GATE_SETTING_FLAG}` };
+    }
+    if (!fetched.flag) {
+        fs.rmSync(file, { force: true });
+        return { status: "removed", company: slug, reason: "flag_off" };
+    }
+    const now = (deps.now?.() ?? new Date()).getTime();
+    writeCacheAtomic(file, { company: slug, checkpointGateEnabled: fetched.enabled, fetched_at: Math.floor(now / 1000) });
+    return { status: "written", company: slug, checkpointGateEnabled: fetched.enabled };
+}
+export function describeRefreshOutcome(outcome) {
+    switch (outcome.status) {
+        case "written":
+            return `checkpoint gate for ${outcome.company}: ${outcome.checkpointGateEnabled ? "on" : "off"} (cached)`;
+        case "removed":
+            return `checkpoint gate for ${outcome.company}: company setting not in use (${CHECKPOINT_GATE_SETTING_FLAG} is off); cache cleared`;
+        case "kept":
+            return `checkpoint gate for ${outcome.company}: could not refresh (${outcome.reason}); cache unchanged`;
+    }
+}
+export function registerCoreCheckpointGateSettingCommand(core) {
+    const command = core
+        .command("checkpoint-gate-setting")
+        .description("Refresh the local cache of a company's checkpoint gate setting (used by the Stop gate)")
+        .requiredOption("--company <slug>", "company whose setting to read")
+        .option("--refresh", "read the setting from HQ and update the local cache")
+        .option("--json", "print the result as JSON")
+        .action(async (options) => {
+        try {
+            assertCompanySlug(options.company);
+            if (!options.refresh) {
+                const file = checkpointGateCachePath(options.company);
+                const cached = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : null;
+                process.stdout.write(`${options.json ? JSON.stringify({ company: options.company, cached }) : cached ? `checkpoint gate for ${options.company}: ${cached.checkpointGateEnabled ? "on" : "off"} (cached at ${new Date(cached.fetched_at * 1000).toISOString()})` : `checkpoint gate for ${options.company}: no cached setting`}\n`);
+                return;
+            }
+            const outcome = await refreshCheckpointGateSetting(options.company);
+            process.stdout.write(`${options.json ? JSON.stringify(outcome) : describeRefreshOutcome(outcome)}\n`);
+            // A timed-out request can keep sockets open; the answer is already out.
+            process.exit(0);
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(1);
+        }
+    });
+    describeCoreCommand(command, { execution: "native", root: "cwd" });
+}
+//# sourceMappingURL=core-checkpoint-gate-setting.js.map

package/dist/commands/core-checkpoint.d.ts

@@ -45,8 +45,10 @@ export declare const SIBLING_PROMPT_TEMPLATE = "You are the HQ checkpoint siblin
  * Rendered into the sibling prompt only when the payload names a company. The
  * flag check happens inside `hq core ontology plan`, in the sibling, because
  * the checkpoint parent performs no network I/O. Only this run's own payload
- * gets the step; claimed queue payloads are covered by the next run, since the
- * plan works from file hashes rather than from the payload's file list.
+ * gets the step. A queued payload's company files are recorded as queued
+ * touches when it is queued (CO-59), and a later plan for that company takes
+ * them while checkpoint.ontology.queued-touches is on; a run with no company
+ * of its own gets the step for the company whose touches waited longest.
  */
 export declare const SIBLING_ONTOLOGY_STEP = "5b. ONTOLOGY (this run's own payload only; skip it for claimed queue payloads).\n   Run: hq core ontology plan --run-dir \"<runDir>\" --hq-root \"<hqRoot>\"\n   If it prints \"ontology: skipped\", do nothing more for this step. Otherwise\n   read <runDir>/ontology-plan.json, follow its \"instructions\" exactly, and\n   write <runDir>/ontology-candidates.json. Read only the files and line\n   ranges the plan lists. Then run:\n   hq core ontology apply --run-dir \"<runDir>\" --hq-root \"<hqRoot>\"\n   Never write under the company's ontology/ folder yourself, and never edit\n   payload.json or ontology-plan.json. Copy the command's one-line output into\n   the report. If either command fails, record the error and continue.\n";
 export declare function renderSiblingPrompt(runDir: string, payloadPath: string, options?: {

package/dist/commands/core-checkpoint.js

@@ -17,6 +17,7 @@ import { toHqStateWriteError } from "../utils/hq-state-write-error.js";
 import { checkpointStampWriteErrorFor, isCheckpointStampWriteError, } from "../utils/checkpoint-stamp-write-error.js";
 import { readBackendPreference } from "../lib/checkpoint-ontology/plan.js";
 import { resolveOntologyCompany } from "../lib/checkpoint-ontology/company.js";
+import { markBorrowed, oldestQueuedCompany, recordQueuedTouches } from "../lib/checkpoint-ontology/queued-touches.js";
 import { describeCoreCommand } from "./core-command-catalog.js";
 const DEFAULT_TRIGGER = "stop-gate";
 const BACKENDS = new Set(["auto", "claude", "codex", "grok", "none"]);
@@ -189,8 +190,10 @@ report instead of guessing.
  * Rendered into the sibling prompt only when the payload names a company. The
  * flag check happens inside `hq core ontology plan`, in the sibling, because
  * the checkpoint parent performs no network I/O. Only this run's own payload
- * gets the step; claimed queue payloads are covered by the next run, since the
- * plan works from file hashes rather than from the payload's file list.
+ * gets the step. A queued payload's company files are recorded as queued
+ * touches when it is queued (CO-59), and a later plan for that company takes
+ * them while checkpoint.ontology.queued-touches is on; a run with no company
+ * of its own gets the step for the company whose touches waited longest.
  */
 export const SIBLING_ONTOLOGY_STEP = `5b. ONTOLOGY (this run's own payload only; skip it for claimed queue payloads).
    Run: hq core ontology plan --run-dir "<runDir>" --hq-root "<hqRoot>"
@@ -1001,15 +1004,43 @@ function startSibling(liveRoot, input, threadPath, backend) {
     fs.mkdirSync(siblingRoot, { recursive: true });
     if (activePid !== null) {
         const depth = appendPending(pendingPath, payload);
+        try {
+            recordQueuedTouches(liveRoot, payload.company, payload.files, new Date());
+        }
+        catch {
+            // Queued touches only help a later ontology plan; they must never fail
+            // the checkpoint itself.
+        }
         printResult(`checkpoint: sibling busy — payload queued (${depth} pending)`);
         return;
     }
     const runDir = path.join(siblingRoot, `${formatTimestamp(new Date())}-${summarySlug(input.summary ?? "checkpoint")}`);
     fs.mkdirSync(runDir, { recursive: true });
     payload.pending_payloads = claimPending(pendingPath, path.join(runDir, "pending-claimed.jsonl"));
+    if (!payload.company) {
+        let queued;
+        try {
+            queued = oldestQueuedCompany(liveRoot);
+        }
+        catch {
+            queued = null;
+        }
+        if (queued) {
+            payload.ontology_company = queued;
+            try {
+                markBorrowed(liveRoot, queued, new Date());
+            }
+            catch {
+                // A borrowed-company marker must never fail the checkpoint.
+            }
+        }
+    }
     const payloadPath = path.join(runDir, "payload.json");
     fs.writeFileSync(payloadPath, `${JSON.stringify(payload, null, 2)}\n`);
-    const prompt = renderSiblingPrompt(runDir, payloadPath, { company: payload.company, hqRoot: liveRoot });
+    const prompt = renderSiblingPrompt(runDir, payloadPath, {
+        company: payload.company ?? payload.ontology_company ?? null,
+        hqRoot: liveRoot,
+    });
     fs.writeFileSync(path.join(runDir, "prompt.md"), prompt);
     const logPath = path.join(runDir, "run.log");
     const logFd = fs.openSync(logPath, "a");

package/dist/commands/core-command-catalog.d.ts

@@ -22,11 +22,13 @@ export declare function describeCoreCommand(command: Command, metadata: CoreComm
 export declare function registeredCoreCommandListing(core: Command): CoreCommandListingEntry[];
 export declare function fastScaffoldListingMismatches(listing: readonly CoreCommandListingEntry[], fastScripts: readonly {
     name: string;
-    asset: string;
+    kind: "shell" | "native";
+    asset?: string;
 }[]): string[];
 export declare function assertFastScaffoldListingParity(listing: readonly CoreCommandListingEntry[], fastScripts: readonly {
     name: string;
-    asset: string;
+    kind: "shell" | "native";
+    asset?: string;
 }[]): void;
 export {};
 //# sourceMappingURL=core-command-catalog.d.ts.map

package/dist/commands/core-command-catalog.js

@@ -43,8 +43,11 @@ export function fastScaffoldListingMismatches(listing, fastScripts) {
         if (!listed) {
             mismatches.push(`${fast.name} is missing from hq core commands`);
         }
-        else if (listed.asset !== fast.asset) {
-            mismatches.push(`${fast.name} lists ${listed.asset ?? "no asset"}, fast path uses ${fast.asset}`);
+        else if (fast.kind === "shell" && listed.asset !== fast.asset) {
+            mismatches.push(`${fast.name} lists ${listed.asset ?? "no asset"}, fast path uses ${fast.asset ?? "no asset"}`);
+        }
+        else if (fast.kind === "native" && (listed.execution !== "native" || listed.asset)) {
+            mismatches.push(`${fast.name} is native in the fast path but not in the command catalog`);
         }
     }
     return mismatches;

package/dist/commands/core-ontology.js

@@ -12,7 +12,7 @@ import * as path from "node:path";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { describeCoreCommand } from "./core-command-catalog.js";
 import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
-import { MULTI_WRITER_FLAG, planOntologyRun, } from "../lib/checkpoint-ontology/plan.js";
+import { MULTI_WRITER_FLAG, planOntologyRun, payloadOntologyCompany, } from "../lib/checkpoint-ontology/plan.js";
 import { applyOntologyRun, ApplyError } from "../lib/checkpoint-ontology/apply.js";
 import { resolveOntologyCompany, WriteBoundsError } from "../lib/checkpoint-ontology/company.js";
 import { findDuplicateGroups, summarizeMergeBack, } from "../lib/checkpoint-ontology/multi-writer.js";
@@ -85,8 +85,8 @@ export async function runOntologyPlan(hqRoot, runDirOption, deps = {}) {
 }
 export function runOntologyApply(hqRoot, runDirOption, deps = {}) {
     const runDir = requireRunDir(runDirOption);
-    const company = readPayload(runDir).company;
-    if (typeof company !== "string" || company === "") {
+    const company = payloadOntologyCompany(readPayload(runDir)).slug;
+    if (company === null) {
         throw new OntologyUsageError("ontology: the run payload names no company");
     }
     const report = applyOntologyRun({ hqRoot, runDir, company, now: deps.now?.() });

package/dist/commands/core.js

@@ -31,6 +31,7 @@
 import { Option } from "commander";
 import { registerCoreCheckpointCommand } from "./core-checkpoint.js";
 import { registerCoreOntologyCommand } from "./core-ontology.js";
+import { registerCoreCheckpointGateSettingCommand } from "./core-checkpoint-gate-setting.js";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { interpreterFor, runBundledScript } from "../utils/run-bundled-script.js";
 import { renderIndexTarget } from "../lib/index-render/index.js";
@@ -286,6 +287,7 @@ export function registerCoreCommands(program) {
     // hosts native TypeScript plumbing when a scaffold contract needs it.
     registerCoreCheckpointCommand(core);
     registerCoreOntologyCommand(core);
+    registerCoreCheckpointGateSettingCommand(core);
     // These command names intentionally own native implementations. Their
     // similarly named scaffold assets are forwarders, so sending them through
     // runEntry would recurse back into this command forever.
@@ -459,7 +461,7 @@ export function registerCoreCommands(program) {
         const chunks = [];
         for await (const chunk of process.stdin)
             chunks.push(chunk);
-        const code = timeoutGuardCommand(Buffer.concat(chunks).toString("utf8"));
+        const code = await timeoutGuardCommand(Buffer.concat(chunks).toString("utf8"));
         if (code !== 0)
             process.exit(code);
     });

package/dist/commands/daemon.d.ts

@@ -41,6 +41,7 @@ export interface DaemonCommandDeps {
     windowsUser?: string;
     windowsHeadlessLauncher?: string;
     systemUnitDir?: string;
+    systemRecordPath?: string;
 }
 /**
  * The HQ folder install records: --hq-root, else the CLI's shared resolution

package/dist/commands/daemon.js

@@ -96,6 +96,7 @@ async function loadDefaults(over) {
         windowsUser: over.windowsUser ?? (platform === "win32" ? mesh.resolveWindowsUser(env) : ""),
         windowsHeadlessLauncher: over.windowsHeadlessLauncher ?? (platform === "win32" ? mesh.resolveWindowsHeadlessLauncher(env) : undefined),
         systemUnitDir: over.systemUnitDir ?? SYSTEM_UNIT_DIR,
+        systemRecordPath: over.systemRecordPath ?? path.join(SYSTEM_ADOPTED_ROOT, "adopted.json"),
     };
 }
 function detect(d, flag, config) {
@@ -250,7 +251,7 @@ function migrateDeps(d, paths) {
         recordPath: path.join(paths.root, "adopted.json"),
         // Box system units: root-owned, outside the login user's daemon folder (which handOver chowns to that user).
         systemAdoptedDir: path.join(SYSTEM_ADOPTED_ROOT, "adopted"),
-        systemRecordPath: path.join(SYSTEM_ADOPTED_ROOT, "adopted.json"),
+        systemRecordPath: d.systemRecordPath ?? path.join(SYSTEM_ADOPTED_ROOT, "adopted.json"),
         systemUnitDir: d.systemUnitDir ?? SYSTEM_UNIT_DIR,
     };
 }
@@ -489,8 +490,13 @@ function binaryFingerprint(bin) {
     }
 }
 async function runTmuxService(d, opts) {
-    const { runRemoteControlHost } = await import("../lib/daemon/remote-control.js");
+    const { installFingerprint, runRemoteControlHost } = await import("../lib/daemon/remote-control.js");
     const { findOnPath } = await import("../lib/daemon/run.js");
+    const { resolveRunningInstall } = await import("../utils/version-gate.js");
+    // The daemon keeps this host running across a CLI update, so a new hq-cli
+    // install also counts as an update and restarts the session once it is quiet.
+    const cliRoot = resolveRunningInstall().packageRoot;
+    const watched = cliRoot ? [opts.watch, path.join(cliRoot, "package.json")] : [opts.watch];
     const hqRoot = d.env.HQ_ROOT?.trim();
     if (!hqRoot)
         throw new DaemonCommandError(`${opts.label} needs HQ_ROOT (the daemon sets it from the saved HQ folder)`);
@@ -508,7 +514,7 @@ async function runTmuxService(d, opts) {
             cwd: hqRoot,
             argv: opts.argv,
             label: opts.label,
-            binaryFingerprint: () => binaryFingerprint(opts.watch),
+            binaryFingerprint: () => installFingerprint(watched, binaryFingerprint),
             now: () => Date.now(),
             run: d.run,
             pollMs: 5_000,

package/dist/commands/feedback.d.ts

@@ -3,6 +3,8 @@ import { type DiagnosticsBlob } from "../utils/feedback-diagnostics.js";
 import { collectFeedbackLogs, feedbackLogsEnabled } from "../utils/feedback-logs.js";
 import { type LogBundleRef } from "../utils/feedback-log-bundle.js";
 export declare const BODY_MAX_BYTES: number;
+/** Validate fields that must be valid before feedback attachments are uploaded. */
+export declare function validateFeedbackContent(title: string, body: string): void;
 /**
  * Mirror of the server's `MAX_BODY_BYTES` in hq-pro
  * `src/vault-service/handlers/feedback.ts`, which rejects the WHOLE request
@@ -36,6 +38,10 @@ export interface FeedbackSubmitOptions {
      * stays a summary and this carries the rest.
      */
     logBundle?: LogBundleRef;
+    /** Diagnostics collected before uploads by the command path. */
+    diagnostics?: DiagnosticsBlob;
+    /** Precomputed setting so environment lookup happens before attachments upload. */
+    logsEnabled?: boolean;
 }
 export declare function readBodyFile(bodyFile: string, stdin?: NodeJS.ReadableStream): Promise<string>;
 /**

package/dist/commands/feedback.js

@@ -1,12 +1,25 @@
 import * as fs from "node:fs";
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { vaultApiFetch } from "../utils/vault-api.js";
+import { assertVaultApiRequestSupported, vaultApiFetch, } from "../utils/vault-api.js";
 import { collectDiagnostics } from "../utils/feedback-diagnostics.js";
 import { MAX_SCREENSHOTS, uploadScreenshots } from "../utils/feedback-screenshots.js";
 import { FEEDBACK_LOGS_MAX_TOTAL_BYTES, FEEDBACK_LOGS_MIN_USEFUL_BYTES, collectFeedbackLogs, feedbackLogsEnabled, } from "../utils/feedback-logs.js";
 import { uploadLogBundle } from "../utils/feedback-log-bundle.js";
 export const BODY_MAX_BYTES = 64 * 1024;
+/** Validate fields that must be valid before feedback attachments are uploaded. */
+export function validateFeedbackContent(title, body) {
+    if (title.trim().length === 0) {
+        throw new Error("title must not be empty. Provide a short, non-whitespace title via --title.");
+    }
+    if (body.trim().length === 0) {
+        throw new Error("body must not be empty. Provide at least one non-whitespace character.");
+    }
+    const bodyBytes = Buffer.byteLength(body, "utf8");
+    if (bodyBytes > BODY_MAX_BYTES) {
+        throw new Error(`Body exceeds 64 KiB limit (${bodyBytes} bytes). Reduce the body size before submitting.`);
+    }
+}
 /**
  * Mirror of the server's `MAX_BODY_BYTES` in hq-pro
  * `src/vault-service/handlers/feedback.ts`, which rejects the WHOLE request
@@ -16,12 +29,36 @@ export const BODY_MAX_BYTES = 64 * 1024;
  * logs are budgeted against whatever headroom is left between them.
  */
 export const REQUEST_MAX_BYTES = 64 * 1024;
+/** Reject JSON envelopes that hq-pro would refuse with HTTP 413. */
+function validateFeedbackRequestSize(requestBody) {
+    const requestBytes = Buffer.byteLength(JSON.stringify(requestBody), "utf8");
+    if (requestBytes > REQUEST_MAX_BYTES) {
+        throw new Error(`Request exceeds 64 KiB limit (${requestBytes} bytes). Reduce the feedback content before submitting.`);
+    }
+}
 /**
  * Headroom held back for the `"logs":{...}` JSON envelope itself — its keys,
  * braces, and the escaping of the tail text. The final size is re-measured
  * after attaching, so this reserve only needs to be roughly right.
  */
 const LOGS_ENVELOPE_RESERVE_BYTES = 1024;
+function buildFeedbackRequestBody(opts) {
+    const requestBody = {
+        type: opts.type,
+        title: opts.title,
+        body: opts.body,
+        diagnostics: opts.diagnostics,
+    };
+    if (opts.company) {
+        requestBody.company = opts.company;
+    }
+    if (opts.screenshots && opts.screenshots.length > 0) {
+        requestBody.screenshots = opts.screenshots;
+    }
+    if (opts.logBundle)
+        requestBody.logBundle = opts.logBundle;
+    return requestBody;
+}
 export async function readBodyFile(bodyFile, stdin) {
     if (bodyFile === "-") {
         const stream = stdin ?? process.stdin;
@@ -79,48 +116,32 @@ export function attachDebugLogs(requestBody, diagnostics, enabled, deps = {}) {
     }
 }
 export async function submitFeedback(opts) {
-    // Validate the title locally, symmetric with the body check below. Commander's
-    // `requiredOption("--title")` only requires the flag to be PRESENT — an empty
-    // or whitespace-only value (`--title ""`, or a title the /hq-bug skill derived
-    // to nothing) passes the flag check, then the server rejects it with a 400
-    // "title (non-empty string) is required" that floods Sentry as a context-free
-    // warning (HQ-AB). Catch it here so the caller gets a clear, actionable error
-    // and the bad request never reaches the server.
-    if (opts.title.trim().length === 0) {
-        throw new Error("title must not be empty. Provide a short, non-whitespace title via --title.");
-    }
-    if (opts.body.trim().length === 0) {
-        throw new Error("body must not be empty. Provide at least one non-whitespace character.");
-    }
-    const bodyBytes = Buffer.byteLength(opts.body, "utf8");
-    if (bodyBytes > BODY_MAX_BYTES) {
-        throw new Error(`Body exceeds 64 KiB limit (${bodyBytes} bytes). Reduce the body size before submitting.`);
-    }
-    const diagnostics = collectDiagnostics();
-    const requestBody = {
+    // Keep submitFeedback safe for direct callers as well as the command path,
+    // which invokes the same validator before uploading any attachments.
+    validateFeedbackContent(opts.title, opts.body);
+    const diagnostics = opts.diagnostics ?? collectDiagnostics();
+    const requestBody = buildFeedbackRequestBody({
         type: opts.type,
         title: opts.title,
         body: opts.body,
+        company: opts.company,
         diagnostics,
-    };
-    if (opts.company) {
-        requestBody.company = opts.company;
-    }
-    if (opts.screenshots && opts.screenshots.length > 0) {
-        requestBody.screenshots = opts.screenshots;
-    }
-    // The bundle reference is four small fields, so unlike the inline logs below
-    // it needs no budgeting — but it is added BEFORE attachDebugLogs so those
-    // bytes are counted against the inline budget rather than overrunning it.
-    if (opts.logBundle) {
-        requestBody.logBundle = opts.logBundle;
-    }
+        screenshots: opts.screenshots,
+        logBundle: opts.logBundle,
+    });
+    // Direct callers can supply attachment references; ensure the complete base
+    // envelope still fits before adding optional inline logs or making a request.
+    validateFeedbackRequestSize(requestBody);
     // Debug logs are attached LAST and sized against the headroom the rest of
     // the request left behind. The server 413s the whole body over 64 KiB, so a
     // fixed log budget would turn a previously-working large-body submission
     // into a hard failure. Measuring the real serialized envelope — the exact
     // bytes vaultApiFetch will send — is what makes that impossible.
-    attachDebugLogs(requestBody, diagnostics, opts.includeLogs !== false);
+    attachDebugLogs(requestBody, diagnostics, opts.includeLogs !== false, {
+        envEnabled: opts.logsEnabled === undefined
+            ? feedbackLogsEnabled
+            : () => opts.logsEnabled === true,
+    });
     const res = await vaultApiFetch({
         token: opts.token,
         path: "/v1/feedback",
@@ -155,8 +176,34 @@ function registerSubcommand(feedbackCmd, type) {
         try {
             const token = await ensureCognitoToken({ interactive: false });
             const body = await readBodyFile(opts.bodyFile);
-            // Validate + upload screenshots (direct-to-S3 via presigned PUT)
-            // before submitting, so the row references uploaded objects.
+            validateFeedbackContent(opts.title, body);
+            // Resolve every required local input before creating S3 objects. These
+            // diagnostics are passed through so submitFeedback does not collect
+            // them again after attachments have been uploaded.
+            const diagnostics = collectDiagnostics();
+            const logsEnabled = opts.logs !== false && feedbackLogsEnabled();
+            // Validate the serialized server request envelope before screenshots
+            // or the log bundle can create remote objects. Attachment references
+            // are added and checked again inside submitFeedback after upload.
+            validateFeedbackRequestSize(buildFeedbackRequestBody({
+                type,
+                title: opts.title,
+                body,
+                company: opts.company,
+                diagnostics,
+            }));
+            // vaultApiFetch can reject an hqk_ token or an invalid API base URL
+            // locally before fetch. Check the mandatory POST, and the screenshot
+            // presign when requested, before any upload can create an orphan.
+            assertVaultApiRequestSupported({ token, path: "/v1/feedback" });
+            if ((opts.screenshot ?? []).length > 0) {
+                assertVaultApiRequestSupported({
+                    token,
+                    path: "/v1/feedback/screenshots/presign",
+                });
+            }
+            // Upload screenshots (direct-to-S3 via presigned PUT) before the
+            // submission, so the row references uploaded objects.
             const screenshots = await uploadScreenshots({
                 paths: opts.screenshot ?? [],
                 token,
@@ -167,7 +214,7 @@ function registerSubcommand(feedbackCmd, type) {
             // this resolves undefined and the report still carries inline logs.
             const logBundle = await uploadLogBundle({
                 token,
-                enabled: opts.logs !== false && feedbackLogsEnabled(),
+                enabled: logsEnabled,
             });
             const result = await submitFeedback({
                 type,
@@ -178,6 +225,8 @@ function registerSubcommand(feedbackCmd, type) {
                 screenshots,
                 includeLogs: opts.logs !== false,
                 logBundle,
+                diagnostics,
+                logsEnabled,
             });
             console.log(`Submitted: ${result.id}`);
         }