@indigoai-us/hq-cli 5.115.6 → 5.116.0

package/dist/commands/agents.js

@@ -15,6 +15,8 @@
  *   hq agents start|stop <uid>     — EC2 start/stop
  *   hq agents retry <uid>          — resume setup from first non-done step
  *   hq agents rm <uid> --yes       — deprovision (destructive; flag-guarded)
+ *   hq agents rotate <uid>         — new enrollment code for an external agent
+ *   hq agents revoke <uid> --yes   — revoke an external agent (--remove deletes it)
  *   hq agents jobs list <uid>      — off-box job roster (schedule + rate)
  *   hq agents jobs pause <uid> <jobId>  — flip schedule State=DISABLED
  *   hq agents jobs cancel <uid> <jobId> — delete schedule + drop the job
@@ -387,6 +389,143 @@ export async function getAgentStatus(token, agentUid) {
         path: `/v1/agents/${encodeURIComponent(agentUid)}/status`,
     });
 }
+function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function safeActionUrl(value) {
+    const raw = nonEmptyString(value);
+    if (!raw)
+        return null;
+    try {
+        const url = new URL(raw);
+        return url.protocol === "https:" && !url.username && !url.password ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+function signInProviderName(url) {
+    const parsed = new URL(url);
+    if (parsed.hostname === "auth.openai.com" &&
+        parsed.pathname.startsWith("/codex/")) {
+        return "Codex";
+    }
+    if (parsed.hostname === "accounts.x.ai")
+        return "Grok";
+    if (parsed.hostname.endsWith("anthropic.com"))
+        return "Claude";
+    return "your provider";
+}
+function currentDeviceSignInAction(status) {
+    const pairing = recordValue(status.pairing);
+    const url = safeActionUrl(pairing?.url);
+    if (!url)
+        return null;
+    const rawCode = nonEmptyString(pairing?.code);
+    const code = rawCode && /^[A-Z0-9]{4,8}-[A-Z0-9]{4,8}$/i.test(rawCode)
+        ? rawCode
+        : undefined;
+    const provider = signInProviderName(url);
+    return {
+        type: provider === "Codex" ? "codex-device-sign-in" : "provider-sign-in",
+        title: `Sign in to ${provider}`,
+        summary: `sign in to ${provider}`,
+        instruction: code
+            ? "Open this page and enter the code."
+            : "Open this page and follow the sign-in instructions.",
+        url,
+        urlLabel: "Open",
+        code,
+    };
+}
+function pendingSlackAction(status) {
+    const agent = recordValue(status.agent);
+    const diagnostics = recordValue(agent?.channelDiagnostics);
+    const slack = recordValue(diagnostics?.slack);
+    const url = safeActionUrl(slack?.pendingInstallUrl);
+    if (!url)
+        return null;
+    if (slack?.inboundCapability === "socket-mode-degraded") {
+        return {
+            type: "slack-app-token",
+            title: "Finish setting up the Slack app",
+            summary: "finish setting up the Slack app",
+            instruction: "Open this page, create the app-level token, then provide it in the agent's Slack setup.",
+            url,
+            urlLabel: "Open",
+        };
+    }
+    if (slack?.inboundCapability !== "pending-install")
+        return null;
+    return {
+        type: "slack-install",
+        title: "Install the Slack app",
+        summary: "install the Slack app so it can talk to your workspace",
+        instruction: "Open this link and install the app in your workspace.",
+        url,
+        urlLabel: "Install",
+    };
+}
+/**
+ * The server owns action detection. This client converts its safe, current
+ * status fields into a list so another operator action can be added without
+ * changing the renderers or command control flow.
+ */
+function pendingOperatorActions(status) {
+    return [
+        currentDeviceSignInAction(status),
+        pendingSlackAction(status),
+    ].filter((action) => action !== null);
+}
+function pendingActionsJson(actions) {
+    return actions.map(({ type, title, instruction, url, code }) => ({
+        type,
+        title,
+        instruction,
+        ...(url ? { url } : {}),
+        ...(code ? { code } : {}),
+    }));
+}
+function statusAgentSlug(status) {
+    return nonEmptyString(recordValue(status.agent)?.slug);
+}
+/** The provision endpoint returns this nested identity; old response shapes omit it. */
+function provisionedAgentIdentity(result) {
+    const agent = recordValue(result.agent);
+    const uid = nonEmptyString(agent?.uid) ?? nonEmptyString(agent?.agentUid);
+    const slug = nonEmptyString(agent?.slug);
+    return uid && slug ? { uid, slug } : null;
+}
+function printPendingOperatorActions(slug, actions) {
+    if (actions.length === 0)
+        return;
+    const first = actions[0];
+    console.log(chalk.yellow(actions.length === 1
+        ? `Your agent's box is up. One step left: ${first.summary}.`
+        : "Your agent's box is up. A few steps remain before it can talk to your workspace."));
+    for (const action of actions) {
+        console.log("");
+        console.log(chalk.bold(`${action.title}:`));
+        console.log(action.instruction);
+        if (action.url)
+            console.log(chalk.cyan(`${action.urlLabel ?? "Open"}: ${action.url}`));
+        if (action.code)
+            console.log(chalk.bold(`Code: ${action.code}`));
+    }
+    const currentCodeHint = actions.some((action) => action.code)
+        ? "current sign-in code and instructions"
+        : "these instructions";
+    const statusCommand = slug
+        ? `Run \`hq agents status ${slug}\` any time to get ${currentCodeHint} again.`
+        : `Run \`hq agents status\` again any time to get ${currentCodeHint}.`;
+    console.log("");
+    console.log(chalk.dim(`Until that's done, the agent will show as still setting up. ${statusCommand}`));
+}
 export async function patchAgentProfile(token, agentUid, patch) {
     return agentsRequest({
         token,
@@ -656,6 +795,59 @@ function shortTime(iso) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * POST /v1/agents/{uid}/rotate — invalidate the current secret and host key
+ * and issue a fresh one-time enrollment code (returned exactly once).
+ */
+export async function rotateAgent(token, agentUid) {
+    const data = await agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/rotate`,
+        method: "POST",
+    });
+    const e = data.enrollment ?? {};
+    if (typeof e.code !== "string" || !e.code) {
+        throw new AgentsHttpError(502, "rotate succeeded but the response carried no enrollment code");
+    }
+    return {
+        agentUid: data.agentUid ?? agentUid,
+        enrollment: {
+            code: e.code,
+            expiresAt: typeof e.expiresAt === "string" ? e.expiresAt : "",
+            enrollmentId: typeof e.enrollmentId === "string" ? e.enrollmentId : "",
+        },
+    };
+}
+/** Display form of a 24-char code: six groups of four. */
+export function groupEnrollmentCode(code) {
+    const flat = code.replace(/[\s-]+/g, "").toUpperCase();
+    return flat.match(/.{1,4}/g)?.join("-") ?? flat;
+}
+/**
+ * POST /v1/agents/{uid}/revoke — disable the Cognito user, drop membership,
+ * mark the enrollment revoked; `remove` also deletes the entity.
+ */
+export async function revokeAgent(token, agentUid, remove) {
+    const data = await agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/revoke`,
+        method: "POST",
+        body: { remove },
+    });
+    return { removed: data.removed === true || remove };
+}
+/** Lines printed after a rotate: the code is shown once and never stored. */
+export function formatRotateOutput(result) {
+    const lines = [
+        `Rotated ${result.agentUid}. The old secret and host key no longer mint.`,
+        "",
+        `  enrollment code: ${groupEnrollmentCode(result.enrollment.code)}`,
+    ];
+    if (result.enrollment.expiresAt)
+        lines.push(`  expires:         ${result.enrollment.expiresAt} (15 minutes)`);
+    lines.push("", "Shown once. On the agent's host run:", `  hq agent enroll ${groupEnrollmentCode(result.enrollment.code)} --replace`, "  hq agent probe");
+    return lines;
+}
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -711,6 +903,11 @@ export function registerAgentsCommand(program) {
             // Interactive terminals are for humans: hq-pro serves no keyed
             // `/v1/keys/agents/{uid}/terminal` route, so machine keys fail closed.
             terminal: { capability: "agents:use", routeAvailable: false },
+            // External-agent lifecycle is an admin action on the JWT-only
+            // /v1/agents/{uid}/rotate|revoke routes (api-contract v1); no keyed
+            // parallel exists, so machine keys fail closed here too.
+            rotate: { capability: "agents:use", routeAvailable: false },
+            revoke: { capability: "agents:use", routeAvailable: false },
         },
     });
     // `--company` may live on the group or the subcommand; the subcommand value
@@ -955,13 +1152,34 @@ export function registerAgentsCommand(program) {
                     quoteCatalogVersion: createOptions.catalogVersion,
                     surface: CLI_AGENT_CREATE_SURFACE,
                 });
