@cruxy/cli 0.29.0 → 0.29.3

package/dist/agent/budget.d.ts

@@ -0,0 +1,52 @@
+import type { Usage } from "@cruxy/sdk";
+import type { LoopBudget } from "./loop.js";
+/**
+ * The live budget primitive for the agent loop: iteration + token + optional
+ * wall-clock caps, checked by {@link runAgent} before every model turn (see
+ * `LoopBudget`). A tripped cap stops the run with a human-readable reason and
+ * the coherent partial history — the loop never runs unbounded.
+ *
+ * It lives beside the loop it guards: the loop defines the `LoopBudget` seam,
+ * this is its one concrete implementation, and the subagent orchestrator, the
+ * job manager, and {@link Session} (per-turn token guard) all consume it.
+ */
+/**
+ * Hard caps a run executes under. `maxTokens` is always finite; `maxIterations`
+ * is finite for a subagent (bounded by construction) but may be
+ * `Number.POSITIVE_INFINITY` for a token-only guard where iteration count is
+ * bounded elsewhere (a main turn is already capped by `agent.maxIterations` in
+ * the loop). `timeoutMs` is an optional wall-clock backstop on top.
+ */
+export interface BudgetLimits {
+    /** Cap on the run's model turns (may be `Infinity` for a token-only guard). */
+    maxIterations: number;
+    /** Cap on the run's combined input+output tokens. */
+    maxTokens: number;
+    /** Optional wall-clock cap in milliseconds. */
+    timeoutMs?: number;
+}
+/**
+ * Resolve the effective limits for one spawn: start from the configured
+ * ceilings and let overrides only *narrow* them. A request above a ceiling is
+ * clamped down, not honored — "budget overrides within limits" by construction.
+ */
+export declare function resolveBudget(defaults: BudgetLimits, overrides?: Partial<BudgetLimits>): BudgetLimits;
+/**
+ * A live budget for one run. The wall clock starts at construction (spawn /
+ * turn start); the clock source is injectable so tests never sleep.
+ */
+export declare class Budget implements LoopBudget {
+    private readonly limits;
+    private readonly now;
+    private readonly startedAt;
+    constructor(limits: BudgetLimits, now?: () => number);
+    /**
+     * The reason to stop before the next model turn, or `null` to continue.
+     * Checked at iteration boundaries — the in-flight turn always completes, so
+     * overshoot is bounded by one turn.
+     */
+    exceeded(state: {
+        iterations: number;
+        usage: Usage;
+    }): string | null;
+}

package/dist/{subagent → agent}/budget.js

