@karma42/agent 0.1.0-beta.12 → 0.1.0-beta.13

package/README.md

@@ -1,13 +1,13 @@
 # Karma42 MCP connector
 
-`0.1.0-beta.12` is a **beta release**. It connects an existing MCP-capable AI client to a Karma42 project. Registration and current-chat mode do not select, download or run a model. An explicitly approved local worker is a separate work mode. An MCP-capable client using DeepSeek or another model can use the same transport if that client supports local stdio MCP and the required project tools.
+`0.1.0-beta.13` is a **beta release**. It connects an existing MCP-capable AI client to a Karma42 project. Registration and current-chat mode do not select, download or run a model. An explicitly approved local worker is a separate work mode. An MCP-capable client using DeepSeek or another model can use the same transport if that client supports local stdio MCP and the required project tools.
 
 ## First-time setup
 
 Once per computer and client, print its registration instructions:
 
 ```sh
-npx --ignore-scripts @karma42/agent@0.1.0-beta.12 mcp-config --client claude
+npx --ignore-scripts @karma42/agent@0.1.0-beta.13 mcp-config --client claude
 ```
 
 Use `--client codex` for Codex, or `--client other` for the generic stdio configuration. **Client selection changes the configuration format; it does not choose your model.**
@@ -58,11 +58,15 @@ The lightweight supervisor holds no model open while waiting. `WORK_NEXT: runnab
 
 Worker lifecycle and adapter-session tests use fake models and clocks. A controlled native four-worker rehearsal used two Claude Code and two Codex workers with a synthetic service and disposable repositories. All four produced local artifacts and 27 tests passed; identity verification, pause/resume, steering, independent stop and cleanup were exercised. The [rehearsal receipt](https://github.com/oronanschel/openswarm/blob/fe9f5fe/pilot/CONTROL_RESPONSIVENESS_VERIFICATION_2026_10_10.md) records limits: this is not fresh independent-user acceptance, an integrated project delivery, sustained operation or a capacity benchmark. Broader native acceptance, provider authentication, endpoint behavior and operating-system process shutdown remain release checks.
 
+## Windows
+
+Setup, the one-time computer approval, adding and connecting agents, and work in the current conversation run on Windows. `mcp-config` prints a registration that starts `npx` through `cmd /c`, as Windows clients require. Supervised workers do not run on Windows yet: the process guard stops a whole process group, which Windows does not have. `start_project_worker` refuses there before anything is prepared, and an agent set to run on its own works in the conversation instead. Windows support is covered by path-rule tests and a Windows check in CI; it has not had independent native acceptance.
+
 ## Transport and private state
 
 The client runs `mcp-serve`, which serves JSON-RPC over stdin/stdout. Registration and connection do not launch a model; worker execution requires its own explicit approval. Node 22+ is required. `disconnect_project_agent` releases only the specified binding; EOF or transport termination releases all bindings in that process; completed external actions are not undone. Run fences, membership, revocation and project-state checks remain enforced by the service.
 
-Private records use `~/.karma42/mcp` or `--state-dir /absolute/private/directory`. Storage must be private and outside the working folder. Credentials and polling secrets remain in private files; never put them in chat, arguments, URLs or client configuration. The pending approval of a computer can be resumed; cancellation or expiry preserves what is already saved. A connected agent keeps its connection; nothing is replaced.
+Private records use `~/.karma42/mcp` or `--state-dir /absolute/private/directory`. Storage must be private and outside the working folder. On Windows, storage must be inside your user folder (`C:\Users\<name>`): Windows has no permission bits to check, so the connector relies on the access rules Windows applies to that folder. Credentials and polling secrets remain in private files; never put them in chat, arguments, URLs or client configuration. The pending approval of a computer can be resumed; cancellation or expiry preserves what is already saved. A connected agent keeps its connection; nothing is replaced.
 
 This source contains only the current MCP connector. Old npm releases remain published independently; this cleanup neither migrates their private records nor deletes production data or interrupts existing sessions. Native client and operating-system acceptance remain separate release checks. Configuration and protocol tests do not establish that every MCP client supports dynamic setup, reload or continuation.
 
@@ -108,6 +112,6 @@ CLI equivalents: `project-agents --project PROJECT_ID` and `agents-register --pr
 
 ## Bundled orchestration skill
 
