@metamynd/agentsafe-signer 0.15.1 → 0.17.1

package/README.md

@@ -25,11 +25,37 @@ below) — no passphrase needed unless none is available on the host, in which c
 tells you what to set. Opens the signing socket (always on) and the admin socket (closes after one
 `generate-key` call or 60s, whichever comes first — see the design doc's "The admin interface").
 
+**0.17.1 — `install` output that can actually start the daemon on macOS and Windows.** The launchd plist
+and the Windows command ran `daemon.mjs` (a library with no argv handling) without `start`, the same defect
+already fixed for systemd; the plist also waited on a launchd socket no client uses, and the Windows command
+was an `sc.exe` service node cannot be (no SCM protocol, error 1053). Now: the plist runs `cli.mjs start` at
+login; Windows gets a per-user Scheduled Task XML (`schtasks /Create /XML`), and `--tier 2` on Windows is
+refused with a clear message. Every platform, systemd included, now passes the full DID as `--identity` —
+the systemd unit passed the `%i` instance hash, which the daemon would reject on every sign. See "OS service
+unit generation".
+
+**0.17.0 — `refund` is its own service-call action.** `sign-service-call` accepts `action: 'refund'` with two
+fields, `[amount, reason]` (`amount` as `String(n)`, or `''` for a full refund; `reason` or `''`), matching the
+issuer's dedicated refund signature (MAGP §8.7.6). A refund used to be signed as a `void`, so one signature could
+stand for either call; the issuer now refuses that. Needs `@metamynd/agentsafe-mcp-guard` 0.15.0 on the Service side.
+
+**0.16.0 — a service-role daemon signs its Service's settlement calls (`sign-service-call`).** A Service
+whose key lives here can now claim, capture, release, mark unknown and reconcile **as its own DID** (MAGP
+§8.7.6) instead of anonymously — required for every mainnet hold, and on testnet once the owner registers
+trusted counterparties (an anonymous claim is refused `COUNTERPARTY_AUTH_REQUIRED`). As with every op, the
+daemon builds the `MAGP-SERVICE-v1 | action | authorizationId | …fields | nonce | issuedAt` message itself
+from validated fields: `action` must be one of `claim`, `dispatched`, `unknown`, `capture`, `void`,
+`reconcile` with exactly the field count the issuer signs for it, `authorizationId` a UUID, fields strings of
+at most 512 characters, `issuedAt` fresh, and `serviceDid` (when given) the daemon's own identity. Service
+role only — an agent-role daemon refuses it (`DAEMON_OPERATION_NOT_PERMITTED`), so an agent can never sign
+as the counterparty that executes for it. Rate limit: 120 per 10 s. Needs `@metamynd/agentsafe-mcp-guard`
+0.13.0 or later on the Service side.
+
 ## Status
 
 **Implemented and tested:**
-- The full nine-operation signing-socket protocol (`sign-authorize`, `sign-envelope`, `sign-payload`,
-  `sign-handshake-nonce`, `sign-key-control-challenge`, `sign-log-checkpoint`,
+- The full ten-operation signing-socket protocol (`sign-authorize`, `sign-envelope`, `sign-payload`,
+  `sign-handshake-nonce`, `sign-service-call`, `sign-key-control-challenge`, `sign-log-checkpoint`,
   `sign-local-decision`, `get-identity`, `ping`) and the two-operation admin socket
   (`generate-key`, `status`), matching the design doc's closed operation set exactly — no generic
   "sign this string" primitive.
@@ -130,15 +156,17 @@ tells you what to set. Opens the signing socket (always on) and the admin socket
   by `sodium-native` (this package's only dependency, added deliberately — this specific property
   cannot be reached via a shell-out the way every other gap here was closed, since it must run
   inside the process that owns the memory). `secure-memory.smoke.mjs`.
-- **Core-dump-disable and Linux `ptrace`-denial**, closed declaratively rather than in the daemon's
-  own runtime code: the generated systemd units now prefix `ExecStart=` with
-  `setpriv --dumpable 0 --` (a real binary, no shell needed — ptrace-deny, pairs with the
-  already-present `LimitCORE=0`), and the generated launchd plist routes through `/bin/sh -c
-  'ulimit -c 0; exec "$@"'` (launchd has no `LimitCORE`-equivalent key, and `ulimit` is a shell
-  builtin) — both a true `exec()` chain, never a forked supervisor process. **Disclosed, not
-  closed**: macOS has no `ptrace`-deny reachable this way at all — `PT_DENY_ATTACH` must be called
-  *by* the target process itself via a syscall, the same architectural limitation `secure-memory.mjs`
-  discloses for `mlock()`.
+- **Core-dump-disable**, closed declaratively rather than in the daemon's own runtime code: the
+  generated systemd units set `LimitCORE=0`, and the generated launchd plist routes through
+  `/bin/sh -c 'ulimit -c 0; exec "$@"'` (launchd has no `LimitCORE`-equivalent key, and `ulimit` is
+  a shell builtin) — a true `exec()` chain, never a forked supervisor process. **`ptrace`-denial is
+  not implemented by a wrapper**: an earlier pass prefixed `ExecStart=` with
+  `setpriv --dumpable 0 --`, but that option does not exist (see the defect table under "OS service
+  unit generation"), so it was removed. On Linux, T3 rests on Tier 2's dedicated `DynamicUser` UID
+  (verified, below) and, at Tier 1, on the host's own `kernel.yama.ptrace_scope`. macOS has no
+  `ptrace`-deny reachable this way at all — `PT_DENY_ATTACH` must be called *by* the target process
+  itself via a syscall, the same architectural limitation `secure-memory.mjs` discloses for
+  `mlock()`. Windows has no core-dump or ptrace directive in the generated Scheduled Task.
 - **`sign-local-decision`, closing the gap left when local-decision audit reporting first
   shipped.** A daemon-custody agent can now sign its own local-first block/escalate/non-value-allow
   verdict for `POST /policy/decisions/local` the same way the static-key provider always could —
@@ -156,14 +184,13 @@ tells you what to set. Opens the signing socket (always on) and the admin socket
   bind a payload failed closed. `daemon-protocol.smoke.mjs`.
 
 **Deliberately not yet implemented — real gaps, not oversights:**
-- **The generated systemd unit has never started a daemon.** Running it for real on Ubuntu 24.04
-  LTS / systemd 255 (the first time this was tried on any Linux host) found five defects in a
-  single `ExecStart` line, four of them fatal before any daemon code ran. Three are fixed here;
-  two remain and are listed under "OS service unit generation" below. Until those two are closed,
-  `cli.mjs install`'s output is a template to adapt, not something that runs as generated.
-- `daemon-hardening.smoke.mjs` **currently fails** — on the two real defects above, not on a test
-  bug. That is deliberate: it is the assertion that would have caught them, and greening it by
-  weakening it would restore the exact blind spot that let a never-runnable unit ship.
+- **Socket activation** (systemd `LISTEN_FDS`, launchd `launch_activate_socket`) — see "Still
+  open" under "OS service unit generation". The daemon always binds its own
+  `<state-dir>/signer.sock`.
+- **The launchd plist and the Windows Scheduled Task have never been installed on a real host.**
+  Their content is asserted by `service-installer.smoke.mjs`; only the systemd unit has been run.
+- **Windows Tier 2** (a separate service account) — node does not implement the Service Control
+  Manager protocol, so `cli.mjs install --platform win32 --tier 2` refuses with a clear message.
 - All the smoke tests the design doc names now exist as their own files:
   `daemon-socket-permissions.smoke.mjs` (T4), `daemon-hardening.smoke.mjs` (Tier 1) and
   `daemon-hardening-tier2.smoke.mjs` (Tier 2, verified against a real system unit — see above). **Log integrity** is its own real file
@@ -263,11 +290,11 @@ used for this check needs to wait for the stop before detaching.
 
 ## OS service unit generation
 
-`service-installer.mjs` generates the real systemd/launchd/Windows unit content from the design
+`service-installer.mjs` generates the real systemd/launchd/Windows definitions from the design
 doc's own templates — parameterized by identity and tier — and `cli.mjs install` writes them to a
 local `--out-dir` you choose. **It never writes to a real system service location
-(`~/.config/systemd/user`, `/etc/systemd/system`, `~/Library/LaunchAgents`, the Windows service
-registry) and never runs `systemctl`/`launchctl`/`sc.exe` itself** — verified by
+(`~/.config/systemd/user`, `/etc/systemd/system`, `~/Library/LaunchAgents`, the Windows Task
+Scheduler) and never runs `systemctl`/`launchctl`/`schtasks` itself** — verified by
 `service-installer.smoke.mjs`'s own static check of the module's source, not just asserted in
 this paragraph. It prints the exact command to actually install the result; running that command
 is always a separate, deliberate, human step — registering a real system service is a genuine
@@ -278,11 +305,30 @@ node cli.mjs install --identity <did> --daemon-path /opt/agentsafe/signer/daemon
   --platform linux --tier 2 --out-dir ./service-units
 ```
 
-Tested: the Tier 1/Tier 2 content differences match the design doc exactly (the `%h`-vs-absolute
-`ExecStart` path and the `RemoveIPC=true` placement — both real bugs the code-review pass on the
-design doc itself caught before any of this was written) for systemd; the launchd plist's
-`SockPathMode`/`RunAtLoad`/`KeepAlive` values; and the Windows `sc.exe` argv shape (Virtual Service
-Account, no password to manage).
+What each platform gets (every one runs `cli.mjs start --state-dir <dir> --role <role> --identity
+<full DID>`, never the `daemon.mjs` library module):
+
+| Platform | Mechanism | State dir | Tiers |
+|---|---|---|---|
+| Linux | systemd `.socket` + `.service` | `%S/agentsafe/<id>` (`StateDirectory=`) | 1 (`--user`) and 2 (`DynamicUser`) |
+| macOS | launchd LaunchAgent, `RunAtLoad`, core dumps off via `ulimit -c 0` | `~/Library/Application Support/agentsafe/<id>` (or `--state-dir`); log in `~/Library/Logs/agentsafe-signer.<id>.log` | 1; Tier 2's Seatbelt profile is not generated |
+| Windows | Task Scheduler XML: logon trigger for one user, runs as that user unelevated (`InteractiveToken`, so the DPAPI KEK works), no 72h time limit, not stopped on battery | `%LOCALAPPDATA%\agentsafe\<id>` (or `--state-dir`) | 1 only — see below |
+
+**Windows is a Scheduled Task, not a service.** Earlier versions printed `sc.exe create
+AgentSafeSigner-<id> binPath="node.exe daemon.mjs --identity <id>"` under a Virtual Service
+Account. That could not work: the Service Control Manager requires the process to call
+`StartServiceCtrlDispatcher`/`SetServiceStatus`, node does not, and SCM kills such a process with
+error 1053 after about 30 seconds. It also ran `daemon.mjs` without `start`. A real Windows service
+needs an SCM-aware host (WinSW, NSSM) — a third-party dependency this package does not take — so
+`--tier 2` on `win32` now exits with a message saying so. The task runs a console window at
+logon; closing it stops the signer.
+
+Tested by `service-installer.smoke.mjs` (content only — nothing is executed): the Tier 1/Tier 2
+systemd differences (`%h`-vs-absolute `ExecStart`, `RemoveIPC=true` placement); the full launchd
+`ProgramArguments` array, `RunAtLoad`/`KeepAlive`/`Umask`, and XML escaping; the Windows task's
+`<Command>`/`<Arguments>` (including Windows command-line quoting of paths with spaces and trailing
+backslashes), trigger, principal and settings, the `schtasks` argv, the UTF-16LE+BOM file the CLI
+writes, and the Tier 2 refusal.
 
 **Now also tested, for the first time, by actually installing and starting it** (Ubuntu 24.04.4
 LTS, systemd 255, `systemctl --user`). The socket unit works: systemd created
@@ -301,8 +347,9 @@ running it:
 | 2 | `%h/` prefixed onto an **absolute** `--daemon-path` | `ExecStart` resolved to `/home/u/home/u/...`; the CLI's own documented example passes an absolute path, so this was the common case | **Fixed** — `%h` now applied only to a relative path |
 | 3 | `nodePath` defaulting to `/usr/bin/node` | Absent on any nvm/asdf/volta host (this one had node only under `~/.nvm`); systemd reports a bare `203/EXEC` with no hint which binary was missing | **Fixed** — defaults to `process.execPath` |
 | 4 | `MemoryDenyWriteExecute=true` | V8 is a JIT; its `mprotect` fails with `ENOMEM` inside `v8::base::OS::SetPermissions` during Isolate init and node dies with `SIGTRAP` (`Check failed: 12 == errno`) before running any daemon code. **No Node service can set this directive** | **Fixed** — removed from both tiers |
-| 5 | `ExecStart` points at `daemon.mjs` | `daemon.mjs` is a library module with no argv handling — `node daemon.mjs` returns 0 immediately and serves nothing | **Fixed** — `ExecStart` now runs `cli.mjs start --state-dir %S/agentsafe/%i --role <role> --identity %i` |
+| 5 | `ExecStart` points at `daemon.mjs` | `daemon.mjs` is a library module with no argv handling — `node daemon.mjs` returns 0 immediately and serves nothing | **Fixed** — `ExecStart` now runs `cli.mjs start --state-dir %S/agentsafe/%i --role <role> --identity …` (see row 7 for the identity value) |
 | 6 | `Type=notify` | Nothing in the package sends `sd_notify READY=1`, so systemd fails the unit with `Result: protocol` even though node is healthy and listening | **Fixed** — `Type=exec`, which still waits for a successful `execve()` without requiring the notify protocol |
+| 7 | `--identity %i` | `%i` is the 8-hex-digit instance id, not the DID. The daemon compares every signing request's `agentDid` against `--identity`, so it answered `ping` (which is how the fixes above were verified) but would refuse every sign with `DAEMON_IDENTITY_MISMATCH`. Found by reading, not by running | **Fixed** (0.17.1) — `--identity <full DID>`, with `%`/`$` escaped for systemd |
 
 **With all six fixed, the generated unit now starts and serves.** Verified by installing the
 generator's own output unmodified (plus a drop-in supplying `AGENTSAFE_SIGNER_PASSPHRASE`, since
@@ -331,8 +378,10 @@ point at the daemon's own `<state-dir>/signer.sock` until this is closed.
 Closing it properly means implementing the sd_notify/`LISTEN_FDS` protocol in the daemon — a real
 feature, not a generator tweak, and deliberately out of scope for this verification pass in the
 same way the macOS ptrace-deny gap above is: disclosed as a first-implementation-pass limit rather
-than quietly left for someone to discover in production. Also still untested: launchd and Windows
-installation, unchanged from the previous pass.
+than quietly left for someone to discover in production. The launchd plist deliberately declares
+no `Sockets` key (an earlier version did, with `RunAtLoad=false`, so the daemon only started when a
+client connected to a launchd socket no client uses — it never started at all). Still untested:
+launchd and Windows installation on a real host.
 
 ## OS-keychain KEK backends
 

package/cli.mjs

@@ -8,7 +8,8 @@ import path from 'node:path';
 import { SignerDaemon } from './daemon.mjs';
 import { deriveKek, loadOrCreateSalt } from './keystore.mjs';
 import { resolveKek } from './kek-backends.mjs';
-import { generateSystemdUnits, generateLaunchdPlist, generateWindowsService } from './service-installer.mjs';
+import { fileURLToPath } from 'node:url';
+import { generateSystemdUnits, generateLaunchdPlist, generateWindowsScheduledTask, instanceId, WINDOWS_TIER2_UNSUPPORTED } from './service-installer.mjs';
 import { verifyLogCheckpoints, listCheckpoints } from './log-checkpoint.mjs';
 import { runLogAnchor } from './log-anchor.mjs';
 import { runMigrate } from './migrate.mjs';
@@ -23,7 +24,22 @@ function runInstall(args) {
   const platform = args.platform ?? process.platform;
   const tier = args.tier === '2' || args.tier === 2 ? 2 : 1;
   const identity = args.identity;
-  const daemonPath = args['daemon-path'] ?? path.join(process.cwd(), 'daemon.mjs');
+  // Default: the daemon.mjs installed next to THIS cli.mjs, not one in the current directory — the
+  // generated unit runs cli.mjs from the same directory, so it must be a path that really exists.
+  const daemonPath = args['daemon-path'] ?? path.join(path.dirname(fileURLToPath(import.meta.url)), 'daemon.mjs');
+  // launchd and Task Scheduler have no %S/%h equivalent, so their state dir is an absolute path
+  // resolved at generation time from the generating user's home. Generating for another platform
+  // (or another user) must name it explicitly.
+  const stateDir = typeof args['state-dir'] === 'string' ? args['state-dir'] : undefined;
+  const homeDir = typeof args['home-dir'] === 'string' ? args['home-dir'] : undefined;
+  if (platform === 'darwin' && process.platform !== 'darwin' && !homeDir) {
+    console.error(`agentsafe-signer install --platform darwin on a ${process.platform} host requires --home-dir <the target user's macOS home, e.g. /Users/alice>`);
+    process.exit(1);
+  }
+  if (platform === 'win32' && process.platform !== 'win32' && (!stateDir || typeof args.user !== 'string')) {
+    console.error(`agentsafe-signer install --platform win32 on a ${process.platform} host requires --state-dir <absolute Windows path> and --user <DOMAIN\\user>`);
+    process.exit(1);
+  }
   const outDir = args['out-dir'] ?? path.join(process.cwd(), 'service-units');
   // --node-path matters most at Tier 2. The generator defaults to process.execPath, which is
   // correct at Tier 1 (the unit runs AS the invoking user, so their nvm/asdf node is reachable)
@@ -54,15 +70,28 @@ function runInstall(args) {
         '          /usr/local/share/agentsafe/signer/.');
     }
   } else if (platform === 'darwin') {
-    const { plist, plistFileName, enableCommand } = generateLaunchdPlist({ identity, tier, daemonPath, socketDir: outDir });
+    const { plist, plistFileName, enableCommand, stateDir: plistStateDir, logPath } = generateLaunchdPlist({
+      identity, tier, daemonPath, role, ...(nodePath ? { nodePath } : {}), ...(stateDir ? { stateDir } : {}), ...(homeDir ? { homeDir } : {}),
+    });
     fs.writeFileSync(path.join(outDir, plistFileName), plist);
     console.log(`Wrote launchd plist to ${outDir}`);
+    console.log(`State dir: ${plistStateDir}\nLog file:  ${logPath}`);
     console.log(`Copy it into ~/Library/LaunchAgents/, then run:\n  ${enableCommand}`);
   } else if (platform === 'win32') {
-    const { serviceName, enableCommand } = generateWindowsService({ identity, daemonPath });
-    fs.writeFileSync(path.join(outDir, `${serviceName}.install.txt`), enableCommand + '\n');
-    console.log(`Wrote the sc.exe install command to ${path.join(outDir, `${serviceName}.install.txt`)}`);
-    console.log(`Run it yourself, from an elevated prompt:\n  ${enableCommand}`);
+    if (tier === 2) {
+      console.error(WINDOWS_TIER2_UNSUPPORTED);
+      process.exit(1);
+    }
+    const xmlPath = path.resolve(outDir, `AgentSafeSigner-${instanceId(identity)}.xml`);
+    const task = generateWindowsScheduledTask({
+      identity, daemonPath, role, xmlPath, ...(nodePath ? { nodePath } : {}), ...(stateDir ? { stateDir } : {}), ...(typeof args.user === 'string' ? { userId: args.user } : {}),
+    });
+    // schtasks /XML reads the file as UTF-16 (the encoding the XML declares), BOM included.
+    fs.writeFileSync(xmlPath, Buffer.from('\ufeff' + task.xml, 'utf16le'));
+    console.log(`Wrote the Scheduled Task definition to ${xmlPath}`);
+    console.log(`State dir: ${task.stateDir}`);
+    console.log(`It starts the signer at your logon, as you, unelevated. Run it yourself:\n  ${task.enableCommand.replace(/\n/g, '\n  ')}`);
+    console.log('A console window opens for the signer at logon; closing it stops the signer.');
   } else {
     console.error(`Unsupported --platform "${platform}" — use linux, darwin, or win32.`);
     process.exit(1);
@@ -153,7 +182,7 @@ async function main() {
   if (command === 'migrate') return runMigrateCommand(args);
   if (command !== 'start') {
     console.error('Usage: agentsafe-signer start --state-dir <dir> --role agent|service [--identity <did>] [--admin] [--allow-rekey]');
-    console.error('   or: agentsafe-signer install --identity <did> --daemon-path <path> [--platform linux|darwin|win32] [--tier 1|2] [--role agent|service] [--node-path <path>] [--out-dir <dir>]');
+    console.error('   or: agentsafe-signer install --identity <did> --daemon-path <path> [--platform linux|darwin|win32] [--tier 1|2] [--role agent|service] [--node-path <path>] [--state-dir <dir>] [--home-dir <macOS home>] [--user <DOMAIN\\user>] [--out-dir <dir>]');
     console.error('   or: agentsafe-signer verify-log --state-dir <dir>');
     console.error('   or: agentsafe-signer log-anchor --state-dir <dir> --api-url <backend base url>');
     console.error('   or: agentsafe-signer migrate --state-dir <dir> --api-url <backend base url> --auth-token <token> --ref <agentIdentityId-or-did> --network-identity-id <id>');

package/daemon.mjs

@@ -18,7 +18,7 @@ export const MAX_LINE_BYTES = 64 * 1024;
 export const FRESHNESS_MS = 5 * 60 * 1000;
 export const CLOCK_SKEW_MS = 30 * 1000;
 
-const ALL_SIGNING_OPS = new Set(['sign-authorize', 'sign-envelope', 'sign-payload', 'sign-handshake-nonce', 'sign-key-control-challenge', 'sign-log-checkpoint', 'sign-local-decision', 'get-identity', 'ping']);
+const ALL_SIGNING_OPS = new Set(['sign-authorize', 'sign-envelope', 'sign-payload', 'sign-handshake-nonce', 'sign-key-control-challenge', 'sign-log-checkpoint', 'sign-local-decision', 'sign-service-call', 'get-identity', 'ping']);
 
 // sign-log-checkpoint is in BOTH role sets, unlike every other sign-* op: it authenticates the
 // daemon's own log-tamper-evidence checkpoint (T11), which every daemon keeps regardless of
@@ -29,7 +29,10 @@ const ALL_SIGNING_OPS = new Set(['sign-authorize', 'sign-envelope', 'sign-payloa
 // mandate locally, so it has nothing to report.
 const SIGNING_OPS_BY_ROLE = {
   agent: new Set(['sign-authorize', 'sign-envelope', 'sign-payload', 'sign-handshake-nonce', 'sign-key-control-challenge', 'sign-log-checkpoint', 'sign-local-decision', 'get-identity', 'ping']),
-  service: new Set(['sign-handshake-nonce', 'sign-log-checkpoint', 'get-identity', 'ping']),
+  // sign-service-call is SERVICE-role only: a Service's own settlement-surface call (claim / capture / void / …,
+  // MAGP §8.7.6). An agent never claims or settles its own holds — an agent-role daemon signing one would let an
+  // agent impersonate the counterparty that executes for it.
+  service: new Set(['sign-handshake-nonce', 'sign-service-call', 'sign-log-checkpoint', 'get-identity', 'ping']),
 };
 
 const DEFAULT_RATE_LIMITS = {
@@ -48,8 +51,31 @@ const DEFAULT_RATE_LIMITS = {
   // catches a misbehaving or compromised anchor script hammering this op instead of running on
   // its own schedule.
   'sign-log-checkpoint': { max: 5, windowMs: 60 * 60 * 1000 },
+  // A settled call is a claim plus one close (capture / void / unknown), so two signatures per executed
+  // action; a busy gateway serves many agents, hence well above sign-authorize's per-agent ceiling.
+  'sign-service-call': { max: 120, windowMs: 10_000 },
 };
 
+// MAGP §8.7.6 — the issuer's own layout (backend counterparty-auth.ts buildCounterpartyMessage):
+//   MAGP-SERVICE-v1 | action | authorizationId | ...fields | nonce | issuedAt   (each field "\" and "|" escaped)
+// The per-action field counts are the ones the issuer reconstructs the message from; anything else could
+// never verify there, so it is refused here rather than signed.
+const SERVICE_CALL_PREFIX = 'MAGP-SERVICE-v1';
+const SERVICE_CALL_FIELD_COUNTS = {
+  claim: [1, 2], // idempotency key [, payload digest field]
+  dispatched: [1, 1], // remote reference
+  unknown: [1, 1], // reason
+  capture: [3, 3], // amountCharged, bookingRef, settlementTxHash
+  void: [1, 1], // reason
+  refund: [2, 2], // amount ('' for a full refund), reason — its own action since 0.17.0, never signed as a void
+  reconcile: [0, 0],
+};
+const MAX_SERVICE_FIELD_LENGTH = 512;
+const escapeServiceField = (v) => String(v).replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+export function buildServiceCallMessage({ action, authorizationId, fields, nonce, issuedAt }) {
+  return [SERVICE_CALL_PREFIX, action, authorizationId, ...fields, nonce, issuedAt].map(escapeServiceField).join('|');
+}
+
 export const DEFAULT_CHECKPOINT_INTERVAL_MS = 15 * 60 * 1000;
 
 // Matches agentsafe-guard.mjs's own REPORTABLE_LOCAL_DECISIONS exactly (LOCAL_DECISIONS the
@@ -251,6 +277,8 @@ export class SignerDaemon {
         return this.#handleSignLogCheckpoint(params);
       case 'sign-local-decision':
         return this.#handleSignLocalDecision(params);
+      case 'sign-service-call':
+        return this.#handleSignServiceCall(params);
       default:
         throw new DaemonError('DAEMON_UNKNOWN_OPERATION');
     }
@@ -345,6 +373,41 @@ export class SignerDaemon {
     return { signature: this.#sign(Buffer.from(message, 'utf8')) };
   }
 
+  /**
+   * A Service's own settlement-surface call, signed as its identity (MAGP §8.7.6): the claim that makes it the one
+   * party allowed to settle the hold, and the capture / void / unknown / reconcile that follow. Without this a
+   * daemon-custody Service could only call anonymously, which the issuer refuses for every mainnet hold and for any
+   * owner who has registered counterparties (COUNTERPARTY_AUTH_REQUIRED).
+   *
+   * As with every op here the daemon builds the message ITSELF from validated fields, never signing caller bytes:
+   * the fixed `MAGP-SERVICE-v1` prefix is a domain no other message this daemon signs starts with (authorize
+   * messages start with the DID, handshake nonces are bare UUIDs, checkpoints and payload bindings carry their own
+   * prefixes), so a signature made here cannot be replayed as anything else. `serviceDid`, when given, must be this
+   * daemon's own bound identity — a Service configured with the wrong DID fails here, loudly, instead of sending a
+   * signature the issuer will reject as COUNTERPARTY_AUTH_INVALID.
+   */
+  #handleSignServiceCall(params = {}) {
+    this.#assertRateLimit('sign-service-call');
+    const { serviceDid, action, authorizationId, fields, nonce, issuedAt } = params;
+    if (typeof action !== 'string' || !Object.hasOwn(SERVICE_CALL_FIELD_COUNTS, action)) {
+      throw new DaemonError('DAEMON_MALFORMED_REQUEST', `action must be one of ${Object.keys(SERVICE_CALL_FIELD_COUNTS).join('|')}`);
+    }
+    if (typeof authorizationId !== 'string' || !UUID_RE.test(authorizationId)) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'authorizationId must be a UUID');
+    const [min, max] = SERVICE_CALL_FIELD_COUNTS[action];
+    if (!Array.isArray(fields) || fields.length < min || fields.length > max) {
+      throw new DaemonError('DAEMON_MALFORMED_REQUEST', `${action} takes ${min === max ? min : `${min}–${max}`} field(s)`);
+    }
+    if (!fields.every((f) => typeof f === 'string' && f.length <= MAX_SERVICE_FIELD_LENGTH)) {
+      throw new DaemonError('DAEMON_MALFORMED_REQUEST', `fields must be strings of at most ${MAX_SERVICE_FIELD_LENGTH} characters`);
+    }
+    if (typeof nonce !== 'string' || nonce.length < 8 || nonce.length > 128) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'nonce must be 8–128 characters');
+    if (typeof issuedAt !== 'string' || !freshnessOk(issuedAt)) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'issuedAt outside freshness window');
+    if (!this.#agentDid) throw new DaemonError('DAEMON_NOT_PROVISIONED');
+    if (serviceDid !== undefined && serviceDid !== this.#agentDid) throw new DaemonError('DAEMON_IDENTITY_MISMATCH');
+    const message = buildServiceCallMessage({ action, authorizationId, fields, nonce, issuedAt });
+    return { signature: this.#sign(Buffer.from(message, 'utf8')), serviceDid: this.#agentDid };
+  }
+
   #handleSignEnvelope(params = {}) {
     this.#assertRateLimit('sign-envelope');
     this.#validateCoreFields(params);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-signer",
-  "version": "0.15.1",
+  "version": "0.17.1",
   "description": "Local signer daemon for AgentSafe agent/service keys \u2014 the key never enters the calling guard's own process. See docs/design/agent-key-custody-local-signer-daemon-plan.md.",
   "type": "module",
   "main": "./daemon.mjs",

package/policy-core.mjs

@@ -643,16 +643,24 @@ function evaluateMandate(mandate, req) {
     };
   }
   for (const p of perms) {
-    const failing = (p.constraint ?? []).find((c) => !constraintSatisfied(c, req, true));
-    if (!failing) return { decision: "allow", reasonCode: "AUTHORIZED" };
+    const failing2 = (p.constraint ?? []).find((c) => !constraintSatisfied(c, req, true));
+    if (!failing2) return { decision: "allow", reasonCode: "AUTHORIZED" };
   }
-  const firstFail = (perms[0].constraint ?? []).find((c) => !constraintSatisfied(c, req, true));
+  const failing = (perms[0].constraint ?? []).filter((c) => !constraintSatisfied(c, req, true));
+  const firstFail = failing[0];
+  const reported = reportedFailure(failing) ?? firstFail;
   return {
     decision: firstFail?.onFail ?? "block",
-    reasonCode: reasonFor(firstFail, req),
-    matched: { kind: "permission", target: perms[0].target, constraint: firstFail }
+    reasonCode: reasonFor(reported, req),
+    matched: { kind: "permission", target: perms[0].target, constraint: reported }
   };
 }
+function reportedFailure(failing) {
+  const first = failing[0];
+  if (!first || !AMOUNT_OPERANDS.has(first.leftOperand)) return void 0;
+  const decision = first.onFail ?? "block";
+  return failing.find((c) => !AMOUNT_OPERANDS.has(c.leftOperand) && (c.onFail ?? "block") === decision);
+}
 function remainingBudget(b) {
   return Math.max(0, b.cap - b.spent - b.held);
 }

package/service-installer.mjs

@@ -2,15 +2,16 @@
 // docs/design/agent-key-custody-local-signer-daemon-plan.md's "OS service unit templates"
 // section. Deliberately writes files ONLY to a local output directory the caller specifies —
 // never to a real system location (~/.config/systemd/user, /etc/systemd/system,
-// ~/Library/LaunchAgents, the Windows service registry) and never invokes systemctl/launchctl/
-// sc.exe itself. It prints the exact command an operator runs to actually install the result;
+// ~/Library/LaunchAgents, the Windows Task Scheduler) and never invokes systemctl/launchctl/
+// schtasks itself. It prints the exact command an operator runs to actually install the result;
 // running that command is always a separate, deliberate, human step. See README.md "Status" for
 // why: registering a real system service is a genuine system modification, out of scope for what
 // this module does on its own.
+import os from 'node:os';
 import path from 'node:path';
 
 /** Deterministic, filesystem-safe short id for a logical identity (agentDid/serviceDid/name). */
-function shortId(identity) {
+export function instanceId(identity) {
   // Not crypto-sensitive — just needs to be stable and safe in a unit filename/pipe name.
   let h = 0;
   for (let i = 0; i < identity.length; i++) h = (Math.imul(h, 31) + identity.charCodeAt(i)) | 0;
@@ -26,10 +27,62 @@ function defaultNodePath() {
   return process.execPath || '/usr/bin/node';
 }
 
+/** One ExecStart= word. systemd splits the line on whitespace, so a path with a space in it (a node under
+ *  `/opt/Node JS/`, or `C:\Program Files\nodejs\node.exe` when the unit is generated on Windows) became two words and
+ *  the unit failed at exec. Double quotes are systemd's own quoting, with `\` and `"` escaped inside them. */
+function systemdArg(value) {
+  return /\s/.test(value) ? `"${value.replace(/(["\\])/g, '\\$1')}"` : value;
+}
+
 function assertTier(tier) {
   if (tier !== 1 && tier !== 2) throw new Error(`tier must be 1 or 2, got ${tier}`);
 }
 
+function assertRole(role) {
+  if (role !== 'agent' && role !== 'service') throw new Error(`role must be 'agent' or 'service', got ${role}`);
+}
+
+/** `--identity` is the full DID the daemon compares every signing request's agentDid against
+ *  (daemon.mjs #assertIdentity), so it goes into the generated command verbatim. A DID never
+ *  contains whitespace, quotes or control characters; rejecting them here keeps every generated
+ *  file free of quoting/injection edge cases (a newline would otherwise start a new unit directive). */
+function assertIdentity(identity) {
+  if (typeof identity !== 'string' || identity.length === 0 || /[\s"'\x00-\x1f\x7f]/.test(identity)) {
+    throw new Error('identity must be a DID string with no whitespace, quotes or control characters');
+  }
+}
+
+/** cli.mjs ships next to daemon.mjs in this package's `files` list, so it is derived from the same
+ *  directory; `cliPath` overrides it outright. */
+function resolveCliPath(daemonPath, cliPath) {
+  return cliPath ?? daemonPath.replace(/daemon\.mjs$/, 'cli.mjs');
+}
+
+function xmlEscape(value) {
+  return String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/** One argument on a Windows command line, quoted by the rules node (MSVCRT/CommandLineToArgvW)
+ *  uses to split it back: backslashes are literal unless they precede a quote. */
+function windowsArg(value) {
+  if (value && !/[\s"]/.test(value)) return value;
+  let out = '"';
+  let backslashes = 0;
+  for (const ch of value) {
+    if (ch === '\\') {
+      backslashes++;
+      continue;
+    }
+    if (ch === '"') {
+      out += '\\'.repeat(backslashes * 2 + 1) + '"';
+    } else {
+      out += '\\'.repeat(backslashes) + ch;
+    }
+    backslashes = 0;
+  }
+  return out + '\\'.repeat(backslashes * 2) + '"';
+}
+
 // --- Linux: systemd, socket-activated -------------------------------------------------------
 
 /**
@@ -39,7 +92,8 @@ function assertTier(tier) {
 export function generateSystemdUnits({ identity, tier, nodePath = defaultNodePath(), daemonPath, role = 'agent', cliPath }) {
   assertTier(tier);
   if (!identity || !daemonPath) throw new Error('generateSystemdUnits requires { identity, daemonPath }');
-  const id = shortId(identity);
+  assertIdentity(identity);
+  const id = instanceId(identity);
 
   const socketUnit = [
     `# agentsafe-signer@.socket (instance: ${id})`,
@@ -68,13 +122,19 @@ export function generateSystemdUnits({ identity, tier, nodePath = defaultNodePat
   // starts and instantly "succeeds" while never listening. Found by installing and starting the
   // unit on a real systemd host. cli.mjs ships alongside daemon.mjs in this package's own `files`
   // list, so deriving it from the same directory is stable, and `cliPath` overrides it outright.
-  if (role !== 'agent' && role !== 'service') throw new Error(`role must be 'agent' or 'service', got ${role}`);
-  const resolvedCliPath = cliPath ?? daemonPath.replace(/daemon\.mjs$/, 'cli.mjs');
+  assertRole(role);
+  const resolvedCliPath = resolveCliPath(daemonPath, cliPath);
   const isAbsolutePath = resolvedCliPath.startsWith('/');
   const cliInvocationPath = tier === 1 && !isAbsolutePath ? `%h/${resolvedCliPath.replace(/^\.?\//, '')}` : resolvedCliPath;
   // %S is systemd's own state-directory root, so this lines up with StateDirectory= below rather
   // than hard-coding a path that has to be kept in sync with it by hand.
-  const invocation = `${nodePath} ${cliInvocationPath} start --state-dir %S/agentsafe/%i --role ${role} --identity %i`;
+  // --identity is the full DID, NOT %i. %i is the 8-hex-digit instance id (a filename-safe hash of
+  // the DID), and the daemon compares every signing request's agentDid against the value given
+  // here — so `--identity %i` started a daemon that answered ping but refused every sign request
+  // with DAEMON_IDENTITY_MISMATCH. `%` and `$` are systemd specifier/variable syntax in ExecStart=,
+  // doubled so a DID containing them (did:web percent-encodes ports as %3A) reaches argv literally.
+  const identityArg = identity.replace(/%/g, '%%').replace(/\$/g, '$$$$');
+  const invocation = `${systemdArg(nodePath)} ${systemdArg(cliInvocationPath)} start --state-dir %S/agentsafe/%i --role ${role} --identity ${identityArg}`;
   // No setpriv wrapper. An earlier pass wrapped this in `setpriv --dumpable 0 --` to deny ptrace
   // via PR_SET_DUMPABLE=0. That option does not exist: util-linux's setpriv has no --dumpable flag
   // (checked on util-linux 2.39.3 / Ubuntu 24.04 LTS — the string is absent from the binary
@@ -146,55 +206,70 @@ export function generateSystemdUnits({ identity, tier, nodePath = defaultNodePat
   return { socketUnit, serviceUnit: serviceLines.join('\n'), id, enableCommand };
 }
 
-// --- macOS: launchd, socket-activated --------------------------------------------------------
+// --- macOS: launchd LaunchAgent, started at login -------------------------------------------
 
 /**
- * @param {{identity:string, tier:1|2, nodePath?:string, daemonPath:string, socketDir:string}} opts
+ * @param {{identity:string, tier:1|2, nodePath?:string, daemonPath:string, role?:'agent'|'service',
+ *   cliPath?:string, stateDir?:string, homeDir?:string}} opts
+ * @returns {{plist:string, plistFileName:string, label:string, id:string, stateDir:string, logPath:string, enableCommand:string}}
  */
-export function generateLaunchdPlist({ identity, tier, nodePath = '/usr/local/bin/node', daemonPath, socketDir }) {
+export function generateLaunchdPlist({ identity, tier, nodePath = defaultNodePath(), daemonPath, role = 'agent', cliPath, stateDir, homeDir = os.homedir() }) {
   assertTier(tier);
-  if (!identity || !daemonPath || !socketDir) throw new Error('generateLaunchdPlist requires { identity, daemonPath, socketDir }');
-  const id = shortId(identity);
+  if (!identity || !daemonPath) throw new Error('generateLaunchdPlist requires { identity, daemonPath }');
+  assertIdentity(identity);
+  assertRole(role);
+  const id = instanceId(identity);
   const label = `ai.metamynd.agentsafe-signer.${id}`;
-  const socketPath = path.posix.join(socketDir, `signer-${id}.sock`);
+  // ProgramArguments runs cli.mjs start, not daemon.mjs — the defect already fixed for systemd.
+  // daemon.mjs is a library module with no argv handling: `node daemon.mjs --identity x` loads it,
+  // exits 0 and serves nothing. The old plist also passed only --identity (no `start`, no
+  // --state-dir, no --role), which cli.mjs would have rejected even if it had been the target.
+  const resolvedCliPath = resolveCliPath(daemonPath, cliPath);
+  // launchd has no %h equivalent and starts jobs with a working directory of /, so a relative
+  // path cannot resolve to anything meaningful. Refuse it rather than emit a job that cannot exec.
+  if (!resolvedCliPath.startsWith('/')) throw new Error(`launchd needs an absolute cli/daemon path, got "${resolvedCliPath}"`);
+  const resolvedStateDir = stateDir ?? path.posix.join(homeDir, 'Library', 'Application Support', 'agentsafe', id);
+  if (!resolvedStateDir.startsWith('/')) throw new Error(`launchd needs an absolute state dir, got "${resolvedStateDir}"`);
+  // ~/Library/Logs always exists on macOS, so launchd can open this before the daemon has created
+  // its state dir. Without it the daemon's stdout/stderr (including the KEK-backend line and any
+  // fatal error) would go nowhere.
+  const logPath = path.posix.join(homeDir, 'Library', 'Logs', `agentsafe-signer.${id}.log`);
 
   // launchd's plist has no LimitCORE-equivalent key at all (unlike systemd), and `ulimit` is a
-  // shell builtin, not a real binary — so, unlike setpriv above, this genuinely needs a shell
-  // hop. `sh -c 'ulimit -c 0; exec "$@"' sh <node> <daemon> --identity <id>` sets $0='sh' (unused,
-  // just a placeholder) and the rest as $1.. via "$@", then `exec` replaces the shell with node —
-  // a true exec chain, not a forked supervisor, same as setpriv's own execve() above.
+  // shell builtin, not a real binary — so this genuinely needs a shell hop.
+  // `sh -c 'ulimit -c 0; exec "$@"' sh <node> <cli> start ...` sets $0='sh' (unused, just a
+  // placeholder) and the rest as $1.. via "$@", then `exec` replaces the shell with node — a true
+  // exec chain, not a forked supervisor. Each argument is its own <string>, so no shell word
+  // splitting applies to paths with spaces.
   //
   // Disclosed, not fixed: macOS has no ptrace-deny equivalent reachable this way at all —
   // PT_DENY_ATTACH must be called BY the target process itself via a syscall, which needs a
-  // native addon or FFI to reach from here, the same architectural limitation secure-memory.mjs's
-  // own header discloses for mlock(). Only RLIMIT_CORE is closed on macOS by this generator.
+  // native addon or FFI to reach from here. Only RLIMIT_CORE is closed on macOS by this generator.
+  //
+  // No launchd Sockets key and RunAtLoad=true. The old plist declared a launchd-owned socket in the
+  // install output directory with RunAtLoad=false, i.e. "start the daemon only when something
+  // connects to that socket". Nothing ever would: the daemon does not implement
+  // launch_activate_socket, it binds its own <state-dir>/signer.sock, and that is the path clients
+  // use. So the job never started. Same gap as the systemd .socket unit (see README.md "Status"),
+  // but here it prevented the daemon from starting at all, so it is removed rather than kept.
+  // KeepAlive stays false, matching the systemd unit (no Restart=): a daemon that fails to resolve
+  // its KEK exits non-zero and should not be relaunched in a loop.
+  const programArguments = ['/bin/sh', '-c', 'ulimit -c 0; exec "$@"', 'sh', nodePath, resolvedCliPath, 'start', '--state-dir', resolvedStateDir, '--role', role, '--identity', identity];
   const plist = [
     '<?xml version="1.0" encoding="UTF-8"?>',
     '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
     '<plist version="1.0">',
     '<dict>',
-    `  <key>Label</key><string>${label}</string>`,
+    `  <key>Label</key><string>${xmlEscape(label)}</string>`,
     '  <key>ProgramArguments</key>',
     '  <array>',
-    '    <string>/bin/sh</string>',
-    '    <string>-c</string>',
-    '    <string>ulimit -c 0; exec "$@"</string>',
-    '    <string>sh</string>',
-    `    <string>${nodePath}</string>`,
-    `    <string>${daemonPath}</string>`,
-    '    <string>--identity</string>',
-    `    <string>${id}</string>`,
+    ...programArguments.map((a) => `    <string>${xmlEscape(a)}</string>`),
     '  </array>',
-    '  <key>Sockets</key>',
-    '  <dict>',
-    '    <key>Listener</key>',
-    '    <dict>',
-    `      <key>SockPathName</key><string>${socketPath}</string>`,
-    '      <key>SockPathMode</key><integer>384</integer>',
-    '    </dict>',
-    '  </dict>',
-    '  <key>RunAtLoad</key><false/>',
+    '  <key>RunAtLoad</key><true/>',
     '  <key>KeepAlive</key><false/>',
+    '  <key>Umask</key><integer>63</integer>',
+    `  <key>StandardOutPath</key><string>${xmlEscape(logPath)}</string>`,
+    `  <key>StandardErrorPath</key><string>${xmlEscape(logPath)}</string>`,
     '  <key>ProcessType</key><string>Background</string>',
     '</dict>',
     '</plist>',
@@ -202,43 +277,138 @@ export function generateLaunchdPlist({ identity, tier, nodePath = '/usr/local/bi
   ].join('\n');
 
   const plistFileName = `${label}.plist`;
+  const bootstrap = `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/${plistFileName}`;
   const enableCommand =
     tier === 1
-      ? `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/${plistFileName}`
+      ? bootstrap
       : `# Tier 2 on macOS is a sandbox-exec Seatbelt profile layered on top of this same LaunchAgent, ` +
-        `not a separate plist mechanism — see README.md "Status" for what's not yet generated here.\n` +
-        `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/${plistFileName}`;
+        `not a separate plist mechanism — see README.md "Status" for what's not yet generated here.\n${bootstrap}`;
 
-  return { plist, plistFileName, id, enableCommand };
+  return { plist, plistFileName, label, id, stateDir: resolvedStateDir, logPath, enableCommand };
 }
 
-// --- Windows: a service under a Virtual Service Account, named pipe transport ---------------
+// --- Windows: a per-user Scheduled Task at logon ---------------------------------------------
+
+/**
+ * Windows Tier 2 is NOT supported by this generator. The previous version emitted
+ * `sc.exe create ... binPath="node.exe daemon.mjs --identity <id>"` under a Virtual Service
+ * Account, which could never work: the Service Control Manager requires the process to speak the
+ * service protocol (StartServiceCtrlDispatcher / SetServiceStatus) and node does not, so SCM kills
+ * it with error 1053 after ~30s. It also ran daemon.mjs (a library with no argv handling) without
+ * the `start` subcommand. Making it work needs a service host that speaks the SCM protocol (e.g.
+ * WinSW or NSSM) — a new third-party dependency, deliberately not added here.
+ */
+export const WINDOWS_TIER2_UNSUPPORTED =
+  'Tier 2 (a dedicated Windows service account) is not supported on Windows: node does not implement the ' +
+  'Service Control Manager protocol, so a plain `sc.exe create` service is killed by SCM (error 1053). ' +
+  'Use --tier 1 (a per-user Scheduled Task at logon), or wrap `node cli.mjs start ...` in an SCM-aware ' +
+  'service host such as WinSW or NSSM yourself.';
 
 /**
- * Returns the exact sc.exe argv this would run — never runs it. Tier 1 has no natural analog on
- * Windows (services are inherently system-level there), so this always targets Tier 2's Virtual
- * Service Account, matching the design doc's own "Tier 2 by default here, not Tier 1" call.
- * @param {{identity:string, nodePath?:string, daemonPath:string}} opts
+ * Generates a Task Scheduler XML definition that starts the signer at the user's logon, running AS
+ * that user with a limited token — the Windows analog of the Tier 1 systemd user unit. Never
+ * registers it: returns the XML and the exact schtasks argv an operator runs.
+ *
+ * Why a Scheduled Task and not a service: see WINDOWS_TIER2_UNSUPPORTED. Why XML and not
+ * `schtasks /Create /SC ONLOGON /TR ...`: /TR is capped at 261 characters (a node path + cli path +
+ * state dir + DID overflows it easily), and a /TR-created task gets the defaults
+ * ExecutionTimeLimit=PT72H (Task Scheduler kills the signer after three days) and
+ * DisallowStartIfOnBatteries/StopIfGoingOnBatteries=true (no signer on a laptop on battery).
+ * InteractiveToken, not S4U ("run whether logged on or not"): the Windows KEK backend is DPAPI in
+ * the user's scope, which needs the user's logon credentials that an S4U token does not carry.
+ *
+ * @param {{identity:string, tier?:1|2, nodePath?:string, daemonPath:string, role?:'agent'|'service',
+ *   cliPath?:string, stateDir?:string, localAppData?:string, userId?:string, xmlPath?:string}} opts
  */
-export function generateWindowsService({ identity, nodePath = 'node.exe', daemonPath }) {
-  if (!identity || !daemonPath) throw new Error('generateWindowsService requires { identity, daemonPath }');
-  const id = shortId(identity);
-  const serviceName = `AgentSafeSigner-${id}`;
-  const virtualAccount = `NT SERVICE\\${serviceName}`;
-  const binPath = `"${nodePath}" "${daemonPath}" --identity ${id}`;
+export function generateWindowsScheduledTask({
+  identity,
+  tier = 1,
+  nodePath = defaultNodePath(),
+  daemonPath,
+  role = 'agent',
+  cliPath,
+  stateDir,
+  localAppData = process.env.LOCALAPPDATA ?? path.win32.join(os.homedir(), 'AppData', 'Local'),
+  userId = process.env.USERNAME ? (process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${process.env.USERNAME}` : process.env.USERNAME) : undefined,
+  xmlPath,
+}) {
+  assertTier(tier);
+  if (tier === 2) throw new Error(WINDOWS_TIER2_UNSUPPORTED);
+  if (!identity || !daemonPath) throw new Error('generateWindowsScheduledTask requires { identity, daemonPath }');
+  assertIdentity(identity);
+  assertRole(role);
+  if (!userId) throw new Error('generateWindowsScheduledTask requires { userId } (DOMAIN\\user) when USERNAME is not set');
+  const id = instanceId(identity);
+  const taskName = `AgentSafeSigner-${id}`;
+  // Task Scheduler starts actions in %windir%\system32, so relative paths cannot work.
+  const resolvedCliPath = resolveCliPath(daemonPath, cliPath);
+  if (!path.win32.isAbsolute(resolvedCliPath)) throw new Error(`a Scheduled Task needs an absolute cli/daemon path, got "${resolvedCliPath}"`);
+  const resolvedStateDir = stateDir ?? path.win32.join(localAppData, 'agentsafe', id);
+  if (!path.win32.isAbsolute(resolvedStateDir)) throw new Error(`a Scheduled Task needs an absolute state dir, got "${resolvedStateDir}"`);
 
-  const createArgv = ['sc.exe', 'create', serviceName, `binPath=${binPath}`, 'start=auto', `obj=${virtualAccount}`, 'password='];
-  const startArgv = ['sc.exe', 'start', serviceName];
+  // Runs cli.mjs `start` with the args it requires — the same defect already fixed for systemd.
+  const argv = [resolvedCliPath, 'start', '--state-dir', resolvedStateDir, '--role', role, '--identity', identity];
+  const commandField = /\s/.test(nodePath) ? `"${nodePath}"` : nodePath;
+  const argumentsField = argv.map(windowsArg).join(' ');
+
+  const xml = [
+    '<?xml version="1.0" encoding="UTF-16"?>',
+    '<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">',
+    '  <RegistrationInfo>',
+    `    <Description>AgentSafe local signer daemon for identity ${id}</Description>`,
+    '  </RegistrationInfo>',
+    '  <Triggers>',
+    '    <LogonTrigger>',
+    '      <Enabled>true</Enabled>',
+    `      <UserId>${xmlEscape(userId)}</UserId>`,
+    '    </LogonTrigger>',
+    '  </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>false</StartWhenAvailable>',
+    '    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>',
+    '    <IdleSettings>',
+    '      <StopOnIdleEnd>false</StopOnIdleEnd>',
+    '      <RestartOnIdle>false</RestartOnIdle>',
+    '    </IdleSettings>',
+    '    <AllowStartOnDemand>true</AllowStartOnDemand>',
+    '    <Enabled>true</Enabled>',
+    '    <Hidden>false</Hidden>',
+    '    <RunOnlyIfIdle>false</RunOnlyIfIdle>',
+    '    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>',
+    '    <Priority>7</Priority>',
+    '  </Settings>',
+    '  <Actions Context="Author">',
+    '    <Exec>',
+    `      <Command>${xmlEscape(commandField)}</Command>`,
+    `      <Arguments>${xmlEscape(argumentsField)}</Arguments>`,
+    '    </Exec>',
+    '  </Actions>',
+    '</Task>',
+    '',
+  ].join('\r\n');
+
+  const xmlFile = xmlPath ?? `${taskName}.xml`;
+  const createArgv = ['schtasks.exe', '/Create', '/TN', taskName, '/XML', xmlFile];
+  const runArgv = ['schtasks.exe', '/Run', '/TN', taskName];
 
   return {
-    serviceName,
-    virtualAccount,
+    taskName,
+    id,
+    xml,
+    stateDir: resolvedStateDir,
     createArgv,
-    startArgv,
-    enableCommand: `${createArgv.map(quoteIfNeeded).join(' ')}\n${startArgv.join(' ')}`,
+    runArgv,
+    enableCommand: `${createArgv.map(windowsArg).join(' ')}\n${runArgv.map(windowsArg).join(' ')}`,
   };
-}
-
-function quoteIfNeeded(arg) {
-  return /\s/.test(arg) && !arg.includes('"') ? `"${arg}"` : arg;
-}
+}