@moxxy/sdk 0.32.0 → 0.34.0

package/src/egress.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  hasProxy,
+  installEgressProxy,
+  parseNoProxy,
+  readProxyEnv,
+  redactProxyUrl,
+  shouldBypassProxy,
+} from './egress.js';
+
+describe('readProxyEnv', () => {
+  it('reads uppercase and lowercase forms', () => {
+    expect(readProxyEnv({ HTTPS_PROXY: 'http://p:3128' })).toEqual({ httpsProxy: 'http://p:3128' });
+    expect(readProxyEnv({ https_proxy: 'http://p:3128' })).toEqual({ httpsProxy: 'http://p:3128' });
+  });
+
+  // Lowercase wins by convention (curl, requests, Go): a shell exporting both
+  // usually set the lowercase one deliberately and more recently.
+  it('prefers the lowercase form when both are set', () => {
+    const env = { https_proxy: 'http://lower:1', HTTPS_PROXY: 'http://upper:2' };
+    expect(readProxyEnv(env).httpsProxy).toBe('http://lower:1');
+  });
+
+  it('treats blank and whitespace values as unset', () => {
+    expect(readProxyEnv({ HTTPS_PROXY: '', HTTP_PROXY: '   ' })).toEqual({});
+  });
+
+  // A plaintext-only proxy declared via http_proxy must not silently swallow
+  // TLS traffic; https origins go direct instead of failing confusingly.
+  it('does not fall back to http_proxy for https origins', () => {
+    expect(readProxyEnv({ HTTP_PROXY: 'http://p:3128' })).toEqual({ httpProxy: 'http://p:3128' });
+  });
+});
+
+describe('parseNoProxy', () => {
+  it('splits on commas and whitespace, lowercases, and drops blanks', () => {
+    expect(parseNoProxy(' localhost, .Corp.Example  10.0.0.1 ,, ')).toEqual([
+      'localhost',
+      '.corp.example',
+      '10.0.0.1',
+    ]);
+  });
+
+  it('returns an empty list for undefined', () => {
+    expect(parseNoProxy(undefined)).toEqual([]);
+  });
+});
+
+describe('shouldBypassProxy', () => {
+  const bypass = (origin: string, rules: string): boolean =>
+    shouldBypassProxy(origin, parseNoProxy(rules));
+
+  it('bypasses everything on *', () => {
+    expect(bypass('https://api.anthropic.com', '*')).toBe(true);
+  });
+
+  it('matches an exact host on any port', () => {
+    expect(bypass('http://localhost:8080/x', 'localhost')).toBe(true);
+    expect(bypass('https://localhost', 'localhost')).toBe(true);
+    expect(bypass('https://notlocalhost', 'localhost')).toBe(false);
+  });
+
+  // A leading dot covers the apex too, matching curl. Getting this wrong sends
+  // internal traffic through the proxy, which is exactly what NO_PROXY exists
+  // to prevent.
+  it('matches subdomains and the apex for a dotted rule', () => {
+    expect(bypass('https://api.corp.example', '.corp.example')).toBe(true);
+    expect(bypass('https://corp.example', '.corp.example')).toBe(true);
+    expect(bypass('https://deep.api.corp.example', '.corp.example')).toBe(true);
+    expect(bypass('https://evilcorp.example', '.corp.example')).toBe(false);
+  });
+
+  it('treats *.domain the same as .domain', () => {
+    expect(bypass('https://api.corp.example', '*.corp.example')).toBe(true);
+  });
+
+  it('honours a port qualifier', () => {
+    expect(bypass('http://registry.internal:8081/x', 'registry.internal:8081')).toBe(true);
+    expect(bypass('http://registry.internal:9999/x', 'registry.internal:8081')).toBe(false);
+  });
+
+  it('resolves the implicit port from the scheme', () => {
+    expect(bypass('https://svc.internal/x', 'svc.internal:443')).toBe(true);
+    expect(bypass('http://svc.internal/x', 'svc.internal:80')).toBe(true);
+    expect(bypass('https://svc.internal/x', 'svc.internal:80')).toBe(false);
+  });
+
+  // `::1` must not be read as host ":" on port "1".
+  it('does not mistake an IPv6 literal for a host:port rule', () => {
+    expect(bypass('http://[::1]:7000/x', '::1')).toBe(true);
+  });
+
+  it('is case-insensitive on the host', () => {
+    expect(bypass('https://API.Corp.Example', '.corp.example')).toBe(true);
+  });
+
+  it('never bypasses with no rules, or on an unparseable origin', () => {
+    expect(bypass('https://api.anthropic.com', '')).toBe(false);
+    expect(shouldBypassProxy('not a url', ['*.corp.example'])).toBe(false);
+  });
+});
+
+describe('redactProxyUrl', () => {
+  it('masks embedded credentials', () => {
+    expect(redactProxyUrl('http://alice:hunter2@proxy.corp:3128')).toBe('http://***:***@proxy.corp:3128/');
+  });
+
+  it('leaves a credential-free url intact', () => {
+    expect(redactProxyUrl('http://proxy.corp:3128')).toBe('http://proxy.corp:3128/');
+  });
+
+  // Never echo something unparseable: it might be a secret pasted by mistake.
+  it('reveals nothing for an unparseable value', () => {
+    expect(redactProxyUrl('hunter2')).toBe('<invalid proxy url>');
+  });
+});
+
+describe('installEgressProxy', () => {
+  /**
+   * Stand-in for undici. Each agent reports its own label through the dispatch
+   * handler, so `routeOf` observes WHICH agent the router picked for an origin,
+   * which is the whole contract worth testing here.
+   */
+  const fakeUndici = () => {
+    let installed: { dispatch: (o: { origin?: string }, h: unknown) => boolean } | null = null;
+    const agent = (label: string) => ({
+      dispatch: (_o: unknown, h: { onPick?: (l: string) => void }) => {
+        h.onPick?.(label);
+        return true;
+      },
+      close: async () => {},
+      destroy: async () => {},
+    });
+    return {
+      routeOf: (origin: string): string => {
+        let picked = '';
+        installed!.dispatch({ origin }, {
+          onPick: (l: string) => {
+            picked = l;
+          },
+        });
+        return picked;
+      },
+      module: {
+        Agent: function Agent() {
+          return agent('direct');
+        } as never,
+        ProxyAgent: function ProxyAgent(o: { uri: string }) {
+          return agent(`proxy:${o.uri}`);
+        } as never,
+        setGlobalDispatcher: (d: never) => {
+          installed = d;
+        },
+      },
+    };
+  };
+
+  it('no-ops when no proxy is configured', async () => {
+    const status = await installEgressProxy({});
+    expect(status).toEqual({ enabled: false, reason: 'no proxy configured' });
+  });
+
+  it('reports and skips an unparseable proxy url instead of throwing', async () => {
+    const warn = vi.fn();
+    const status = await installEgressProxy({ httpsProxy: 'not a url' }, { warn });
+    expect(status.enabled).toBe(false);
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('https_proxy is not a valid URL'));
+  });
+
+  // A proxy is configured but the dependency is missing: degrade to direct with
+  // a loud warning rather than a failed boot.
+  it('warns and degrades when undici cannot be loaded', async () => {
+    const warn = vi.fn();
+    const status = await installEgressProxy(
+      { httpsProxy: 'http://p:3128' },
+      { warn, loadUndici: () => Promise.reject(new Error('not installed')) },
+    );
+    expect(status.enabled).toBe(false);
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('`undici` package is unavailable'));
+  });
+
+  it('installs a dispatcher and redacts credentials in the reported status', async () => {
+    const u = fakeUndici();
+    const status = await installEgressProxy(
+      { httpsProxy: 'http://bob:secret@p:3128', noProxy: 'localhost' },
+      { loadUndici: async () => u.module as never },
+    );
+    expect(status.enabled).toBe(true);
+    expect(status.httpsProxy).toBe('http://***:***@p:3128/');
+    expect(status.httpsProxy).not.toContain('secret');
+    expect(status.noProxy).toEqual(['localhost']);
+  });
+
+  it('routes https through the proxy and bypassed hosts direct', async () => {
+    const u = fakeUndici();
+    await installEgressProxy(
+      { httpsProxy: 'http://p:3128', noProxy: '.corp.example' },
+      { loadUndici: async () => u.module as never },
+    );
+    expect(u.routeOf('https://api.anthropic.com')).toBe('proxy:http://p:3128');
+    expect(u.routeOf('https://git.corp.example')).toBe('direct');
+  });
+
+  // Only http_proxy set: https origins must go direct, not through it.
+  it('sends https direct when only an http proxy is configured', async () => {
+    const u = fakeUndici();
+    await installEgressProxy(
+      { httpProxy: 'http://p:3128' },
+      { loadUndici: async () => u.module as never },
+    );
+    expect(u.routeOf('http://example.com')).toBe('proxy:http://p:3128');
+    expect(u.routeOf('https://example.com')).toBe('direct');
+  });
+});
+
+describe('hasProxy', () => {
+  it('is true when either proxy is set', () => {
+    expect(hasProxy({})).toBe(false);
+    expect(hasProxy({ noProxy: 'localhost' })).toBe(false);
+    expect(hasProxy({ httpProxy: 'http://p' })).toBe(true);
+    expect(hasProxy({ httpsProxy: 'http://p' })).toBe(true);
+  });
+});
+
+describe('shouldBypassProxy IPv6 port qualifiers', () => {
+  const bypass = (origin: string, rules: string): boolean =>
+    shouldBypassProxy(origin, parseNoProxy(rules));
+
+  // A port on an IPv6 address requires brackets, exactly as in a URL.
+  it('honours a bracketed IPv6 host:port rule', () => {
+    expect(bypass('http://[::1]:7000/x', '[::1]:7000')).toBe(true);
+    expect(bypass('http://[::1]:9999/x', '[::1]:7000')).toBe(false);
+  });
+
+  it('matches a bracketed IPv6 rule on any port', () => {
+    expect(bypass('http://[::1]:7000/x', '[::1]')).toBe(true);
+  });
+});

