@indigoai-us/hq-cli 5.345.177 → 5.345.179

package/dist/commands/cloud.js

@@ -22,7 +22,7 @@ import * as path from "path";
 import { share, getStateDir, listJournals, createIgnoreFilter, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, readSyncProgress, syncDoctor, } from "@indigoai-us/hq-cloud";
 import { syncLeg } from "../utils/sync-operation-lock.js";
 import { SYNC_WATCHDOG_EXIT_CODE, SYNC_WATCHDOG_REPORT_GRACE_MS, SyncWatchdogTimeoutError, createSnapshotProgressProbe, resolveSyncWatchdogLimits, withSyncWatchdog, } from "../utils/sync-watchdog.js";
-import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, loadCachedTokens, } from "../utils/cognito-session.js";
+import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, IdentitySwapRefusal, cognitoCachePrincipalUid, isDefinitivePersonAuthRejection, isIdentitySwapRefusal, loadCachedTokens, } from "../utils/cognito-session.js";
 import { resolveUploadAuthor } from "../utils/upload-author.js";
 import { companyFolderExceedsThreshold, emitNarrowHint, isStrictRefusal, resolveBannerLevel, resolveNarrowHintPresentationLevel, resolveNarrowHintMinBytes, } from "../lib/narrow-hint-banner.js";
 import { beginSyncHealthReport, classifySyncFailure, } from "../utils/client-health.js";
@@ -66,12 +66,130 @@ async function ensureSyncCognitoToken() {
         interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
     });
 }
