@moxxy/sdk 0.41.2 → 0.42.0

package/src/compactor-helpers.test.ts

@@ -254,6 +254,28 @@ describe('runCompactionIfNeeded', () => {
     expect(observedWindow).toBe(800_000);
   });
 
+  it('uses a user-supplied context window for a custom model before provider fallback', async () => {
+    let observedWindow = -1;
+    const compactor: CompactorDef = {
+      name: 'inspect-custom-window',
+      shouldCompact: (_log, budget) => {
+        observedWindow = budget.contextWindow;
+        return false;
+      },
+      compact: async () => { throw new Error('should not run'); },
+    };
+    const ctx = makeCtx({
+      compactor,
+      contextWindow: 128_000,
+      ctxModelId: 'vendor/model-v2',
+      contextWindowOverride: 200_000,
+    });
+
+    await runCompactionIfNeeded(ctx);
+
+    expect(observedWindow).toBe(200_000);
+  });
+
   it('force-compacts even when the provider exposes no usable context window', async () => {
     // Reactive overflow recovery: the provider already said the prompt is too
     // big, so a missing/zero window must NOT block the forced compaction.
@@ -525,6 +547,7 @@ interface MakeCtxOpts {
   readonly compactor: CompactorDef | null;
   readonly model?: string;
   readonly contextWindow?: number;
+  readonly contextWindowOverride?: number;
   readonly events?: ReadonlyArray<MoxxyEvent>;
   /** Set ctx.model to an id the provider's descriptor list does NOT contain,
    *  so `models.find(...)` misses and the models[0] fallback must kick in. */
@@ -561,6 +584,9 @@ function makeCtx(opts: MakeCtxOpts): ModeContext & { emitted: EmittedEvent[] } {
     // ctx.model may intentionally differ from the descriptor id to exercise the
     // unlisted-model fallback.
     model: opts.ctxModelId ?? opts.model ?? 'fake-model',
+    ...(opts.contextWindowOverride !== undefined
+      ? { contextWindowOverride: opts.contextWindowOverride }
+      : {}),
     provider,
     tools: { list: () => [], get: () => undefined, execute: async () => undefined },
     skills: { list: () => [], get: () => undefined, byName: () => undefined, filterByTriggers: () => [] },

package/src/compactor-helpers.ts

@@ -3,7 +3,7 @@ import {
   conversationalStub,
   conversationalStubbed,
   toolResultBytes,
-  toolResultStub,
+  toolResultStubText,
   toolResultStubbed,
   type ElisionState,
 } from './elision-state.js';
@@ -58,8 +58,7 @@ export function estimateContextTokens(
   for (const e of events) {
     if (isCompacted(e.seq)) continue;
     if (e.type === 'tool_result' && toolResultStubbed(e, el)) {
-      const recalled = el.recalledCallIds.has(e.callId) || el.recalledSeqs.has(e.seq);
-      chars += toolResultStub(e.callId, toolResultBytes(e.output), recalled).length;
+      chars += toolResultStubText(e, el).length;
       continue;
     }
     if ((e.type === 'user_prompt' || e.type === 'assistant_message') && conversationalStubbed(e, el)) {
@@ -116,7 +115,7 @@ function safeJsonLen(v: unknown): number {
  *
  * `config.model` is a free-form, unvalidated string, and providers happily
  * serve ids that aren't in their fixed descriptor list — a newer release
- * (`claude-opus-5`), a dated id, or a model registered at runtime via
+ * (`claude-opus-5-5`), a dated id, or a model registered at runtime via
  * provider-admin. So an exact `models.find(m => m.id === ctx.model)` often
  * MISSES, and both auto-compaction and auto-elision used to silently turn into
  * permanent no-ops for the whole session (the context then grows unbounded and
@@ -139,6 +138,19 @@ export function resolveModelContext(
     ? ctx.provider.models.find((model) => model.id === baseId)
     : undefined;
   const descriptor = exact ?? variant ?? ctx.provider.models[0];
+  const override = ctx.contextWindowOverride;
+  if (
+    override !== undefined && Number.isSafeInteger(override)
+    && override > 0 && override <= 10_000_000
+  ) {
+    const matchingDescriptor = exact ?? variant;
+    const reserveForOutput = matchingDescriptor?.maxOutputTokens
+      ?? Math.floor(override * 0.1);
+    return {
+      contextWindow: override,
+      reserveForOutput: Math.min(reserveForOutput, Math.floor(override * 0.5)),
+    };
+  }
   const contextWindow = descriptor?.contextWindow;
   if (!contextWindow || contextWindow <= 0) return null;
   // Signal (once) when the exact-id lookup missed and we fell back to the first

package/src/computer-control.test.ts

@@ -15,3 +15,14 @@ it('validates bounded control-state snapshots, never executable commands', () =>
   expect(computerControlSnapshotSchema.safeParse({...snapshot,state:'running arbitrary code'}).success).toBe(false);
   expect(computerControlSnapshotSchema.safeParse({...snapshot,windowId:'x'.repeat(200)}).success).toBe(false);
 });
+
+it('carries the agent cursor as a fraction of the target window, and the target the human sees', () => {
+  const snapshot={sessionId:'s',turnId:'t',state:'background',windowId:null,
+    cursor:{phase:'moving',x:0.25,y:1},target:{app:'TextEdit',window:'Untitled'}};
+  expect(computerControlSnapshotSchema.safeParse(snapshot).success).toBe(true);
+  expect(computerControlSnapshotSchema.safeParse({...snapshot,cursor:{...snapshot.cursor,x:1.5}}).success).toBe(false);
+  expect(computerControlSnapshotSchema.safeParse({...snapshot,cursor:{...snapshot.cursor,phase:'teleporting'}}).success).toBe(false);
+  expect(computerControlSnapshotSchema.safeParse({...snapshot,cursor:{...snapshot.cursor,screenX:10}}).success).toBe(false);
+  expect(computerControlSnapshotSchema.safeParse({...snapshot,target:{app:'',window:null}}).success).toBe(false);
+  expect(computerControlSnapshotSchema.safeParse({...snapshot,target:{app:'TextEdit',window:'x'.repeat(300)}}).success).toBe(false);
+});

package/src/computer-control.ts

@@ -6,15 +6,28 @@ export const computerControlStateSchema = z.enum([
 ]);
 const identity = z.string().min(1).max(160);
 export const computerControlOwnerSchema = z.object({ sessionId: identity, turnId: identity }).strict();
+/** `takeover` pauses like `pause`, hides the agent cursor and lets go of any held key or button. */
 export const computerControlCommandSchema = computerControlOwnerSchema.extend({
-  command: z.enum(['pause', 'resume', 'stop']),
+  command: z.enum(['pause', 'resume', 'stop', 'takeover']),
 }).strict();
+/** Where an action is in its life; the cursor overlay and the PiP draw from it. */
+export const computerCursorPhaseSchema = z.enum(['idle', 'moving', 'executing', 'delivered', 'failed']);
+const fraction = z.number().min(0).max(1);
+/** The agent cursor as a fraction of the target window, so any surface can draw it over that window. */
+export const computerCursorSchema = z.object({ phase: computerCursorPhaseSchema, x: fraction, y: fraction }).strict();
+/** The app and window being operated; the window title is application content shown to the human only. */
+export const computerTargetSchema = z.object({ app: identity, window: z.string().max(200).nullable() }).strict();
 export const computerControlSnapshotSchema = computerControlOwnerSchema.extend({
   state: computerControlStateSchema,
   windowId: identity.nullable(),
+  /** Absent while no cursor is shown (before the first observation, after Stop or a helper failure). */
+  cursor: computerCursorSchema.optional(),
+  target: computerTargetSchema.optional(),
 }).strict();
 
 export type ComputerControlState = z.infer<typeof computerControlStateSchema>;
+export type ComputerCursor = z.infer<typeof computerCursorSchema>;
+export type ComputerTarget = z.infer<typeof computerTargetSchema>;
 export const computerApprovalFocusSchema = computerControlOwnerSchema.extend({
   windowId: identity, callId: identity, hostPid: z.number().int().min(1).max(2147483647),
   stage: z.enum(['begin', 'finish']), approved: z.boolean(),
@@ -28,4 +41,6 @@ export interface ComputerControlService {
   snapshot(): Promise<ReadonlyArray<ComputerControlSnapshot>>;
   /** Human control only: never starts a helper or grants tool permission. */
   control(command: ComputerControlCommand): Promise<void>;
+  /** Pushes this session's turns after every change, so surfaces never poll; returns the unsubscribe. */
+  subscribe?(listener: (turns: ReadonlyArray<ComputerControlSnapshot>) => void): () => void;
 }

package/src/conduct.test.ts

@@ -0,0 +1,62 @@
+/**
+ * How Moxxy conducts herself, whatever surface or mode the conversation is on.
+ * Each rule answers a fault seen in a live session: live facts stated without
+ * checking, a choice the user settled lost on a redo, and the voice and the
+ * agent speaking of themselves in different grammatical genders in one chat.
+ */
+import { describe, expect, it } from 'vitest';
+import type { ProviderRequest } from './provider.js';
+import { AGENT_CONDUCT, SELF_REFERENCE_NOTE, withAgentConduct } from './conduct.js';
+
+const request = (system?: string): ProviderRequest => ({
+  model: 'm',
+  messages: [],
+  ...(system !== undefined ? { system } : {}),
+});
+
+describe('SELF_REFERENCE_NOTE', () => {
+  it('asks for the feminine form, with Polish examples, whatever earlier messages used', () => {
+    expect(SELF_REFERENCE_NOTE).toMatch(/feminine/);
+    expect(SELF_REFERENCE_NOTE).toContain('sprawdziłam');
+    expect(SELF_REFERENCE_NOTE).toContain('never "sprawdziłem"');
+    expect(SELF_REFERENCE_NOTE).toMatch(/whatever earlier messages/);
+  });
+});
+
+describe('AGENT_CONDUCT', () => {
+  it('says live facts are only known after checking, and an unchecked one is said to be unchecked', () => {
+    expect(AGENT_CONDUCT).toMatch(/prices, timetables, availability/);
+    expect(AGENT_CONDUCT).toMatch(/Check them with a tool before stating them/);
+    expect(AGENT_CONDUCT).toMatch(/say plainly that you have not checked/);
+  });
+
+  it('carries every choice the user settled into a redo of earlier work', () => {
+    expect(AGENT_CONDUCT).toMatch(/carry over every choice the user already settled/);
+    expect(AGENT_CONDUCT).toMatch(/one-way or return/);
+  });
+
+  it('holds the self-reference rule the voice uses too', () => {
+    expect(AGENT_CONDUCT).toContain(SELF_REFERENCE_NOTE);
+  });
+});
+
+describe('withAgentConduct', () => {
+  it('sets the conduct as the system text when a request has none', () => {
+    expect(withAgentConduct(request()).system).toBe(AGENT_CONDUCT);
+  });
+
+  it('appends it after system text another plugin already added', () => {
+    expect(withAgentConduct(request('[user-model] likes tea')).system).toBe(`[user-model] likes tea\n\n${AGENT_CONDUCT}`);
+  });
+
+  it('adds it once, so a request passed through twice stays byte-identical', () => {
+    const once = withAgentConduct(request('x'));
+    expect(withAgentConduct(once)).toBe(once);
+  });
+
+  it('leaves everything else in the request as it was', () => {
+    const req: ProviderRequest = { model: 'm', messages: [{ role: 'user', content: [{ type: 'text', text: 'hi' }] }], maxTokens: 9 };
+    const out = withAgentConduct(req);
+    expect(out).toMatchObject({ model: 'm', messages: req.messages, maxTokens: 9 });
+  });
+});

package/src/conduct.ts

@@ -0,0 +1,37 @@
+import type { ProviderRequest } from './provider.js';
+
+/**
+ * One grammatical gender for Moxxy, shared by the agent and the voice. Both
+ * write into the same chat, and each tends to copy whatever form it finds
+ * there, so without one rule a chat drifts between "sprawdziłam" and
+ * "sprawdziłem".
+ */
+export const SELF_REFERENCE_NOTE =
+  'Speak of yourself in the feminine grammatical form in every language that marks it ' +
+  '(Polish: "sprawdziłam", "ustawiłam", "jestem gotowa"; never "sprawdziłem"), in every reply, ' +
+  'whatever earlier messages in the chat used.';
+
+const MARKER = '## How Moxxy works';
+
+/** Appended to every agent request, in every mode and on every surface. */
+export const AGENT_CONDUCT = [
+  MARKER,
+  'You are Moxxy.',
+  'Live facts — prices, timetables, availability, opening hours, news, weather, anything about the ' +
+    'current state of the world — are known only after checking. Check them with a tool before stating ' +
+    'them. If you cannot check, say plainly that you have not checked and that they may be out of date. ' +
+    'Never present a remembered or guessed detail as current.',
+  'When you redo or extend earlier work (a new search, a new tab, another attempt), carry over every ' +
+    'choice the user already settled — dates, one-way or return, sizes, names, filters — unless the user ' +
+    'changed it, and check that the result shows them before you report.',
+  SELF_REFERENCE_NOTE,
+].join('\n');
+
+/**
+ * `onBeforeProviderCall` body: append the conduct to the request's system
+ * text. Idempotent and byte-stable, so the cached prompt prefix holds.
+ */
+export function withAgentConduct(request: ProviderRequest): ProviderRequest {
+  if (request.system?.includes(MARKER)) return request;
+  return { ...request, system: request.system ? `${request.system}\n\n${AGENT_CONDUCT}` : AGENT_CONDUCT };
+}

package/src/cross-process-lock.test.ts

@@ -1,8 +1,9 @@
-import { mkdtemp, rm, readdir, utimes } from 'node:fs/promises';
+import { mkdtemp, readdir, utimes } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path, { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { CrossProcessFireLock } from './cross-process-lock.js';
+import { removeDir } from '@moxxy/vitest-preset/fs';
 
 describe('CrossProcessFireLock', () => {
   let dir: string;
@@ -10,7 +11,7 @@ describe('CrossProcessFireLock', () => {
     dir = await mkdtemp(path.join(tmpdir(), 'moxxy-xproc-lock-'));
   });
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true });
+    await removeDir(dir);
   });
 
   it('claims a key exactly once — the first caller wins, the rest lose', async () => {

package/src/define.ts

@@ -49,6 +49,9 @@ export function defineTool<S extends z.ZodTypeAny, O = unknown>(spec: {
   compact?: ToolCompactPresentation;
   icon?: ToolIcon;
   isolation?: ToolIsolationSpec;
+  liveState?: boolean;
+  alwaysLoaded?: boolean;
+  modes?: ReadonlyArray<string>;
 }): ToolDef {
   return Object.freeze({
     name: spec.name,
@@ -62,6 +65,9 @@ export function defineTool<S extends z.ZodTypeAny, O = unknown>(spec: {
     compact: spec.compact,
     icon: spec.icon,
     isolation: spec.isolation,
+    ...(spec.liveState ? { liveState: true } : {}),
+    ...(spec.alwaysLoaded ? { alwaysLoaded: true } : {}),
+    ...(spec.modes ? { modes: Object.freeze([...spec.modes]) } : {}),
   });
 }
 

package/src/elision-state.ts

@@ -1,4 +1,5 @@
 import type { MoxxyEvent } from './events.js';
+import { supersededCallIds, supersededStub } from './supersede.js';
 import { isToolDisplayResult } from './tool-display.js';
 
 /**
@@ -56,6 +57,11 @@ export interface ElisionState {
   readonly unpinnedRecallCallIds: ReadonlySet<string>;
   /** Seq of the first user_prompt (task anchor) — never elided. */
   readonly firstUserPromptSeq: number;
+  /**
+   * callIds of results a later whole result of the same key replaced (see
+   * `supersede.ts`). Independent of the high-water mark: stubbed at any age.
+   */
+  readonly supersededCallIds?: ReadonlySet<string>;
 }
 
 const EMPTY_STATE: ElisionState = {
@@ -118,6 +124,9 @@ export function computeElisionState(events: ReadonlyArray<MoxxyEvent>): ElisionS
 }
 
 function computeElisionStateUncached(events: ReadonlyArray<MoxxyEvent>): ElisionState {
+  const superseded = supersededCallIds(events);
+  const withSuperseded = (state: ElisionState): ElisionState =>
+    superseded.size > 0 ? { ...state, supersededCallIds: superseded } : state;
   let hwm = -1;
   let elideConversational = false;
   let conversationalRecallThreshold = Number.POSITIVE_INFINITY;
@@ -132,7 +141,7 @@ function computeElisionStateUncached(events: ReadonlyArray<MoxxyEvent>): Elision
       neverElide = e.neverElideTools;
     }
   }
-  if (hwm < 0) return EMPTY_STATE;
+  if (hwm < 0) return withSuperseded(EMPTY_STATE);
 
   const toolNameByCall = new Map<string, string>();
   const recalledCallIds = new Set<string>();
@@ -185,7 +194,7 @@ function computeElisionStateUncached(events: ReadonlyArray<MoxxyEvent>): Elision
     }
   }
 
-  return {
+  return withSuperseded({
     hwm,
     effectiveElideConversational: elideConversational && seqRecalls < conversationalRecallThreshold,
     neverElide: new Set(neverElide),
@@ -195,7 +204,7 @@ function computeElisionStateUncached(events: ReadonlyArray<MoxxyEvent>): Elision
     recallResultCallIds,
     unpinnedRecallCallIds,
     firstUserPromptSeq,
-  };
+  });
 }
 
 /** Is this tool_result sent as a stub? (Shared by projection + estimate.) */
@@ -203,6 +212,7 @@ export function toolResultStubbed(
   e: Extract<MoxxyEvent, { type: 'tool_result' }>,
   state: ElisionState,
 ): boolean {
+  if (!e.error && state.supersededCallIds?.has(e.callId)) return true;
   if (e.seq > state.hwm || e.error) return false;
   const name = state.toolNameByCall.get(e.callId);
   if (name !== undefined && state.neverElide.has(name)) return false;
@@ -214,6 +224,17 @@ export function toolResultStubbed(
   return true;
 }
 
+/** What a stubbed tool_result is sent as: the superseded marker, or the elided one. */
+export function toolResultStubText(
+  e: Extract<MoxxyEvent, { type: 'tool_result' }>,
+  state: ElisionState,
+): string {
+  const recalled = state.recalledCallIds.has(e.callId) || state.recalledSeqs.has(e.seq);
+  const bytes = toolResultBytes(e.output);
+  if (!recalled && state.supersededCallIds?.has(e.callId)) return supersededStub(e.callId, bytes);
+  return toolResultStub(e.callId, bytes, recalled);
+}
+
 /** Is this user/assistant turn collapsed to a conversational stub? */
 export function conversationalStubbed(
   e: Extract<MoxxyEvent, { type: 'user_prompt' | 'assistant_message' }>,

package/src/events.ts

@@ -64,9 +64,13 @@ export interface UserPromptAttachment {
  * kinds it does not open a turn — renderers that treat `user_prompt` as a
  * turn boundary must skip their boundary resets for it (see chat-model's
  * pair-events).
+ *
+ * `kind: 'voice'` marks the voice conversation (GPT-Live) held while an agent
+ * turn ran and recorded after it as one transcript: context for later turns,
+ * not a request, and shown as one collapsed block.
  */
 export interface TriggerOrigin {
-  readonly kind: 'webhook' | 'schedule' | 'workflow' | 'checkpoint';
+  readonly kind: 'webhook' | 'schedule' | 'workflow' | 'checkpoint' | 'voice';
   /** The trigger's name (webhook/schedule/workflow/checkpoint), for the marker label. */
   readonly name: string;
 }
@@ -137,6 +141,8 @@ export interface ToolCallApprovedEvent extends EventBase {
   readonly callId: ToolCallId;
   readonly decidedBy: 'policy' | 'resolver' | 'hook';
   readonly mode: 'allow' | 'allow_session' | 'allow_always';
+  /** See `PermissionDecision.decidedNow`. */
+  readonly decidedNow?: boolean;
 }
 
 export interface ToolCallDeniedEvent extends EventBase {
@@ -232,6 +238,12 @@ export interface CompactionEvent extends EventBase {
   readonly replacedRange: readonly [number, number];
   readonly summary: string;
   readonly tokensSaved: number;
+  /**
+   * A step of the compactor's regular bookkeeping (recording a finished turn,
+   * folding old records) rather than a response to a nearly full context.
+   * Surfaces may leave it out of the transcript; it still frees context.
+   */
+  readonly routine?: true;
 }
 
 /**

package/src/finish-pairing.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { EXIT_AFTER_PAIR_FLAG, finishPairing } from './channel.js';
+
+/** Records the order of the two lifecycle steps a finished pairing performs. */
+function harness(flags: Record<string, string | boolean | undefined> = {}) {
+  const steps: string[] = [];
+  const ctx = {
+    args: { positional: [], flags },
+    deps: { cwd: '/tmp' },
+    startChannel: async (options?: Readonly<Record<string, unknown>>) => {
+      steps.push(`start:${JSON.stringify(options ?? {})}`);
+      return 7;
+    },
+  };
+  const stopPairingBot = async () => {
+    steps.push('stop-pairing-bot');
+  };
+  return { ctx, stopPairingBot, steps };
+}
+
+describe('finishPairing', () => {
+  it('stops the pairing bot (it runs on a provider-less probe session) and starts the channel for real', async () => {
+    const { ctx, stopPairingBot, steps } = harness();
+
+    const code = await finishPairing(ctx, stopPairingBot);
+
+    expect(steps).toEqual(['stop-pairing-bot', 'start:{}']);
+    expect(code).toBe(7);
+  });
+
+  it('forwards the channel start options (e.g. an allow-list chosen during setup)', async () => {
+    const { ctx, stopPairingBot, steps } = harness();
+
+    await finishPairing(ctx, stopPairingBot, { allowedTools: ['Read'] });
+
+    expect(steps).toEqual(['stop-pairing-bot', 'start:{"allowedTools":["Read"]}']);
+  });
+
+  it('hands control back without starting when an orchestrator asked to exit after pairing', async () => {
+    const { ctx, stopPairingBot, steps } = harness({ [EXIT_AFTER_PAIR_FLAG]: true });
+
+    expect(await finishPairing(ctx, stopPairingBot)).toBe(0);
+    expect(steps).toEqual(['stop-pairing-bot']);
+  });
+});

package/src/fs-utils.test.ts

@@ -1,8 +1,10 @@
 import { generateKeyPairSync, sign } from 'node:crypto';
-import { chmod, mkdir, mkdtemp, readFile, readdir, stat, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import { chmod, mkdir, mkdtemp, open, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { Worker } from 'node:worker_threads';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { posixFileModes } from '@moxxy/vitest-preset/platform';
 import {
   ensurePrivateDir,
   ensurePrivateFile,
@@ -37,7 +39,7 @@ describe('writeFileAtomic', () => {
     expect(leftovers).toEqual([]);
   });
 
-  it('enforces the requested mode past umask', async () => {
+  it.skipIf(!posixFileModes)('enforces the requested mode past umask', async () => {
     const target = join(dir, 'secret.json');
     await writeFileAtomic(target, 'shh', { mode: 0o600 });
     const mode = (await stat(target)).mode & 0o777;
@@ -51,6 +53,19 @@ describe('writeFileAtomic', () => {
     const read = await readFile(target);
     expect(Array.from(read)).toEqual([0, 1, 2, 255]);
   });
+
+  // Windows refuses to rename over a file another handle has open (EPERM), so a
+  // reader that happens to be mid-read — another moxxy process loading
+  // config.yaml — used to make the write fail outright.
+  it('lands while another reader briefly holds the file open', async () => {
+    const target = join(dir, 'config.yaml');
+    await writeFile(target, 'old');
+    const reader = await open(target, 'r');
+    const released = new Promise((resolve) => setTimeout(resolve, 100)).then(() => reader.close());
+    await writeFileAtomic(target, 'new');
+    await released;
+    expect(await readFile(target, 'utf8')).toBe('new');
+  });
 });
 
 describe('network cache writers', () => {
@@ -133,7 +148,7 @@ describe('writeFileAtomicSync', () => {
     expect(leftovers).toEqual([]);
   });
 
-  it('enforces the requested mode past umask', async () => {
+  it.skipIf(!posixFileModes)('enforces the requested mode past umask', async () => {
     const target = join(dir, 'secret.json');
     writeFileAtomicSync(target, 'shh', { mode: 0o600 });
     const mode = (await stat(target)).mode & 0o777;
@@ -146,6 +161,25 @@ describe('writeFileAtomicSync', () => {
     expect(Array.from(await readFile(target))).toEqual([0, 1, 2, 255]);
   });
 
+  it('lands while another thread briefly holds the file open', async () => {
+    const target = join(dir, 'config.yaml');
+    await writeFile(target, 'old');
+    // A worker holds the handle: this thread blocks inside the sync write, so it
+    // could not release a handle of its own.
+    const holder = new Worker(
+      `const { openSync, closeSync } = require('node:fs');
+       const { parentPort, workerData } = require('node:worker_threads');
+       const fd = openSync(workerData, 'r');
+       parentPort.postMessage('open');
+       setTimeout(() => closeSync(fd), 100);`,
+      { eval: true, workerData: target },
+    );
+    await new Promise((resolve) => holder.once('message', resolve));
+    writeFileAtomicSync(target, 'new');
+    await new Promise((resolve) => holder.once('exit', resolve));
+    expect(await readFile(target, 'utf8')).toBe('new');
+  });
+
   it('cleans up the temp file and throws when rename fails', async () => {
     // A directory in place of the final file makes renameSync fail; the temp
     // file must be removed and the error surfaced rather than swallowed.
@@ -168,12 +202,12 @@ describe('moxxyHome / moxxyPath', () => {
   it('honors MOXXY_HOME when set', () => {
     process.env.MOXXY_HOME = '/custom/moxxy';
     expect(moxxyHome()).toBe('/custom/moxxy');
-    expect(moxxyPath('vault.json')).toBe('/custom/moxxy/vault.json');
+    expect(moxxyPath('vault.json')).toBe(join('/custom/moxxy', 'vault.json'));
   });
 
   it('falls back to ~/.moxxy when unset', () => {
     delete process.env.MOXXY_HOME;
-    expect(moxxyHome().endsWith('/.moxxy')).toBe(true);
+    expect(moxxyHome()).toBe(join(homedir(), '.moxxy'));
   });
 });
 

package/src/fs-utils.ts

@@ -75,13 +75,53 @@ async function commitAtomic(
     // chmod explicitly: writeFile's mode option is masked by umask, but a
     // 0o600 secret file must be exactly 0o600 regardless of the host umask.
     if (opts.mode != null) await chmod(tmp, opts.mode);
-    await rename(tmp, target);
+    await renameOverReaders(tmp, target);
   } catch (err) {
     await rm(tmp, { force: true }).catch(() => {});
     throw err;
   }
 }
 
+/**
+ * Windows refuses to rename over a file that any other handle has open — a
+ * reader mid-read in this or another process — with EPERM / EACCES / EBUSY.
+ * Readers hold the file for milliseconds, so the rename is retried briefly
+ * instead of failing the write. Elsewhere rename never blocks on readers.
+ */
+const RENAME_RETRY_BUDGET_MS = 2000;
+const MAX_RENAME_BACKOFF_MS = 50;
+
+function isHeldByReader(err: unknown): boolean {
+  if (process.platform !== 'win32') return false;
+  const code = (err as NodeJS.ErrnoException | null)?.code;
+  return code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+}
+
+async function renameOverReaders(from: string, to: string): Promise<void> {
+  const deadline = Date.now() + RENAME_RETRY_BUDGET_MS;
+  for (let backoff = 1; ; backoff = Math.min(backoff * 2, MAX_RENAME_BACKOFF_MS)) {
+    try {
+      return await rename(from, to);
+    } catch (err) {
+      if (!isHeldByReader(err) || Date.now() >= deadline) throw err;
+      await new Promise((resolve) => setTimeout(resolve, backoff));
+    }
+  }
+}
+
+function renameOverReadersSync(from: string, to: string): void {
+  const deadline = Date.now() + RENAME_RETRY_BUDGET_MS;
+  const pause = new Int32Array(new SharedArrayBuffer(4));
+  for (let backoff = 1; ; backoff = Math.min(backoff * 2, MAX_RENAME_BACKOFF_MS)) {
+    try {
+      return renameSync(from, to);
+    } catch (err) {
+      if (!isHeldByReader(err) || Date.now() >= deadline) throw err;
+      Atomics.wait(pause, 0, 0, backoff);
+    }
+  }
+}
+
 /**
  * Persist an authenticated network payload as a data-only cache envelope.
  * Verification happens again at the filesystem boundary so callers cannot
@@ -166,7 +206,7 @@ function commitAtomicSync(
     // chmod explicitly: writeFileSync's mode option is masked by umask, but a
     // 0o600 secret file must be exactly 0o600 regardless of the host umask.
     if (opts.mode != null) chmodSync(tmp, opts.mode);
-    renameSync(tmp, target);
+    renameOverReadersSync(tmp, target);
   } catch (err) {
     try {
       rmSync(tmp, { force: true });