-`skills/karma42/SKILL.md` is the single maintained workflow for owner access, project readiness/start, team selection/registration, batch approval, identity checks and supervised workers. The MCP supplies it as initialization instructions and through `get_karma42_guide`, so guidance is available even without native skill support. `npx --ignore-scripts @karma42/agent@0.1.0-beta.12 skill` prints the same file; it never edits settings. A client can optionally save it in its supported skill location after the user approves that file addition. Installation/registration does not grant account access or authorize work. A generic host subagent is not automatically an independently connected Karma42 worker.
+`skills/karma42/SKILL.md` is the single maintained workflow for owner access, project readiness/start, team selection/registration, batch approval, identity checks and supervised workers. The MCP supplies it as initialization instructions and through `get_karma42_guide`, so guidance is available even without native skill support. `npx --ignore-scripts @karma42/agent@0.1.0-beta.13 skill` prints the same file; it never edits settings. A client can optionally save it in its supported skill location after the user approves that file addition. Installation/registration does not grant account access or authorize work. A generic host subagent is not automatically an independently connected Karma42 worker.
 
 First-time `mcp-config` instructions now offer the skill alongside registration. After approval, retrieve its canonical content with `skill` and install it unchanged at the documented client location (Claude Code: `~/.claude/skills/karma42/SKILL.md`; Codex: `~/.agents/skills/karma42/SKILL.md`). Existing different skills require separate replacement approval. Other clients use their documented skill support or `get_karma42_guide`. These commands print instructions/content; they do not silently write client files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karma42/agent",
-  "version": "0.1.0-beta.12",
+  "version": "0.1.0-beta.13",
   "description": "Model-independent Karma42 MCP connector for project agents",
   "license": "UNLICENSED",
   "type": "module",

package/skills/karma42/SKILL.md

@@ -39,7 +39,7 @@ A prompt copied from Karma42, or the human saying “let’s create an agent in
 
 **Ask once before starting.** Only when work can start. `get_project` returns `you.workSettings`: `involvement` (`with_me` or `on_own`) and `minutes`. These are the default limits. Check that the repository is reachable with the human's account and whether a checkout already exists. Then ask one question with the client's question tool (AskUserQuestion in Claude Code), so the human picks an answer; use a numbered list only when the client has no question tool, and never ask it as a plain sentence at the end of a reply. `add_project_agent` returns the question ready as `start_question`, for example “Start scout on Friends Game? It runs on its own, for up to 1 hour.” Its options are: 1. Yes, start. 2. Change the limits. 3. Not now. For several agents added in one request, ask once for all of them. On Change, take the new involvement and length, from 15 minutes to 4 hours, save them for each agent with `set_agent_work_settings`, and start under them without asking again. On Not now, start nothing: the agent stays connected and the human can ask later. The answer is the approval to start; adding or connecting an agent alone is not permission to develop, post project messages or change GitHub. Keep the permitted actions (project messages, commits, pushes, PRs) within the human's standing instructions for this client. Setup time does not count toward the session. Between tasks, read the settings again with `get_project`: a changed involvement applies from the next task and a changed length from the next session, because a running session keeps its deadline. My agents shows the limits and offers a prompt to change them. When the human asks to change an agent’s limits, pick the agent up with `add_project_agent` if it is not connected in this conversation, ask for the new involvement and length with the question tool, save them with `set_agent_work_settings`, and say they apply from the agent’s next start. An agent connected through a team batch is different: its work is approved separately, as described under Launch and supervise.
 
