@indigoai-us/hq-cli 5.245.0 → 5.247.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## [Unreleased]
 
+## [5.247.0] — 2026-09-27
+### Changed
+
+- The default-off `lanes.supersession-lineage-aware` flag lets a worker's lane
+  keep-alive and message delivery continue when its newer lane senior or a
+  same-profile sibling under that senior would otherwise look like a replacement.
+- Keep-alive setup reads lineage settings before provider locks, and message
+  eligibility rechecks lane and retirement state after that read.
+
+### Changed
+
+- `hq agent kit install` no longer implies the `@reboot` crontab entry is
+  enough on its own. The entry is installed and does restart the kit on an
+  ordinary host, but on a container whose root filesystem is rebuilt each boot
+  both cron and the CLI are erased along with it. The line now says so and
+  says what to do instead.
+
+## [5.246.0] — 2026-09-27
+
+### Fixed
+
+- Every file the agent kit writes now works on storage that has no file
+  permissions. A bot whose agent home is a CIFS/SMB share (Azure Files) gets
+  EPERM from `chmod`, and the writes were hitting that one at a time: the wake
+  config could not be saved, so the bot could never be told mail had arrived,
+  and any message carrying an attachment failed on download. All of them now
+  go through one writer that asks for owner-only permissions, reports whether
+  they actually took, and carries on either way. The same writer makes those
+  writes atomic, so the inbox mirror, the seen/handled id lists, the kit
+  config, the heartbeat record and saved attachments can no longer be read
+  half-written by a concurrent poller. A chmod refused for any reason other
+  than a missing capability is still a real error.
+- Picks up hq-cloud 6.18.10, which publishes the token refresh lock without
+  hard links so a bot on a network share can mint a token at all.
+
 ## [5.245.0] — 2026-09-27
 
 ### Fixed

package/dist/command-catalog.generated.d.ts