+/** Shown when the session expires during a sync and cannot be renewed. */
+export const SYNC_SESSION_EXPIRED_MESSAGE = "Your HQ session expired during sync and could not be refreshed. Run `hq login`, then rerun the sync.";
+/** Shown when the refresh failed for a network or server reason. */
+export const SYNC_REFRESH_UNAVAILABLE_MESSAGE = "Could not refresh your HQ session during sync because the sign-in service did not respond. Check your connection, then rerun the sync.";
+/** Shown when the start token carries no principal to bind the run to. */
+export const SYNC_NO_IDENTITY_MESSAGE = "The HQ session token does not identify an account, so the sync did not start. Run `hq login`, then rerun the sync.";
+/** Shown when the token would change to a different account mid-run. */
+export const SYNC_IDENTITY_CHANGED_MESSAGE = "The signed-in HQ account changed while this sync was running, so the sync stopped instead of continuing as a different account. Rerun the sync as the account you want.";
+/**
+ * The session token expired during a sync run and the non-interactive
+ * refresh failed. `kind` separates a rejected session (sign in again) from a
+ * network or server failure (retry later).
+ */
+export class SyncSessionExpiredError extends Error {
+    kind;
+    reason;
+    constructor(kind, reason) {
+        const base = kind === "reauth" ? SYNC_SESSION_EXPIRED_MESSAGE : SYNC_REFRESH_UNAVAILABLE_MESSAGE;
+        super(reason ? `${base} (${reason})` : base);
+        this.kind = kind;
+        this.reason = reason;
+        this.name = "SyncSessionExpiredError";
+    }
+}
+/**
+ * Per-config record of the last token-function failure. hq-cloud's one-shot
+ * 401 retry swallows getter errors and rethrows the original 401, so
+ * {@link formatSyncFailure} reads this (given the run's config) to report the
+ * real cause. Keyed by config so two runs in one process never share a record.
+ */
+const syncAuthFailures = new WeakMap();
+/** The last token failure recorded by a {@link buildSyncVaultConfig} config. */
+export function syncAuthFailureFor(config) {
+    return config ? (syncAuthFailures.get(config)?.() ?? null) : null;
+}
+function classifyRefreshFailure(err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    const reauth = isDefinitivePersonAuthRejection(err) ||
+        /No valid HQ session|Run `hq login`/i.test(reason);
+    return new SyncSessionExpiredError(reauth ? "reauth" : "unavailable", reason);
+}
+/**
+ * Vault config for a sync run whose token stays valid for the whole run.
+ *
+ * `initialToken` is resolved (and, on a TTY, logged in) before the run starts.
+ * The config carries a getter instead of that string, so every vault request
+ * re-reads the cached session and refreshes it when it is close to expiry.
+ * When a request still gets a 401, hq-cloud's VaultClient calls the getter
+ * once more and retries once if the token changed (no loop). A multi-company
+ * `hq sync pull --all` can outlast the one-hour Cognito access token; a
+ * captured string made every later target fail with 401 (feedback_3d3fab0b).
+ *
+ * The getter is bound to the principal of `initialToken`. If a later token
+ * belongs to a different principal (a mid-run `hq login` as another account,
+ * or the machine-identity fallback after a rejected person refresh), it throws
+ * an {@link IdentitySwapRefusal} and the run stops. It never continues as a
+ * different principal.
+ *
+ * Mid-run refreshes never open a browser.
+ */
+export function buildSyncVaultConfig(initialToken, deps = {}) {
+    const ensureToken = deps.ensureToken ?? (() => ensureCognitoToken({ interactive: false }));
+    const runPrincipal = cognitoCachePrincipalUid(initialToken);
+    // A start token with no sub/entityUid cannot be bound to a principal, and a
+    // null binding would accept any later identity-less token. Refuse up front.
+    if (runPrincipal === null) {
+        throw new IdentitySwapRefusal(SYNC_NO_IDENTITY_MESSAGE);
+    }
+    let refused = null;
+    let lastSyncAuthFailure = null;
+    const authToken = async () => {
+        // Once refused, stay refused for the rest of the run.
+        if (refused)
+            throw refused;
+        let token;
+        try {
+            token = await ensureToken();
+        }
+        catch (err) {
+            const failure = isIdentitySwapRefusal(err) ? err : classifyRefreshFailure(err);
+            if (isIdentitySwapRefusal(failure))
+                refused = failure;
+            lastSyncAuthFailure = failure;
+            throw failure;
+        }
+        if (cognitoCachePrincipalUid(token) !== runPrincipal) {
+            refused = new IdentitySwapRefusal(SYNC_IDENTITY_CHANGED_MESSAGE);
+            lastSyncAuthFailure = refused;
+            throw refused;
+        }
+        lastSyncAuthFailure = null;
+        return token;
+    };
+    const config = { ...buildVaultConfig(initialToken), authToken };
+    syncAuthFailures.set(config, () => lastSyncAuthFailure);
+    return config;
+}
+function isVaultAuthRejection(err) {
+    // Duck-typed (VaultAuthError sets statusCode 401) so this stays compatible
+    // across independently released hq-cloud versions.
+    if (typeof err !== "object" || err === null)
+        return false;
+    const e = err;
+    return e.name === "VaultAuthError" || e.statusCode === 401;
+}
 /**
  * Preserve the vault's typed write-scope refusal at the CLI boundary. This is
  * deliberately duck-typed so hq-cli remains compatible while hq-cloud and the
  * CLI are released independently.
  */
 export function formatSyncFailure(err, ctx = {}) {
+    if (err instanceof SyncSessionExpiredError || isIdentitySwapRefusal(err)) {
+        return err.message;
+    }
+    if (isVaultAuthRejection(err)) {
+        // hq-cloud's 401 retry swallowed the token-function error; report it.
+        const recorded = syncAuthFailureFor(ctx.vaultConfig);
+        if (recorded)
+            return recorded.message;
+        // A 401 that survived the one refresh-and-retry: the session is no longer
+        // accepted, so the fix is a fresh sign-in.
+        const base = err instanceof Error ? err.message : String(err);
+        return `${base}. ${SYNC_SESSION_EXPIRED_MESSAGE}`;
+    }
     const unreachable = formatUnreachablePushPaths(err, ctx);
     if (unreachable)
         return unreachable;
@@ -694,7 +812,7 @@ export async function pullAll(options, deps) {
             }
         }
         catch (err) {
-            const message = formatSyncFailure(err);
+            const message = (deps.formatFailure ?? formatSyncFailure)(err);
             result.errors.push({ company: entry.slug, message });
             result.perCompany.push({ slug: entry.slug, error: message });
         }
@@ -823,7 +941,7 @@ export async function pushAll(options, deps) {
             });
         }
         catch (err) {
-            const message = formatSyncFailure(err);
+            const message = (deps.formatFailure ?? formatSyncFailure)(err);
             result.errors.push({ company: entry.slug, message });
             result.perCompany.push({ slug: entry.slug, error: message });
         }