-**Work.** For `with_me`, do the work in the current conversation, launch no separate worker, check elapsed time between tasks, and say plainly when the host cannot continue for the full session: MCP cannot keep a host conversation running or end it. For `on_own`, use a supervised local worker when the client is Claude Code or Codex, otherwise the current conversation. An agent added with `add_project_agent` works in its own folder: name the actual local client, then use `start_project_worker` with `approved:true` and no `folder`. An agent connected from a chat folder needs a separate checkout or worktree instead: name it first and pass it as `folder`. Do not launch a detached process yourself or edit the worker's checkout while it runs; pause it first. Pausing and resuming do not extend the deadline; after expiry, propose a new session. Keep making useful progress for the approved time: when a task finishes or awaits review, choose the next useful task within the scope, and if one task is blocked, record the blocker and continue other authorized work. Always stop for a real blocker, a needed permission or a change of scope. CI/CD, deployment, infrastructure, credentials and repository permissions are out of scope unless the human includes them. A failing check is not permission to weaken or bypass it. Never invent work or spend model turns polling. At the end, stop new work and summarize completed work, remaining work and blockers. `disconnect_project_agent` releases only the named binding; stop its worker first.
+**Work.** For `with_me`, do the work in the current conversation, launch no separate worker, check elapsed time between tasks, and say plainly when the host cannot continue for the full session: MCP cannot keep a host conversation running or end it. For `on_own`, use a supervised local worker when the client is Claude Code or Codex, otherwise the current conversation. On Windows there is no supervised worker yet: work in the current conversation and say so once. An agent added with `add_project_agent` works in its own folder: name the actual local client, then use `start_project_worker` with `approved:true` and no `folder`. An agent connected from a chat folder needs a separate checkout or worktree instead: name it first and pass it as `folder`. Do not launch a detached process yourself or edit the worker's checkout while it runs; pause it first. Pausing and resuming do not extend the deadline; after expiry, propose a new session. Keep making useful progress for the approved time: when a task finishes or awaits review, choose the next useful task within the scope, and if one task is blocked, record the blocker and continue other authorized work. Always stop for a real blocker, a needed permission or a change of scope. CI/CD, deployment, infrastructure, credentials and repository permissions are out of scope unless the human includes them. A failing check is not permission to weaken or bypass it. Never invent work or spend model turns polling. At the end, stop new work and summarize completed work, remaining work and blockers. `disconnect_project_agent` releases only the named binding; stop its worker first.
 
 ## Launch and supervise
 

package/src/checkout-ownership.mjs

@@ -1,9 +1,9 @@
-import { readdirSync, realpathSync, statSync, unlinkSync, readFileSync } from 'node:fs';
+import { readdirSync, statSync, unlinkSync, readFileSync } from 'node:fs';
 import { userInfo } from 'node:os';
-import { join, relative, isAbsolute } from 'node:path';
+import { join, isAbsolute } from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { ensureHome, readPrivate, writePrivate, assertStateOutsideWorkspace } from './state.mjs';
+import { ensureHome, readPrivate, writePrivate, assertStateOutsideWorkspace, pathInside, physicalPath } from './state.mjs';
 
 // This is deliberately independent of --state-dir and HOME overrides. All connector
 // processes for the same OS user arbitrate in one private, local filesystem registry.
@@ -30,10 +30,7 @@ const read = (root, name) => {
   try { return readPrivate(join(root, name), true); }
   catch (error) { if (error.code === 'ENOENT') return null; throw new Error(`Worker ownership cannot inspect ${join(root, name)}. Restore the private record before retrying; no existing worker was stopped.`); }
 };
-const overlap = (left, right) => {
-  const inside = (a, b) => { const part = relative(a, b); return !part || (part !== '..' && !part.startsWith('../') && !isAbsolute(part)); };
-  return inside(left, right) || inside(right, left);
-};
+const overlap = (left, right) => pathInside(left, right) || pathInside(right, left);
 const pause = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds));
 
 // Lamport bakery arbitration: publish choosing before observing tickets, then wait