@@ -1,9 +1,3 @@
-/**
- * The subagent budget (C.14): iteration + token + optional wall-clock caps,
- * checked by the agent loop before every model turn (see `LoopBudget`). A
- * tripped cap stops the run with a human-readable reason — the subagent
- * returns a partial result, it never runs unbounded.
- */
 /**
  * Resolve the effective limits for one spawn: start from the configured
  * ceilings and let overrides only *narrow* them. A request above a ceiling is
@@ -23,8 +17,8 @@ export function resolveBudget(defaults, overrides) {
     };
 }
 /**
- * A live budget for one subagent run. The wall clock starts at construction
- * (spawn time); the clock source is injectable so tests never sleep.
+ * A live budget for one run. The wall clock starts at construction (spawn /
+ * turn start); the clock source is injectable so tests never sleep.
  */
 export class Budget {
     limits;

package/dist/agent/loop.d.ts

@@ -103,6 +103,21 @@ export interface RunAgentArgs {
      * is kill-tree'd rather than orphaned.
      */
     signal?: AbortSignal;
+    /**
+     * Mid-loop compaction seam (build item 3). Called at the top of every
+     * iteration with the running history; returns the history to continue from —
+     * unchanged when under threshold, or with its older prefix summarized away
+     * when over. Supplied by {@link Session}, which reuses its own
+     * threshold/cut/summarize machinery, so the loop gains no summarization
+     * knowledge and no logic is duplicated. Omitted → history is never compacted
+     * mid-loop (unchanged behavior; subagents pass nothing).
+     *
+     * This is what keeps a long autonomous turn — where `send` compacts only once
+     * up front and never again — within the context window: without it a run that
+     * drives dozens of tool calls (each result appended, some tens of KB) grows
+     * unbounded until the next `send`, which in one-shot never comes.
+     */
+    compact?: (messages: Message[]) => Promise<Message[]>;
 }
 /**
  * The budget seam for {@link runAgent}: implementations track their own caps

package/dist/agent/loop.js

@@ -40,8 +40,9 @@ async function driveLoop(args, renderer, routed) {
     const { provider, registry, config, ctx } = args;
     const { logger } = ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the
-    // extended history is returned for the caller to adopt.
-    const messages = [...args.messages];
+    // extended history is returned for the caller to adopt. Reassigned wholesale
+    // when the mid-loop compaction seam folds away an older prefix.
+    let messages = [...args.messages];
     const usage = { input_tokens: 0, output_tokens: 0 };
     const maxIterations = config.agent.maxIterations;
     // The tool catalogue and environment are stable across the loop, so build the
@@ -88,6 +89,14 @@ async function driveLoop(args, renderer, routed) {
                 usage,
             };
         }
+        // Mid-loop compaction (build item 3), after the abort/budget checks so a
+        // cancelled or over-budget run never spends a summary call: fold away the
+        // older prefix when the history has grown past threshold *this* iteration.
+        // The seam preserves tool_use/tool_result integrity (it only cuts at a
+        // completed turn boundary), so adopting its result mid-turn is safe.
+        if (args.compact) {
+            messages = await args.compact(messages);
+        }
         iterations = i + 1;
         const tools = registry.toToolSpecs();
         // ── Consume one model turn ──────────────────────────────────────────────

package/dist/agent/session.d.ts

@@ -145,23 +145,46 @@ export declare class Session {
     /** Drop the conversation history but keep the session (for `/clear`). */
     clear(): void;
     /**
-     * Compact only when the estimated history exceeds
-     * `compactThreshold * maxTokens`. On success logs a one-line notice and
-     * returns the number of older messages folded into the summary; otherwise
-     * returns `null` (under threshold, nothing safe to cut, or summary failed).
+     * Compact `this.messages` only when it has grown past threshold, adopting the
+     * result. On success logs a one-line notice and returns the number of older
+     * messages folded into the summary; otherwise returns `null` (under threshold,
+     * nothing safe to cut, or summary failed).
      */
     maybeCompact(onRequestUsage?: (req: RequestUsage) => void): Promise<number | null>;
+    /**
+     * The mid-loop compaction seam (build item 3) handed to {@link runAgent}: same
+     * threshold/cut/summarize path as {@link maybeCompact}, but over the loop's own
+     * running history rather than `this.messages` (the loop owns and adopts its
+     * copy). Reuses the exact machinery so no summarization logic is duplicated and
+     * the loop stays ignorant of it. Under threshold it returns the history
+     * unchanged — cheap, no model call.
+     */
+    private compactLoopHistory;
     /**
      * Force compaction regardless of the threshold (backs `/compact`). Returns the
      * number of older messages summarized, or `null` if there was nothing safe to
      * cut or the summary call failed.
      */
     compact(): Promise<number | null>;
+    /**
+     * Compact `messages` when its estimated footprint exceeds
+     * `compactThreshold * maxTokens`, else return it untouched. The estimate adds a
+     * fixed `reserveTokens` allowance for the system prompt and tool schemas that
+     * {@link estimateTokens} never sees (~4.5k+ tokens of real request payload), so
+     * the trigger reflects the actual request size rather than only the visible
+     * history — otherwise the loop can sit just under the visible threshold while
+     * the real request has already overrun the window. Logs a one-line notice on a
+     * successful compaction.
+     */
+    private compactIfOverThreshold;
     /**
      * Find a clean cut, summarize the older prefix into a synthetic user/assistant
      * pair, and splice it in front of the kept-recent messages. Best-effort: a
-     * failed summary call leaves the history untouched and returns `null` (fail
-     * open — losing compaction is degraded, not unsafe).
+     * failed summary call leaves the history untouched and reports `compacted:
+     * null` (fail open — losing compaction is degraded, not unsafe). Pure with
+     * respect to `this.messages`: it returns the new array for the caller to adopt
+     * (the loop and the session each own their own history), and only accumulates
+     * the summary's usage into the session total.
      */
     private runCompaction;
     /**
@@ -171,7 +194,9 @@ export declare class Session {
      * matching `tool_result` (the next user message) must never straddle the cut,
      * or the next provider call breaks. A real user *prompt* (`role:"user"` with
      * string content) only occurs at a completed turn boundary, where every prior
-     * tool exchange is already resolved — so the kept region must begin there.
+     * tool exchange is already resolved — so the kept region must begin there. The
+     * synthetic compaction-summary user message is also string content, so a
+     * repeat compaction always finds at least the previous summary as a clean cut.
      *
      * Start from `length - keepRecentMessages` and walk *backwards* to the nearest
      * such prompt: this keeps at least the recent floor and lands clean. Returns

package/dist/agent/session.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { loadProjectInstructions } from "../config/index.js";
 import { resolveTaskModel } from "../routing/index.js";
 import { UsageCollector, } from "../usage/index.js";
+import { Budget } from "./budget.js";
 import { runAgent, } from "./loop.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
 /**
@@ -115,6 +116,20 @@ export class Session {
         const onReq = (req) => collector.record(req);
         // Compact *before* the agent call so the turn runs against a bounded history.
         await this.maybeCompact(onReq);
+        // Per-turn runaway guard (build item 4): when `agent.maxTokensPerTurn` is
+        // set, hand the loop a fresh token-only budget for THIS turn. Reusing the
+        // Budget primitive with an infinite iteration cap makes it purely a token
+        // stop — the loop's own `agent.maxIterations` already bounds turn count.
+        // Unset/0 → no budget object at all, so the loop's budget check is a no-op
+        // and behavior is byte-identical to before. Rebuilt each `send`, so the cap
+        // is per-turn, never cumulative across the session (cost is C.22's concern).
+        const maxTokensPerTurn = this.args.config.agent.maxTokensPerTurn;
+        const budget = maxTokensPerTurn > 0
+            ? new Budget({
+                maxIterations: Number.POSITIVE_INFINITY,
+                maxTokens: maxTokensPerTurn,
+            })
+            : undefined;
         // before-run (C.19): a blocking pre-run hook — or an untrusted project's
         // hooks — throws here and aborts the turn before the model is engaged
         // (fail-closed). No-op when hooks are disabled or none are registered.
@@ -133,12 +148,21 @@ export class Session {
             : await runAgent({
                 messages: this.messages,
                 ...this.args, // carries `router` through to the loop
+                // The per-turn token guard (build item 4). After the spread because
+                // SessionArgs has no `budget` field — it is a per-turn construction,
+                // not session state. `undefined` when the cap is off (no-op check).
+                budget,
                 taskClass: "main-turn",
                 // After the spread so a mid-session `/reload` wins over the initial value.
                 projectInstructions: this.projectInstructions,
                 planMode: false, // the plan directive belongs only to the runner's propose phase
                 renderer,
                 onRequestUsage: onReq,
+                // Mid-loop compaction (build item 3): let a long autonomous turn
+                // compact between iterations, not just once up front. Reuses this
+                // session's threshold/cut/summarize path over the loop's own history
+                // and attributes the summary usage to this run's collector.
+                compact: (messages) => this.compactLoopHistory(messages, onReq),
             });
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;
@@ -169,21 +193,27 @@ export class Session {
         this.messages = [];
     }
     /**
-     * Compact only when the estimated history exceeds
-     * `compactThreshold * maxTokens`. On success logs a one-line notice and
-     * returns the number of older messages folded into the summary; otherwise
-     * returns `null` (under threshold, nothing safe to cut, or summary failed).
+     * Compact `this.messages` only when it has grown past threshold, adopting the
+     * result. On success logs a one-line notice and returns the number of older
+     * messages folded into the summary; otherwise returns `null` (under threshold,
+     * nothing safe to cut, or summary failed).
      */
     async maybeCompact(onRequestUsage) {
-        const { maxTokens, compactThreshold } = this.args.config.context;
-        if (estimateTokens(this.messages) <= compactThreshold * maxTokens) {
-            return null;
-        }
-        const n = await this.runCompaction(onRequestUsage);
-        if (n) {
-            this.args.ctx.logger.info(`compacted ${n} older message${n === 1 ? "" : "s"} to stay within context`);
-        }
-        return n;
+        const { messages, compacted } = await this.compactIfOverThreshold(this.messages, onRequestUsage);
+        this.messages = messages;
+        return compacted;
+    }
+    /**
+     * The mid-loop compaction seam (build item 3) handed to {@link runAgent}: same
+     * threshold/cut/summarize path as {@link maybeCompact}, but over the loop's own
+     * running history rather than `this.messages` (the loop owns and adopts its
+     * copy). Reuses the exact machinery so no summarization logic is duplicated and
+     * the loop stays ignorant of it. Under threshold it returns the history
+     * unchanged — cheap, no model call.
+     */
+    async compactLoopHistory(messages, onRequestUsage) {
+        const result = await this.compactIfOverThreshold(messages, onRequestUsage);
+        return result.messages;
     }
     /**
      * Force compaction regardless of the threshold (backs `/compact`). Returns the
@@ -191,20 +221,47 @@ export class Session {
      * cut or the summary call failed.
      */
     async compact() {
-        return this.runCompaction();
+        const { messages, compacted } = await this.runCompaction(this.messages);
+        this.messages = messages;
+        return compacted;
+    }
+    /**
+     * Compact `messages` when its estimated footprint exceeds
+     * `compactThreshold * maxTokens`, else return it untouched. The estimate adds a
+     * fixed `reserveTokens` allowance for the system prompt and tool schemas that
+     * {@link estimateTokens} never sees (~4.5k+ tokens of real request payload), so
+     * the trigger reflects the actual request size rather than only the visible
+     * history — otherwise the loop can sit just under the visible threshold while
+     * the real request has already overrun the window. Logs a one-line notice on a
+     * successful compaction.
+     */
+    async compactIfOverThreshold(messages, onRequestUsage) {
+        const { maxTokens, compactThreshold, reserveTokens } = this.args.config.context;
+        const estimated = estimateTokens(messages) + reserveTokens;
+        if (estimated <= compactThreshold * maxTokens) {
+            return { messages, compacted: null };
+        }
+        const result = await this.runCompaction(messages, onRequestUsage);
+        if (result.compacted) {
+            this.args.ctx.logger.info(`compacted ${result.compacted} older message${result.compacted === 1 ? "" : "s"} to stay within context`);
+        }
+        return result;
     }
     /**
      * Find a clean cut, summarize the older prefix into a synthetic user/assistant
      * pair, and splice it in front of the kept-recent messages. Best-effort: a
-     * failed summary call leaves the history untouched and returns `null` (fail
-     * open — losing compaction is degraded, not unsafe).
+     * failed summary call leaves the history untouched and reports `compacted:
+     * null` (fail open — losing compaction is degraded, not unsafe). Pure with
+     * respect to `this.messages`: it returns the new array for the caller to adopt
+     * (the loop and the session each own their own history), and only accumulates
+     * the summary's usage into the session total.
      */
-    async runCompaction(onRequestUsage) {
-        const cut = this.findCut();
+    async runCompaction(messages, onRequestUsage) {
+        const cut = this.findCut(messages);
         if (cut === null)
-            return null;
-        const prefix = this.messages.slice(0, cut);
-        const kept = this.messages.slice(cut);
+            return { messages, compacted: null };
+        const prefix = messages.slice(0, cut);
+        const kept = messages.slice(cut);
         let synopsis;
         try {
             const summary = await this.summarize(prefix, onRequestUsage);
@@ -214,7 +271,7 @@ export class Session {
         }
         catch (err) {
             this.args.ctx.logger.warn(`compaction skipped: summary failed (${err.message})`);
-            return null;
+            return { messages, compacted: null };
         }
         // A user/assistant pair, not a lone message: the kept region begins with a
         // user prompt, so a single synthetic user message would put two user turns
@@ -229,8 +286,10 @@ export class Session {
                 content: `${COMPACTION_MARKER} Summary of the conversation so far:\n\n${synopsis}`,
             },
         ];
-        this.messages = [...summaryMessages, ...kept];
-        return prefix.length;
+        return {
+            messages: [...summaryMessages, ...kept],
+            compacted: prefix.length,
+        };
     }
     /**
      * Choose the boundary between the summarized prefix and the kept-recent tail.
@@ -239,18 +298,20 @@ export class Session {
      * matching `tool_result` (the next user message) must never straddle the cut,
      * or the next provider call breaks. A real user *prompt* (`role:"user"` with
      * string content) only occurs at a completed turn boundary, where every prior
-     * tool exchange is already resolved — so the kept region must begin there.
+     * tool exchange is already resolved — so the kept region must begin there. The
+     * synthetic compaction-summary user message is also string content, so a
+     * repeat compaction always finds at least the previous summary as a clean cut.
      *
      * Start from `length - keepRecentMessages` and walk *backwards* to the nearest
      * such prompt: this keeps at least the recent floor and lands clean. Returns
      * the cut index, or `null` if no safe boundary leaves a non-empty prefix
      * (e.g. a single long in-progress turn — nothing safe to compact).
      */
-    findCut() {
+    findCut(messages) {
         const { keepRecentMessages } = this.args.config.context;
-        const start = this.messages.length - keepRecentMessages;
+        const start = messages.length - keepRecentMessages;
         for (let i = start; i >= 1; i--) {
-            const msg = this.messages[i];
+            const msg = messages[i];
             if (msg.role === "user" && typeof msg.content === "string")
                 return i;
         }

package/dist/cli/commands/mcp.js

@@ -131,7 +131,7 @@ export function mcpCommand() {
             ]);
         }
         const io = defaultOnboardingIO(shouldUseColor(process.stderr));
-        io.write(`${t.strong(`credential for "${server}"`)} ${t.muted(`(stored as "${ref}" in ~/.cruxy/credentials.json, 0600)`)}\n`);
+        io.write(`${t.strong(`credential for "${server}"`)} ${t.muted(`(stored as "${ref}" in ~/.cruxy/credentials.json, owner-only)`)}\n`);
         io.write(`${t.muted("paste the bearer token (input hidden): ")}`);
         const token = (await io.readSecret()).trim();
         if (!token) {

package/dist/config/credentials.d.ts

@@ -9,11 +9,10 @@ export declare function readCredential(provider: string, file?: string): string
  * secret is sourced from. Never throws.
  */
 export declare function readMcpCredential(ref: string, file?: string): string | undefined;
-/** Persist MCP bearer token for credential name `ref`. Same 0600/0700 as keys. */
+/** Persist MCP bearer token for credential name `ref`. Same owner-only guarantee. */
 export declare function writeMcpCredential(ref: string, token: string, file?: string): void;
 /**
- * Persist `key` for `provider`, merging into any existing store. The file is
- * written `0600` and its directory `0700` so the secret is owner-only — enforced
- * with an explicit `chmod` after write (mkdir/write modes are umask-masked).
+ * Persist `key` for `provider`, merging into any existing store. Written
+ * owner-only (see {@link writeInto}); refuses loudly if that can't be enforced.
  */
 export declare function writeCredential(provider: string, key: string, file?: string): void;

package/dist/config/credentials.js

@@ -1,13 +1,23 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { CREDENTIALS_FILE_NAME } from "../constants.js";
+import { credentialsUnprotected } from "../errors/index.js";
+import { logger } from "../utils/logger.js";
+import { enforceOwnerOnly, isOwnerOnly } from "./owner-only.js";
 import { globalDir } from "./paths.js";
 /**
  * The credentials store (U.6) — the one place a provider API key is persisted.
  * It lives **outside** `config.json` on purpose: config is secret-free by design
  * ("the API key comes from env"), so secrets get their own file with restrictive
- * permissions (`0600`, dir `0700`), the same shape as gh/aws/npm. `resolveApiKey`
- * reads it as a fallback after the environment.
+ * permissions, the same shape as gh/aws/npm. `resolveApiKey` reads it as a
+ * fallback after the environment.
+ *
+ * "Restrictive" means **owner-only**: POSIX `0600` (dir `0700`), and on Windows
+ * an NTFS ACL granting only the current user (POSIX modes are meaningless there —
+ * see {@link enforceOwnerOnly}). The guarantee is enforced AND verified on every
+ * write; if it cannot be established the write is refused loudly
+ * (`CRUXY_E_CREDENTIALS_UNPROTECTED`) rather than persisting a secret at
+ * permissions we could not secure.
  */
 /** Bumped if the on-disk shape ever changes. */
 const CREDENTIALS_VERSION = 1;
@@ -15,6 +25,26 @@ const CREDENTIALS_VERSION = 1;
 export function credentialsPath() {
     return join(globalDir(), CREDENTIALS_FILE_NAME);
 }
+/** Paths already warned about this process, so a loose-perms warning fires once. */
+const warnedLoosePerms = new Set();
+/**
+ * Best-effort: warn (never refuse) if an existing store is readable beyond its
+ * owner, so an upgrade from a build that couldn't secure it isn't silently
+ * insecure — and isn't bricked either. Fires at most once per path per process.
+ */
+function warnIfLoosePerms(file) {
+    if (warnedLoosePerms.has(file))
+        return;
+    warnedLoosePerms.add(file);
+    try {
+        if (existsSync(file) && !isOwnerOnly(file)) {
+            logger.warn(`credentials store ${file} is not owner-only — other users on this machine may be able to read it. Re-run \`cruxy login\` (or re-store the MCP credential) to repair its permissions.`);
+        }
+    }
+    catch {
+        // Perms could not be inspected — stay silent rather than cry wolf.
+    }
+}
 /** Parse the store at `file`, or `null` if absent/unreadable/malformed. */
 function readStore(file) {
     if (!existsSync(file))
@@ -35,6 +65,7 @@ function readStore(file) {
 }
 /** The stored key for `provider`, or `undefined`. Never throws. */
 export function readCredential(provider, file = credentialsPath()) {
+    warnIfLoosePerms(file);
     const store = readStore(file);
     const key = store?.keys[provider];
     return typeof key === "string" && key !== "" ? key : undefined;
@@ -46,52 +77,74 @@ export function readCredential(provider, file = credentialsPath()) {
  * secret is sourced from. Never throws.
  */
 export function readMcpCredential(ref, file = credentialsPath()) {
+    warnIfLoosePerms(file);
     const store = readStore(file);
     const token = store?.mcp?.[ref];
     return typeof token === "string" && token !== "" ? token : undefined;
 }
-/** Persist MCP bearer token for credential name `ref`. Same 0600/0700 as keys. */
+/** Persist MCP bearer token for credential name `ref`. Same owner-only guarantee. */
 export function writeMcpCredential(ref, token, file = credentialsPath()) {
     writeInto(file, (store) => {
         store.mcp ??= {};
         store.mcp[ref] = token;
-    });
+    }, "mcp");
 }
 /**
- * Persist `key` for `provider`, merging into any existing store. The file is
- * written `0600` and its directory `0700` so the secret is owner-only — enforced
- * with an explicit `chmod` after write (mkdir/write modes are umask-masked).
+ * Persist `key` for `provider`, merging into any existing store. Written
+ * owner-only (see {@link writeInto}); refuses loudly if that can't be enforced.
  */
 export function writeCredential(provider, key, file = credentialsPath()) {
     writeInto(file, (store) => {
         store.keys[provider] = key;
-    });
+    }, "provider");
 }
 /**
- * Merge `mutate` into the store and persist it owner-only: dir `0700`, file
- * `0600`, enforced with an explicit `chmod` after write (mkdir/write modes are
- * umask-masked). The one write path shared by every credential namespace.
+ * Merge `mutate` into the store and persist it owner-only. The one write path
+ * shared by every credential namespace, and the single place the owner-only
+ * guarantee is enforced:
+ *
+ *   1. The DIRECTORY is made owner-only FIRST, before any secret is written — so
+ *      the file inherits owner-only at creation (no window where it exists under
+ *      inherited permissions), and if the directory can't be secured we refuse
+ *      before a secret ever touches disk.
+ *   2. The new content is written to a temp file, made owner-only + VERIFIED,
+ *      then atomically renamed over the target. A failure removes the temp and
+ *      leaves any existing store untouched — never a torn or clobbered write.
+ *
+ * Enforcement runs on every write, so a pre-existing store with loose
+ * permissions is repaired in place. If owner-only cannot be established the write
+ * is refused with `CRUXY_E_CREDENTIALS_UNPROTECTED` (`kind` tailors the
+ * remediation: provider keys → env var; MCP tokens → no env fallback).
  */
-function writeInto(file, mutate) {
+function writeInto(file, mutate, kind) {
     const dir = dirname(file);
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    mkdirSync(dir, { recursive: true });
     try {
-        chmodSync(dir, 0o700);
+        enforceOwnerOnly(dir, { directory: true });
     }
-    catch {
-        // Best-effort on platforms without POSIX modes (e.g. Windows).
+    catch (err) {
+        // Refuse BEFORE writing any secret — nothing sensitive has hit disk yet.
+        throw credentialsUnprotected(kind, dir, err);
     }
     const store = readStore(file) ?? { version: CREDENTIALS_VERSION, keys: {} };
     store.version = CREDENTIALS_VERSION;
     mutate(store);
-    writeFileSync(file, JSON.stringify(store, null, 2) + "\n", {
+    const tmp = `${file}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n", {
         encoding: "utf8",
         mode: 0o600,
     });
     try {
-        chmodSync(file, 0o600);
+        enforceOwnerOnly(tmp, { directory: false }); // sets + verifies, or throws
+        renameSync(tmp, file); // atomic replace; the owner-only ACL moves with it
     }
-    catch {
-        // Best-effort (see above).
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // The temp may already be gone; the target store is untouched regardless.
+        }
+        throw credentialsUnprotected(kind, file, err);
     }
 }

package/dist/config/owner-only.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Make `path` owner-only, or throw. On Windows the ACL is verified after the
+ * edit (both the `icacls` exit code AND a read-back), so a returned call is a
+ * genuine guarantee, never a best-effort attempt.
+ *
+ * @throws if owner-only permissions cannot be established (non-zero `icacls`,
+ *   an unresolvable SID, a filesystem without ACLs/modes, …).
+ */
+export declare function enforceOwnerOnly(path: string, opts?: {
+    directory?: boolean;
+}): void;
+/**
+ * Whether `path` is currently owner-only. POSIX: no group/other bits. Windows:
+ * best-effort — the ACL names no broad principal (Everyone / Authenticated
+ * Users / Users). Used both to verify {@link enforceOwnerOnly} and to warn on a
+ * pre-existing store with loose permissions. Returns `true` when it genuinely
+ * cannot tell (a missing tool), so a warning path never cries wolf.
+ */
+export declare function isOwnerOnly(path: string): boolean;