@cortexkit/opencode-magic-context 0.33.1 → 0.34.0

package/src/shared/models-dev-cache.test.ts

@@ -10,6 +10,8 @@ import {
     refreshModelLimitsAfterAuthOnce,
     refreshModelLimitsFromApi,
     resetAuthRewarmLatchForTest,
+    resolveLimit,
+    setOutputReserveConfig,
 } from "./models-dev-cache";
 
 /**
@@ -18,6 +20,88 @@ import {
  * cold start. We no longer read OpenCode's `models.json` file ourselves (a torn
  * read produced impossible limits and a stale copy out-voted the live cap).
  */
+describe("output-token reservation", () => {
+    beforeEach(() => setOutputReserveConfig(undefined));
+
+    test("keeps a pre-carved OpenAI catalog input limit unchanged", () => {
+        expect(
+            resolveLimit(
+                { context: 1_050_000, input: 922_000, output: 128_000 },
+                "openai",
+                "gpt-5.4",
+            ),
+        ).toBe(922_000);
+    });
+
+    test("input equal to context falls through to shared-window reservation", () => {
+        expect(
+            resolveLimit(
+                { context: 372_000, input: 372_000, output: 64_000 },
+                "openai",
+                "literal-config",
+            ),
+        ).toBe(308_000);
+    });
+
+    test("reserves output for Anthropic shared windows", () => {
+        expect(resolveLimit({ context: 1_000_000, output: 64_000 }, "anthropic", "claude")).toBe(
+            936_000,
+        );
+    });
+
+    test("makes the reporter's 95% send safe under the shared provider wall", () => {
+        const usable = resolveLimit(
+            { context: 122_880, output: 16_384 },
+            "openai-compatible",
+            "reporter-model",
+        );
+        expect(usable).toBe(106_496);
+        expect((usable ?? 0) * 0.95 + 16_384).toBeLessThanOrEqual(131_072);
+    });
+
+    test("caps absurd catalog output at 25% of context", () => {
+        expect(
+            resolveLimit({ context: 100_000, output: 60_000 }, "anthropic", "absurd-output"),
+        ).toBe(75_000);
+    });
+
+    test("keeps proven separate-quota Gemini windows unchanged", () => {
+        expect(
+            resolveLimit({ context: 1_048_576, output: 65_536 }, "google", "gemini-2.5-pro"),
+        ).toBe(1_048_576);
+        expect(
+            resolveLimit(
+                { context: 1_048_576, output: 65_536 },
+                "google-antigravity",
+                "gemini-2.5-pro",
+            ),
+        ).toBe(1_048_576);
+    });
+
+    test("output_reserve overrides shared and separate quota defaults", () => {
+        expect(resolveLimit({ context: 100_000, output: 20_000 }, "anthropic", "claude", 0)).toBe(
+            100_000,
+        );
+        const perModelReserve = { default: 4_000, "google/gemini": 8_000 };
+        expect(
+            resolveLimit({ context: 100_000, output: 20_000 }, "google", "gemini", perModelReserve),
+        ).toBe(92_000);
+        expect(
+            resolveLimit(
+                { context: 100_000, output: 20_000 },
+                "google-antigravity",
+                "gemini",
+                perModelReserve,
+            ),
+        ).toBe(92_000);
+    });
+
+    test("clamps reservation to both the 50% and 1024-token usable floors", () => {
+        expect(resolveLimit({ context: 100_000 }, "custom", "tiny", 90_000)).toBe(50_000);
+        expect(resolveLimit({ context: 1_200 }, "custom", "micro", 1_000)).toBe(1_024);
+    });
+});
+
 describe("models-dev-cache (SDK-only)", () => {
     let tempDir: string;
     let originalXdgData: string | undefined;
@@ -32,6 +116,7 @@ describe("models-dev-cache (SDK-only)", () => {
         // touch the real ~/.local/share/cortexkit/magic-context cache.
         originalXdgData = process.env.XDG_DATA_HOME;
         process.env.XDG_DATA_HOME = tempDir;
+        setOutputReserveConfig(undefined);
         clearModelsDevCache();
     });
 
@@ -103,6 +188,32 @@ describe("models-dev-cache (SDK-only)", () => {
         expect(getSdkContextLimit("openai", "gpt-5.4-mini")).toBe(922000);
     });
 
+    test("narrows raw context with detected wire truth before reserving output", async () => {
+        await refreshModelLimitsFromApi(
+            makeClient([
+                {
+                    id: "anthropic",
+                    models: {
+                        claude: { limit: { context: 200_000, output: 20_000 } },
+                    },
+                },
+            ]),
+        );
+
+        expect(
+            getSdkContextLimit("anthropic", "claude", 120_000, {
+                detectedLimitProvenance: "combined",
+            }),
+        ).toBe(100_000);
+        // A provider-reported prompt ceiling is already pre-carved. Treating it
+        // as combined would subtract the 20K output allowance a second time.
+        expect(
+            getSdkContextLimit("anthropic", "claude", 120_000, {
+                detectedLimitProvenance: "prompt_only",
+            }),
+        ).toBe(120_000);
+    });
+
     test("matches a tagged ollama model against its tag-less SDK entry", async () => {
         await refreshModelLimitsFromApi(
             makeClient([
@@ -379,3 +490,63 @@ describe("models-dev-cache (SDK-only)", () => {
         expect(getSdkContextLimit("p", "m3")).toBe(200000);
     });
 });
+
+describe("getSdkContextLimit prompt_only pre-carve arm", () => {
+    // The v0.34.0 re-verify found no behavioral test for the provenance
+    // ternary: a prompt_only detected limit must enter the pre-carved INPUT
+    // arm (no output subtraction), while combined detections narrow the raw
+    // context BEFORE reservation. A regression routing prompt_only through
+    // the context arm double-reserves and these fixtures go red.
+    beforeEach(() => clearModelsDevCache());
+    afterEach(() => clearModelsDevCache());
+    const seed = () =>
+        refreshModelLimitsFromApi({
+            config: {
+                providers: async () => ({
+                    data: {
+                        providers: [
+                            {
+                                id: "anthropic",
+                                models: {
+                                    "prov-model": {
+                                        limit: { context: 200000, output: 64000 },
+                                    },
+                                },
+                            },
+                        ],
+                    },
+                }),
+            },
+        });
+
+    test("prompt_only detection routes through the input arm without double reservation", async () => {
+        await seed();
+        expect(
+            getSdkContextLimit("anthropic", "prov-model", 167000, {
+                detectedLimitProvenance: "prompt_only",
+            }),
+        ).toBe(167000);
+    });
+
+    test("combined detection narrows raw context before reservation", async () => {
+        await seed();
+        // min(200000, 131072) = 131072, then arm-2 reserve min(64000, 25%) = 32768.
+        expect(
+            getSdkContextLimit("anthropic", "prov-model", 131072, {
+                detectedLimitProvenance: "combined",
+            }),
+        ).toBe(131072 - 32768);
+    });
+
+    test("prompt_only with reservation none serves the prompt cap as the native denominator", async () => {
+        await seed();
+        // The input arm short-circuits before reservation: the native metric
+        // sees the provider-enforced prompt wall, not the raw window.
+        expect(
+            getSdkContextLimit("anthropic", "prov-model", 167000, {
+                detectedLimitProvenance: "prompt_only",
+                reservation: "none",
+            }),
+        ).toBe(167000);
+    });
+});

package/src/shared/models-dev-cache.ts

@@ -27,9 +27,12 @@
 
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import type { ContextLimitProvenance } from "./context-limit-provenance";
 import { getMagicContextStorageDir } from "./data-path";
 import { getHarness } from "./harness";
+import { piModelRefToCanonical } from "./harness-provider-map";
 import { sessionLog } from "./logger";
+import { shouldEnforcePrivateStoragePermissions } from "./storage-permissions";
 
 interface OpencodeClientLike {
     config: {
@@ -54,14 +57,35 @@ export function isSaneLimit(limit: number | undefined): limit is number {
     return typeof limit === "number" && limit >= MIN_SANE_LIMIT && limit <= MAX_SANE_LIMIT;
 }
 
+export type OutputReserveConfig = number | { default: number; [modelKey: string]: number };
+
+export interface ModelLimit {
+    context?: number;
+    input?: number;
+    output?: number;
+}
+
 interface CachedModelMetadata {
+    /** Legacy resolved value, retained so pre-upgrade persisted caches remain readable. */
     limit?: number;
+    /** Raw combined context window. Reservation is applied only when the value is read. */
+    contextLimit?: number;
     /** Provider-enforced prompt cap. Undefined when only a combined context window is known. */
     inputLimit?: number;
+    /** Maximum generated tokens advertised by the provider/model catalog. */
+    outputLimit?: number;
     /** Provider metadata says the model accepts image input. Unknown is false. */
     vision?: boolean;
 }
 
+// Proven-separate allowlist only. Unknown providers reserve by default because
+// wasting some input capacity is safer than a shared-window hard rejection.
+const SEPARATE_OUTPUT_QUOTA_PROVIDERS = new Set(["google", "google-antigravity"]);
+const MIN_PLAUSIBLE_CONTEXT_LIMIT = 1024;
+const OUTPUT_RESERVE_CAP_RATIO = 0.25;
+let outputReserveConfig: OutputReserveConfig | undefined;
+const reserveClampLogSeen = new Set<string>();
+
 /**
  * Authoritative source (OpenCode only): populated async from the SDK
  * `config.providers()`, which is OpenCode's fully-resolved config — models.dev +
@@ -96,17 +120,28 @@ function loadPersistedApiCacheOnce(): void {
         const raw = readFileSync(persistFilePath(), "utf-8");
         const obj = JSON.parse(raw) as Record<
             string,
-            number | { limit?: number; inputLimit?: number; vision?: boolean }
+            | number
+            | {
+                  limit?: number;
+                  contextLimit?: number;
+                  inputLimit?: number;
+                  outputLimit?: number;
+                  vision?: boolean;
+              }
         >;
         const map = new Map<string, CachedModelMetadata>();
         for (const [key, persisted] of Object.entries(obj)) {
             const limit = typeof persisted === "number" ? persisted : persisted.limit;
+            const contextLimit = typeof persisted === "number" ? undefined : persisted.contextLimit;
             const inputLimit = typeof persisted === "number" ? undefined : persisted.inputLimit;
+            const outputLimit = typeof persisted === "number" ? undefined : persisted.outputLimit;
             const vision = typeof persisted === "number" ? false : persisted.vision === true;
-            if (isSaneLimit(limit)) {
+            if (isSaneLimit(contextLimit) || isSaneLimit(limit)) {
                 map.set(key, {
-                    limit,
+                    limit: isSaneLimit(limit) ? limit : undefined,
+                    contextLimit: isSaneLimit(contextLimit) ? contextLimit : undefined,
                     inputLimit: isSaneLimit(inputLimit) ? inputLimit : undefined,
+                    outputLimit: isFinitePositive(outputLimit) ? outputLimit : undefined,
                     vision,
                 });
             }
@@ -133,7 +168,9 @@ function persistApiCache(): void {
         if (isSaneLimit(value.limit)) {
             obj[key] = {
                 limit: value.limit,
+                contextLimit: isSaneLimit(value.contextLimit) ? value.contextLimit : undefined,
                 inputLimit: isSaneLimit(value.inputLimit) ? value.inputLimit : undefined,
+                outputLimit: isFinitePositive(value.outputLimit) ? value.outputLimit : undefined,
                 vision: value.vision === true,
             };
         }
@@ -143,29 +180,110 @@ function persistApiCache(): void {
         mkdirSync(dir, { recursive: true });
         const target = persistFilePath();
         const tmp = `${target}.${process.pid}.tmp`;
-        writeFileSync(tmp, JSON.stringify(obj), { encoding: "utf-8", mode: 0o600 });
+        if (shouldEnforcePrivateStoragePermissions()) {
+            writeFileSync(tmp, JSON.stringify(obj), { encoding: "utf-8", mode: 0o600 });
+        } else {
+            writeFileSync(tmp, JSON.stringify(obj), { encoding: "utf-8" });
+        }
         renameSync(tmp, target);
     } catch {
         // best-effort — a failed persist only loses cold-start warmth, not correctness
     }
 }
 
+function isFinitePositive(value: number | undefined): value is number {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+function modelKeyLookupOrder(providerID: string, modelID: string): string[] {
+    const full = `${providerID}/${modelID}`;
+    const canonicalFull = piModelRefToCanonical(full);
+    const candidates = [full, canonicalFull, modelID];
+    const colon = modelID.lastIndexOf(":");
+    if (colon > 0) {
+        const bareModel = modelID.slice(0, colon);
+        const providerBare = `${providerID}/${bareModel}`;
+        candidates.push(providerBare, piModelRefToCanonical(providerBare), bareModel);
+    }
+    return [...new Set(candidates)];
+}
+
+function configuredOutputReserve(
+    config: OutputReserveConfig | undefined,
+    providerID: string,
+    modelID: string,
+): number | undefined {
+    if (typeof config === "number")
+        return Number.isFinite(config) && config >= 0 ? config : undefined;
+    if (!config) return undefined;
+    for (const candidate of modelKeyLookupOrder(providerID, modelID)) {
+        const value = config[candidate];
+        if (typeof value === "number" && Number.isFinite(value) && value >= 0) return value;
+    }
+    return Number.isFinite(config.default) && config.default >= 0 ? config.default : undefined;
+}
+
+function logReserveClampOnce(key: string, message: string): void {
+    if (reserveClampLogSeen.has(key)) return;
+    reserveClampLogSeen.add(key);
+    sessionLog("global", `models-dev-cache: ${message}`);
+}
+
+/** Set the user-tier reservation override shared by every resolved-limit consumer. */
+export function setOutputReserveConfig(config: OutputReserveConfig | undefined): void {
+    outputReserveConfig = config;
+}
+
 /**
- * Resolve the effective pressure limit for a model's `limit` object.
+ * Resolve the usable prompt budget from raw provider metadata.
  *
- * Prefers `limit.input` (max prompt tokens the provider will accept) over
- * `limit.context` (total window including output). For GitHub Copilot and
- * several proxy providers, `context` is the marketing number (input + output
- * combined), and sending a prompt sized against `context` gets rejected.
- * OpenCode's own `session/overflow.ts` uses `input ?? context` for the same
- * reason — the denominator that drives overflow/pressure must be the number
- * the provider actually enforces on input.
+ * A genuinely smaller input cap is already pre-carved and wins unchanged. All
+ * other providers reserve generated tokens from the shared context window by
+ * default, except the small allowlist whose APIs document a separate output
+ * quota. `output_reserve` overrides that shared/separate decision, including 0
+ * to disable reservation. Reservation can never leave less than half the raw
+ * context window or the module's 1024-token plausibility floor.
  */
-function resolveLimit(limit: { context?: number; input?: number } | undefined): number | undefined {
+export function resolveLimit(
+    limit: ModelLimit | undefined,
+    providerID: string,
+    modelID: string,
+    reserveConfig: OutputReserveConfig | undefined = outputReserveConfig,
+): number | undefined {
     if (!limit) return undefined;
-    if (typeof limit.input === "number" && limit.input > 0) return limit.input;
-    if (typeof limit.context === "number" && limit.context > 0) return limit.context;
-    return undefined;
+    const context = isFinitePositive(limit.context) ? limit.context : undefined;
+    const input = isFinitePositive(limit.input) ? limit.input : undefined;
+    if (input !== undefined && (context === undefined || input < context)) return input;
+    if (context === undefined) return undefined;
+
+    const configuredReserve = configuredOutputReserve(reserveConfig, providerID, modelID);
+    let reserve: number;
+    if (configuredReserve !== undefined) {
+        reserve = configuredReserve;
+    } else if (SEPARATE_OUTPUT_QUOTA_PROVIDERS.has(providerID)) {
+        reserve = 0;
+    } else {
+        const output = isFinitePositive(limit.output) ? limit.output : 0;
+        const cap = context * OUTPUT_RESERVE_CAP_RATIO;
+        reserve = Math.min(output, cap);
+        if (output > cap) {
+            logReserveClampOnce(
+                `cap|${providerID}/${modelID}|${context}|${output}`,
+                `output reserve capped at 25% for ${providerID}/${modelID}: ${output} → ${cap}`,
+            );
+        }
+    }
+
+    const floor = Math.max(MIN_PLAUSIBLE_CONTEXT_LIMIT, context * 0.5);
+    const maxReserve = Math.max(0, context - floor);
+    if (reserve > maxReserve) {
+        logReserveClampOnce(
+            `floor|${providerID}/${modelID}|${context}|${reserve}`,
+            `output reserve clamped for ${providerID}/${modelID}: ${reserve} → ${maxReserve} (usable floor ${floor})`,
+        );
+        reserve = maxReserve;
+    }
+    return Math.floor(context - reserve);
 }
 
 function setCachedModelMetadata(
@@ -173,7 +291,7 @@ function setCachedModelMetadata(
     key: string,
     model:
         | {
-              limit?: { context?: number; input?: number };
+              limit?: ModelLimit;
               experimental?: { modes?: Record<string, unknown> };
               capabilities?: unknown;
               modalities?: unknown;
@@ -182,15 +300,19 @@ function setCachedModelMetadata(
           }
         | undefined,
 ): void {
-    const limit = resolveLimit(model?.limit);
+    const contextLimit = model?.limit?.context;
     const inputLimit = model?.limit?.input;
+    const outputLimit = model?.limit?.output;
+    const rawLimit = isSaneLimit(contextLimit)
+        ? contextLimit
+        : isSaneLimit(inputLimit)
+          ? inputLimit
+          : undefined;
 
-    // Only cache plausible limits. A value outside [20k, 3M] is garbage (torn
-    // read / unconfigured default) and must never enter the cache or get
-    // persisted — see isSaneLimit.
-    if (!isSaneLimit(limit)) {
-        return;
-    }
+    // Validate the raw provider metadata before reservation. A legitimate 20K
+    // context may resolve below MIN_SANE_LIMIT after carving output, but it must
+    // still remain cached; the 50%/1024 usable floor protects the result.
+    if (rawLimit === undefined) return;
 
     const values = [model?.capabilities, model?.modalities, model?.input, model?.attachment];
     const vision = values.some(
@@ -203,8 +325,12 @@ function setCachedModelMetadata(
                 .includes("vision"),
     );
     const value: CachedModelMetadata = {
-        limit,
+        // Keep a sane raw fallback for old persisted-cache readers. Runtime
+        // resolution below uses context/input/output so user overrides stay live.
+        limit: rawLimit,
+        contextLimit: isSaneLimit(contextLimit) ? contextLimit : undefined,
         inputLimit: isSaneLimit(inputLimit) ? inputLimit : undefined,
+        outputLimit: isFinitePositive(outputLimit) ? outputLimit : undefined,
         vision,
     };
     cache.set(key, value);
@@ -307,7 +433,7 @@ async function refreshModelLimitsOnce(client: OpencodeClientLike): Promise<boole
                 models?: Record<
                     string,
                     {
-                        limit?: { context?: number; input?: number };
+                        limit?: ModelLimit;
                         experimental?: { modes?: Record<string, unknown> };
                     }
                 >;
@@ -359,18 +485,51 @@ async function refreshModelLimitsOnce(client: OpencodeClientLike): Promise<boole
  *
  * Resolution:
  *   1. Seed `apiCache` from the persisted last-known-good file once (cold start).
- *   2. Return the SDK value (sane by construction — only [20k,3M] is cached).
+ *   2. Resolve the sane raw SDK metadata into its output-reserved usable value.
  *   3. `undefined` when the SDK hasn't reported this model yet → the caller
  *      defaults / retries (the startup warm retries when OpenCode isn't ready).
  *
  * OpenCode-only: Pi never warms `apiCache` (it resolves from its own
- * `ctx.getModel().contextWindow`), so for Pi this returns `undefined` and Pi's
+ * `ctx.model.contextWindow`), so for Pi this returns `undefined` and Pi's
  * own resolution path is used.
  */
-export function getSdkContextLimit(providerID: string, modelID: string): number | undefined {
+export function getSdkContextLimit(
+    providerID: string,
+    modelID: string,
+    detectedContextLimit?: number,
+    options?: {
+        reservation?: "default" | "none";
+        detectedLimitProvenance?: ContextLimitProvenance;
+    },
+): number | undefined {
     loadPersistedApiCacheOnce();
-    const fromApi = lookupLimitWithTagFallback(apiCache, providerID, modelID);
-    return isSaneLimit(fromApi) ? fromApi : undefined;
+    const metadata = lookupMetadataWithTagFallback(apiCache, providerID, modelID);
+    if (!metadata) return undefined;
+    const rawContext = metadata.contextLimit ?? metadata.limit;
+    const promptOnlyDetected =
+        options?.detectedLimitProvenance === "prompt_only" && isFinitePositive(detectedContextLimit)
+            ? detectedContextLimit
+            : undefined;
+    const context =
+        promptOnlyDetected === undefined &&
+        isFinitePositive(detectedContextLimit) &&
+        isFinitePositive(rawContext)
+            ? Math.min(rawContext, detectedContextLimit)
+            : promptOnlyDetected === undefined && isFinitePositive(detectedContextLimit)
+              ? detectedContextLimit
+              : rawContext;
+    const inputCandidates = [metadata.inputLimit, promptOnlyDetected].filter(isFinitePositive);
+    const input = inputCandidates.length > 0 ? Math.min(...inputCandidates) : undefined;
+    return resolveLimit(
+        {
+            context,
+            input,
+            output: metadata.outputLimit,
+        },
+        providerID,
+        modelID,
+        options?.reservation === "none" ? 0 : undefined,
+    );
 }
 
 /**
@@ -411,20 +570,18 @@ export function getSdkInputLimit(providerID: string, modelID: string): number |
  * Strategy: exact match first (never collapses a legitimately-tagged model),
  * then retry once with the last `:tag` segment stripped.
  */
-function lookupLimitWithTagFallback(
+function lookupMetadataWithTagFallback(
     cache: Map<string, CachedModelMetadata> | null,
     providerID: string,
     modelID: string,
-): number | undefined {
+): CachedModelMetadata | undefined {
     if (!cache) return undefined;
-    const exact = cache.get(`${providerID}/${modelID}`)?.limit;
-    if (typeof exact === "number") return exact;
+    const exact = cache.get(`${providerID}/${modelID}`);
+    if (exact) return exact;
 
     const colonIdx = modelID.lastIndexOf(":");
     if (colonIdx > 0) {
-        const baseModel = modelID.slice(0, colonIdx);
-        const fallback = cache.get(`${providerID}/${baseModel}`)?.limit;
-        if (typeof fallback === "number") return fallback;
+        return cache.get(`${providerID}/${modelID.slice(0, colonIdx)}`);
     }
     return undefined;
 }

package/src/shared/rpc-server.ts

@@ -19,6 +19,7 @@ import {
     registerNotificationSink,
 } from "./rpc-notifications";
 import { isPidAlive, parseRpcPortFile, rpcPortDir, rpcPortFilePath } from "./rpc-utils";
+import { shouldEnforcePrivateStoragePermissions } from "./storage-permissions";
 
 type RpcHandler = (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
 
@@ -152,16 +153,20 @@ export class MagicContextRpcServer {
         try {
             this.warnIfOtherLiveInstance();
             const dir = dirname(this.portFilePath);
-            // The port file holds the per-process bearer token that gates
-            // side-effecting RPC endpoints and the push channel. Under the default
-            // umask 0o022 a plain write lands at 0o644 in a 0o755 dir —
-            // world-readable, so any local UID could read the token. Restrict both:
-            // dir 0o700, file 0o600.
-            mkdirSync(dir, { recursive: true, mode: 0o700 });
-            try {
-                chmodSync(dir, 0o700);
-            } catch {
-                // best-effort
+            // The port file carries the RPC bearer token. The normal policy keeps
+            // it owner-only; a trusted-group deployment explicitly delegates every
+            // storage mode to its operator, so this path must not chmod or supply a
+            // restrictive creation mode in that case.
+            const enforcePrivatePermissions = shouldEnforcePrivateStoragePermissions();
+            if (enforcePrivatePermissions) {
+                mkdirSync(dir, { recursive: true, mode: 0o700 });
+                try {
+                    chmodSync(dir, 0o700);
+                } catch {
+                    // Continue RPC startup when directory tightening is rejected.
+                }
+            } else {
+                mkdirSync(dir, { recursive: true });
             }
             const tmpPath = `${this.portFilePath}.tmp`;
             // A stale tmp from a crashed write could exist with loose perms;
@@ -171,9 +176,9 @@ export class MagicContextRpcServer {
             } catch {
                 // best-effort
             }
-            // Synchronous write so the renameSync below sees a fully-written file
-            // (a 0o600 mode keeps the bearer token out of world-readable reach;
-            // renameSync preserves the tmp's mode for the final path).
+            // Synchronous write so the renameSync below sees a fully-written file.
+            // The private mode keeps the bearer token out of other local accounts;
+            // externally managed storage intentionally leaves its mode to the umask.
             writeFileSync(
                 tmpPath,
                 JSON.stringify({
@@ -183,13 +188,17 @@ export class MagicContextRpcServer {
                     token: this.token,
                     instance_id: this.instanceId,
                 }),
-                { encoding: "utf-8", mode: 0o600 },
+                enforcePrivatePermissions
+                    ? { encoding: "utf-8", mode: 0o600 }
+                    : { encoding: "utf-8" },
             );
             renameSync(tmpPath, this.portFilePath);
-            try {
-                chmodSync(this.portFilePath, 0o600);
-            } catch {
-                // best-effort
+            if (enforcePrivatePermissions) {
+                try {
+                    chmodSync(this.portFilePath, 0o600);
+                } catch {
+                    // Continue RPC startup when port-file tightening is rejected.
+                }
             }
             log(`[rpc] server listening on 127.0.0.1:${this.port}`);
         } catch (err) {