@indigoai-us/hq-cli 5.300.0 → 5.302.0

package/dist/commands/core-job-remediate-native.js

@@ -0,0 +1,374 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { spawnSync } from "node:child_process";
+import { serializeJqJson } from "../lib/core-utils/jq-json-serializer.js";
+import { registerCoreJobLeaf } from "./core-job-native-utils.js";
+const ASSET = "core/scripts/hq-job-remediate.sh";
+const USAGE = [
+    "hq-job-remediate.sh — bounded self-remediation for Outpost scheduled jobs (US-006).",
+    "",
+    "Allowlist (v1):",
+    "  - Cognito / HQ token refresh via `hq auth refresh` when available",
+    "  - one `hq sync pull` (personal or --company)",
+    "  - single immediate retry for transient infra (signaled via retry_recommended)",
+    "Always-human (never auto-looped):",
+    "  - device re-login (Claude/Codex CLI)",
+    "  - secret share / missing vault grants",
+    "",
+    "Usage:",
+    "  core/scripts/hq-job-remediate.sh --failure-class <class> [--job-id <id>] \\",
+    "    [--company <slug>] [--hq-root <dir>]",
+    "",
+    "Env / overrides (tests):",
+    "  HQ_ROOT, HQ_JOB_REMEDIATE_AUTH_REFRESH_CMD, HQ_JOB_REMEDIATE_SYNC_PULL_CMD",
+    "  HQ_JOB_REMEDIATE_DRY=1 — print plan only; do not execute side effects",
+    "",
+    "stdout: JSON {failure_class, attempted, actions[], retry_recommended, always_human, next_action, notes}",
+    "Exit: 0 always on successful classify/plan (even if nothing attempted); 2 usage.",
+    "",
+    "set -euo pipefail",
+    "",
+].join("\n");
+function defaultCommandExists(command, env) {
+    if (command.includes(path.sep)) {
+        try {
+            fs.accessSync(command, fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+        if (!directory)
+            continue;
+        try {
+            fs.accessSync(path.join(directory, command), fs.constants.X_OK);
+            return true;
+        }
+        catch { /* Continue PATH lookup. */ }
+    }
+    return false;
+}
+function defaultRun(command, args, options) {
+    // The shell redirects both streams to the append-only log (or /dev/null). No
+    // timeout is set, matching its direct command invocation exactly.
+    let fd;
+    try {
+        fd = fs.openSync(options.logPath || os.devNull, "a");
+    }
+    catch {
+        // Bash reports failed redirection as a nonzero action; remediation still
+        // emits its classification JSON and exit status 0.
+        return 1;
+    }
+    try {
+        const result = spawnSync(command, args, {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ["ignore", fd, fd],
+        });
+        if (result.error) {
+            fs.writeSync(fd, `${result.error.message}\n`);
+            return 127;
+        }
+        return result.status ?? 0;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function defaultJobRemediateDependencies(env = process.env, cwd = process.cwd()) {
+    return {
+        env,
+        cwd,
+        readFile: (file) => fs.readFileSync(file, "utf8"),
+        commandExists: (command) => defaultCommandExists(command, env),
+        run: defaultRun,
+        stdout: (text) => { process.stdout.write(text); },
+        stderr: (text) => { process.stderr.write(text); },
+    };
+}
+function parseArguments(argv, deps) {
+    const values = { hqRoot: deps.env.HQ_ROOT ?? "", failureClass: "", jobId: "", company: "", dryRun: false };
+    const aliases = {
+        "--hq-root": "hqRoot", "--failure-class": "failureClass", "--job-id": "jobId", "--company": "company",
+    };
+    for (let index = 0; index < argv.length;) {
+        const flag = argv[index];
+        if (flag === "-h" || flag === "--help") {
+            deps.stdout(USAGE);
+            return 0;
+        }
+        if (flag === "--dry-run") {
+            values.dryRun = true;
+            index += 1;
+            continue;
+        }
+        if (flag === "--")
+            break;
+        const key = aliases[flag];
+        if (key) {
+            const value = argv[index + 1] ?? "";
+            if ((key === "hqRoot" || key === "failureClass") && !value) {
+                deps.stderr(`hq-job-remediate: --${key === "hqRoot" ? "hq-root" : "failure-class"} requires ${key === "hqRoot" ? "a directory" : "a value"}\n`);
+                return 2;
+            }
+            values[key] = value;
+            index += 2;
+            continue;
+        }
+        if (flag.startsWith("-")) {
+            deps.stderr(`hq-job-remediate: unknown option: ${flag}\n`);
+            return 2;
+        }
+        deps.stderr(`hq-job-remediate: unexpected argument: ${flag}\n`);
+        return 2;
+    }
+    if (!values.failureClass) {
+        deps.stderr("hq-job-remediate: usage: hq-job-remediate.sh --failure-class <auth|secrets|timeout|agent_error|infra>\n");
+        return 2;
+    }
+    if (!["auth", "secrets", "timeout", "agent_error", "infra"].includes(values.failureClass)) {
+        deps.stderr(`hq-job-remediate: unknown failure_class: ${values.failureClass} (want auth|secrets|timeout|agent_error|infra)\n`);
+        return 2;
+    }
+    if (values.company && values.company !== "null" && !/^[a-z0-9]([a-z0-9_-]*[a-z0-9])?$/.test(values.company)) {
+        deps.stderr(`hq-job-remediate: invalid --company slug '${values.company}' (want lowercase kebab/underscore)\n`);
+        return 2;
+    }
+    return values;
+}
+function canUseLiveRootForArguments(argv) {
+    const parsed = parseArguments(argv, {
+        env: {},
+        stdout: () => undefined,
+        stderr: () => undefined,
+    });
+    return typeof parsed !== "number";
+}
+function globRegex(segment) {
+    let pattern = "^";
+    for (let index = 0; index < segment.length; index += 1) {
+        const char = segment[index];
+        if (char === "\\" && index + 1 < segment.length) {
+            pattern += segment[++index].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        }
+        else if (char === "*")
+            pattern += ".*";
+        else if (char === "?")
+            pattern += ".";
+        else if (char === "[") {
+            const end = segment.indexOf("]", index + 1);
+            if (end < 0)
+                pattern += "\\[";
+            else {
+                let body = segment.slice(index + 1, end);
+                if (body.startsWith("!"))
+                    body = `^${body.slice(1)}`;
+                pattern += `[${body.replace(/\\/g, "")} ]`.replace(" ]", "]");
+                index = end;
+            }
+        }
+        else
+            pattern += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`${pattern}$`);
+}
+/** Bash's unquoted array assignment splits on IFS, then expands pathname globs. */
+function splitOverrideCommand(command, cwd) {
+    const words = command.split(/[ \t\n]+/).filter(Boolean);
+    const expanded = [];
+    for (const word of words) {
+        if (!/[?*[]/.test(word)) {
+            expanded.push(word);
+            continue;
+        }
+        const absolute = path.isAbsolute(word);
+        const parts = word.split(path.sep);
+        let prefixes = [absolute ? path.sep : ""];
+        for (const part of parts) {
+            if (!part)
+                continue;
+            if (!/[?*[]/.test(part)) {
+                prefixes = prefixes.map((prefix) => path.join(prefix || cwd, part));
+                continue;
+            }
+            const matcher = globRegex(part);
+            const next = [];
+            for (const prefix of prefixes) {
+                const directory = prefix || cwd;
+                let names;
+                try {
+                    names = fs.readdirSync(directory);
+                }
+                catch {
+                    continue;
+                }
+                for (const name of names) {
+                    if (!part.startsWith(".") && name.startsWith("."))
+                        continue;
+                    if (matcher.test(name))
+                        next.push(path.join(directory, name));
+                }
+            }
+            prefixes = next;
+            if (!prefixes.length)
+                break;
+        }
+        if (!prefixes.length)
+            expanded.push(word);
+        else
+            expanded.push(...prefixes.map((entry) => absolute ? entry : path.relative(cwd, entry) || "."));
+    }
+    return expanded;
+}
+const UNSAFE_OVERRIDE = /[;|&$`()<>]/;
+export function runJobRemediate(argv, options = {}) {
+    const deps = {
+        ...defaultJobRemediateDependencies(options.dependencies?.env ?? process.env, options.dependencies?.cwd ?? process.cwd()),
+        ...options.dependencies,
+    };
+    if (options.hqRoot)
+        deps.env = { ...deps.env, HQ_ROOT: options.hqRoot };
+    const parsed = parseArguments(argv, deps);
+    if (typeof parsed === "number")
+        return parsed;
+    const hqRoot = parsed.hqRoot || options.hqRoot || deps.env.HQ_ROOT || "";
+    if (hqRoot)
+        deps.env = { ...deps.env, HQ_ROOT: hqRoot };
+    const dryRun = parsed.dryRun || deps.env.HQ_JOB_REMEDIATE_DRY === "1";
+    const actions = [];
+    let attempted = false;
+    let retryRecommended = false;
+    let alwaysHuman = false;
+    let nextAction = "";
+    let notes = "";
+    const logPath = deps.env.HQ_JOB_REMEDIATE_LOG || os.devNull;
+    const log = (message) => deps.stderr(`hq-job-remediate: ${message}\n`);
+    const emit = (code) => {
+        if (code === 2)
+            return 2;
+        deps.stdout(serializeJqJson({
+            failure_class: parsed.failureClass,
+            job_id: parsed.jobId,
+            attempted,
+            actions,
+            retry_recommended: retryRecommended,
+            always_human: alwaysHuman,
+            next_action: nextAction,
+            notes,
+        }, "compact"));
+        return 0;
+    };
+    const runOrDry = (label, command, args) => {
+        actions.push(label);
+        if (dryRun) {
+            log(`dry-run: would run: ${[command, ...args].join(" ")}`);
+            return true;
+        }
+        return deps.run(command, args, { cwd: deps.cwd, env: deps.env, logPath }) === 0;
+    };
+    const runOverrideOrArgv = (label, overrideOrCommand, args = []) => {
+        let command = overrideOrCommand;
+        let commandArgs = args;
+        if (args.length === 0 && overrideOrCommand.includes(" ")) {
+            if (UNSAFE_OVERRIDE.test(overrideOrCommand)) {
+                deps.stderr("hq-job-remediate: unsafe remediate override command rejected\n");
+                return 2;
+            }
+            [command, ...commandArgs] = splitOverrideCommand(overrideOrCommand, deps.cwd);
+            if (!command)
+                return true;
+        }
+        return runOrDry(label, command, commandArgs);
+    };
+    const resolveAuthRefresh = () => {
+        const override = deps.env.HQ_JOB_REMEDIATE_AUTH_REFRESH_CMD || "";
+        if (override)
+            return override;
+        if (deps.commandExists("hq"))
+            return "hq auth refresh";
+        if (deps.commandExists("hq-auth-refresh"))
+            return "hq-auth-refresh";
+        return "";
+    };
+    switch (parsed.failureClass) {
+        case "secrets":
+            alwaysHuman = true;
+            nextAction = "share the missing secret to this Outpost (hq secrets share KEY) then re-probe";
+            notes = "secret share is always-human; no self-remediation";
+            return emit(0);
+        case "auth": {
+            alwaysHuman = true;
+            nextAction = "re-login on Outpost (device code) for the job runtime CLI";
+            notes = "attempt Cognito refresh if available; never loop device re-login";
+            const command = resolveAuthRefresh();
+            if (command) {
+                attempted = true;
+                const result = runOverrideOrArgv("cognito_token_refresh", command);
+                if (result === 2)
+                    return 2;
+                if (result)
+                    notes = "cognito refresh ok; device re-login still required if CLI creds missing";
+                else
+                    notes = "cognito refresh failed or unavailable; device re-login required";
+            }
+            else
+                notes = "no hq auth refresh on PATH; device re-login required";
+            return emit(0);
+        }
+        case "timeout":
+            nextAction = "raise timeout_seconds or split the job work";
+            notes = "timeout is not self-retried in v1 (avoid thrash)";
+            return emit(0);
+        case "agent_error":
+            nextAction = "inspect the job log and fix the prompt/skill";
+            notes = "agent_error is not self-remediated in v1";
+            return emit(0);
+        case "infra": {
+            nextAction = "retry after sync; if it persists, check Outpost disk/network";
+            notes = "allowlist: cognito refresh + one hq-sync pull + single retry";
+            const authCommand = resolveAuthRefresh();
+            if (authCommand) {
+                attempted = true;
+                const result = runOverrideOrArgv("cognito_token_refresh", authCommand);
+                if (result === 2)
+                    return 2;
+            }
+            const syncOverride = deps.env.HQ_JOB_REMEDIATE_SYNC_PULL_CMD || "";
+            attempted = true;
+            if (syncOverride) {
+                const result = runOverrideOrArgv("hq_sync_pull", syncOverride);
+                if (result === 2)
+                    return 2;
+                retryRecommended = true;
+                notes = result ? "sync pull ok; recommend single immediate retry" : "sync pull failed; still recommend one infra retry";
+            }
+            else if (deps.commandExists("hq")) {
+                const syncArgs = parsed.company && parsed.company !== "null"
+                    ? ["sync", "pull", "--company", parsed.company, "--hq-root", hqRoot]
+                    : ["sync", "pull", "--personal", "--hq-root", hqRoot];
+                const result = runOrDry("hq_sync_pull", "hq", syncArgs);
+                retryRecommended = true;
+                notes = result ? "sync pull ok; recommend single immediate retry" : "sync pull failed; still recommend one infra retry";
+            }
+            else {
+                actions.push("hq_sync_pull_unavailable");
+                retryRecommended = true;
+                notes = "hq sync pull unavailable; recommend single infra retry anyway";
+            }
+            return emit(0);
+        }
+        default:
+            // parseArguments rejects unknown classes before any remediation path.
+            return 2;
+    }
+}
+export function registerCoreJobRemediateNativeCommand(group, core) {
+    registerCoreJobLeaf(group, core, "remediate", ASSET, "Run bounded remediation for a scheduled-job failure", (argv, hqRoot) => runJobRemediate(argv, { hqRoot }), canUseLiveRootForArguments, [
+        "--hq-root", "--failure-class", "--job-id", "--company",
+    ], ["--dry-run"]);
+}
+//# sourceMappingURL=core-job-remediate-native.js.map

package/dist/commands/core.js

@@ -40,7 +40,7 @@ import { registerCoreJobsNativeCommand } from "./core-job-native.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";
+import { CompanyIndexUserError, renderIndexTarget } from "../lib/index-render/index.js";
 import { generateWorkersRegistry } from "../lib/workers-registry/index.js";
 import { scanPackages } from "../lib/scan-packages/index.js";
 import { detectStaleCorePolicyMirror } from "../lib/core-utils/detect-stale-core-policy-mirror.js";
@@ -57,6 +57,7 @@ import { timeoutGuardCommand } from "../lib/core-utils/timeout-guard.js";
 import { readSentryReportStdin, reportSentryEvent } from "../lib/core-utils/sentry-report.js";
 import { CLEAN_HANDOFF_ASSET, RESUME_LOCK_ASSET, VERIFY_DELIVERABLES_ASSET, WORKTREE_GC_ASSET, runCleanWorktreeReconcileHandoff, runResumeThreadLock, runVerifyStoryDeliverables, runWorktreeGc, } from "../lib/core-utils/worktree-resume.js";
 import { coreNativeHandoffEnabled } from "./core-native-handoff-flag.js";
+import { coreCompanyIndexScopeEnabled } from "./core-company-index-scope-flag.js";
 import { describeCoreCommand, registeredCoreCommandListing, } from "./core-command-catalog.js";
 /**
  * These commands are now native implementations. Their retained shell assets
@@ -489,18 +490,35 @@ export function registerCoreCommands(program) {
             throw expectedUserError(`Unknown rebuild-index target "${target}". Valid targets: ${validTargets.join(", ")}.`);
         }
         const scope = core.opts();
-        const hqRoot = resolveLiveRoot({ hqRoot: scope.hqRoot });
         const operands = cmd.args.length > 0 ? cmd.args : args;
         const passthrough = operands.slice(1);
         const force = passthrough.includes("--accept");
         const rendererArgs = passthrough.filter((arg) => arg !== "--accept");
+        const isCompaniesTarget = entry.renderer === "companies";
+        const wantsHelp = rendererArgs.some((arg) => arg === "--help" || arg === "-h");
+        if (isCompaniesTarget && wantsHelp) {
+            renderIndexTarget(entry.renderer, { root: "", output: (message) => process.stdout.write(message) }, rendererArgs);
+            return;
+        }
+        const requestsCompanyScope = isCompaniesTarget && rendererArgs.some((arg) => arg === "--company" || arg.startsWith("--company="));
+        if (requestsCompanyScope && !coreCompanyIndexScopeEnabled()) {
+            throw expectedUserError("rebuild-index companies --company is disabled; enable cli.rebuild-index-company-scope for a canary.");
+        }
+        const hqRoot = resolveLiveRoot({ hqRoot: scope.hqRoot });
         const refused = [];
-        renderIndexTarget(entry.renderer, {
-            root: hqRoot,
-            log: (message) => process.stderr.write(`${message}\n`),
-            force,
-            refused,
-        }, rendererArgs);
+        try {
+            renderIndexTarget(entry.renderer, {
+                root: hqRoot,
+                log: (message) => process.stderr.write(`${message}\n`),
+                force,
+                refused,
+            }, rendererArgs);
+        }
+        catch (error) {
+            if (error instanceof CompanyIndexUserError)
+                throw expectedUserError(error.message);
+            throw error;
+        }
         if (refused.length > 0) {
             throw expectedUserError(`rebuild-index: refused to overwrite ${refused.length} hand-edited INDEX.md file(s). Re-run with --accept to overwrite.`);
         }

package/dist/commands/deploy-comments.js

@@ -1,4 +1,5 @@
 import { deployApiRequest } from "../lib/deploy-api.js";
+import { listDeployApps } from "../lib/deploy-apps.js";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken } from "../utils/cognito-session.js";
 import { readActiveCompanySlug } from "./skill.js";
 class DeployCommentsError extends Error {
@@ -50,8 +51,10 @@ async function deployJson(token, route, orgHeaders) {
     }
 }
 async function resolveAppId(token, appNameOrId, orgHeaders) {
-    const result = await deployJson(token, "/api/apps", orgHeaders);
-    const apps = Array.isArray(result.apps) ? result.apps : [];
+    const apps = await listDeployApps((cursor) => {
+        const route = cursor ? `/api/apps?cursor=${encodeURIComponent(cursor)}` : "/api/apps";
+        return deployJson(token, route, orgHeaders);
+    });
     const byId = apps.find((app) => app && typeof app.id === "string" && app.id === appNameOrId);
     const matches = byId
         ? [byId]

package/dist/commands/files.js

@@ -14,6 +14,7 @@ import { findHqRoot } from "../utils/manifest.js";
 import { maxLength } from "../utils/table-width.js";
 import { resolveCompanyFlagGate } from "../lib/flag-registry.js";
 const PERSON_UID_PATTERN = /^(prs|agt)_[A-Za-z0-9_-]+$/;
+const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
 export const FILES_SHARE_EMPTY_PREFIX_WARNING_FLAG = "files.share-empty-prefix-warning";
 const FILES_SHARE_EMPTY_PREFIX_CHECK_TIMEOUT_MS = 5_000;
 function collectMentions(value, previous) {
@@ -265,14 +266,15 @@ export function registerFilesCommand(program) {
     files
         .command("unshare <prefix>")
         .description("Remove a file access grant. A trailing slash targets the private-folder row exactly.")
-        .requiredOption("--with <principal>", "Person uid, email address, group id, or '@all' to remove the grant")
+        .requiredOption("--with <principal>", "Person uid, agent uid, email address, group id, or '@all' to remove the grant")
         .action(async (prefix, opts) => {
         try {
-            // Unshare MUTATES access with no preview, and it resolves the target
-            // company from --company (not from the pasted anchor), so a mismatched
-            // anchor would revoke a real grant in the wrong company.
+            // Unshare MUTATES access with no preview. Anchored content paths remain
+            // refused; the exact company-root ACL row is the sole exception and
+            // resolves its anchor against the selected company before revoking.
             const canonicalPrefix = normalizeCompanyFilePrefix(prefix, {
                 mutating: true,
+                allowCompanyRootAclRow: true,
                 ...(files.opts().company !== undefined
                     ? { companySlug: files.opts().company }
                     : {}),
@@ -281,11 +283,14 @@ export function registerFilesCommand(program) {
             const isAll = principal === "@all";
             const isEmail = !isAll && EMAIL_PATTERN.test(principal);
             const isGroup = !isAll && GROUP_ID_PATTERN.test(principal);
-            const isPerson = !isAll && !isEmail && !isGroup && PERSON_UID_PATTERN.test(principal);
-            if (!isAll && !isEmail && !isGroup && !isPerson) {
-                console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, or a group id matching grp_<alphanumeric>`));
+            const isAgent = !isAll && !isEmail && !isGroup && AGENT_UID_PATTERN.test(principal);
+            const isPerson = !isAll && !isEmail && !isGroup && !isAgent && PERSON_UID_PATTERN.test(principal);
+            if (!isAll && !isEmail && !isGroup && !isPerson && !isAgent) {
+                console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, a person uid matching prs_<alphanumeric>, an agent uid matching agt_<alphanumeric>, or a group id matching grp_<alphanumeric>`));
                 process.exit(1);
             }
+            // The vault ACL API stores first-class agent access on its backwards-
+            // compatible person tuple: { granteeType: "person", granteeId: "agt_*" }.
             const granteeType = isAll
                 ? "company-wide"
                 : isEmail
@@ -300,8 +305,14 @@ export function registerFilesCommand(program) {
                     : principal;
             const principalLabel = isAll ? "everyone in the company" : granteeId;
             const token = (await resolveVaultCredential()).token;
-            const companySlug = files.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            const explicitCompanySlug = files.opts().company;
+            const companyRootSlug = stripRedundantCompanyScope(prefix)?.prefix === ""
+                ? companySlugFromAnchor(prefix)
+                : undefined;
+            const companyUid = await resolveCompanyUidForAnchoredPath(token, {
+                explicit: explicitCompanySlug,
+                anchorSlug: companyRootSlug,
+            });
             const res = await vaultApiFetch({
                 token,
                 path: `/files/${encodeURIComponent(companyUid)}/acl/revoke`,
@@ -361,6 +372,7 @@ export function registerFilesCommand(program) {
             // a DIFFERENT company's ACL than the one the operator pasted.
             const explicitCompany = files.opts().company;
             const canonicalPrefix = normalizeCompanyFilePrefix(prefix, {
+                allowCompanyRootAclRow: true,
                 ...(explicitCompany !== undefined
                     ? { companySlug: explicitCompany }
                     : {}),
@@ -1085,9 +1097,11 @@ export function companySlugFromAnchor(prefix, personal) {
  * Normalize company paths at the CLI boundary, preserving personal keys.
  *
  * `mutating` marks a route that CHANGES access and has no preview or
- * confirmation step (grant, share, unshare). Those refuse an anchored path
- * outright rather than guessing, because stripping the anchor changes which
+ * confirmation step (grant, share, unshare). Those refuse anchored content
+ * paths rather than guessing, because stripping the anchor changes which
  * objects the operation reaches and there is nothing downstream to catch it.
+ * `allowCompanyRootAclRow` is limited to exact-root ACL inspect/revoke calls:
+ * those need the original anchor to match a legacy company-root ACL row.
  *
  * `companySlug` is the company the command is actually targeting. When the
  * anchor names a DIFFERENT company we refuse in every mode: stripping would
@@ -1115,9 +1129,12 @@ function normalizeCompanyFilePrefix(prefix, options = {}) {
             `operation to '${options.companySlug}' instead. Re-run with ` +
             `--company ${scope.strippedSlug}, or pass the bucket-relative path.`);
     }
-    // A bare anchor strips to nothing. The ACL routes would ship that empty
-    // prefix to a server that answers 400, so fail here with a message that says
-    // what to do instead. `deferRootReject` is for callers that already have a
+    if (!scope.prefix && options.allowCompanyRootAclRow) {
+        return normalizeFilePrefix(prefix);
+    }
+    // A bare anchor strips to nothing. Content operations must fail with a
+    // message that says what to do instead; exact-root ACL operations preserve
+    // the original anchor above. `deferRootReject` is for callers that already have a
     // root guard with better copy — `runFilesDelete` says "Refusing to delete the
     // vault root", which beats anything this generic helper could write.
     if (!scope.prefix && !options.deferRootReject) {

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

@@ -163,15 +163,15 @@ export interface InstallInput {
     };
 }
 export declare function installIntegration(token: string, companyUid: string, input: InstallInput): Promise<InstallResult>;
-export declare function uninstallIntegration(token: string, companyUid: string, installationId: string): Promise<{
+export declare function uninstallIntegration(token: string, companyUid: string, target: {
     installationId: string;
+} | {
+    connectionId: string;
+}): Promise<{
+    installationId: string | null;
     connectionId: string;
 }>;
-/**
- * Permanently remove a revoked connection tombstone. The admin purge endpoint
- * deliberately accepts only the connection id: it derives the company and
- * enforces owner authorization from the authenticated connection record.
- */
+/** Permanently remove a revoked connection tombstone for one company. */
 export declare function purgeConnection(token: string, companyUid: string, connectionId: string): Promise<{
     connectionId: string;
 }>;

package/dist/commands/integrations-api.js

@@ -74,33 +74,24 @@ export async function installIntegration(token, companyUid, input) {
     }
     return (await res.json());
 }
-export async function uninstallIntegration(token, companyUid, installationId) {
+export async function uninstallIntegration(token, companyUid, target) {
     const res = await vaultApiFetch({
         token,
         path: "/v1/integrations/factory/uninstall",
         method: "POST",
-        body: { companyUid, installationId },
+        body: { companyUid, ...target },
     });
     if (!res.ok)
         await raiseForResponse(res, "Failed to disconnect the app");
     return (await res.json());
 }
-/**
- * Permanently remove a revoked connection tombstone. The admin purge endpoint
- * deliberately accepts only the connection id: it derives the company and
- * enforces owner authorization from the authenticated connection record.
- */
+/** Permanently remove a revoked connection tombstone for one company. */
 export async function purgeConnection(token, companyUid, connectionId) {
-    // Keep the company in this client's call signature with the other
-    // connection mutations. It is resolved before the target connection so a
-    // caller cannot use a slug from a different company, but the server's purge
-    // contract intentionally takes only connectionId in its body.
-    void companyUid;
     const res = await vaultApiFetch({
         token,
         path: "/v1/integrations/admin/purge",
         method: "POST",
-        body: { connectionId },
+        body: { companyUid, connectionId },
     });
     if (!res.ok)
         await raiseForResponse(res, "Failed to purge the revoked connection");

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

@@ -30,6 +30,7 @@ interface ConnectOptions {
     displayName?: string;
     token?: string;
     tokenStdin?: boolean;
+    authHeader?: string;
     auth?: string;
     browser?: boolean;
     timeout?: string;
@@ -48,6 +49,8 @@ interface ConnectOptions {
  * than fall through to a default.
  */
 export declare function assertAuthMode(value: string | undefined): void;
+/** RFC 7230 token characters accepted for an HTTP field name. */
+export declare function assertAuthHeader(value: string | undefined): void;
 /** Single-quote a value for a copy-pasteable shell command. */
 export declare function shellQuote(value: string): string;
 /** Everything the connect verbs need to name one app to hq-pro. */