@commonlyai/cli 0.1.232 → 0.1.234

package/src/lib/daemon-service-windows.js

@@ -0,0 +1,256 @@
+/**
+ * D245: the Windows form of `commonly daemon install` (ADR-026 D1).
+ *
+ * macOS has launchd and Linux has systemd; Windows has Task Scheduler. A
+ * per-user task needs no administrator, so the install stays a one-liner a
+ * person can run in their own PowerShell. The shape mirrors the other two:
+ *
+ * - The task starts at this user's logon (a LogonTrigger naming the user; a
+ *   trigger for ANY user's logon needs an administrator).
+ * - Keep-alive lives in the launcher, a PowerShell script that loops on
+ *   `node <cli> daemon run --foreground`: it restarts on every exit except 77
+ *   and 78, the same codes `RestartPreventExitStatus=77 78` exempts on systemd
+ *   (a revoked key and a bad local registration). Task Scheduler's own
+ *   "restart on failure" fires when a task fails to START, not when its
+ *   program exits non-zero, so it cannot be the keep-alive.
+ * - A one-minute repeating trigger with `IgnoreNew` is the watchdog for the
+ *   launcher itself: while the task runs it starts nothing, and if the
+ *   launcher is killed the next minute brings it back.
+ * - On 77/78 the launcher disables the task before it exits, so the watchdog
+ *   does not restart a daemon that has been told to stop. That is launchd's
+ *   "park on a successful exit" in Task Scheduler's terms; `daemon start` and
+ *   `daemon restart` enable it again.
+ *
+ * A task cannot carry environment variables, so the provider keys the seats
+ * need (TASK-049) go in a JSON file the launcher loads before it starts node.
+ * The file is written through the same 0600-at-creation writer as the unit
+ * files, and its ACL is then narrowed to this user (best effort; the profile
+ * directory is already private by default).
+ *
+ * Windows has no Seatbelt or bwrap, so a daemon-run seat here is unconfined.
+ * That is stated on the BYO page and in docs/agents/daemon-service-windows.md.
+ */
+
+import { join } from 'path';
+
+export const WINDOWS_TASK_NAME = 'CommonlyDaemon';
+
+export const windowsServicePaths = (home) => {
+  const dir = join(home, '.commonly', 'daemon', 'service');
+  return {
+    kind: 'schtasks',
+    // The task definition doubles as the "is it installed" record, the way the
+    // plist and the unit file do on the other two platforms.
+    file: join(dir, 'commonly-daemon-task.xml'),
+    launcher: join(dir, 'commonly-daemon.ps1'),
+    envFile: join(dir, 'service-env.json'),
+    taskName: WINDOWS_TASK_NAME,
+  };
+};
+
+const xmlEscape = (value) => String(value)
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;');
+
+// A PowerShell single-quoted string ends at ANY of the four single-quote
+// characters it recognises (' and the curly ‘ ’ ‚ ‛), and each is escaped by
+// doubling. A user named O'Brien, or a path with a curly quote in it, would
+// otherwise close the string and run the rest of the path as script.
+export const psQuote = (value) => `'${String(value).replace(/['‘’‚‛]/g, (q) => q + q)}'`;
+
+export const windowsLauncherScript = ({ nodePath, cliPath, logPath, envFile, taskName = WINDOWS_TASK_NAME }) => `# Commonly daemon launcher. Written by \`commonly daemon install\`; re-run that command instead of editing this file.
+# It loads the service environment, then keeps \`commonly daemon run\` alive: every exit restarts it after 5 s,
+# except 77 (this computer's key was revoked) and 78 (no valid local registration), which disable the task and stop.
+$ErrorActionPreference = 'Continue'
+$node = ${psQuote(nodePath)}
+$cli = ${psQuote(cliPath)}
+$log = ${psQuote(logPath)}
+$envFile = ${psQuote(envFile)}
+$task = ${psQuote(taskName)}
+if (Test-Path -LiteralPath $envFile) {
+  $cfg = Get-Content -LiteralPath $envFile -Raw -Encoding UTF8 | ConvertFrom-Json
+  foreach ($p in $cfg.PSObject.Properties) { [Environment]::SetEnvironmentVariable($p.Name, [string]$p.Value, 'Process') }
+}
+$env:Path = (Split-Path -Parent $node) + ';' + $env:Path
+# Ending the task kills this script, not the node it started. The daemon watches this pid and
+# exits (stopping its seats) once it is gone, so stop, restart and reinstall leave no daemon behind.
+$env:COMMONLY_DAEMON_LAUNCHER_PID = "$PID"
+# Read node's output as UTF-8; Windows PowerShell 5.1 otherwise decodes it in the console code page.
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+while ($true) {
+  & $node $cli daemon run --foreground 2>&1 | ForEach-Object { "$_" } | Add-Content -LiteralPath $log -Encoding UTF8
+  $code = $LASTEXITCODE
+  if ($code -eq 77 -or $code -eq 78) {
+    & schtasks.exe /Change /TN $task /DISABLE | Out-Null
+    if ($LASTEXITCODE -eq 0) { exit $code }
+    # The task could not be disabled, so exiting would let the watchdog start
+    # it again within a minute. Park here instead; stop or uninstall ends it.
+    "commonly daemon exited $code and the task could not be disabled; parked" | Add-Content -LiteralPath $log -Encoding UTF8
+    while ($true) { Start-Sleep -Seconds 3600 }
+  }
+  Start-Sleep -Seconds 5
+}
+`;
+
+// UTF-8 with a BOM: Windows PowerShell 5.1 reads a BOM-less .ps1 in the ANSI
+// code page, which would mangle a non-ASCII user name in any of the paths.
+export const encodeLauncher = (script) => Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from(script, 'utf8')]);
+
+export const POWERSHELL = '%SystemRoot%\\System32\\WindowsPowerShell\\v1.0\\powershell.exe';
+
+export const windowsTaskXml = ({ launcher, userId, home }) => `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>Commonly local agent daemon (ADR-026). Installed by: commonly daemon install</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${xmlEscape(userId)}</UserId>
+    </LogonTrigger>
+    <TimeTrigger>
+      <Repetition>
+        <Interval>PT1M</Interval>
+        <StopAtDurationEnd>false</StopAtDurationEnd>
+      </Repetition>
+      <StartBoundary>2026-01-01T00:00:00</StartBoundary>
+      <Enabled>true</Enabled>
+    </TimeTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${xmlEscape(userId)}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${xmlEscape(POWERSHELL)}</Command>
+      <Arguments>${xmlEscape(`-NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File "${launcher}"`)}</Arguments>
+      <WorkingDirectory>${xmlEscape(home)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+
+// schtasks reads a task file as UTF-16; the declaration above says so, and the
+// bytes must agree with it (little-endian, with the BOM).
+export const encodeTaskXml = (xml) => Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(xml, 'utf16le')]);
+
+// Task Scheduler names a user DOMAIN\user. A bare name resolves too, but the
+// qualified one cannot be mistaken for a same-named account on the domain.
+export const windowsUserId = ({ env = process.env, lookupUsername }) => {
+  if (env.USERNAME) return env.USERDOMAIN ? `${env.USERDOMAIN}\\${env.USERNAME}` : env.USERNAME;
+  return lookupUsername();
+};
+
+export const installWindowsService = async ({
+  home, nodePath, cliPath, logPath, providerEnv, env, writeFile, execCmd, lookupUsername, warn,
+}) => {
+  const target = windowsServicePaths(home);
+  const userId = windowsUserId({ env, lookupUsername });
+  writeFile(target.envFile, `${JSON.stringify(Object.fromEntries(providerEnv), null, 2)}\n`);
+  try {
+    await execCmd(['icacls', target.envFile, '/inheritance:r', '/grant:r', `${userId}:F`]);
+  } catch (error) {
+    warn(`Could not narrow the permissions on ${target.envFile} (${error.message}). It holds your provider keys; it sits in your profile, which only you can read by default.`);
+  }
+  writeFile(target.launcher, encodeLauncher(windowsLauncherScript({ nodePath, cliPath, logPath, envFile: target.envFile })));
+  writeFile(target.file, encodeTaskXml(windowsTaskXml({ launcher: target.launcher, userId, home })));
+  // A running launcher keeps the environment it started with, so end it first
+  // (an absent task fails by design) and start the new definition after.
+  await execCmd(['schtasks', '/End', '/TN', target.taskName]).catch(() => {});
+  await execCmd(['schtasks', '/Create', '/TN', target.taskName, '/XML', target.file, '/F']);
+  await execCmd(['schtasks', '/Run', '/TN', target.taskName]);
+  return target;
+};
+
+export const LAUNCHER_PID_ENV = 'COMMONLY_DAEMON_LAUNCHER_PID';
+
+const pidAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+};
+
+/**
+ * `schtasks /End` terminates the launcher only; the node it started would
+ * keep running, unsupervised and invisible to the task (seen on windows-latest,
+ * 11-04: a stopped task left its daemon checking in). A daemon started by the
+ * launcher therefore polls the launcher's pid and calls `onGone` once it has
+ * exited. Returns a stop function; does nothing outside the launcher.
+ */
+export const watchWindowsLauncher = ({
+  env = process.env,
+  platform = process.platform,
+  isAlive = pidAlive,
+  onGone,
+  everyMs = 2000,
+  setIntervalFn = setInterval,
+  clearIntervalFn = clearInterval,
+  streams = [process.stdout, process.stderr],
+}) => {
+  const pid = Number(env[LAUNCHER_PID_ENV]);
+  if (platform !== 'win32' || !Number.isInteger(pid) || pid <= 0) return () => {};
+  // The launcher holds this process's stdout and stderr. Once it exits, any
+  // log line (a poll, a heartbeat) fails with EPIPE, and an unhandled stream
+  // error would end the daemon before it stops its seats. So the streams
+  // swallow errors from the moment the watch is armed, not only after the
+  // launcher's exit is noticed up to two seconds later.
+  for (const stream of streams) stream?.on?.('error', () => {});
+  const timer = setIntervalFn(() => {
+    if (isAlive(pid)) return;
+    clearIntervalFn(timer);
+    onGone(pid);
+  }, everyMs);
+  if (typeof timer?.unref === 'function') timer.unref();
+  return () => clearIntervalFn(timer);
+};
+
+export const uninstallWindowsService = async ({ home, execCmd, removeFile, existsFile }) => {
+  const target = windowsServicePaths(home);
+  await execCmd(['schtasks', '/End', '/TN', target.taskName]).catch(() => {});
+  await execCmd(['schtasks', '/Delete', '/TN', target.taskName, '/F']).catch(() => {});
+  for (const file of [target.file, target.launcher, target.envFile]) {
+    if (existsFile(file)) removeFile(file);
+  }
+  return target;
+};
+
+export const windowsServiceAction = async ({ action, home, execCmd }) => {
+  const target = windowsServicePaths(home);
+  const name = target.taskName;
+  if (action === 'stop') {
+    // Disabled first, so the one-minute watchdog cannot start it again.
+    await execCmd(['schtasks', '/Change', '/TN', name, '/DISABLE']);
+    await execCmd(['schtasks', '/End', '/TN', name]).catch(() => {});
+    return target;
+  }
+  if (action === 'restart') await execCmd(['schtasks', '/End', '/TN', name]).catch(() => {});
+  await execCmd(['schtasks', '/Change', '/TN', name, '/ENABLE']);
+  await execCmd(['schtasks', '/Run', '/TN', name]);
+  return target;
+};

package/src/lib/daemon-service.js

@@ -1,7 +1,8 @@
 /**
  * ADR-026 D1: install-once service registration for the resident daemon.
  *
- * macOS gets a launchd LaunchAgent, Linux a systemd user unit. Both run the
+ * macOS gets a launchd LaunchAgent, Linux a systemd user unit, Windows a
+ * per-user Task Scheduler task (daemon-service-windows.js). All three run the
  * exact interpreter + CLI entry that executed `daemon install`, resolved at
  * install time — a PATH lookup at boot would race version managers and
  * silently run a different install than the one the user tested.
@@ -14,17 +15,20 @@ import { randomBytes } from 'crypto';
 import { existsSync, renameSync, unlinkSync, writeFileSync } from 'fs';
 import { homedir, userInfo } from 'os';
 import { join, dirname, resolve } from 'path';
+import {
+  installWindowsService, uninstallWindowsService, windowsServiceAction, windowsServicePaths,
+} from './daemon-service-windows.js';
 
 export const LAUNCHD_LABEL = 'me.commonly.daemon';
 export const SYSTEMD_UNIT = 'commonly-daemon.service';
 
 export const daemonLogPath = (home = homedir()) => join(home, '.commonly', 'logs', 'daemon', 'daemon.log');
 
-export const servicePaths = (platform = process.platform, home = homedir()) => (
-  platform === 'darwin'
-    ? { kind: 'launchd', file: join(home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`) }
-    : { kind: 'systemd', file: join(home, '.config', 'systemd', 'user', SYSTEMD_UNIT) }
-);
+export const servicePaths = (platform = process.platform, home = homedir()) => {
+  if (platform === 'darwin') return { kind: 'launchd', file: join(home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`) };
+  if (platform === 'win32') return windowsServicePaths(home);
+  return { kind: 'systemd', file: join(home, '.config', 'systemd', 'user', SYSTEMD_UNIT) };
+};
 
 const xmlEscape = (value) => String(value)
   .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -287,7 +291,22 @@ export const installDaemonService = async ({
   const missing = missingProviderKeys({ names: providerKeyEnvNames, env });
 
   let startsAtBoot = false;
-  if (target.kind === 'launchd') {
+  if (target.kind === 'schtasks') {
+    // A logon task, like a LaunchAgent: it starts when this user logs in.
+    mkdirp(dirname(target.launcher));
+    await installWindowsService({
+      home,
+      nodePath,
+      cliPath,
+      logPath: daemonLogPath(home),
+      providerEnv,
+      env,
+      writeFile,
+      execCmd,
+      lookupUsername,
+      warn,
+    });
+  } else if (target.kind === 'launchd') {
     // The mode and the atomicity are the WRITER's, not an ordering rule here:
     // `writeServiceFile` creates a 0600 sibling and renames it over the target,
     // so no chmod is needed on this path and no half-written unit is ever
@@ -335,6 +354,11 @@ export const uninstallDaemonService = async ({
     log('No installed daemon service found.');
     return null;
   }
+  if (target.kind === 'schtasks') {
+    await uninstallWindowsService({ home, execCmd, removeFile, existsFile });
+    log(`Removed the ${target.taskName} scheduled task and its files (${dirname(target.file)}).`);
+    return target;
+  }
   if (target.kind === 'launchd') {
     await execCmd(['launchctl', 'unload', '-w', target.file]).catch(() => {});
   } else {
@@ -352,6 +376,7 @@ const serviceAction = async ({
   execCmd,
 }) => {
   const target = servicePaths(platform, home);
+  if (target.kind === 'schtasks') return windowsServiceAction({ action, home, execCmd });
   if (target.kind === 'launchd') {
     if (action === 'start') {
       // `install` already loads the plist. A second `start` should be

package/src/lib/daemon-store.js

@@ -64,14 +64,19 @@ const validateRecord = (record) => {
   return record;
 };
 
-export const loadDaemonRecord = () => {
+export const loadDaemonRecord = ({ platform = process.platform } = {}) => {
   const path = daemonRecordPath();
   const dir = daemonDir();
   if (!existsSync(path)) return null;
-  if ((statSync(dir).mode & 0o077) !== 0) {
+  // D245: Windows has no POSIX mode bits. Node reports every file there as
+  // 0o666 (0o444 when read-only) whatever its ACL, so this check refused every
+  // registration on Windows. Access there is the ACL's job; the record sits in
+  // the user's profile, which only that user (and administrators) can read.
+  const posix = platform !== 'win32';
+  if (posix && (statSync(dir).mode & 0o077) !== 0) {
     throw new Error(`Daemon credential directory permissions are insecure at ${dir}. Set them to 0700 before running the daemon.`);
   }
-  if ((statSync(path).mode & 0o077) !== 0) {
+  if (posix && (statSync(path).mode & 0o077) !== 0) {
     throw new Error(`Daemon credential file permissions are insecure at ${path}. Set them to 0600 before running the daemon.`);
   }
   try {

package/src/lib/daemon-supervisor.js

@@ -65,6 +65,9 @@ export const createDaemonSupervisor = ({
   loadToken, // (agentName) => token record | null
   saveToken, // (agentName, record) => void
   runtimeInventory = async () => undefined,
+  // Machine-level facts for the check-in, read locally each beat (D245: the
+  // Windows unsandboxed opt-in). Never derived from anything the server sent.
+  machineReport = () => ({}),
   resolveAdapter, // async (runtime) => adapter name for THIS machine
   persistState = () => {}, // (agentStates) => void; must not persist secrets
   log = () => {},
@@ -555,7 +558,11 @@ export const createDaemonSupervisor = ({
   const heartbeat = async () => {
     if (stopped || now() < reconnectAfter) return;
     try {
-      await client.post(`/api/machines/${record.machineDbId}/heartbeat`, { agents: agentStates(), runtimeInventory: await runtimeInventory() });
+      await client.post(`/api/machines/${record.machineDbId}/heartbeat`, {
+        ...machineReport(),
+        agents: agentStates(),
+        runtimeInventory: await runtimeInventory(),
+      });
       connectionRestored();
     } catch (error) {
       connectionFailure(error, 'heartbeat failed');

package/src/lib/enforcement.js

@@ -668,6 +668,9 @@ export const deliverChatReply = async ({
   attachThreshold = 800,
   uploadName = 'reply.md',
   log = () => {},
+  // D245 item 4: how this reply was made (lib/reply-receipt.js). It rides
+  // the first message that actually reaches the pod and no later one.
+  receipt = null,
 }) => {
   const messagesPath = `/api/agents/runtime/pods/${podId}/messages`;
   const chunks = splitForChat(text, { limit });
@@ -697,7 +700,14 @@ export const deliverChatReply = async ({
   // override per delivery; a post that still fails throws to the next rung as
   // before. Nothing here loops.
   let freshnessOverride = false;
-  const postMessage = async (body) => {
+  let receiptDelivered = !receipt;
+  const postOnce = async (rawBody) => {
+    const body = receiptDelivered ? rawBody : { ...rawBody, receipt };
+    const response = await postGuarded(body);
+    if (response?.refused !== true && response?.skipped !== true) receiptDelivered = true;
+    return response;
+  };
+  const postGuarded = async (body) => {
     if (freshnessOverride) return client.post(messagesPath, { ...body, continueAnyway: true });
     try {
       return await client.post(messagesPath, body);
@@ -774,7 +784,7 @@ export const deliverChatReply = async ({
   // the gate (found by the fleet's implementation audit).
   const hasIndivisibleOversize = chunks.some((c) => c.length > attachThreshold);
   if (chunks.length <= 1 && !hasIndivisibleOversize) {
-    const response = await postMessage({ content: chunks[0] ?? text });
+    const response = await postOnce({ content: chunks[0] ?? text });
     if (undelivered(response)) return nonDelivery(response, 0, 1);
     return { mode: 'single', messages: 1 };
   }
@@ -782,7 +792,7 @@ export const deliverChatReply = async ({
     let messages = 0;
     for (const chunk of chunks) {
       // eslint-disable-next-line no-await-in-loop
-      const response = await postMessage({ content: chunk }); // in order, so the reply reads top-down
+      const response = await postOnce({ content: chunk }); // in order, so the reply reads top-down
       if (undelivered(response)) return nonDelivery(response, messages, chunks.length);
       messages += 1;
     }
@@ -802,7 +812,7 @@ export const deliverChatReply = async ({
     // fail at the root-id step before any continuation has posted.
     let posted = 0;
     try {
-      const rootRes = await postMessage({ content: chunks[0] });
+      const rootRes = await postOnce({ content: chunks[0] });
       if (undelivered(rootRes)) return nonDelivery(rootRes, 0, chunks.length);
       posted = 1;
       // The runtime route answers `res.json(result)` with the created row on
@@ -814,7 +824,7 @@ export const deliverChatReply = async ({
       if (!rootId) throw new Error('no message id in post response — cannot root the thread');
       for (const chunk of chunks.slice(1)) {
         // eslint-disable-next-line no-await-in-loop
-        const response = await postMessage({ content: chunk, threadRootId: String(rootId) });
+        const response = await postOnce({ content: chunk, threadRootId: String(rootId) });
         if (undelivered(response)) return nonDelivery(response, posted, chunks.length);
         posted += 1;
       }
@@ -829,7 +839,7 @@ export const deliverChatReply = async ({
         log(`thread continuation failed (${err.message}) — posting the remainder top-level`);
         for (const chunk of chunks.slice(posted)) {
           // eslint-disable-next-line no-await-in-loop
-          const response = await postMessage({ content: chunk });
+          const response = await postOnce({ content: chunk });
           if (undelivered(response)) return nonDelivery(response, posted, chunks.length);
           posted += 1;
         }
@@ -855,7 +865,7 @@ export const deliverChatReply = async ({
     const lead = chunks[0] && chunks[0].length <= limit
       ? chunks[0]
       : '(reply too large for chat — attached in full)';
-    const response = await postMessage({ content: `${lead}\n\n${directive}` });
+    const response = await postOnce({ content: `${lead}\n\n${directive}` });
     if (undelivered(response)) return nonDelivery(response, 0, 1);
     return { mode: 'attach', messages: 1 };
   } catch (err) {
@@ -863,7 +873,7 @@ export const deliverChatReply = async ({
     let messages = 0;
     for (const chunk of chunks) {
       // eslint-disable-next-line no-await-in-loop
-      const response = await postMessage({ content: chunk });
+      const response = await postOnce({ content: chunk });
       if (undelivered(response)) return nonDelivery(response, messages, chunks.length);
       messages += 1;
     }

package/src/lib/grant-broker-guard.js

@@ -184,13 +184,21 @@ export const confinementReason = (environment, adapter, platform = process.platf
   const declared = sandbox;
   if (declared.mode === 'none') return 'sandbox_mode_none';
   if (effectiveSandboxTrust(declared.trust) !== 'public') return 'sandbox_trust_not_public';
+  // D245: native Windows has no OS jail for any adapter. Claude there runs
+  // only by the user's --unsandboxed (policy without a jail), and Codex runs on
+  // its own profiles with no Commonly sandbox, so neither carries a grant.
+  if (platform === 'win32') return 'sandbox_mode_unenforceable';
   const mode = resolvePublicSandboxMode(declared, platform);
   if (typeof mode !== 'string' || !ENFORCING_MODES.has(mode)) return 'sandbox_mode_unenforceable';
   return null;
 };
 
-const detailFor = (reason, adapter, environment) => {
+const detailFor = (reason, adapter, environment, platform = process.platform) => {
   const drop = 'or drop the grant broker from this seat';
+  if (reason === 'sandbox_mode_unenforceable' && platform === 'win32') {
+    return 'native Windows has no sandbox Commonly can enforce, so no agent on this computer gets connector grants;'
+      + ` run the agent on macOS or Linux to use grants, ${drop}`;
+  }
   if (reason === 'adapter_cannot_confine') {
     return `the seat runs the '${adapter || 'unresolved'}' adapter, which is not approved to receive the grant broker;`
       + ' move this seat to the claude or codex'
@@ -245,7 +253,7 @@ export const withholdGrantBroker = (environment, adapter, {
       code: GRANT_BROKER_REFUSAL_CODE,
       decidedBy: 'daemon',
       reason,
-      detail: detailFor(reason, adapter, environment),
+      detail: detailFor(reason, adapter, environment, platform),
     }, withheld);
   }
   return { ...environment, mcp: kept };

package/src/lib/native-runtime-inventory.js

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process';
 import { readFile, stat } from 'node:fs/promises';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { resolveWindowsCommandWithReason } from './windows-command.js';
 
 export const claudeEffortsFromHelp = (help) => {
   const section = String(help).match(/--effort\s+<[^>]+>([\s\S]*?)(?=\n\s+--|$)/)?.[1];
@@ -17,8 +18,14 @@ export const codexModelsFromCache = (cache) => {
     // Only levels supported by every advertised model are offered globally.
     efforts: levels.length ? levels[0].filter((level) => levels.every((list) => list.includes(level))) : [] };
 };
-export const claudeRuntimeInventory = async ({ spawnSyncImpl = spawnSync, env = process.env } = {}) => {
-  const result = spawnSyncImpl('claude', ['--help'], {
+export const claudeRuntimeInventory = async ({
+  spawnSyncImpl = spawnSync, env = process.env, commandResolution = {},
+} = {}) => {
+  // Windows: an npm `claude.cmd` is resolved to its target, never run through
+  // a shell (#2141). Elsewhere this is `claude --help`, unchanged.
+  const located = resolveWindowsCommandWithReason('claude', { env, ...commandResolution });
+  if (!located.command) return { models: null, efforts: [] };
+  const result = spawnSyncImpl(located.command, [...located.args, '--help'], {
     encoding: 'utf8', timeout: 5000, maxBuffer: 128 * 1024, cwd: tmpdir(), env,
   });
   return { models: null, efforts: result.status === 0 ? claudeEffortsFromHelp(result.stdout) : [] };

package/src/lib/reply-receipt.js

@@ -0,0 +1,53 @@
+// D245 item 4: the receipt the wrapper posts with a reply, so a BYO reply
+// carries "how this reply was made" the way a hosted reply has its run trace.
+// It is the wrapper's own account and the server stores it as self-reported
+// (backend/services/byoReceipt.ts), which also bounds and checks every field.
+// This side keeps to what it actually observed: an adapter that reports no
+// stats sends only its name and the measured duration.
+
+const isName = (value) => typeof value === 'string' && value.length > 0;
+const isCount = (value) => Number.isInteger(value) && value >= 0;
+
+const parseLine = (raw) => {
+  try { return JSON.parse(raw); } catch { return null; }
+};
+
+/**
+ * What a Claude Code stream-json run says about itself: the model from the
+ * init event, the turn count from the result event, and each tool it called,
+ * once, in first-use order.
+ */
+export const claudeRunStats = (stdout) => {
+  const events = String(stdout || '').split('\n').map(parseLine).filter(Boolean);
+  const stats = {};
+  const init = events.find((event) => event.type === 'system' && event.subtype === 'init');
+  if (isName(init?.model)) stats.model = init.model;
+  const result = [...events].reverse().find((event) => event.type === 'result');
+  if (isCount(result?.num_turns)) stats.turns = result.num_turns;
+  const tools = [];
+  for (const event of events) {
+    if (event.type !== 'assistant') continue;
+    for (const block of event.message?.content || []) {
+      if (block?.type === 'tool_use' && isName(block.name) && !tools.includes(block.name)) tools.push(block.name);
+    }
+  }
+  if (tools.length) stats.tools = tools;
+  return stats;
+};
+
+/** The receipt for one reply, or null when there is no adapter to name. */
+export const buildReplyReceipt = ({ adapterName, stats = {}, durationMs } = {}) => {
+  if (!isName(adapterName)) return null;
+  const receipt = { adapter: adapterName };
+  // A cloud-hosted model can be named by an ARN or a resource path that
+  // carries the account or project it runs in; that is not this reply's to
+  // publish, so such a model id is left out.
+  if (isName(stats?.model) && !/^arn:|(^|\/)projects\//i.test(stats.model)) receipt.model = stats.model;
+  if (isCount(stats?.turns)) receipt.turns = stats.turns;
+  if (Array.isArray(stats?.tools)) {
+    const tools = stats.tools.filter(isName);
+    if (tools.length) receipt.tools = tools;
+  }
+  if (Number.isFinite(durationMs) && durationMs >= 0) receipt.durationMs = Math.round(durationMs);
+  return receipt;
+};

package/src/lib/sandbox/bwrap.js

@@ -34,7 +34,13 @@ const expandHome = (p) => {
 // Never advise `sandbox.mode: none` here: a public seat refuses it, and the
 // mechanisms that do exist are named instead.
 const MACOS_MESSAGE = 'bwrap is Linux-only. On macOS a public seat runs under Seatbelt '
-  + '(sandbox.mode workspace or read-only); Windows has no supported sandbox yet, so use WSL 2.';
+  + '(sandbox.mode workspace or read-only).';
+// D245: Windows has no sandbox for agents, and WSL does not give Claude Code
+// one either (host-check.js linuxClaudeMessage), so the only honest way
+// forward named here is the user's own opt-in (sandbox/windows-unsandboxed.js).
+const WINDOWS_MESSAGE = 'bwrap is Linux-only, and native Windows has no sandbox for agents yet. '
+  + 'To run this agent without one, with your own access to files and commands, add --unsandboxed.';
+const nonLinuxMessage = (platform) => (platform === 'win32' ? WINDOWS_MESSAGE : MACOS_MESSAGE);
 
 const DEFAULT_RO_BINDS = [
   '/etc/ssl/certs',
@@ -55,7 +61,7 @@ const NAMESPACE_PROBE = ['--unshare-all', '--ro-bind', '/', '/', 'true'];
 
 export const detectBwrap = ({ spawn = spawnSync, platform = process.platform } = {}) => {
   if (platform !== 'linux') {
-    return { available: false, error: MACOS_MESSAGE };
+    return { available: false, error: nonLinuxMessage(platform) };
   }
   try {
     const res = spawn('bwrap', ['--version'], { encoding: 'utf8' });
@@ -98,7 +104,7 @@ export const detectBwrap = ({ spawn = spawnSync, platform = process.platform } =
  */
 export const wrapArgvWithBwrap = (innerArgv, env, opts = {}) => {
   if (process.platform !== 'linux') {
-    throw new Error(MACOS_MESSAGE);
+    throw new Error(nonLinuxMessage(process.platform));
   }
   if (!Array.isArray(innerArgv) || innerArgv.length === 0) {
     throw new Error('wrapArgvWithBwrap requires a non-empty innerArgv');

package/src/lib/sandbox/host-check.js

@@ -21,6 +21,9 @@ import { PUBLIC_SANDBOX_MODES, resolvePublicSandboxMode } from './mode.js';
 import { detectBwrap as defaultDetectBwrap } from './bwrap.js';
 import { detectSeatbelt as defaultDetectSeatbelt } from './seatbelt.js';
 
+// D245: the Windows opt-in (windows-unsandboxed.js re-exports it; defined here to avoid an import cycle).
+export const UNSANDBOXED_FLAG = '--unsandboxed';
+
 // The Seatbelt modes come from mode.js, as grant-broker-guard's do, so a mode
 // added there is not silently missing here.
 const SEATBELT_MODES = PUBLIC_SANDBOX_MODES;
@@ -36,7 +39,13 @@ export const windowsSandboxMessage = (adapterName) => {
   // Code (see linuxClaudeMessage).
   return [
     `Commonly runs a connected ${label} inside a sandbox, and has no sandbox for Windows yet,`,
-    'so this agent cannot listen for @mentions from native Windows. Instead:',
+    'so by default this agent cannot listen for @mentions from native Windows. You can:',
+    // D245: the user's own choice, never a default (sandbox/windows-unsandboxed.js).
+    ...(adapterName === 'claude'
+      ? [`  - Run it without an OS sandbox: add ${UNSANDBOXED_FLAG}`
+        + ` (commonly agent run <name> ${UNSANDBOXED_FLAG}, or commonly daemon install ${UNSANDBOXED_FLAG}).`
+        + " It keeps Commonly's restricted tool settings and gets no shell, but nothing at the OS level confines it, and it gets no connector grants."]
+      : []),
     ...(adapterName === 'claude'
       ? ['  - Use Commonly from your own Claude Code sessions: the Connect page shows a PowerShell `claude mcp add` command.']
       : [`  - WSL 2 (Ubuntu): install Node and ${label} inside WSL, run \`sudo apt install bubblewrap\`,`
@@ -66,6 +75,9 @@ export const hostSandboxRefusal = ({
   environment,
   adapterName,
   platform = process.platform,
+  // D245: the user's own opt-in for this run (windows-unsandboxed.js
+  // hostUnconfinedForRun). Never derived from the environment.
+  hostUnconfined = false,
   detectBwrap = defaultDetectBwrap,
   detectSeatbelt = defaultDetectSeatbelt,
 } = {}) => {
@@ -77,7 +89,9 @@ export const hostSandboxRefusal = ({
   const mode = sandbox.mode ?? resolvePublicSandboxMode(sandbox, platform);
   if (mode !== 'bwrap' && !SEATBELT_MODES.has(mode)) return null;
 
-  if (platform === 'win32') return windowsSandboxMessage(adapterName);
+  if (platform === 'win32') {
+    return hostUnconfined === true && adapterName === 'claude' ? null : windowsSandboxMessage(adapterName);
+  }
   // A workspace claude seat falls through to the bubblewrap probe below; the
   // probe failing, for any reason, is a refusal like any other adapter's.
   if (mode === 'bwrap' && adapterName === 'claude' && sandbox.trust !== 'workspace') {