@@ -4669,7 +4669,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "exec";
-        readonly description: "Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command). Default is synchronous (API Gateway ~20s cap). Use --async for long jobs, or --detach to print the commandId and return immediately.";
+        readonly description: "Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command). The command waits for the submitted job to finish. Use --wait-timeout-seconds to bound local waiting, or --detach to print the commandId and return immediately.";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly usage: "[options] <command...>";
@@ -4692,7 +4692,10 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "Submit via the async transport, print commandId, and return immediately (pair with `hq outposts exec-result --wait`)";
         }, {
             readonly flags: "--timeout-seconds <n>";
-            readonly description: "Async shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800). Implies --async unless --detach is set.";
+            readonly description: "Remote shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800)";
+        }, {
+            readonly flags: "--wait-timeout-seconds <n>";
+            readonly description: "Maximum time this client waits for the command result (1..172800; default: 1800)";
         }, {
             readonly flags: "--json";
             readonly description: "Emit raw JSON";

package/dist/command-catalog.generated.js

@@ -6036,7 +6036,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "exec",
-                "description": "Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command). Default is synchronous (API Gateway ~20s cap). Use --async for long jobs, or --detach to print the commandId and return immediately.",
+                "description": "Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command). The command waits for the submitted job to finish. Use --wait-timeout-seconds to bound local waiting, or --detach to print the commandId and return immediately.",
                 "aliases": [],
                 "hidden": false,
                 "usage": "[options] <command...>",
@@ -6066,7 +6066,11 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--timeout-seconds <n>",
-                        "description": "Async shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800). Implies --async unless --detach is set."
+                        "description": "Remote shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800)"
+                    },
+                    {
+                        "flags": "--wait-timeout-seconds <n>",
+                        "description": "Maximum time this client waits for the command result (1..172800; default: 1800)"
                     },
                     {
                         "flags": "--json",

package/dist/commands/agent-kit.js

@@ -279,6 +279,10 @@ export function registerAgentKitCommand(agent) {
                 console.log(`  kit log:   ${result.fallback.logPath}`);
                 if (result.fallback.reboot.installed) {
                     console.log(chalk.green("  reboot:    a @reboot crontab entry was installed, so the kit restarts with the host"));
+                    console.log(chalk.dim("             That holds only if cron and this CLI survive the restart. On a container " +
+                        "whose root filesystem is rebuilt each boot, both are erased and the entry goes with " +
+                        "them — reinstall the kit from your persistent storage after a restart, or have your " +
+                        "platform start `hq agent kit run all` for you."));
                 }
                 else {
                     console.log(chalk.red(`  reboot:    NOT protected — ${result.fallback.reboot.reason}. Until this is fixed the kit ` +

package/dist/commands/lanes.js

@@ -46,7 +46,7 @@ import { effectiveAccountHome } from "../lib/lanes/account-home.js";
 import { AccountResolutionError, compareLaneQueueOrder, coveredLaneIds, LANE_PROVIDERS, LANE_STATES, QUESTION_STATUSES, SENIOR_KINDS, accountStatus, appendCappedHistory, canonicalizeHome, createLane, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, aliveDirectChildren, assignedChildHireGrants, hireGrantCapacityError, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, laneStoryLedgerEnabled, validateProjectStories, buildLaneStatusSnapshot, formatLaneStatusHuman, listLaneIds, listQuestionIds, loadLanesConfig, laneRunsHere, MAX_LANE_DEPTH, MONITOR_ERROR_EXIT_CODE, MONITOR_ENGINES, MONITOR_MAX_TIMEOUT_MS, MONITOR_UNCOVERED_EXIT_CODE, MAX_WATCHED_LANES, monitorReminderText, readLiveMonitorEvidence, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, parseLaneRecord, parseLaneState, parseQuestionRecord, parseSeniorKind, readLane, retryUpdateLane, syncLaneRecordFromOwner, readQuestion, resolveAccount, resolveLaneWorker, ignoredWorkerProfileFields, loadWorkerProfile, loadWorkerProfileWithRegistry, registryWorkerRecord, runReconcilePass, runLaneWatch, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, appendDropboxMessage, deliveryRefusalReason, resumeCommandRefusal, dropboxDir, dropboxInboxPath, laneAcceptsOperatorMessage, laneDeliveryMechanism, hasActiveAdmissionReservation, hasActivePendingResume, hasRecordedSessionId, hasEarlierEligibleQueuedLane, laneAdmissionCapReason, providerSupportsSessionResume, providerSessionPortable, sessionNotPortableMessage, withLaneAdmissionLock, withAllLaneAdmissionLocks, withLaneHireLocks, operatorMessageRefusalReason, raiseLaneQuestion, sha256Text, } from "../lib/lanes/index.js";
 import { activeLaneStories, laneStories, laneStory, storyWarning, } from "../lib/lanes/stories.js";
 import { resolveLaneKeepAlive } from "../lib/lanes/profile.js";
-import { keepAliveExclusion, LEAD_LANE_KEEP_ALIVE_FLAG, loadRetiredLaneIds, } from "../lib/lanes/keep-alive.js";
+import { keepAliveExclusion, LEAD_LANE_KEEP_ALIVE_FLAG, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, loadRetiredLaneIds, } from "../lib/lanes/keep-alive.js";
 import { questionBodyAbsPath, resolveQuestionCompanyWithFallback, resolveProjectQuestionCompany, } from "../lib/lanes/questions.js";
 import { assertQuestionBodySecretSafe } from "../lib/lanes/questions.js";
 import { compactionAfterUsage, } from "../lib/lanes/compaction.js";
@@ -4891,21 +4891,22 @@ async function runKeepAlive(ctx, laneId, opts) {
         throw new LanesError("keep_alive_mode_invalid", "Pass exactly one of --on or --off", { lane_id: laneId });
     }
     const hqRoot = ctx.hqRoot();
+    let lineageAware = false;
+    if (opts.on) {
+        const initialLane = readLane(hqRoot, laneId);
+        assertKeepAliveChangeAllowed(ctx, initialLane, laneId);
+        lineageAware = await readLanesRegistryFlag(LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, {
+            company: initialLane.company,
+            env: ctx.env,
+        });
+    }
     const updated = await withAllLaneAdmissionLocks(hqRoot, async () => {
         const lane = readLane(hqRoot, laneId);
-        if (!callerMatchesSenior(ctx, lane.senior)) {
-            throw new LanesError("keep_alive_unauthorized", `Only senior ${seniorKey(lane.senior)} may change lane ${laneId}'s keep-alive setting`, { lane_id: laneId, senior: lane.senior });
-        }
-        if (!laneRunsHere(lane, reconcileHostFromCtx(ctx))) {
-            throw new LanesError("keep_alive_owner_host_required", `Run hq lanes keep-alive ${laneId} on its owner host ${lane.host.kind}:${lane.host.id}`, { lane_id: laneId, host: lane.host });
-        }
-        if (lane.state === "killed" || lane.state === "cancelled" || lane.state === "failed") {
-            throw new LanesError("keep_alive_terminal_lane", `Cannot change keep-alive for lane ${laneId} in terminal state ${lane.state}`, { lane_id: laneId, state: lane.state });
-        }
+        assertKeepAliveChangeAllowed(ctx, lane, laneId);
         let optedInAt;
         if (opts.on) {
             const retiredLaneIds = loadRetiredLaneIds(hqRoot);
-            const exclusion = keepAliveExclusion(lane, loadAllLanes(hqRoot), retiredLaneIds);
+            const exclusion = keepAliveExclusion(lane, loadAllLanes(hqRoot), retiredLaneIds, lineageAware);
             if (exclusion !== undefined) {
                 throw new LanesError("keep_alive_lane_excluded", `Cannot opt in lane ${laneId}: it is ${exclusion}`, { lane_id: laneId, blocked_reason: exclusion });
             }
@@ -4926,6 +4927,17 @@ async function runKeepAlive(ctx, laneId, opts) {
         lane: updated,
     });
 }
+function assertKeepAliveChangeAllowed(ctx, lane, laneId) {
+    if (!callerMatchesSenior(ctx, lane.senior)) {
+        throw new LanesError("keep_alive_unauthorized", "Only senior " + seniorKey(lane.senior) + " may change lane " + laneId + "'s keep-alive setting", { lane_id: laneId, senior: lane.senior });
+    }
+    if (!laneRunsHere(lane, reconcileHostFromCtx(ctx))) {
+        throw new LanesError("keep_alive_owner_host_required", "Run hq lanes keep-alive " + laneId + " on its owner host " + lane.host.kind + ":" + lane.host.id, { lane_id: laneId, host: lane.host });
+    }
+    if (lane.state === "killed" || lane.state === "cancelled" || lane.state === "failed") {
+        throw new LanesError("keep_alive_terminal_lane", "Cannot change keep-alive for lane " + laneId + " in terminal state " + lane.state, { lane_id: laneId, state: lane.state });
+    }
+}
 async function runGrant(ctx, laneId, opts) {
     if (opts.hire === undefined) {
         throw new LanesError("missing_hire_grant", "--hire is required", {});
@@ -5808,7 +5820,9 @@ async function runMessage(ctx, laneId, opts) {
         }
     }
     try {
-        const exclusion = messageLaneExclusion(ctx, lane);
+        const eligibility = await messageLaneExclusion(ctx, lane);
+        lane = eligibility.lane;
+        const exclusion = eligibility.exclusion;
         if (exclusion !== undefined) {
             let messageCount;
             if (dropboxInboxHasMessages(hqRoot, laneId)) {
@@ -6183,10 +6197,24 @@ async function runMessage(ctx, laneId, opts) {
         throw err;
     }
 }
-function messageLaneExclusion(ctx, lane) {
-    if (lane.state === "killed" || lane.state === "cancelled")
-        return lane.state;
-    return keepAliveExclusion(lane, loadAllLanes(ctx.hqRoot()), loadRetiredLaneIds(ctx.hqRoot()));
+async function messageLaneExclusion(ctx, lane) {
+    if (lane.state === "killed" || lane.state === "cancelled") {
+        return { lane, exclusion: lane.state };
+    }
+    const lineageAware = await readLanesRegistryFlag(LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, {
+        company: lane.company,
+        env: ctx.env,
+    });
+    const currentLane = readLane(ctx.hqRoot(), lane.lane_id);
+    if (currentLane.state === "killed" || currentLane.state === "cancelled") {
+        return { lane: currentLane, exclusion: currentLane.state };
+    }
+    const lanes = loadAllLanes(ctx.hqRoot());
+    const retiredLaneIds = loadRetiredLaneIds(ctx.hqRoot());
+    return {
+        lane: currentLane,
+        exclusion: keepAliveExclusion(currentLane, lanes, retiredLaneIds, lineageAware),
+    };
 }
 function recordMessageUndeliverable(ctx, lane, reason, messageCount) {
     writeWatcherDecision(watcherOutLogPath(ctx.hqRoot(), lane.lane_id), {
@@ -6206,10 +6234,12 @@ function recordMessageUndeliverable(ctx, lane, reason, messageCount) {
  */
 async function recoverQueuedMessages(ctx, laneId) {
     const hqRoot = ctx.hqRoot();
-    const lane = readLane(hqRoot, laneId);
+    let lane = readLane(hqRoot, laneId);
     if (!dropboxInboxHasMessages(hqRoot, laneId))
         return { action: "none", message_count: 0 };
-    const exclusion = messageLaneExclusion(ctx, lane);
+    const eligibility = await messageLaneExclusion(ctx, lane);
+    lane = eligibility.lane;
+    const exclusion = eligibility.exclusion;
     const refusal = exclusion ?? (lane.state === "done"
         ? "done_before_envelope"
         : lane.state === "awaiting_input"

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

@@ -25,6 +25,7 @@
  * would only have moved it somewhere it silently disappears.
  */
 import type { AgentKitPaths, KitComponent } from "./paths.js";
+import { type PrivateFileOutcome } from "./private-file.js";
 /** Exact `machine-creds.json` shape for an external agent (api-contract v1). */
 export interface ExternalMachineCreds {
     username: string;
@@ -49,18 +50,7 @@ export interface HostKeyPair {
 /** Contract fingerprint: sha256(DER SPKI public key) hex, first 16 chars. */
 export declare function hostFingerprint(publicPem: string): string;
 export declare function generateHostKeyPair(): HostKeyPair;
-/**
- * What a write could actually guarantee about who can read the file.
- * `enforced: false` means the bytes are on disk but readable beyond the
- * owner — true of a share mounted with a fixed `file_mode`.
- */
-export interface PrivateFileOutcome {
-    enforced: boolean;
-    /** Mode observed after the write, when it could be read back. */
-    observedMode?: number;
-    /** errno of a refused chmod (EPERM on Azure Files), when there was one. */
-    chmodError?: string;
-}
+export type { PrivateFileOutcome } from "./private-file.js";
 export declare function writeHostKeyPair(paths: Pick<AgentKitPaths, "hostKeyPath" | "hostKeyPubPath">, pair: HostKeyPair): PrivateFileOutcome;
 export declare function writeMachineCreds(paths: Pick<AgentKitPaths, "machineCredsPath">, creds: ExternalMachineCreds): PrivateFileOutcome;
 /**

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

@@ -26,8 +26,8 @@
  */
 import { createHash, createPublicKey, generateKeyPairSync } from "node:crypto";
 import * as fs from "node:fs";
-import * as path from "node:path";
 import { componentStatePath } from "./paths.js";
+import { writePrivateFile, } from "./private-file.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" });
@@ -39,65 +39,6 @@ export function generateHostKeyPair() {
     const publicPem = publicKey.export({ type: "spki", format: "pem" }).toString();
     return { privatePem, publicPem, fingerprint: hostFingerprint(publicPem) };
 }
-/**
- * chmod failures that mean "this filesystem does not do modes" rather than
- * "something is wrong". Anything else still throws: a refused chmod on a
- * local disk is a real fault and must not be swallowed.
- */
-const MODE_UNSUPPORTED_CODES = new Set([
-    "EPERM",
-    "EACCES",
-    "EINVAL",
-    "ENOTSUP",
-    "EOPNOTSUPP",
-]);
-/** 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 });
-    // Date.now() as well as the pid: two writes from one process must not
-    // collide on a temp name, and a leftover from a crashed run must not be
-    // adopted by the next one.
-    const tmp = `${dest}.tmp.${process.pid}.${Date.now()}`;
-    let chmodError;
-    try {
-        fs.writeFileSync(tmp, contents, { mode });
-        try {
-            fs.chmodSync(tmp, mode);
-        }
-        catch (err) {
-            const code = err.code ?? "";
-            if (!MODE_UNSUPPORTED_CODES.has(code))
-                throw err;
-            chmodError = code;
-        }
-        // Read the truth back rather than trusting either call: a mount can
-        // accept chmod and ignore it just as easily as it can refuse.
-        let observedMode;
-        try {
-            observedMode = fs.statSync(tmp).mode & 0o777;
-        }
-        catch {
-            /* stat is not worth failing a write over */
-        }
-        fs.renameSync(tmp, dest);
-        return {
-            enforced: observedMode === undefined ? !chmodError : (observedMode & 0o077) === 0,
-            ...(observedMode === undefined ? {} : { observedMode }),
-            ...(chmodError ? { chmodError } : {}),
-        };
-    }
-    catch (err) {
-        // Never leave the temp file behind — it holds the same secret as the
-        // file that failed to land.
-        try {
-            fs.unlinkSync(tmp);
-        }
-        catch {
-            /* already gone */
-        }
-        throw err;
-    }
-}
 export function writeHostKeyPair(paths, pair) {
     const key = writePrivateFile(paths.hostKeyPath, pair.privatePem, 0o600);
     // The public half is public; its mode is not a promise worth reporting.

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

@@ -11,6 +11,7 @@ import { spawn, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { kitServiceEnv } from "./services.js";
+import { writePrivateFile } from "./private-file.js";
 export const KIT_PID_NAME = "kit.pid";
 export const KIT_FALLBACK_LOG_NAME = "kit.log";
 export function kitPidPath(paths) {
@@ -119,7 +120,7 @@ export function startFallback(paths, host, deps = {}) {
         if (!child.pid)
             throw new Error(`could not start ${cmd} ${args.join(" ")}`);
         child.unref();
-        fs.writeFileSync(kitPidPath(paths), `${child.pid}\n`, { mode: 0o600 });
+        writePrivateFile(kitPidPath(paths), `${child.pid}\n`, 0o600);
         return { pid: child.pid, logPath, pidFile: kitPidPath(paths) };
     }
     finally {

package/dist/lib/agent-kit/inbox-state.js

@@ -10,6 +10,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { writePrivateFile } from "./private-file.js";
 export const DONE_IDS_NAME = "done-ids.json";
 export const MAX_DONE_IDS = 5000;
 const INBOX_JSONL = "inbox.jsonl";
@@ -31,8 +32,7 @@ export function markInboxDone(paths, ids) {
             added.push(id);
         }
     }
-    fs.mkdirSync(paths.inboxDir, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(path.join(paths.inboxDir, DONE_IDS_NAME), JSON.stringify([...done].slice(-MAX_DONE_IDS)), { mode: 0o600 });
+    writePrivateFile(path.join(paths.inboxDir, DONE_IDS_NAME), JSON.stringify([...done].slice(-MAX_DONE_IDS)), 0o600);
     return added;
 }
 /** Every mirrored entry, oldest first, de-duplicated by id (last write wins). */

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

@@ -7,6 +7,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { KIT_COMPONENTS } from "./paths.js";
+import { writePrivateFile } from "./private-file.js";
 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;
@@ -36,8 +37,7 @@ export function defaultKitConfig(paths, cliVersion, now = () => new Date()) {
     };
 }
 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 });
+    writePrivateFile(paths.kitConfigPath, `${JSON.stringify(config, null, 2)}\n`, 0o600);
 }
 /** Read kit.json, falling back to defaults for any missing/invalid field. */
 export function readKitConfig(paths, cliVersion) {

package/dist/lib/agent-kit/mcp/attachments.js

@@ -32,9 +32,9 @@
  * with a sanitized name, so nothing from the message can pick the location.
  */
 import { createHash } from "node:crypto";
-import * as fs from "node:fs";
 import * as path from "node:path";
 import { McpToolInputError } from "./jsonrpc.js";
+import { mkdirPrivate, writePrivateFile } from "../private-file.js";
 /**
  * Refuse anything larger than this. Chat uploads are capped at 25 MB
  * (MAX_CHAT_ATTACHMENT_BYTES in hq-desktop-app); 26 MiB leaves a little
@@ -147,27 +147,15 @@ export async function saveAttachment(input) {
     }
     const name = sanitizeAttachmentFileName(input.name || key.split("/").pop() || "file");
     const dir = path.join(attachmentsDir, sanitizeAttachmentFileName(scopeUid));
-    for (const d of [attachmentsDir, dir]) {
-        fs.mkdirSync(d, { recursive: true, mode: 0o700 });
-        fs.chmodSync(d, 0o700);
-    }
+    for (const d of [attachmentsDir, dir])
+        mkdirPrivate(d);
     // A short digest of scope+key keeps two same-named files apart and makes a
     // re-fetch of the same attachment overwrite rather than pile up.
     const digest = createHash("sha256").update(`${scopeUid}\0${key}`).digest("hex").slice(0, 12);
     const localPath = path.join(dir, `${digest}-${name}`);
     if (path.dirname(localPath) !== dir)
         throw new Error("refusing to write outside the attachments directory");
-    const tmp = `${localPath}.${process.pid}.tmp`;
-    try {
-        fs.writeFileSync(tmp, bytes, { mode: 0o600 });
-        fs.chmodSync(tmp, 0o600);
-        fs.renameSync(tmp, localPath);
-    }
-    catch (err) {
-        // Never leave a partial copy of the attachment behind.
-        fs.rmSync(tmp, { force: true });
-        throw err;
-    }
+    writePrivateFile(localPath, bytes, 0o600);
     const ext = name.split(".").pop()?.toLowerCase() ?? "";
     const text = renderText(bytes, name, input.contentType);
     const note = text !== undefined

package/dist/lib/agent-kit/private-file.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What a write could actually guarantee about who can read the file.
+ * `enforced: false` means the bytes are on disk but readable beyond the
+ * owner — true of a share mounted with a fixed `file_mode`.
+ */
+export interface PrivateFileOutcome {
+    enforced: boolean;
+    /** Mode observed after the write, when it could be read back. */
+    observedMode?: number;
+    /** errno of a refused chmod (EPERM on Azure Files), when there was one. */
+    chmodError?: string;
+}
+/**
+ * chmod failures that mean "this filesystem does not do modes" rather than
+ * "something is wrong". Anything else still throws: a refused chmod on a
+ * local disk is a real fault and must not be swallowed.
+ */
+export declare const MODE_UNSUPPORTED_CODES: Set<string>;
+/** Apply a mode, tolerating filesystems that do not have modes. Returns the errno if refused. */
+export declare function chmodIfSupported(target: string, mode: number): string | undefined;
+/**
+ * Make a directory and try to make it owner-only. The `mode` argument to
+ * mkdir(2) is silently ignored on a share, and the follow-up chmod is refused
+ * there, so neither is allowed to fail the call.
+ */
+export declare function mkdirPrivate(dir: string, mode?: number): void;
+/** Write a file atomically with the given mode, replacing any existing one. */
+export declare function writePrivateFile(dest: string, contents: string | Uint8Array, mode: number): PrivateFileOutcome;
+//# sourceMappingURL=private-file.d.ts.map

package/dist/lib/agent-kit/private-file.js

@@ -0,0 +1,91 @@
+/**
+ * Writing owner-only files on filesystems that may not have owner-only files.
+ *
+ * The agent kit keeps credentials, wake config, and downloaded attachments in
+ * the agent's home directory, and writes all of it 0600/0700. Not every
+ * filesystem can honour that. A CIFS/SMB mount (Azure Files is the one that
+ * found this) is mounted with a fixed `file_mode` and fails `chmod` outright
+ * with EPERM; an NFS export or a Docker volume may accept the call and ignore
+ * it. A bot whose only persistent storage is such a share must still be able
+ * to run — so these helpers write the bytes, ask for the mode, and report
+ * whether the mode actually took instead of dying on the request.
+ *
+ * Every helper here is atomic: bytes land in a temp file in the destination
+ * directory and are renamed into place, so a reader never sees a half-written
+ * file and a failed write never leaves a partial one behind.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * chmod failures that mean "this filesystem does not do modes" rather than
+ * "something is wrong". Anything else still throws: a refused chmod on a
+ * local disk is a real fault and must not be swallowed.
+ */
+export const MODE_UNSUPPORTED_CODES = new Set([
+    "EPERM",
+    "EACCES",
+    "EINVAL",
+    "ENOTSUP",
+    "EOPNOTSUPP",
+]);
+/** Apply a mode, tolerating filesystems that do not have modes. Returns the errno if refused. */
+export function chmodIfSupported(target, mode) {
+    try {
+        fs.chmodSync(target, mode);
+        return undefined;
+    }
+    catch (err) {
+        const code = err.code ?? "";
+        if (!MODE_UNSUPPORTED_CODES.has(code))
+            throw err;
+        return code;
+    }
+}
+/**
+ * Make a directory and try to make it owner-only. The `mode` argument to
+ * mkdir(2) is silently ignored on a share, and the follow-up chmod is refused
+ * there, so neither is allowed to fail the call.
+ */
+export function mkdirPrivate(dir, mode = 0o700) {
+    fs.mkdirSync(dir, { recursive: true, mode });
+    chmodIfSupported(dir, mode);
+}
+/** Write a file atomically with the given mode, replacing any existing one. */
+export function writePrivateFile(dest, contents, mode) {
+    mkdirPrivate(path.dirname(dest));
+    // Date.now() as well as the pid: two writes from one process must not
+    // collide on a temp name, and a leftover from a crashed run must not be
+    // adopted by the next one.
+    const tmp = `${dest}.tmp.${process.pid}.${Date.now()}`;
+    try {
+        fs.writeFileSync(tmp, contents, { mode });
+        const chmodError = chmodIfSupported(tmp, mode);
+        // Read the truth back rather than trusting either call: a mount can
+        // accept chmod and ignore it just as easily as it can refuse.
+        let observedMode;
+        try {
+            observedMode = fs.statSync(tmp).mode & 0o777;
+        }
+        catch {
+            /* stat is not worth failing a write over */
+        }
+        fs.renameSync(tmp, dest);
+        return {
+            enforced: observedMode === undefined ? !chmodError : (observedMode & 0o077) === 0,
+            ...(observedMode === undefined ? {} : { observedMode }),
+            ...(chmodError ? { chmodError } : {}),
+        };
+    }
+    catch (err) {
+        // Never leave the temp file behind — it may hold the same secret as the
+        // file that failed to land.
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            /* already gone */
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=private-file.js.map

package/dist/lib/agent-kit/run/heartbeat.js

@@ -18,6 +18,7 @@ import { captureHeartbeatIdentityMismatch, identityMismatchMessage, isHeartbeatI
 import { vaultApiFetch } from "../../../utils/vault-api.js";
 import { readComponentStatus } from "../creds.js";
 import { KIT_COMPONENTS } from "../paths.js";
+import { writePrivateFile } from "./../private-file.js";
 /** A component stamp older than this reads as error. */
 export const COMPONENT_STALE_AFTER_MS = {
     sync: 3 * 60 * 60_000, // sync passes every 5 min; three hours of silence is real trouble
@@ -40,8 +41,7 @@ export function buildHeartbeatBody(paths, now = () => new Date(), hostInfo, comp
     };
 }
 export function writeLastHeartbeat(paths, record) {
-    fs.mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(paths.lastHeartbeatPath, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+    writePrivateFile(paths.lastHeartbeatPath, `${JSON.stringify(record)}\n`, 0o600);
 }
 export function readLastHeartbeat(paths) {
     try {

package/dist/lib/agent-kit/run/inbox.js

@@ -20,6 +20,7 @@ import * as path from "node:path";
 import { vaultApiFetch } from "../../../utils/vault-api.js";
 import { writeComponentStatus } from "../creds.js";
 import { pendingInbox } from "../inbox-state.js";
+import { writePrivateFile } from "./../private-file.js";
 import { buildWakeNotice, currentWakeState, fireWake, readWakeConfig, shouldWake, } from "../wake.js";
 export const SEEN_IDS_NAME = "seen-ids.json";
 export const INBOX_JSONL_NAME = "inbox.jsonl";
@@ -50,14 +51,12 @@ export function readSeenIds(paths) {
     }
 }
 export function writeSeenIds(paths, seen) {
-    fs.mkdirSync(paths.inboxDir, { recursive: true, mode: 0o700 });
     const list = [...seen].slice(-MAX_SEEN_IDS);
-    fs.writeFileSync(path.join(paths.inboxDir, SEEN_IDS_NAME), JSON.stringify(list), { mode: 0o600 });
+    writePrivateFile(path.join(paths.inboxDir, SEEN_IDS_NAME), JSON.stringify(list), 0o600);
 }
 export function mirrorInboxItem(paths, item) {
-    fs.mkdirSync(paths.inboxDir, { recursive: true, mode: 0o700 });
     const dest = path.join(paths.inboxDir, `${item.id}.json`);
-    fs.writeFileSync(dest, `${JSON.stringify(item.raw, null, 2)}\n`, { mode: 0o600 });
+    writePrivateFile(dest, `${JSON.stringify(item.raw, null, 2)}\n`, 0o600);
     fs.appendFileSync(path.join(paths.inboxDir, INBOX_JSONL_NAME), `${JSON.stringify({ id: item.id, mirroredAt: new Date().toISOString(), ...item.raw })}\n`, { mode: 0o600 });
     return dest;
 }

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

@@ -21,6 +21,7 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { writePrivateFile } from "./private-file.js";
 export const WAKE_FILE_NAME = "wake.json";
 export const WAKE_STATE_NAME = "wake-state.json";
 export const DEFAULT_WAKE_RETRY_MS = 10 * 60_000;
@@ -92,10 +93,10 @@ export function readWakeConfig(paths) {
     return null;
 }
 export function writeWakeConfig(paths, config) {
-    fs.mkdirSync(paths.agentDir, { recursive: true, mode: 0o700 });
-    const file = wakePath(paths);
-    fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
-    fs.chmodSync(file, 0o600);
+    // Owner-only if the filesystem allows it. A bot whose only persistent
+    // storage is a CIFS share cannot have owner-only files at all, and refusing
+    // to write there would mean it could never be woken.
+    writePrivateFile(wakePath(paths), `${JSON.stringify(config, null, 2)}\n`, 0o600);
 }
 export function clearWakeConfig(paths) {
     try {