-                const uid = typeof result.uid === "string" ? result.uid : slug;
+                const identity = provisionedAgentIdentity(result);
+                const status = identity
+                    ? await getAgentStatus(token, identity.uid)
+                    : null;
+                const actions = status ? pendingOperatorActions(status) : [];
+                const slackInstall = actions.find((action) => action.type === "slack-install");
                 if (opts.json) {
-                    console.log(JSON.stringify(result));
+                    console.log(JSON.stringify({
+                        ...result,
+                        ...(actions.length > 0
+                            ? { pendingActions: pendingActionsJson(actions) }
+                            : {}),
+                        ...(slackInstall?.url
+                            ? {
+                                slackInstallPending: true,
+                                slackInstallUrl: slackInstall.url,
+                            }
+                            : {}),
+                    }));
                 }
                 else {
                     console.log(chalk.green(`Provisioning started for agent "${name}".`));
-                    console.log(chalk.dim(`Track setup: hq agents status ${uid} --company <slug>`));
+                    if (actions.length > 0) {
+                        printPendingOperatorActions(identity?.slug ?? null, actions);
+                    }
+                    else {
+                        console.log(chalk.dim(`Track setup: hq agents status ${identity?.slug ?? slug} --company <slug>`));
+                    }
                 }
             }
             catch (err) {
@@ -1050,16 +1268,28 @@ export function registerAgentsCommand(program) {
         }
     });
     agents