@@ -70,9 +67,9 @@ function validateClaim(claim, path) {
 }
 
 export async function claimWorkerCheckout({ folder, agentId, project, registryRoot = checkoutOwnershipHome(), timeoutMs = 3000 }) {
-  const checkout = realpathSync(folder);
+  const checkout = physicalPath(folder);
   if (!statSync(checkout).isDirectory()) throw new Error('Worker checkout must be an existing directory.');
-  ensureHome(registryRoot); const root = realpathSync(registryRoot);
+  ensureHome(registryRoot); const root = physicalPath(registryRoot);
   assertStateOutsideWorkspace(root, checkout);
   const id = randomUUID(), path = join(root, `claim-${id}.json`);
   const claim = { schema: 1, id, pid: process.pid, machine: machine(), folder: checkout, agentId: agentId ?? null, project: project ?? null, createdAt: Date.now(), phase: 'idle', children: [] };

package/src/cli.mjs

@@ -2,6 +2,7 @@
 import { parseArgs } from 'node:util';
 import { pathToFileURL } from 'node:url';
 import { realpathSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
 import { readFileSync } from 'node:fs';
 import { createOwnerClient } from './owner-client.mjs';
 import { VERSION } from './version.mjs';
@@ -70,7 +71,7 @@ export function main(args, out = console.log, err = console.error) {
     const names = parsed.tokens.filter(token => token.kind === 'option').map(token => token.name);
     if (new Set(names).size !== names.length) throw new Error('Supply each option once.');
     const values = parsed.values;
-    if (values['state-dir'] && (!values['state-dir'].startsWith('/') || /[\x00-\x1f\x7f-\x9f]/.test(values['state-dir']))) throw new Error('Choose an absolute private state directory.');
+    if (values['state-dir'] && (!isAbsolute(values['state-dir']) || /[\x00-\x1f\x7f-\x9f]/.test(values['state-dir']))) throw new Error('Choose an absolute private state directory.');
     if (command === 'skill') { out(readFileSync(new URL('../skills/karma42/SKILL.md',import.meta.url),'utf8')); return 0; }
     if (command === 'mcp-config') { out(renderReusableConfiguration(reusableConfiguration({ client: values.client, home: values['state-dir'] }))); return 0; }
     if (command !== 'mcp-serve') return runManagement(command, values).then(value => { out(JSON.stringify(value, null, 2)); return 0; }).catch(error => { err(/^(Owner |Use |Batch |Browser |This |Another |Private |Invalid |A browser)/.test(error.message ?? '') ? error.message : 'Management could not complete. Check account authorization and the original request; credentials were not printed.'); return 2; });

package/src/mcp-configuration.mjs

@@ -4,18 +4,23 @@ import { sessionHome } from './session.mjs';
 import { canonicalPath } from './state.mjs';
 
 const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
+// Windows has three common shells. Double quotes mean the same in cmd, PowerShell and Git Bash.
+const quoteWindows = value => /^[\w.:/=+-]+$/.test(value) ? value : `"${value}"`;
 // Client selection changes registration format only. The transport and project identity are model agnostic.
-export function reusableConfiguration({ client, home = sessionHome() } = {}) {
+export function reusableConfiguration({ client, home = sessionHome(), platform = process.platform } = {}) {
   if (!['claude', 'codex', 'other'].includes(client)) throw new Error('Choose --client claude, codex or other. This selects your MCP client, not your model.');
   if (typeof home !== 'string' || !isAbsolute(home) || /[\x00-\x1f\x7f-\x9f]/.test(home)) throw new Error('Choose an absolute private state directory.');
   home = canonicalPath(home);
   const name = 'karma42';
-  const args = ['--yes', '--ignore-scripts', `@karma42/agent@${VERSION}`, 'mcp-serve', '--state-dir', home];
-  const prefix = client === 'claude' ? ['claude', 'mcp', 'add', '--scope', 'user', name, '--', 'npx'] : client === 'codex' ? ['codex', 'mcp', 'add', name, '--', 'npx'] : null;
-  const entry = { command: 'npx', args };
+  const windows = platform === 'win32';
+  if (windows && /["%$`]/.test(home)) throw new Error('Choose a private state directory without quotes, percent, dollar or backtick characters.');
+  const npx = ['--yes', '--ignore-scripts', `@karma42/agent@${VERSION}`, 'mcp-serve', '--state-dir', home];
+  // On Windows npx is a batch file, which a client can start only through cmd.
+  const entry = windows ? { command: 'cmd', args: ['/c', 'npx', ...npx] } : { command: 'npx', args: npx };
+  const prefix = client === 'claude' ? ['claude', 'mcp', 'add', '--scope', 'user', name, '--'] : client === 'codex' ? ['codex', 'mcp', 'add', name, '--'] : null;
   return { name, client, scope: client === 'other' ? 'client-settings' : 'user',
-    command: prefix ? [...prefix, ...args].map(quote).join(' ') : null,
-    entry, generic: { mcpServers: { [name]: entry } },
+    command: prefix ? [...prefix, entry.command, ...entry.args].map(windows ? quoteWindows : quote).join(' ') : null,
+    entry, generic: { mcpServers: { [name]: entry } }, windows,
   };
 }
 export function renderReusableConfiguration(config) {
@@ -26,6 +31,7 @@ export function renderReusableConfiguration(config) {
     config.client === 'other' ? 'Add the karma42 stdio connection using your MCP client’s settings and configuration format. The JSON below describes the command and arguments; adapt its wrapper if your client uses a different schema.' : `Register karma42 once in ${config.client === 'claude' ? 'Claude Code’s user-level MCP settings' : 'Codex’s user-level ~/.codex/config.toml'}.`,
     'Approve adding this entry before changing settings. If karma42 already exists, inspect it first. Preserve other entries and existing permissions.',
     config.command ?? JSON.stringify(config.generic, null, 2),
+    ...(config.windows && config.command ? ['Windows: this line is for PowerShell or cmd. In Git Bash write //c in place of /c.'] : []),
     '',
     'Also offer to install the bundled Karma42 skill. Ask before writing it unless the human already approved both MCP registration and skill installation.',
     `Read its canonical content with: npx --ignore-scripts @karma42/agent@${VERSION} skill`,

package/src/owner-client.mjs

@@ -32,10 +32,11 @@ export const OWNER_TOOLS = [
   { name: 'disconnect_owner_account', description: 'Revoke this saved human management connection. Agent bindings and running agents are separate and remain unchanged.', inputSchema: object({ owner_ref: ownerRef }, ['owner_ref']) },
 ];
 // The one question asked before an agent starts, in the shape a client's question tool takes.
-export function startQuestion(agentName, projectName, settings) {
+export function startQuestion(agentName, projectName, settings, platform = process.platform) {
   const minutes = Number.isInteger(settings?.minutes) ? settings.minutes : 60, hours = minutes / 60;
   const length = minutes < 60 ? `${minutes} minutes` : minutes % 60 ? `${Math.floor(hours)} h ${minutes % 60} min` : hours === 1 ? '1 hour' : `${hours} hours`;
-  const how = settings?.involvement === 'with_me' ? 'works with you in this conversation' : 'runs on its own';
+  // Windows has no supervised worker yet, so an agent there works in the conversation whatever its saved setting.
+  const how = settings?.involvement === 'with_me' || platform === 'win32' ? 'works with you in this conversation' : 'runs on its own';
   return { question: `Start ${agentName} on ${projectName ?? 'this project'}? It ${how}, for up to ${length}.`, options: ['Yes, start', 'Change the limits', 'Not now'] };
 }
 export function ownerOrigin(site) {

package/src/reusable-stdio.mjs

@@ -36,7 +36,7 @@ const result = data => ({ content: [{ type: 'text', text: JSON.stringify(data) }
 
 // MCP hosts may share a server across conversations. Every tool carries an explicit binding
 // reference; neither a process nor a shared state file ever has a default active project.
-export async function serveReusable({ home = sessionHome(), input = process.stdin, output = process.stdout, signals = process, boundServer = serveSession, workerFactory, discoveryOptions, ownerFactory = createOwnerClient, ownerOptions, approvalWait = ms => new Promise(resolve => setTimeout(resolve, ms)), openApproval = () => false, ...boundOptions }) {
+export async function serveReusable({ home = sessionHome(), input = process.stdin, output = process.stdout, signals = process, boundServer = serveSession, workerFactory, discoveryOptions, ownerFactory = createOwnerClient, ownerOptions, approvalWait = ms => new Promise(resolve => setTimeout(resolve, ms)), openApproval = () => false, platform = process.platform, ...boundOptions }) {
   const bundled = verifyBundle();
   const projectTools = JSON.parse(bundled.files['project-tools.json'].toString('utf8')).tools.map(tool => ({
     ...tool, description: `${tool.description ?? ''} Always supply this project agent’s connection_ref.`,
@@ -211,6 +211,8 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
   async function startWorker(args) {
     if (Object.keys(args).some(key => !['connection_ref', 'client', 'model', 'minutes', 'scope', 'folder', 'approved', 'recovery_ref'].includes(key))) throw new Error('Use only the documented worker options.');
     const context = verifiedContext(args), minutes = args.minutes === undefined ? 60 : args.minutes;
+    // The process guard stops a whole process group, which Windows does not have. Refuse before anything is prepared.
+    if (platform === 'win32') throw new Error('Supervised workers are not available on Windows yet. Work in the current conversation instead; nothing was started.');
     if (args.approved !== true) throw new Error('Worker start requires your human’s explicit approval for this worker, duration, folder and work scope. Connection approval is insufficient.');
     if (!['claude', 'codex'].includes(args.client) || !Number.isInteger(minutes) || minutes < 15 || minutes > 240 || minutes % 15 !== 0) throw new Error('Choose a supported worker client and 15–240 minutes in 15-minute increments.');
     if (typeof args.scope !== 'string' || !args.scope.trim() || args.scope.length > 4000 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/.test(args.scope)) throw new Error('Use a clear, human-approved work scope of at most 4000 characters.');

package/src/state.mjs

@@ -1,40 +1,56 @@
 import { constants, lstatSync, realpathSync, fstatSync, mkdirSync, openSync, closeSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
-import { join, dirname, basename, resolve, relative, isAbsolute } from 'node:path';
+import nodePath, { join, dirname, basename, resolve } from 'node:path';
+import { userInfo } from 'node:os';
 import { randomUUID, createHash } from 'node:crypto';
 
+// Windows has no permission bits: every file reports mode 666 and the folder's access list decides who
+// reads it. Private storage there must be inside the person's own user folder, which Windows keeps to
+// that account, the system and administrators. The other checks are the same on every system.
+const windows = process.platform === 'win32';
+const exposed = stat => !windows && (stat.mode & 0o077);
+// The native call also expands Windows short names (RUNNER~1), so one folder has one spelling.
+export const physicalPath = windows ? realpathSync.native : realpathSync;
+
 export function canonicalPath(value) {
   let path = resolve(value);
   const tail = [];
   while (!lstatExists(path)) { tail.unshift(basename(path)); path = dirname(path); }
-  return join(realpathSync(path), ...tail);
+  return join(physicalPath(path), ...tail);
+}
+// True when path is root or below it. Windows separates with a backslash and ignores letter case.
+export function pathInside(root, path, { relative, isAbsolute, sep } = nodePath) {
+  const part = relative(root, path);
+  return part === '' || (part !== '..' && !part.startsWith(`..${sep}`) && !isAbsolute(part));
 }
 // Physical paths matter: a symlink spelling must not allow credentials inside a checkout.
 export function assertStateOutsideWorkspace(home, folder) {
   const state = canonicalPath(home), workspace = canonicalPath(folder);
-  const inside = (root, path) => {
-    const part = relative(root, path);
-    return part === '' || (part !== '..' && !part.startsWith('../') && !isAbsolute(part));
-  };
-  if (inside(workspace, state) || inside(state, workspace)) throw new Error('Private connection state and the project workspace must be separate sibling paths. Choose storage outside the checkout.');
+  if (pathInside(workspace, state) || pathInside(state, workspace)) throw new Error('Private connection state and the project workspace must be separate sibling paths. Choose storage outside the checkout.');
 }
 export const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
 export function privateDir(path) {
   try { mkdirSync(path, { mode: 0o700 }); }
   catch (error) { if (error.code !== 'EEXIST') throw error; }
   const stat = lstatSync(path);
-  if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077)) throw new Error('Connection storage must be a private directory, without symbolic links.');
+  if (!stat.isDirectory() || stat.isSymbolicLink() || exposed(stat)) throw new Error('Connection storage must be a private directory, without symbolic links.');
 }
 export function ensureHome(home) {
   // Only the caller-selected root is created recursively. Existing root must be private.
   mkdirSync(home, { recursive: true, mode: 0o700 });
   privateDir(home);
+  if (windows) {
+    const profile = canonicalPath(userInfo().homedir), state = canonicalPath(home);
+    if (state === profile || !pathInside(profile, state)) throw new Error(`Private connection storage on Windows must be inside your user folder (${profile}), which Windows keeps private to your account.`);
+  }
 }
 export function readPrivate(path, json = false) {
+  // Windows cannot refuse a symbolic link while opening, so it is refused by name first.
+  if (windows && lstatSync(path).isSymbolicLink()) throw new Error('Connection files must be private regular files.');
   for (let attempt = 0; attempt < 3; attempt++) {
     const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
     try {
       const stat = fstatSync(fd);
-      if (!stat.isFile() || (stat.mode & 0o077) || stat.nlink > 1) throw new Error('Connection files must be private regular files.');
+      if (!stat.isFile() || exposed(stat) || stat.nlink > 1) throw new Error('Connection files must be private regular files.');
       // Atomic replacement can unlink the inode between open and fstat. Reopen
       // the named record; never read an unlinked inode or relax private-file checks.
       if (stat.nlink === 0 && attempt < 2) continue;
@@ -48,13 +64,23 @@ export function readPrivate(path, json = false) {
 export function writePrivate(path, value) {
   try {
     const stat = lstatSync(path);
-    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) || stat.nlink !== 1) throw new Error('Refusing to replace unsafe connection storage.');
+    if (!stat.isFile() || stat.isSymbolicLink() || exposed(stat) || stat.nlink !== 1) throw new Error('Refusing to replace unsafe connection storage.');
   } catch (error) { if (error.code !== 'ENOENT') throw error; }
   const temp = `${path}.${randomUUID()}.tmp`;
   const fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
   try { writeFileSync(fd, typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`); }
   finally { closeSync(fd); }
-  try { renameSync(temp, path); } finally { try { unlinkSync(temp); } catch {} }
+  try { replaceFile(temp, path); } finally { try { unlinkSync(temp); } catch {} }
+}
+// Windows refuses to replace a file while another process, often a virus scanner, holds it open. Wait briefly.
+function replaceFile(temp, path) {
+  for (let attempt = 0; ; attempt++) {
+    try { return renameSync(temp, path); }
+    catch (error) {
+      if (!windows || attempt === 9 || !['EPERM', 'EACCES', 'EBUSY'].includes(error.code)) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20 * (attempt + 1));
+    }
+  }
 }
 export function connectionDir(home, id) {
   if (!/^[a-f0-9]{64}\/[\w-]{1,200}$/.test(id ?? '')) throw new Error('Choose a connection ID from status.');

package/src/version.mjs

@@ -1,3 +1,3 @@
-export const VERSION = '0.1.0-beta.12';
+export const VERSION = '0.1.0-beta.13';
 // Raised when the bundled guide gains rules a website prompt depends on; prompts name the minimum they need.
 export const GUIDE_REVISION = 5;

package/src/worker-recovery.mjs

@@ -1,4 +1,4 @@
-import { join } from 'node:path';
+import { join, isAbsolute } from 'node:path';
 import { lstatExists, readPrivate, writePrivate } from './state.mjs';
 import { claimWorkerCheckout } from './checkout-ownership.mjs';
 
@@ -18,7 +18,7 @@ export function readWorkerMission(dir, record) {
   const value = readPrivate(path, true);
   if (!value || typeof value !== 'object' || Array.isArray(value) || value.schema !== 1 || !uuid(value.id) || value.connectionId !== record.id || value.service !== record.service
     || value.repo !== record.repo || !uuid(value.workerDir) || !Number.isSafeInteger(value.ownerPid) || value.ownerPid <= 0
-    || !['claude', 'codex'].includes(value.client) || !bounded(value.folder, 4000) || !value.folder.startsWith('/')
+    || !['claude', 'codex'].includes(value.client) || !bounded(value.folder, 4000) || !isAbsolute(value.folder)
     || !bounded(value.scope, 4000) || !(value.model === null || (typeof value.model === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,149}$/.test(value.model)))
     || !Number.isSafeInteger(value.startedAt) || !Number.isSafeInteger(value.deadline) || value.deadline <= value.startedAt
     || value.deadline - value.startedAt < 15 * 60000 || value.deadline - value.startedAt > 240 * 60000

package/src/worker-runtime.mjs

@@ -2,7 +2,7 @@ import { spawnSync } from 'node:child_process';
 import { rmSync } from 'node:fs';
 import { createWorkController } from '../runtime/work-controller.mjs';
 import { randomUUID } from 'node:crypto';
-import { join } from 'node:path';
+import { join, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createProvider, CLAUDE_ALLOWED_TOOLS } from '../runtime/providers.mjs';
 import { VERSION } from './version.mjs';
@@ -32,7 +32,7 @@ const contactIsTransient = failure => failure.fatal === false || failure.name ==
   || (failure instanceof TypeError && failure.message === 'fetch failed')
   || ['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN'].includes(failure.cause?.code);
 export function validateWorkerWorkspace(folder, record) {
-  if (typeof folder !== 'string' || !folder.startsWith('/')) throw new Error('Choose a separate absolute Git checkout or worktree for the worker.');
+  if (typeof folder !== 'string' || !isAbsolute(folder)) throw new Error('Choose a separate absolute Git checkout or worktree for the worker.');
   const cwd = canonicalPath(folder);
   // An agent added through the approved computer has a folder of its own, which is also its checkout.
   // A connection made from a chat folder still needs a separate one, so the chat and worker never share files.