@@ -1126,6 +1244,8 @@ export function registerCloudCommands(program) {
         // Assigned right before the sync engine runs, so option-validation
         // failures never count as a sync attempt (US-003).
         let syncHealth;
+        /** The run's vault config, so the catch can report its recorded token failure. */
+        let runVaultConfig;
         let explicitPersonalPaths;
         // Company folder the push resolves relative paths against; names the
         // .hqinclude line and the blocked path in failure output.
@@ -1172,11 +1292,13 @@ export function registerCloudCommands(program) {
                 // Upload creds are pre-vended in entityContext, but prefix filtering
                 // still needs vault-service membership/grant resolution.
                 const accessToken = await ensureSyncCognitoToken();
-                scopeVaultConfig = buildVaultConfig(accessToken);
+                scopeVaultConfig = buildSyncVaultConfig(accessToken);
+                runVaultConfig = scopeVaultConfig;
             }
             else {
                 const accessToken = await ensureSyncCognitoToken();
-                vaultConfig = buildVaultConfig(accessToken);
+                vaultConfig = buildSyncVaultConfig(accessToken);
+                runVaultConfig = vaultConfig;
                 scopeVaultConfig = vaultConfig;
             }
             // Resolve the target. For `--personal`, look up the caller's
@@ -1426,6 +1548,7 @@ export function registerCloudCommands(program) {
             const message = formatSyncFailure(err, {
                 hqRoot: options.hqRoot,
                 companySlug: pushCompanySlug,
+                vaultConfig: runVaultConfig,
             });
             if (jsonMode) {
                 // In JSON mode, the parent process is parsing stderr for ndjson —
@@ -1493,12 +1616,15 @@ export function registerCloudCommands(program) {
             return;
         }
         let syncHealth;
+        /** The run's vault config, so the catch can report its recorded token failure. */
+        let runVaultConfig;
         try {
             console.log(chalk.bold("\nHQ Sync — Pull"));
             console.log(`  HQ root:  ${options.hqRoot}`);
             console.log(`  Company:  ${options.company ?? "(from .hq/config.json)"}\n`);
             const accessToken = await ensureSyncCognitoToken();
-            const vaultConfig = buildVaultConfig(accessToken);
+            const vaultConfig = buildSyncVaultConfig(accessToken);
+            runVaultConfig = vaultConfig;
             // US-011 (2026-05-21 fix): resolve the caller's sync-config for
             // the targeted membership BEFORE the pull, so we can (a) emit the
             // narrow-hint banner after success if still on all-mode and
@@ -1581,7 +1707,7 @@ export function registerCloudCommands(program) {
         catch (err) {
             if (syncHealth)
                 await syncHealth.failed();
-            const message = formatSyncFailure(err);
+            const message = formatSyncFailure(err, { vaultConfig: runVaultConfig });
             console.error(chalk.red("\n✗ Pull failed:"), message);
             process.exit(1);
         }
@@ -1843,9 +1969,12 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, for
     logVaultSkips(skipPersonal, skipCompanies);
     console.log("");
     let result;
+    /** The run's vault config, so the catch can report its recorded token failure. */
+    let runVaultConfig;
     try {
         const accessToken = await ensureSyncCognitoToken();
-        const vaultConfig = buildVaultConfig(accessToken);
+        const vaultConfig = buildSyncVaultConfig(accessToken);
+        runVaultConfig = vaultConfig;
         const realClient = new VaultClient(vaultConfig);
         const adapter = {
             listMyMemberships: () => realClient.listMyMemberships(),
@@ -1871,6 +2000,7 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, for
             ...(skipCompanies && skipCompanies.size > 0 ? { skipCompanies } : {}),
         }, {
             vaultClient: adapter,
+            formatFailure: (err) => formatSyncFailure(err, { vaultConfig }),
             // DEV-1768: resolve each company's REAL pull scope (mode + prefixSet)
             // via the shared resolver, so the actual pull is scoped — the CLI no
             // longer seeds an all-mode PullRecord that wedges the menubar runner.
@@ -1898,7 +2028,7 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, for
         });
     }
     catch (err) {
-        console.error(chalk.red("\n✗ Pull-all failed:"), describeSyncError(err));
+        console.error(chalk.red("\n✗ Pull-all failed:"), formatSyncFailure(err, { vaultConfig: runVaultConfig }));
         // Unwind (never process.exit) so withSyncHealthReport records the
         // terminal sync_failure before exiting on our behalf.
         throw new SyncExitError(1);
@@ -1937,9 +2067,12 @@ export async function runPullPersonal(hqRoot, onConflict) {
     console.log(chalk.bold("\nHQ Sync — Pull (personal)"));
     console.log(`  HQ root:  ${hqRoot}`);
     console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+    /** The run's vault config, so the catch can report its recorded token failure. */
+    let runVaultConfig;
     try {
         const accessToken = await ensureSyncCognitoToken();
-        const vaultConfig = buildVaultConfig(accessToken);
+        const vaultConfig = buildSyncVaultConfig(accessToken);
+        runVaultConfig = vaultConfig;
         const client = new VaultClient(vaultConfig);
         const personalUid = await resolveCanonicalPersonUid({
             listMyMemberships: () => client.listMyMemberships(),
@@ -1967,7 +2100,7 @@ export async function runPullPersonal(hqRoot, onConflict) {
     catch (err) {
         if (err instanceof SyncExitError)
             throw err;
-        console.error(chalk.red("\n✗ Pull (personal) failed:"), describeSyncError(err));
+        console.error(chalk.red("\n✗ Pull (personal) failed:"), formatSyncFailure(err, { vaultConfig: runVaultConfig }));
         throw new SyncExitError(1);
     }
 }
@@ -1983,9 +2116,12 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal, skipCompani
     logVaultSkips(skipPersonal, skipCompanies);
     console.log("");
     let result;
+    /** The run's vault config, so the catch can report its recorded token failure. */
+    let runVaultConfig;
     try {
         const accessToken = await ensureSyncCognitoToken();
-        const vaultConfig = buildVaultConfig(accessToken);
+        const vaultConfig = buildSyncVaultConfig(accessToken);
+        runVaultConfig = vaultConfig;
         const realClient = new VaultClient(vaultConfig);
         const author = resolveUploadAuthor();
         const adapter = {
@@ -2008,6 +2144,7 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal, skipCompani
             ...(skipCompanies && skipCompanies.size > 0 ? { skipCompanies } : {}),
         }, {
             vaultClient: adapter,
+            formatFailure: (err) => formatSyncFailure(err, { vaultConfig }),
             resolveScope: (companyUid, slug) => resolvePullScope(realClient, companyUid, slug, hqRoot),
             beforeShare: async ({ slug, companyUid, companyRoot }) => warnAboutInvalidOntologyEntities({
                 hqRoot,
@@ -2052,7 +2189,7 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal, skipCompani
         });
     }
     catch (err) {
-        console.error(chalk.red("\n✗ Push-all failed:"), describeSyncError(err));
+        console.error(chalk.red("\n✗ Push-all failed:"), formatSyncFailure(err, { vaultConfig: runVaultConfig }));
         // Unwind (never process.exit) so withSyncHealthReport records the
         // terminal sync_failure before exiting on our behalf.
         throw new SyncExitError(1);
@@ -2149,9 +2286,12 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
     console.log(`  HQ root:  ${hqRoot}`);
     console.log(`  Target:   ${personal ? "(personal)" : (company ?? "(active company)")}`);
     console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+    /** The run's vault config, so the catch can report its recorded token failure. */
+    let runVaultConfig;
     try {
         const accessToken = await ensureSyncCognitoToken();
-        const vaultConfig = buildVaultConfig(accessToken);
+        const vaultConfig = buildSyncVaultConfig(accessToken);
+        runVaultConfig = vaultConfig;
         const author = resolveUploadAuthor();
         // Resolve the target. For --personal, look up the canonical person and
         // route paths/journal through personalMode. Otherwise use the company arg
@@ -2403,7 +2543,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
     catch (err) {
         if (err instanceof SyncExitError)
             throw err;
-        console.error(chalk.red("\n✗ Sync now failed:"), describeSyncError(err));
+        console.error(chalk.red("\n✗ Sync now failed:"), formatSyncFailure(err, { vaultConfig: runVaultConfig }));
         throw new SyncExitError(1);
     }
 }

package/dist/commands/daemon.d.ts

@@ -59,6 +59,8 @@ export interface DaemonCommandDeps {
     /** Reads stdin for the one-shot daemon machine login; never reads env or argv credentials. */
     readStdin?: () => Promise<string>;
     windowsUser?: string;
+    /** The Windows user's SID; the daemon's Scheduled Task name carries it so each user on a PC has their own task. */
+    windowsSid?: string;
     windowsHeadlessLauncher?: string;
     systemUnitDir?: string;
     systemRecordPath?: string;

package/dist/commands/daemon.js

@@ -24,7 +24,7 @@ import { DEFAULT_SERVICES, SERVICE_DESCRIPTIONS, enabledServices, hqCloudUnits }
 import { applyServiceToggle, effectiveSyncOwner, readDaemonConfig, writeDaemonConfig } from "../lib/daemon/config.js";
 import { daemonUnitInstalled } from "../lib/daemon/handoff.js";
 import { adoptLegacyUnits, readAdoptedUnits, restoreLegacyUnits } from "../lib/daemon/migrate.js";
-import { DAEMON_WINDOWS_TASK, ROOT_REFUSAL, SYSTEM_UNIT_DIR, WINDOWS_START_WAIT_MS, daemonRootRefusal, installDaemonUnit, installScopeFor, uninstallDaemonUnit, windowsInteractiveSession, } from "../lib/daemon/install.js";
+import { ROOT_REFUSAL, SYSTEM_UNIT_DIR, WINDOWS_START_WAIT_MS, daemonRootRefusal, installDaemonUnit, installScopeFor, classifyWindowsTask, legacyWindowsTask, readWindowsSid, uninstallDaemonUnit, windowsInteractiveSession, windowsTaskName, } from "../lib/daemon/install.js";
 import { describeLegacyUnit, findLegacyUnits } from "../lib/daemon/legacy.js";
 import { isDaemonProcess, liveDaemonLock, runningDaemonPid } from "../lib/daemon/lock.js";
 import { bundledHqCloud, managedHqCloud, managedHqCloudRoot, readHqCloudCopy, readHqCloudUpdateState } from "../lib/daemon/hq-cloud.js";
@@ -132,7 +132,10 @@ async function loadDefaults(over) {
                 existsSync: fs.existsSync,
                 listDir: (dir) => fs.readdirSync(dir),
                 launchdJobLoaded: (label) => run("launchctl", ["print", `gui/${process.getuid?.() ?? 0}/${label}`]).status === 0,
-                windowsTaskExists: (task) => run("schtasks.exe", ["/Query", "/TN", task]).status === 0,
+                windowsTaskOwner: (task) => classifyWindowsTask(run, task, {
+                    windowsSid: over.windowsSid ?? readWindowsSid(run),
+                    windowsUser: over.windowsUser ?? mesh.resolveWindowsUser(env),
+                }).state,
             })),
         resolveHqRoot: over.resolveHqRoot ?? ((flag) => resolveDaemonHqRoot(flag, { env, cwd: process.cwd(), home })),
         userHome: over.userHome ?? ((user) => loginHome(user, run)),
@@ -140,6 +143,7 @@ async function loadDefaults(over) {
         sleep: over.sleep,
         interactiveSession: over.interactiveSession,
         windowsUser: over.windowsUser ?? (platform === "win32" ? mesh.resolveWindowsUser(env) : ""),
+        windowsSid: over.windowsSid ?? (platform === "win32" ? readWindowsSid(run) : undefined),
         windowsHeadlessLauncher: over.windowsHeadlessLauncher ?? (platform === "win32" ? mesh.resolveWindowsHeadlessLauncher(env) : undefined),
         systemUnitDir: over.systemUnitDir ?? SYSTEM_UNIT_DIR,
         syncModeClient: over.syncModeClient,
@@ -196,6 +200,7 @@ function hostFor(d, paths, pathEnv) {
         uid: d.uid,
         isRoot: d.isRoot,
         windowsUser: d.windowsUser ?? "",
+        windowsSid: d.windowsSid,
         windowsHeadlessLauncher: d.windowsHeadlessLauncher,
         systemUnitDir: d.systemUnitDir ?? SYSTEM_UNIT_DIR,
         env,
@@ -306,6 +311,8 @@ async function runInstall(d, opts) {
         runningDaemon: () => liveDaemonLock(paths.lockPath, d.daemonAlive),
     });
     handOver(d, { paths, detected, runAsUser });
+    if (result.notice)
+        d.out(result.notice);
     if (result.warning)
         d.err(result.warning);
     if (result.kind === "manual") {
@@ -333,7 +340,7 @@ async function runInstall(d, opts) {
                 ? `Installed ${result.unitPath}, but the daemon did not start within ${seconds} seconds although you are signed in to Windows.`
                 : `Installed ${result.unitPath}, but the daemon did not start within ${seconds} seconds, and HQ could not check whether you are signed in to Windows.`,
             "Check it with: hq daemon status",
-            `The task's last result: powershell -NoProfile -Command "(Get-ScheduledTaskInfo -TaskName '${DAEMON_WINDOWS_TASK}').LastTaskResult"`,
+            `The task's last result: powershell -NoProfile -Command "(Get-ScheduledTaskInfo -TaskName '${windowsTaskName({ windowsSid: d.windowsSid, windowsUser: d.windowsUser ?? "" })}').LastTaskResult"`,
         ].join("\n"));
     }
     if (!result.running) {
@@ -386,6 +393,8 @@ async function runUninstall(d, opts) {
     }
     const result = uninstallDaemonUnit(hostFor(d, paths, false), { scope: installScopeFor(detected.type) }, { run: d.run });
     d.out(result.removed ? `Removed ${result.unitPath}` : "hq daemon was not installed.");
+    if (result.notice)
+        d.out(result.notice);
     if (result.warning)
         d.err(result.warning);
     if (opts.restoreLegacy) {
@@ -869,7 +878,9 @@ async function runMigrate(d, opts) {
             platform: d.platform,
             home: d.home,
             systemUnitDir: d.systemUnitDir,
+            windowsTaskName: windowsTaskName({ windowsSid: d.windowsSid, windowsUser: d.windowsUser ?? "" }),
             windowsTaskExists: (task) => d.run("schtasks.exe", ["/Query", "/TN", task]).status === 0,
+            windowsLegacyTaskIsMine: () => legacyWindowsTask(d.run, { windowsSid: d.windowsSid, windowsUser: d.windowsUser ?? "" }).state === "mine",
         });
         if (!installed) {
             throw new DaemonCommandError("hq daemon is not installed here yet. Run `hq daemon install` first, then `hq daemon migrate --apply`.");
@@ -893,7 +904,7 @@ async function runMigrate(d, opts) {
         if (u.migratable)
             d.out(`Would take over ${u.unitId} from ${describeLegacyUnit(u)}${u.path ? ` (${u.path})` : ""}`);
         else
-            d.out(`Leaving ${u.unitId} to ${describeLegacyUnit(u)} (owned by the HQ desktop app)`);
+            d.out(`Leaving ${u.unitId} to ${describeLegacyUnit(u)} (${u.notMineReason ?? "owned by the HQ desktop app"})`);
     }
     d.out("Nothing was changed. `hq daemon migrate --apply` takes them over.");
 }

package/dist/commands/dm-attach.js

@@ -18,7 +18,8 @@
  *
  * Network is injected (`presign`, `put`) so the sequence is unit-testable.
  */
-import { createReadStream, statSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
+import { Readable } from "node:stream";
 import path from "node:path";
 import { vaultApiFetch } from "../utils/vault-api.js";
 import { contentTypeFor, streamPut } from "./library-add.js";
@@ -89,7 +90,17 @@ export function validateAttachmentPaths(paths, stat = statSync) {
 }
 export const defaultAttachmentUploadDeps = {
     presign: (token, body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body }),
-    put: (file, url, headers) => streamPut(url, headers, createReadStream(file.path), file.sizeBytes),
+    // Read the bytes once and declare their real length. Streaming with the
+    // size from validateAttachmentPaths' earlier stat sent a Content-Length the
+    // body could fall short of (file rewritten or truncated in between); S3 then
+    // waits ~20s and answers 400 RequestTimeout. Attachments are capped at 25 MB.
+    put: (file, url, headers) => {
+        const bytes = readFileSync(file.path);
+        if (bytes.length > MAX_DM_ATTACHMENT_BYTES) {
+            return Promise.reject(new Error(`Attachment too large: ${file.path} grew past the 25 MB limit after it was checked.`));
+        }
+        return streamPut(url, headers, Readable.from([bytes]), bytes.length);
+    },
 };
 /**
  * Presign-put every file into `scopeUid`, then return the `attachments[]`
@@ -138,7 +149,8 @@ export async function uploadDmAttachments(args) {
         }
         const put = await deps.put(p.file, row.url, headers);
         if (put.status < 200 || put.status >= 300) {
-            throw new Error(`Upload failed for ${p.file.path} (HTTP ${put.status}). The message was not sent.`);
+            const reason = [put.errorCode, put.errorMessage].filter(Boolean).join(": ");
+            throw new Error(`Upload failed for ${p.file.path} (HTTP ${put.status}${reason ? ` ${reason}` : ""}). The message was not sent.`);
         }
         out.push({
             vaultPath: p.key,

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

@@ -299,6 +299,8 @@ export interface UsableApp {
      * provider, else `--connection <id>`.
      */
     selector: string;
+    /** The caller created this connection (`viewerAccess.isCreator`). */
+    ownedByCaller: boolean;
 }
 export interface UsableAppsResult {
     companyUid: string;

package/dist/commands/integrations-core.js

@@ -529,6 +529,7 @@ export async function fetchUsableApps(token, companyUid) {
                 status: row.status,
                 providerArg,
                 selector: shared ? `--connection ${row.id}` : `--provider ${providerArg}`,
+                ownedByCaller: row.viewerAccess?.isCreator === true,
             };
         })
             .sort((a, b) => compareNames(a.name, b.name))

package/dist/commands/library-add.d.ts

@@ -19,7 +19,16 @@ export interface OpenedSource {
 export interface PutResponse {
     status: number;
     headers: Record<string, string | undefined>;
+    /** S3 `<Code>` from a non-2xx response body (e.g. `RequestTimeout`), when present. */
+    errorCode?: string;
+    /** S3 `<Message>` from a non-2xx response body, when present. */
+    errorMessage?: string;
 }
+/** Pull `<Code>` and `<Message>` out of an S3 XML error body. Pure. */
+export declare function parseS3Error(body: string): {
+    errorCode?: string;
+    errorMessage?: string;
+};
 export interface LibraryAddDeps {
     hqRoot: string;
     now: () => Date;

package/dist/commands/library-add.js

@@ -33,6 +33,14 @@ import { CONTENT_SHA256_METADATA_KEY, PLACEHOLDER_SUFFIX, companyOffloadKey, con
 import { formatPlanGateError, formatUpgradeRefusal, planGateErrorFromResponse, } from "../utils/plan-gate-error.js";
 /** Metadata key hq-pro binds to `checksumSha256` (sync's content hash). */
 const CONTENT_SHA256_META_KEY = CONTENT_SHA256_METADATA_KEY;
+/** Cap on how much of a non-2xx PUT response body is kept for the error reason. */
+const PUT_ERROR_BODY_LIMIT = 8 * 1024;
+/** Pull `<Code>` and `<Message>` out of an S3 XML error body. Pure. */
+export function parseS3Error(body) {
+    const code = /<Code>([^<]{1,200})<\/Code>/.exec(body)?.[1]?.trim();
+    const message = /<Message>([^<]{1,500})<\/Message>/.exec(body)?.[1]?.trim();
+    return { ...(code ? { errorCode: code } : {}), ...(message ? { errorMessage: message } : {}) };
+}
 const MEDIA_TYPES = {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -515,12 +523,21 @@ export function streamPut(url, headers, body, size) {
     return new Promise((resolve, reject) => {
         const target = new URL(url);
         const request = (target.protocol === "http:" ? http : https).request(target, { method: "PUT", headers: { ...headers, "content-length": String(size) } }, (res) => {
-            res.resume();
+            const status = res.statusCode ?? 0;
+            // Keep the start of a failure body so the caller can name S3's reason
+            // (RequestTimeout, EntityTooLarge, ...) instead of a bare status.
+            let errorBody = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => {
+                if ((status < 200 || status >= 300) && errorBody.length < PUT_ERROR_BODY_LIMIT) {
+                    errorBody += chunk.slice(0, PUT_ERROR_BODY_LIMIT - errorBody.length);
+                }
+            });
             res.on("end", () => {
                 const out = {};
                 for (const [k, v] of Object.entries(res.headers))
                     out[k] = Array.isArray(v) ? v.join(", ") : v;
-                resolve({ status: res.statusCode ?? 0, headers: out });
+                resolve({ status, headers: out, ...(errorBody ? parseS3Error(errorBody) : {}) });
             });
             res.on("error", reject);
         });

package/dist/commands/run.js

@@ -10,7 +10,7 @@ import { computeSha256 } from '../utils/integrity.js';
 import { isUnavailableSecretLoadHttpStatus, SecretLoadUnavailableError, } from '../utils/secret-load-availability.js';
 import { vaultApiFetch, getCompanyUid } from '../utils/vault-api.js';
 import { discoverSchemas } from '../run/discover-schemas.js';
-import { installHqPlugin, prewarmHqSecrets } from '../run/hq-plugin.js';
+import { installHqPlugin, itemIsOptional, prewarmHqSecrets } from '../run/hq-plugin.js';
 import { assertEnvGraphLoaded, resolveEnvValuesOrThrow, EnvGraphLoadError, EnvResolutionError, } from '../run/env-graph-guard.js';
 import { hadFatalRejection } from '../unhandled-rejection-boundary.js';
 import { withRunSecretReadTelemetry } from './run-feature-telemetry.js';
@@ -223,6 +223,14 @@ export function registerRunCommand(program) {
                 const schemaItems = Object.entries(graph.configSchema);
                 const itemMessages = (wantWarnings) => schemaItems.flatMap(([k, item]) => (item.errors ?? [])
                     .filter((e) => Boolean(e?.isWarning) === wantWarnings)
+                    .filter((e) => {
+                    if (wantWarnings)
+                        return true;
+                    if (!itemIsOptional(item))
+                        return true;
+                    const msg = e?.message ?? '';
+                    return !/No read permission|does not exist in company|not returned by vault/.test(msg);
+                })
                     .map((e) => `  ${k}: ${e?.message ?? String(e)}`));
                 const warningMsgs = itemMessages(true);
                 if (warningMsgs.length > 0) {

package/dist/commands/sources.d.ts

@@ -11,6 +11,8 @@
  *   hq sources get       Fetch one source by id.
  *   hq sources channels  Print the canonical SOURCE_CHANNELS enum.
  *   hq sources entities  List entities the caller has access to.
+ *   hq sources runs      Show the local hot-channel run ledger for one day.
+ *   hq sources sync      Run every hot channel now for the signed-in person.
  *
  * Defaults:
  *   --entity   falls back to .hq/config.json activeCompany (per sync.ts).
@@ -18,5 +20,92 @@
  *   --limit    50.
  */
 import { Command } from "commander";
+import { type RunLedgerAdapterSummary, type RunLedgerEntry, type RunTrigger, type SignalsGeneratedFn } from "../lib/hot-channels/ledger.js";
+import type { HotChannelRegistry } from "../lib/hot-channels/registry.js";
+import { type OnDemandSyncDeps, type OnDemandSyncReport } from "../lib/hot-channels/run.js";
+type ListFormat = "table" | "json";
+export interface RunsOptions {
+    today?: boolean;
+    date?: string;
+    company?: string;
+    email?: string;
+    format?: ListFormat;
+    hqRoot: string;
+}
+export interface RunsReport {
+    company: string;
+    personKey: string;
+    day: string;
+    adapters: RunLedgerAdapterSummary[];
+    entries: RunLedgerEntry[];
+    malformed: number;
+}
+/**
+ * Reads one day's run ledger (`sources/_runs/@{personKey}/{day}.jsonl` in the
+ * company folder of the local HQ tree). The person key is
+ * `audienceKey([email])` of the signed-in person. No network calls.
+ */
+export declare function runRuns(options: RunsOptions, now?: Date): Promise<RunsReport>;
+export interface SyncOptions {
+    adapter?: string;
+    company?: string;
+    hqRoot: string;
+    json?: boolean;
+}
+export interface SyncOverrides {
+    /** Adapters to run. This build registers none, so the default is empty. */
+    registry?: HotChannelRegistry;
+    now?: () => Date;
+    /** The signals pass; defaults to the local `claude -p` pass under the user's own login. */
+    signalsGenerated?: SignalsGeneratedFn;
+}
+/**
+ * Network access for one sync: the catalog, the person's usable connections,
+ * and tool calls through the HQ gateway. Integration tokens stay server-side;
+ * the gateway routes each call by connection id.
+ */
+export declare function gatewaySyncDeps(token: string, companyUid: string): OnDemandSyncDeps;
+export interface CompanyHotChannelSyncInput {
+    hqRoot: string;
+    company: string;
+    adapter?: string;
+    registry?: HotChannelRegistry;
+    now?: () => Date;
+    /** `scheduled` for the bot's hot-signal-sync job; `on-demand` by default. */
+    trigger?: RunTrigger;
+    catchUp?: boolean;
+    signalsGenerated?: SignalsGeneratedFn;
+    /** The signed-in person's `prs_` person uid in this company; defaults to a roster lookup by email. */
+    resolvePersonUid?: (token: string, companyUid: string, email: string) => Promise<string | null>;
+    /**
+     * Where the signals-failure alert goes (US-012). Unset = no alert check.
+     * The company-channel post defaults to the Slack channel in the company's
+     * `settings/signals/preferences.yaml`, through the HQ integrations gateway.
+     */
+    signalsAlert?: SignalsAlertSenders;
+}
+export interface SignalsAlertSenders {
+    /** The primary alert to the owner; throws when it was not delivered. */
+    sendOwnerDm: (text: string) => Promise<void>;
+    postCompanyChannel?: (text: string) => Promise<void>;
+    log?: (message: string) => void;
+}
+/**
+ * One hot-channel sync for the signed-in person in one company: each adapter
+ * once per usable connection. Writes under `companies/{company}/`: landed
+ * sources in `sources/`, index rows in `sources/_index/`, cursors in
+ * `sources/_cursors/`, one ledger line per adapter in `sources/_runs/`, and
+ * signals in `signals/@{key}/`. `hq sources sync` and the bot's scheduled
+ * hot-signal-sync job both call it. Only one run per person per company goes
+ * at a time: a second one writes a `skipped` ledger line and lands nothing.
+ */
+export declare function runCompanyHotChannelSync(input: CompanyHotChannelSyncInput): Promise<OnDemandSyncReport>;
+/**
+ * Run every hot channel for the signed-in person now: each adapter once per
+ * usable connection. Writes cursors, landed sources and an `on-demand` ledger
+ * line under `companies/{company}/sources/`, and nothing else.
+ */
+export declare function runSync(options: SyncOptions, overrides?: SyncOverrides): Promise<OnDemandSyncReport>;
 export declare function registerSourcesCommand(program: Command): void;
+export {};
 //# sourceMappingURL=sources.d.ts.map