-        .command("status <agentUid>")
+        .command("status <agent>")
         .description("Show an agent's setup state and runtime detail")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--json", "Emit raw JSON")
-        .action(async function (agentUid, opts) {
+        .action(async function (agent, opts) {
         try {
             const token = (await resolveVaultCredential()).token;
+            const agentUid = await resolveAgentUid(token, agent, companyOf(this));
             const status = await getAgentStatus(token, agentUid);
+            const actions = pendingOperatorActions(status);
             if (opts.json) {
-                process.stdout.write(JSON.stringify(status, null, 2) + "\n");
+                process.stdout.write(JSON.stringify({
+                    ...status,
+                    ...(actions.length > 0
+                        ? { pendingActions: pendingActionsJson(actions) }
+                        : {}),
+                }, null, 2) + "\n");
+                return;
+            }
+            if (actions.length > 0) {
+                printPendingOperatorActions(statusAgentSlug(status) ??
+                    (AGENT_UID_PATTERN.test(agent.trim()) ? null : agent.trim()), actions);
                 return;
             }
             // Pretty but faithful: dump the top-level fields as key: value.
@@ -1268,6 +1498,50 @@ export function registerAgentsCommand(program) {
             fail(err);
         }
     });
+    agents
+        .command("rotate <agentUid>")
+        .description("Issue a fresh enrollment code for an external agent (old secret + host key stop minting)")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--json", "Emit raw JSON (code included — pipe carefully)")
+        .action(async function (agentUid, opts) {
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const result = await rotateAgent(token, agentUid);
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            for (const line of formatRotateOutput(result))
+                console.log(line);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    agents
+        .command("revoke <agentUid>")
+        .description("Revoke an external agent: disable its login and drop it from the team")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--remove", "Also delete the agent entity (it disappears from the roster)")
+        .option("--yes", "Confirm the revoke (required)")
+        .action(async function (agentUid, opts) {
+        if (!opts.yes) {
+            console.error(chalk.yellow(`This will revoke agent ${agentUid}: its credentials stop working immediately and it ` +
+                `leaves the team${opts.remove ? ", and the agent record is deleted" : ""}. ` +
+                `Re-run with --yes to confirm: hq agents revoke ${agentUid}${opts.remove ? " --remove" : ""} --yes`));
+            process.exit(1);
+        }
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const result = await revokeAgent(token, agentUid, opts.remove === true);
+            console.log(chalk.green(result.removed
+                ? `Revoked and removed agent ${agentUid}.`
+                : `Revoked agent ${agentUid}. Its next mint will be refused (401).`));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
     // Off-box job control (US-003). Nested group so `hq agents jobs --help`
     // lists list|pause|cancel. Same vaultApiFetch + person JWT as the rest of
     // this file; keyed HQ_API_KEY rewrites /v1/agents → /v1/keys/agents.

package/dist/commands/secrets.js

@@ -43,7 +43,19 @@ export const CLI_SECRETS_SET_SURFACE = "cli_secrets_set";
  */
 async function requireCognitoTokenForSecrets(commandLabel, capability = null) {
     requireApiKeyCapability(capability, commandLabel, { routeAvailable: false });
-    return ensureCognitoToken();
+    return ensureCognitoToken(secretsCredentialOptions());
+}
+/**
+ * A browser login is safe only when a person can answer it. This mirrors the
+ * repository's existing terminal convention in `canOfferTeamUpgrade`: both
+ * stdin and stderr must be TTYs, and CI is always non-interactive.
+ */
+function secretsCredentialOptions() {
+    return {
+        interactive: process.stdin.isTTY === true &&
+            process.stderr.isTTY === true &&
+            !process.env.CI,
+    };
 }
 function scopeOpts(opts) {
     if (opts.personal && opts.company) {
@@ -96,7 +108,7 @@ function resolveApiKeyCompanyUid(scope, commandLabel) {
     return ref;
 }
 async function resolveSecretsTarget(capability, commandLabel, scopeOptions) {
-    const cred = await resolveVaultCredentialForCapability(capability, commandLabel);
+    const cred = await resolveVaultCredentialForCapability(capability, commandLabel, secretsCredentialOptions());
     const scope = scopeOpts(scopeOptions);
     const isApiKey = cred.kind === "api-key";
     const companyUid = isApiKey
@@ -883,7 +895,7 @@ export function registerSecretsCommand(program) {
         .option("--reveal", "Include the decrypted secret value")
         .action(async (name, opts) => {
         try {
-            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets get");
+            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets get", secretsCredentialOptions());
             if (cred.kind === "api-key") {
                 if (!opts.reveal) {
                     console.error(chalk.red("HQ_API_KEY is set; `hq secrets get` without --reveal is not supported for API keys. " +
@@ -1434,7 +1446,7 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const keys = parseSecretNameList(_opts.only);
-            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets exec");
+            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets exec", secretsCredentialOptions());
             const companyUid = cred.kind === "api-key"
                 ? "__api_key__"
                 : await getEntityUid(cred.token, scopeOpts(secrets.opts()));
@@ -1485,7 +1497,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.yellow("stdout is a terminal — values redacted. Use: source <(hq secrets env --only KEY1,KEY2)"));
             }
             const keys = parseSecretNameList(opts.only);
-            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets env");
+            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets env", secretsCredentialOptions());
             const companyUid = cred.kind === "api-key"
                 ? "__api_key__"
                 : await getEntityUid(cred.token, scopeOpts(secrets.opts()));

package/dist/lib/agent-kit/creds.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Host key + machine-creds file handling for external agents.
+ *
+ * The private key and the creds file are the whole credential: a stolen
+ * creds file without the key mints nothing (hq-cloud signs every mint with
+ * the key), so both are written 0600 and never printed. Nothing in this
+ * module reads `~/.hq/cognito-tokens.json` — a human's session is never
+ * consulted, copied, or reused by an agent identity (policy
+ * never-extract-stored-session-tokens-to-forge-privileged-calls).
+ */
+import type { AgentKitPaths, KitComponent } from "./paths.js";
+/** Exact `machine-creds.json` shape for an external agent (api-contract v1). */
+export interface ExternalMachineCreds {
+    username: string;
+    secret: string;
+    /** Cognito user pool the machine user lives in (informational for the host). */
+    userPoolId?: string;
+    clientId: string;
+    region: string;
+    entityType: "agent";
+    entityUid: string;
+    runtime: "external";
+    hostKeyPath: string;
+    companySlug: string;
+    apiBaseUrl: string;
+}
+export interface HostKeyPair {
+    privatePem: string;
+    publicPem: string;
+    /** SHA-256 of the DER (SPKI) public key, hex, first 16 chars. */
+    fingerprint: string;
+}
+/** Contract fingerprint: sha256(DER SPKI public key) hex, first 16 chars. */
+export declare function hostFingerprint(publicPem: string): string;
+export declare function generateHostKeyPair(): HostKeyPair;
+export declare function writeHostKeyPair(paths: Pick<AgentKitPaths, "hostKeyPath" | "hostKeyPubPath">, pair: HostKeyPair): void;
+export declare function writeMachineCreds(paths: Pick<AgentKitPaths, "machineCredsPath">, creds: ExternalMachineCreds): void;
+/**
+ * Read the creds file without trusting it: returns null unless it is an
+ * external-agent file with every contract field present.
+ */
+export declare function readExternalMachineCreds(paths: Pick<AgentKitPaths, "machineCredsPath">): ExternalMachineCreds | null;
+/** Whether ANY machine-creds file exists (external or hosted) at the kit path. */
+export declare function machineCredsFileExists(paths: Pick<AgentKitPaths, "machineCredsPath">): boolean;
+/**
+ * Component health stamp the kit services write and the heartbeat reads:
+ * `<status> <iso8601>` — same line shape as the hosted box's component files.
+ */
+export type ComponentStatus = "ok" | "error";
+export declare function writeComponentStatus(paths: Pick<AgentKitPaths, "stateDir">, component: KitComponent, status: ComponentStatus, now?: () => Date): void;
+export interface ComponentReading {
+    status: ComponentStatus;
+    at: Date | null;
+}
+/**
+ * Read a component stamp. A missing file, an unparseable line, or a stamp
+ * older than `staleAfterMs` reads as `error` — silence is never health.
+ */
+export declare function readComponentStatus(paths: Pick<AgentKitPaths, "stateDir">, component: KitComponent, staleAfterMs: number, now?: () => Date): ComponentReading;
+//# sourceMappingURL=creds.d.ts.map

package/dist/lib/agent-kit/creds.js

@@ -0,0 +1,123 @@
+/**
+ * Host key + machine-creds file handling for external agents.
+ *
+ * The private key and the creds file are the whole credential: a stolen
+ * creds file without the key mints nothing (hq-cloud signs every mint with
+ * the key), so both are written 0600 and never printed. Nothing in this
+ * module reads `~/.hq/cognito-tokens.json` — a human's session is never
+ * consulted, copied, or reused by an agent identity (policy
+ * never-extract-stored-session-tokens-to-forge-privileged-calls).
+ */
+import { createHash, createPublicKey, generateKeyPairSync } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { componentStatePath } from "./paths.js";
+/** Contract fingerprint: sha256(DER SPKI public key) hex, first 16 chars. */
+export function hostFingerprint(publicPem) {
+    const der = createPublicKey(publicPem).export({ type: "spki", format: "der" });
+    return createHash("sha256").update(der).digest("hex").slice(0, 16);
+}
+export function generateHostKeyPair() {
+    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+    const privatePem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+    const publicPem = publicKey.export({ type: "spki", format: "pem" }).toString();
+    return { privatePem, publicPem, fingerprint: hostFingerprint(publicPem) };
+}
+/** Write a file atomically with the given mode, replacing any existing one. */
+function writePrivateFile(dest, contents, mode) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+    const tmp = `${dest}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, contents, { mode });
+    fs.chmodSync(tmp, mode);
+    fs.renameSync(tmp, dest);
+}
+export function writeHostKeyPair(paths, pair) {
+    writePrivateFile(paths.hostKeyPath, pair.privatePem, 0o600);
+    writePrivateFile(paths.hostKeyPubPath, pair.publicPem, 0o644);
+}
+export function writeMachineCreds(paths, creds) {
+    writePrivateFile(paths.machineCredsPath, `${JSON.stringify(creds, null, 2)}\n`, 0o600);
+}
+/**
+ * Read the creds file without trusting it: returns null unless it is an
+ * external-agent file with every contract field present.
+ */
+export function readExternalMachineCreds(paths) {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(paths.machineCredsPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const str = (k) => typeof r[k] === "string" && r[k].length > 0 ? r[k] : null;
+    const username = str("username");
+    const secret = str("secret");
+    const clientId = str("clientId");
+    const region = str("region");
+    const entityUid = str("entityUid");
+    const userPoolId = str("userPoolId");
+    const hostKeyPath = str("hostKeyPath");
+    const companySlug = str("companySlug");
+    const apiBaseUrl = str("apiBaseUrl");
+    if (r.runtime !== "external" ||
+        r.entityType !== "agent" ||
+        !username ||
+        !secret ||
+        !clientId ||
+        !region ||
+        !entityUid ||
+        !entityUid.startsWith("agt_") ||
+        !hostKeyPath ||
+        !companySlug ||
+        !apiBaseUrl) {
+        return null;
+    }
+    return {
+        username,
+        secret,
+        ...(userPoolId ? { userPoolId } : {}),
+        clientId,
+        region,
+        entityType: "agent",
+        entityUid,
+        runtime: "external",
+        hostKeyPath,
+        companySlug,
+        apiBaseUrl,
+    };
+}
+/** Whether ANY machine-creds file exists (external or hosted) at the kit path. */
+export function machineCredsFileExists(paths) {
+    return fs.existsSync(paths.machineCredsPath);
+}
+export function writeComponentStatus(paths, component, status, now = () => new Date()) {
+    fs.mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(componentStatePath(paths, component), `${status} ${now().toISOString()}\n`, { mode: 0o600 });
+}
+/**
+ * Read a component stamp. A missing file, an unparseable line, or a stamp
+ * older than `staleAfterMs` reads as `error` — silence is never health.
+ */
+export function readComponentStatus(paths, component, staleAfterMs, now = () => new Date()) {
+    let line;
+    try {
+        line = fs.readFileSync(componentStatePath(paths, component), "utf8").trim();
+    }
+    catch {
+        return { status: "error", at: null };
+    }
+    const [status, iso] = line.split(/\s+/, 2);
+    const at = iso ? new Date(iso) : null;
+    if (status !== "ok" || !at || Number.isNaN(at.getTime())) {
+        return { status: "error", at: at && !Number.isNaN(at.getTime()) ? at : null };
+    }
+    if (now().getTime() - at.getTime() > staleAfterMs) {
+        return { status: "error", at };
+    }
+    return { status: "ok", at };
+}
+//# sourceMappingURL=creds.js.map

package/dist/lib/agent-kit/kit-config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ~/.hq-agent/kit.json — settings `hq agent kit install` records so the
+ * services (which only receive `hq agent kit run <service>`) know where to
+ * sync and how often. Kept separate from machine-creds.json, which is the
+ * contract-shaped credential file and nothing else.
+ */
+import type { AgentKitPaths } from "./paths.js";
+export declare const DEFAULT_SYNC_INTERVAL_MS: number;
+export declare const DEFAULT_INBOX_POLL_MS = 15000;
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+export declare const DEFAULT_MESH_REFRESH_MS: number;
+export interface KitConfig {
+    /** Local HQ tree the company vault syncs into (companies/<slug>/ …). */
+    hqRoot: string;
+    syncIntervalMs: number;
+    inboxPollMs: number;
+    heartbeatIntervalMs: number;
+    meshRefreshMs: number;
+    /** Ack mirrored inbox items on the server after writing them locally. */
+    inboxAck: boolean;
+    installedAt: string;
+    cliVersion: string;
+}
+export declare function defaultHqRoot(paths: Pick<AgentKitPaths, "agentDir">): string;
+export declare function defaultKitConfig(paths: Pick<AgentKitPaths, "agentDir">, cliVersion: string, now?: () => Date): KitConfig;
+export declare function writeKitConfig(paths: Pick<AgentKitPaths, "kitConfigPath">, config: KitConfig): void;
+/** Read kit.json, falling back to defaults for any missing/invalid field. */
+export declare function readKitConfig(paths: Pick<AgentKitPaths, "kitConfigPath" | "agentDir">, cliVersion: string): KitConfig;
+//# sourceMappingURL=kit-config.d.ts.map

package/dist/lib/agent-kit/kit-config.js

@@ -0,0 +1,54 @@
+/**
+ * ~/.hq-agent/kit.json — settings `hq agent kit install` records so the
+ * services (which only receive `hq agent kit run <service>`) know where to
+ * sync and how often. Kept separate from machine-creds.json, which is the
+ * contract-shaped credential file and nothing else.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const DEFAULT_SYNC_INTERVAL_MS = 5 * 60_000;
+export const DEFAULT_INBOX_POLL_MS = 15_000;
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 60_000;
+export const DEFAULT_MESH_REFRESH_MS = 5 * 60_000;
+export function defaultHqRoot(paths) {
+    return path.join(paths.agentDir, "hq");
+}
+export function defaultKitConfig(paths, cliVersion, now = () => new Date()) {
+    return {
+        hqRoot: defaultHqRoot(paths),
+        syncIntervalMs: DEFAULT_SYNC_INTERVAL_MS,
+        inboxPollMs: DEFAULT_INBOX_POLL_MS,
+        heartbeatIntervalMs: DEFAULT_HEARTBEAT_INTERVAL_MS,
+        meshRefreshMs: DEFAULT_MESH_REFRESH_MS,
+        inboxAck: false,
+        installedAt: now().toISOString(),
+        cliVersion,
+    };
+}
+export function writeKitConfig(paths, config) {
+    fs.mkdirSync(path.dirname(paths.kitConfigPath), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(paths.kitConfigPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+/** Read kit.json, falling back to defaults for any missing/invalid field. */
+export function readKitConfig(paths, cliVersion) {
+    const base = defaultKitConfig(paths, cliVersion);
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(paths.kitConfigPath, "utf8"));
+    }
+    catch {
+        return base;
+    }
+    const num = (k) => typeof raw[k] === "number" && raw[k] > 0 ? raw[k] : base[k];
+    return {
+        hqRoot: typeof raw.hqRoot === "string" && raw.hqRoot ? raw.hqRoot : base.hqRoot,
+        syncIntervalMs: num("syncIntervalMs"),
+        inboxPollMs: num("inboxPollMs"),
+        heartbeatIntervalMs: num("heartbeatIntervalMs"),
+        meshRefreshMs: num("meshRefreshMs"),
+        inboxAck: raw.inboxAck === true,
+        installedAt: typeof raw.installedAt === "string" ? raw.installedAt : base.installedAt,
+        cliVersion: typeof raw.cliVersion === "string" ? raw.cliVersion : base.cliVersion,
+    };
+}
+//# sourceMappingURL=kit-config.js.map