package/src/egress.ts

@@ -0,0 +1,274 @@
+/**
+ * Outbound HTTP egress: corporate proxy support for everything moxxy fetches.
+ *
+ * Node's global `fetch` ignores `HTTPS_PROXY` entirely, and every provider
+ * reaches its API through it (`@anthropic-ai/sdk`, `openai`, and the plain
+ * `fetch` calls in tools). On a network that requires an outbound proxy that
+ * means the first provider call fails with an opaque network error and there is
+ * no setting that fixes it. Installing a global undici dispatcher is the only
+ * way to route global `fetch` through a proxy.
+ *
+ * `undici` is imported DYNAMICALLY and only when a proxy is actually configured,
+ * so `@moxxy/sdk` keeps zero hard runtime dependencies and a host with no proxy
+ * pays nothing. The package is a real dependency of `@moxxy/cli`.
+ *
+ * Not handled here, on purpose: a corporate TLS-terminating CA is Node's job,
+ * via `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` in the environment before Node
+ * starts. There is no in-process equivalent, so the doctor surfaces whether it
+ * is set rather than pretending to configure it.
+ */
+
+/** Proxy inputs, already resolved from env and/or config. */
+export interface EgressProxySettings {
+  /** Proxy for `http:` origins. */
+  readonly httpProxy?: string;
+  /** Proxy for `https:` origins. */
+  readonly httpsProxy?: string;
+  /** Raw `NO_PROXY` value: comma/whitespace separated bypass rules. */
+  readonly noProxy?: string;
+}
+
+export interface EgressStatus {
+  /** True when a global dispatcher was installed. */
+  readonly enabled: boolean;
+  /** Credential-redacted proxy in use for `http:`, when set. */
+  readonly httpProxy?: string;
+  /** Credential-redacted proxy in use for `https:`, when set. */
+  readonly httpsProxy?: string;
+  /** Parsed bypass rules. */
+  readonly noProxy?: ReadonlyArray<string>;
+  /** Why nothing was installed, or why installation failed. */
+  readonly reason?: string;
+}
+
+/**
+ * Read proxy settings from an environment. Lowercase wins over uppercase, which
+ * is the de-facto convention (curl, requests, Go): a shell that exports both
+ * usually means the lowercase one was set deliberately and more recently.
+ *
+ * `http_proxy` is deliberately NOT used as a fallback for https origins. Some
+ * environments set only `http_proxy` for a plaintext-only proxy, and silently
+ * tunnelling TLS through it would fail confusingly rather than going direct.
+ */
+export function readProxyEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): EgressProxySettings {
+  const pick = (lower: string, upper: string): string | undefined => {
+    const value = (env[lower] ?? env[upper] ?? '').trim();
+    return value.length > 0 ? value : undefined;
+  };
+  const httpProxy = pick('http_proxy', 'HTTP_PROXY');
+  const httpsProxy = pick('https_proxy', 'HTTPS_PROXY');
+  const noProxy = pick('no_proxy', 'NO_PROXY');
+  return {
+    ...(httpProxy ? { httpProxy } : {}),
+    ...(httpsProxy ? { httpsProxy } : {}),
+    ...(noProxy ? { noProxy } : {}),
+  };
+}
+
+/** Split a `NO_PROXY` value into normalized rules. Separators are commas and
+ *  whitespace; empty entries are dropped and matching is case-insensitive. */
+export function parseNoProxy(value: string | undefined): string[] {
+  if (!value) return [];
+  return value
+    .split(/[,\s]+/)
+    .map((rule) => rule.trim().toLowerCase())
+    .filter((rule) => rule.length > 0);
+}
+
+/**
+ * Whether `origin` bypasses the proxy under `rules` (already parsed by
+ * {@link parseNoProxy}).
+ *
+ * Follows the de-facto `NO_PROXY` convention rather than inventing one:
+ *   - `*` bypasses everything.
+ *   - a bare host matches that host exactly, on any port.
+ *   - a leading `.` or `*.` matches the domain and every subdomain, so
+ *     `.corp.example` covers `api.corp.example` AND `corp.example`.
+ *   - an entry carrying `:port` matches only that port; the origin's port is
+ *     resolved from the scheme when the URL omits it.
+ *
+ * A malformed origin never bypasses: failing closed here sends the request
+ * through the proxy, which an operator can observe, rather than silently
+ * leaking it direct.
+ */
+export function shouldBypassProxy(origin: string, rules: ReadonlyArray<string>): boolean {
+  if (rules.length === 0) return false;
+  if (rules.includes('*')) return true;
+
+  let url: URL;
+  try {
+    url = new URL(origin);
+  } catch {
+    return false;
+  }
+  const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  const port = url.port || (url.protocol === 'https:' ? '443' : '80');
+
+  for (const rule of rules) {
+    const { host: ruleHost, port: rulePort } = splitRule(rule);
+    if (rulePort !== undefined && rulePort !== port) continue;
+    if (ruleHost.length === 0) continue;
+
+    const suffix = ruleHost.startsWith('*.')
+      ? ruleHost.slice(1)
+      : ruleHost.startsWith('.')
+        ? ruleHost
+        : undefined;
+    if (suffix) {
+      // `.corp.example` covers the apex too, matching curl.
+      if (host === suffix.slice(1) || host.endsWith(suffix)) return true;
+      continue;
+    }
+    if (host === ruleHost) return true;
+  }
+  return false;
+}
+
+/**
+ * Split a bypass rule into host and optional port.
+ *
+ * A bare IPv6 literal contains colons of its own, so `::1` must not be read as
+ * host `:` on port `1`. As in a URL, a port qualifier on an IPv6 address
+ * requires brackets (`[::1]:7000`); an unbracketed rule with more than one
+ * colon is therefore an address, never a host:port pair.
+ */
+function splitRule(rule: string): { host: string; port?: string } {
+  if (rule.startsWith('[')) {
+    const end = rule.indexOf(']');
+    if (end === -1) return { host: rule.slice(1) };
+    const host = rule.slice(1, end);
+    const rest = rule.slice(end + 1);
+    return rest.startsWith(':') && /^\d+$/.test(rest.slice(1))
+      ? { host, port: rest.slice(1) }
+      : { host };
+  }
+  const first = rule.indexOf(':');
+  if (first === -1 || first !== rule.lastIndexOf(':')) return { host: rule };
+  const maybePort = rule.slice(first + 1);
+  return /^\d+$/.test(maybePort)
+    ? { host: rule.slice(0, first), port: maybePort }
+    : { host: rule };
+}
+
+/**
+ * A proxy URL with any embedded credentials masked, safe to log or show in
+ * `moxxy doctor`. Proxy URLs routinely carry `user:password@`, and this string
+ * ends up on terminals and in support pastes.
+ */
+export function redactProxyUrl(value: string): string {
+  try {
+    const url = new URL(value);
+    if (!url.username && !url.password) return url.toString();
+    url.username = url.username ? '***' : '';
+    url.password = url.password ? '***' : '';
+    return url.toString();
+  } catch {
+    // Unparseable: reveal nothing rather than echoing a possible secret.
+    return '<invalid proxy url>';
+  }
+}
+
+/** True when at least one proxy is configured, i.e. there is work to do. */
+export function hasProxy(settings: EgressProxySettings): boolean {
+  return Boolean(settings.httpProxy ?? settings.httpsProxy);
+}
+
+interface UndiciModule {
+  readonly Agent: new (opts?: unknown) => UndiciDispatcher;
+  readonly ProxyAgent: new (opts: { uri: string }) => UndiciDispatcher;
+  readonly setGlobalDispatcher: (dispatcher: UndiciDispatcher) => void;
+}
+
+interface UndiciDispatcher {
+  dispatch(opts: { origin?: string | URL }, handler: unknown): boolean;
+  close(): Promise<void>;
+  destroy(): Promise<void>;
+}
+
+export interface InstallEgressProxyOptions {
+  /** Surface for the "configured but unusable" case. Defaults to stderr. */
+  readonly warn?: (message: string) => void;
+  /** Injectable module loader for tests. */
+  readonly loadUndici?: () => Promise<UndiciModule>;
+}
+
+/**
+ * Install a global dispatcher routing outbound requests through the configured
+ * proxy, honouring the bypass rules. No-ops (and reports why) when no proxy is
+ * configured, so this is safe to call unconditionally at boot.
+ *
+ * Never throws: a broken proxy setting must degrade to a loud warning plus
+ * direct connections, not a failed boot.
+ */
+export async function installEgressProxy(
+  settings: EgressProxySettings,
+  opts: InstallEgressProxyOptions = {},
+): Promise<EgressStatus> {
+  if (!hasProxy(settings)) return { enabled: false, reason: 'no proxy configured' };
+
+  const warn = opts.warn ?? ((m: string) => process.stderr.write(`[moxxy] ${m}\n`));
+  for (const [label, value] of [
+    ['http_proxy', settings.httpProxy],
+    ['https_proxy', settings.httpsProxy],
+  ] as const) {
+    if (value === undefined) continue;
+    try {
+      new URL(value);
+    } catch {
+      const reason = `${label} is not a valid URL; continuing without a proxy`;
+      warn(reason);
+      return { enabled: false, reason };
+    }
+  }
+
+  let undici: UndiciModule;
+  try {
+    undici = await (opts.loadUndici ?? defaultLoadUndici)();
+  } catch {
+    const reason =
+      'a proxy is configured but the `undici` package is unavailable; ' +
+      'outbound requests will bypass it and may fail';
+    warn(reason);
+    return { enabled: false, reason };
+  }
+
+  const rules = parseNoProxy(settings.noProxy);
+  const direct = new undici.Agent();
+  const httpProxy = settings.httpProxy ? new undici.ProxyAgent({ uri: settings.httpProxy }) : undefined;
+  const httpsProxy = settings.httpsProxy
+    ? new undici.ProxyAgent({ uri: settings.httpsProxy })
+    : undefined;
+
+  const route = (origin: string | URL | undefined): UndiciDispatcher => {
+    if (origin === undefined) return direct;
+    const href = typeof origin === 'string' ? origin : origin.href;
+    if (shouldBypassProxy(href, rules)) return direct;
+    const secure = href.startsWith('https:');
+    return (secure ? httpsProxy : httpProxy) ?? direct;
+  };
+
+  const all = [direct, httpProxy, httpsProxy].filter(Boolean) as UndiciDispatcher[];
+  const router: UndiciDispatcher = {
+    dispatch: (dispatchOpts, handler) => route(dispatchOpts.origin).dispatch(dispatchOpts, handler),
+    close: async () => {
+      await Promise.all(all.map((d) => d.close()));
+    },
+    destroy: async () => {
+      await Promise.all(all.map((d) => d.destroy()));
+    },
+  };
+  undici.setGlobalDispatcher(router);
+
+  return {
+    enabled: true,
+    ...(settings.httpProxy ? { httpProxy: redactProxyUrl(settings.httpProxy) } : {}),
+    ...(settings.httpsProxy ? { httpsProxy: redactProxyUrl(settings.httpsProxy) } : {}),
+    ...(rules.length > 0 ? { noProxy: rules } : {}),
+  };
+}
+
+async function defaultLoadUndici(): Promise<UndiciModule> {
+  return (await import('undici')) as unknown as UndiciModule;
+}

package/src/events.ts

@@ -1,4 +1,5 @@
 import type { EventId, PluginId, SessionId, SkillId, ToolCallId, TurnId } from './ids.js';
+import type { Principal } from './principal.js';
 
 export type EventSource = 'user' | 'model' | 'tool' | 'plugin' | 'system' | 'compactor';
 
@@ -10,6 +11,23 @@ export interface EventBase {
   readonly turnId: TurnId;
   readonly causationId?: EventId;
   readonly source: EventSource;
+  /**
+   * Who the action was taken on behalf of. `source` is a CATEGORY (user, model,
+   * tool, …); this is the SUBJECT, and without it a transcript proves a machine
+   * did something rather than that a person did.
+   *
+   * Stamped on EVERY event, not only turn boundaries, and carrying the whole
+   * principal rather than a reference. That repeats ~55 bytes per event, which
+   * is small against an envelope that already carries three ULIDs, and it buys
+   * the property an audit sink needs: a single record is self-attributing, so
+   * shipping one line to a SIEM requires no fold and no join. This is the same
+   * trade CloudTrail and the Kubernetes audit log make.
+   *
+   * OPTIONAL because the log is append-only and persisted: sessions recorded
+   * before identity existed replay with no actor, and must keep replaying.
+   * Treat absent as "unattributed", never as an error.
+   */
+  readonly actor?: Principal;
 }
 
 export interface UserPromptAttachment {

package/src/fs-utils.test.ts

@@ -1,8 +1,16 @@
-import { mkdtemp, readFile, readdir, stat } from 'node:fs/promises';
+import { chmod, mkdir, mkdtemp, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { moxxyHome, moxxyPath, writeFileAtomic, writeFileAtomicSync } from './fs-utils.js';
+import {
+  ensurePrivateDir,
+  ensurePrivateFile,
+  moxxyHome,
+  moxxyPath,
+  pruneStaleTempFiles,
+  writeFileAtomic,
+  writeFileAtomicSync,
+} from './fs-utils.js';
 
 describe('writeFileAtomic', () => {
   let dir: string;
@@ -105,3 +113,91 @@ describe('moxxyHome / moxxyPath', () => {
     expect(moxxyHome().endsWith('/.moxxy')).toBe(true);
   });
 });
+
+// POSIX modes are meaningless on Windows (chmod only toggles the read-only
+// flag), where these helpers are deliberate no-ops. Assert the guarantee only
+// where the platform can actually provide it.
+describe.skipIf(process.platform === 'win32')('ensurePrivateDir / ensurePrivateFile', () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'moxxy-priv-'));
+  });
+
+  it('creates a directory owner-only', async () => {
+    const target = join(dir, 'sessions');
+    await ensurePrivateDir(target);
+    expect((await stat(target)).mode & 0o777).toBe(0o700);
+  });
+
+  it('tightens a directory that already exists with group/other bits', async () => {
+    const target = join(dir, 'legacy');
+    await mkdir(target, { mode: 0o755 });
+    await chmod(target, 0o755); // defeat umask so the pre-state is really loose
+    await ensurePrivateDir(target);
+    expect((await stat(target)).mode & 0o777).toBe(0o700);
+  });
+
+  it('creates a missing file owner-only without truncating an existing one', async () => {
+    const target = join(dir, 'log.jsonl');
+    await ensurePrivateFile(target);
+    expect((await stat(target)).mode & 0o777).toBe(0o600);
+
+    await writeFile(target, 'line\n');
+    await ensurePrivateFile(target);
+    expect(await readFile(target, 'utf8')).toBe('line\n');
+  });
+
+  it('tightens a file that already exists world-readable', async () => {
+    const target = join(dir, 'legacy.jsonl');
+    await writeFile(target, 'secret transcript\n');
+    await chmod(target, 0o644);
+    await ensurePrivateFile(target);
+    expect((await stat(target)).mode & 0o777).toBe(0o600);
+    expect(await readFile(target, 'utf8')).toBe('secret transcript\n');
+  });
+
+  it('creates parent directories', async () => {
+    const target = join(dir, 'a', 'b', 'c');
+    await ensurePrivateDir(target);
+    expect((await stat(target)).isDirectory()).toBe(true);
+  });
+});
+
+describe('pruneStaleTempFiles', () => {
+  let dir: string;
+  const DAY = 24 * 60 * 60 * 1000;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'moxxy-prune-'));
+  });
+
+  const tmpName = (base: string): string =>
+    `${base}.4242.3f2504e0-4f89-11d3-9a0c-0305e82c3301.tmp`;
+
+  it('removes an abandoned temp file older than a day', async () => {
+    const stale = join(dir, tmpName('schedules.json'));
+    await writeFile(stale, '{}');
+    const removed = await pruneStaleTempFiles([dir], Date.now() + 2 * DAY);
+    expect(removed).toBe(1);
+    expect(await readdir(dir)).toEqual([]);
+  });
+
+  // The guarantee that makes this safe to run while another moxxy process is
+  // mid-write: a live temp file is milliseconds old and can never be selected.
+  it('leaves a freshly-written temp file alone', async () => {
+    const live = join(dir, tmpName('vault.json'));
+    await writeFile(live, '{}');
+    expect(await pruneStaleTempFiles([dir])).toBe(0);
+    expect(await readdir(dir)).toEqual([tmpName('vault.json')]);
+  });
+
+  it('ignores files that merely end in .tmp', async () => {
+    await writeFile(join(dir, 'notes.tmp'), 'user data');
+    await writeFile(join(dir, 'draft.md.tmp'), 'user data');
+    expect(await pruneStaleTempFiles([dir], Date.now() + 2 * DAY)).toBe(0);
+    expect((await readdir(dir)).sort()).toEqual(['draft.md.tmp', 'notes.tmp']);
+  });
+
+  it('never throws on a missing directory', async () => {
+    await expect(pruneStaleTempFiles([join(dir, 'nope')])).resolves.toBe(0);
+  });
+});