@syntax-syllogism/sfd 0.1.0 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Windows: `sfd start` and every other command failed with
+  "process.getuid is not a function". The daemon now listens on a per-user
+  named pipe, finds `sf` with `where` (including npm `sf.cmd` shims), and
+  starts without a console window. CI runs on Windows as well as Linux.
+
+## [0.3.1] - 2026-10-22
+
+### Changed
+
+- Internal maintenance and tooling updates
+
+## [0.3.0] - 2026-10-22
+
+### Added
+
+- Added `sfd retrieve` for pulling metadata from an org into the local project
+- Added tracking commands for inspecting changes between local source and the org
+- Added filtered debug log output
+- Added automatic TraceFlag creation when debug logs are requested
+
+### Fixed
+
+- Fixed a startup failure on Windows (`process.getuid is not a function`)
+
+## [0.2.0] - 2026-10-22
+
+### Added
+
+- Agent hook that rewrites supported `sf` commands to their faster `sfd` equivalents
+
 ## [0.1.0] - 2026-10-22
 
 ### Added

package/README.md

@@ -29,12 +29,17 @@ sfd query "SELECT Id, Name FROM Account LIMIT 5" -o my-org
 | `sfd rest <path>` | REST call. `-X <method>`, `--body <json\|@file>` | `sf api request rest` |
 | `sfd describe <sobject>` | Compact describe; `--raw` for the full one. `--tooling` | `sf sobject describe` |
 | `sfd deploy -d <path> \| -m <Type[:Name]>` | Deploy source. `--check-only`, `-l <level>`, `-t <test>`, `-w <minutes>` | `sf project deploy start` |
-| `sfd test` | Run Apex tests. `-n <class>`, `-t <Class.method>`, `-s <suite>`, `-l <level>`, `-c` (coverage), `-w <minutes>` | `sf apex run test --wait` |
+| `sfd retrieve [-d <path> \| -m <Type[:Name]> \| -x <package.xml>]` | Retrieve source; no selector pulls tracked remote changes. `--ignore-conflicts`, `-w <minutes>` | `sf project retrieve start` |
+| `sfd tracking [--local \| --remote] [--conflicts]` | List local, remote and conflicting source-tracked changes; `--conflicts` shows only conflicts | |
+| `sfd test` | Run Apex tests. `-n <class>`, `-t <Class.method>`, `-s <suite>`, `-l <level>`, `-c` (coverage), `-w <minutes>`, `--logs` | `sf apex run test --wait` |
+| `sfd logs [--count 10] [--user <username>]` | Recent debug logs, one line each; `--limit` aliases `--count` | `sf apex list log` |
+| `sfd logs get <id\|latest>` | Debug, exception, validation, Flow error and high limit usage lines. `--full` prints raw text | `sf apex get log` |
 | `sfd org` | Resolved username, org id, instance URL and API version | `sf org display` |
+| `sfd hook <agent>`, `check`, `install`, `uninstall` | Agent integration: rewrite `sf` commands before an agent runs them. See [docs/agent-hooks.md](docs/agent-hooks.md) | |
 | `sfd start \| stop \| status \| reload` | Daemon lifecycle; `reload` drops cached orgs and auth state | |
 
-`-d`, `-m`, `-n`, `-t` and `-s` repeat or take comma-separated lists. Every
-command takes `-o <alias>` and `--json` (the raw daemon response). Without `-o`
+`-d`, `-m`, `-n`, `-t` and `-s` repeat or take comma-separated lists. The org
+commands take `-o <alias>`, and `--json` prints the raw daemon response. Without `-o`
 the org resolves like `sf`: `SF_TARGET_ORG`, then the nearest
 `.sf/config.json`, then the global config.
 
@@ -44,13 +49,15 @@ not be reached or started, or a request timed out. Unreadable input files are
 usage errors and include the file path.
 
 Use `sf` (with `--json` when scripting) for anything sfd does not cover (org creation, package
-commands, retrieve, data import).
+commands, data import).
 
 ## Daemon lifecycle
 
 The first command starts the daemon detached; there is nothing to set up. It
 listens on a Unix socket in `$XDG_RUNTIME_DIR/sfd-<uid>/` (or the system temp
 directory), in a directory with mode `0700` and a socket with mode `0600`.
+On Windows it listens on a per-user named pipe (`\\.\pipe\sfd-<hash>`), and
+the log and pid files go in `%LOCALAPPDATA%\sfd\`.
 Access tokens stay in daemon memory and are never written to disk. The daemon
 log is `sfd.log` in the same directory; `sfd status` prints its path.
 
@@ -76,9 +83,11 @@ it down even if its protocol differs.
 
 - Queries fetch every page without a record cap. Compact results preserve
   `done` and any continuation URL supplied by Salesforce.
-- Deploys reload `sfdx-project.json` on every call and run one at a time per
-  daemon. After a successful deploy to an org that tracks source, sfd updates
-  source tracking as `sf project deploy start` does.
+- Deploys, retrieves and `tracking` share one queue per daemon, so they run
+  one at a time. Deploys reload `sfdx-project.json` on every call.
+- Retrieve conflicts, changes-only retrieves, and how `tracking` and deploys
+  update source tracking are described in
+  [docs/source-tracking.md](docs/source-tracking.md).
 - `deploy` without `-l` uses the Metadata API default. `-t` alone implies
   `RunSpecifiedTests`.
 - `test` without selectors runs `RunLocalTests`. A non-matching method is
@@ -86,13 +95,23 @@ it down even if its protocol differs.
 - Paths in `-d` and the project directory resolve from the client's working
   directory, not the daemon's.
 
+### Debug logs
+
+`logs`, `logs get` and `test --logs` create or extend the current user's
+developer TraceFlag for 30 minutes when it is missing, expired or has less than
+five minutes left, and print one notice on stderr when they do. `--no-trace`
+skips that setup. `logs --user` only filters the list. Setup needs Tooling API
+permission to manage TraceFlag and DebugLevel records. The TraceFlag rules,
+filtered output format and `test --logs` behavior are in
+[docs/debug-logs.md](docs/debug-logs.md).
+
 ## Environment
 
 | Variable | Purpose |
 | --- | --- |
-| `SFD_TIMEOUT_SECONDS` | Positive request deadline in seconds, including connection time. Overrides defaults: 3 seconds for health/lifecycle requests; 120 seconds for other operations, extended to at least the deploy/test `-w` wait plus 60 seconds (default waits: 33/60 minutes). Increase this for long queries or queued deploys. Timeout exits 3. |
+| `SFD_TIMEOUT_SECONDS` | Positive request deadline in seconds, including connection time. Overrides defaults: 3 seconds for health/lifecycle requests; 120 seconds for other operations, extended to at least the deploy/retrieve/test `-w` wait plus 60 seconds (default waits: 33/33/60 minutes). Increase this for long queries or queued deploys. Timeout exits 3. |
 | `SFD_IDLE_MINUTES` | Idle timeout, default 60. |
-| `SFD_RUNTIME_DIR` | Socket, log and pid directory. |
+| `SFD_RUNTIME_DIR` | Socket, log and pid directory (on Windows, log and pid only; the pipe name is derived from it). |
 | `SFD_SF_ROOT` | `@salesforce/cli` install to load libraries from, instead of the `sf` on `PATH`. |
 | `SFD_HANDLERS_MODULE` | Test seam: stub handlers module used by the CLI tests. |
 
@@ -100,8 +119,9 @@ it down even if its protocol differs.
 
 `npm test` covers project and org resolution, output formatting, the socket
 protocol (dispatch, version restart, drain, idle, stale socket), and the CLI
-end to end against stub handlers. Injected Salesforce modules cover handler
-paging, auth refresh, deployment and test orchestration without an org.
+end to end against stub handlers, and the agent hook adapters and `sf` rewrite
+rules. Injected Salesforce modules cover handler
+paging, auth refresh, deployment, retrieve, source tracking and test orchestration without an org.
 A real-org check is opt-in:
 
 ```bash
@@ -124,3 +144,20 @@ See [SECURITY.md](SECURITY.md) for how to report vulnerabilities.
 ## License
 
 [MIT](LICENSE) © Jacob Richter
+
+## Agent integration
+
+`sfd hook` rewrites supported `sf` shell commands before a coding agent runs
+them, so they reach the warm daemon. Install an adapter for Claude Code, Codex
+CLI or Gemini CLI (user scope by default):
+
+```bash
+sfd hook install --agent claude
+sfd hook install --agent codex
+sfd hook install --agent gemini
+```
+
+Add `--project` to install into the current project instead. Preview a rewrite
+with `sfd hook check '<sf command>'`. The supported commands, adapter details,
+skip rules and the `SFD_HOOK_DISABLE=1` switch are in
+[docs/agent-hooks.md](docs/agent-hooks.md).

package/bin/sfd.mjs

@@ -4,8 +4,9 @@ import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { call, isRunning, startDaemon, DaemonError, VERSION } from "../src/client.mjs";
 import { findProjectDir, resolveTargetOrg } from "../src/project.mjs";
-import { formatApex, formatDeploy, formatTests } from "../src/format.mjs";
+import { formatApex, formatLog, formatLogList, formatDeploy, formatTests, formatRetrieve, formatTracking } from "../src/format.mjs";
 import { paths } from "../src/paths.mjs";
+import { UsageError } from "../src/usage-error.mjs";
 
 const USAGE = `sfd ${VERSION}: fast Salesforce CLI operations through a warm local daemon
 
@@ -18,9 +19,16 @@ Commands:
   describe <sobject>    Compact describe. --tooling, --raw for the full describe
   deploy                Deploy source. -d <path> (repeatable), -m <Type[:Name]> (repeatable),
                         --check-only, -l <test level>, -t <test> (repeatable), -w <minutes>
+  retrieve              Retrieve source. -d <path>, -m <Type[:Name]> or -x <package.xml>,
+                        -w <minutes>, --ignore-conflicts. No selector pulls tracked remote changes
+  tracking              Show source-tracked changes. --local | --remote, --conflicts (conflicts only)
   test                  Run Apex tests. -n <class> (repeatable), -t <Class.method> (repeatable),
-                        -s <suite> (repeatable), -l <test level>, -c (coverage), -w <minutes>
+                        -s <suite> (repeatable), -l <test level>, -c (coverage), -w <minutes>, --logs, --no-trace
+  logs                  List recent debug logs. --count/--limit <10>, --user <username>, --no-trace
+  logs get <id|latest>  Print a filtered log. --full for raw text, --no-trace
   org                   Show the resolved org (username, id, instance, API version)
+  hook <agent|check|install|uninstall>
+                        Integrate with Claude Code, Codex CLI or Gemini CLI
   start | stop | status | reload
                         Manage the daemon. reload drops cached orgs and auth state
 
@@ -39,11 +47,22 @@ const options = {
   all: { type: "boolean" },
   raw: { type: "boolean" },
   log: { type: "boolean" },
+  logs: { type: "boolean" },
+  full: { type: "boolean" },
+  "no-trace": { type: "boolean" },
+  count: { type: "string" },
+  limit: { type: "string" },
+  user: { type: "string" },
   file: { type: "string", short: "f" },
   method: { type: "string", short: "X" },
   body: { type: "string" },
   "source-dir": { type: "string", short: "d", multiple: true },
   metadata: { type: "string", short: "m", multiple: true },
+  manifest: { type: "string", short: "x" },
+  "ignore-conflicts": { type: "boolean" },
+  local: { type: "boolean" },
+  remote: { type: "boolean" },
+  conflicts: { type: "boolean" },
   "check-only": { type: "boolean" },
   "test-level": { type: "string", short: "l" },
   tests: { type: "string", short: "t", multiple: true },
@@ -53,8 +72,6 @@ const options = {
   wait: { type: "string", short: "w" }
 };
 
-class UsageError extends Error {}
-
 const split = list => list?.flatMap(v => v.split(",")).map(v => v.trim()).filter(Boolean);
 
 function readStdin() {
@@ -86,8 +103,12 @@ function print(value) {
 }
 
 async function run(argv) {
+  if (argv[0] === "hook") {
+    const { runHook } = await import("../src/hooks.mjs");
+    return runHook(argv.slice(1));
+  }
   const { values, positionals } = parseArgs({ args: argv, options, allowPositionals: true });
-  const [command, ...rest] = positionals;
+  let [command, ...rest] = positionals;
   if (values.help || !command) { print(USAGE); return 0; }
 
   const cwd = process.cwd();
@@ -167,10 +188,46 @@ async function run(argv) {
       render = result => formatDeploy(result, req.org);
       break;
     }
+    case "retrieve": {
+      const dir = projectDir();
+      const sourcePaths = split(values["source-dir"])?.map(d => resolve(cwd, d));
+      const manifest = values.manifest ? resolve(cwd, values.manifest) : undefined;
+      for (const p of [...(sourcePaths ?? []), ...(manifest ? [manifest] : [])]) {
+        if (!existsSync(p)) throw new UsageError(`No such path: ${p}`);
+      }
+      const metadata = split(values.metadata);
+      if ([Boolean(sourcePaths?.length), Boolean(metadata?.length), Boolean(manifest)].filter(Boolean).length > 1) {
+        throw new UsageError("retrieve accepts only one of -d, -m or -x.");
+      }
+      req = { org: org(), projectDir: dir, sourcePaths, metadata, manifest,
+        ignoreConflicts: values["ignore-conflicts"], waitMinutes: wait(values) };
+      render = result => formatRetrieve(result, req.org);
+      break;
+    }
+    case "tracking":
+      if (values.local && values.remote) throw new UsageError("tracking accepts only one of --local or --remote.");
+      req = { org: org(), projectDir: projectDir(), local: values.local, remote: values.remote, conflicts: values.conflicts };
+      render = formatTracking;
+      break;
+    case "logs": {
+      if (rest[0] === "get") {
+        if (rest.length !== 2) throw new UsageError("logs get needs an ID or latest.");
+        command = "logGet";
+        req = { org: org(), id: rest[1], noTrace: values["no-trace"] };
+        render = result => values.full ? result.body : formatLog(result);
+      } else {
+        if (rest.length) throw new UsageError("logs accepts only get <id|latest>.");
+        const count = Number(values.count ?? values.limit ?? 10);
+        if (!Number.isSafeInteger(count) || count < 1) throw new UsageError("Log count must be a positive integer.");
+        req = { org: org(), count, user: values.user, noTrace: values["no-trace"] };
+        render = result => formatLogList(result.records);
+      }
+      break;
+    }
     case "test":
       req = {
         org: org(), classNames: split(values["class-names"]), tests: split(values.tests), suiteNames: split(values["suite-names"]),
-        testLevel: values["test-level"], codeCoverage: values["code-coverage"], waitMinutes: wait(values)
+        logs: values.logs, noTrace: values["no-trace"], testLevel: values["test-level"], codeCoverage: values["code-coverage"], waitMinutes: wait(values)
       };
       render = result => formatTests(result, req.org);
       break;
@@ -182,10 +239,14 @@ async function run(argv) {
   }
 
   const res = await call(command, req);
-  if (values.json) { print(res); return res.status === 0 ? okStatus(command, res.result) : 1; }
+  const trace = res.result?.trace ?? res.trace;
+  if (trace) {
+    process.stderr.write(`sfd: enabled debug logging for ${trace.username} until ${trace.expires} (TraceFlag ${trace.id})\n`);
+  }
+  if (values.json) { print(res); return res.status === 0 ? okStatus(command, res.result) : res.name === "UsageError" ? 2 : 1; }
   if (res.status !== 0) {
     process.stderr.write(`${res.name}: ${res.message}\n`);
-    return 1;
+    return res.name === "UsageError" ? 2 : 1;
   }
   print(render(res.result));
   return okStatus(command, res.result);
@@ -194,7 +255,7 @@ async function run(argv) {
 // A request can succeed while the Salesforce operation fails (compile error, failed deploy or test).
 function okStatus(command, result) {
   if (command === "apex") return result.compiled && result.success ? 0 : 1;
-  if (command === "deploy") return result.success ? 0 : 1;
+  if (command === "deploy" || command === "retrieve") return result.success ? 0 : 1;
   if (command === "test") return result.failing === 0 && !result.setupFailures?.length ? 0 : 1;
   return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntax-syllogism/sfd",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "Warm Salesforce CLI daemon: SOQL, anonymous Apex, REST, describe, deploy, and Apex tests without sf startup cost.",
   "type": "module",
   "bin": {
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "for f in bin/sfd.mjs src/*.mjs; do node --check \"$f\" || exit 1; done",
+    "build": "node scripts/check-syntax.mjs",
     "test": "node --test test/*.test.mjs"
   }
 }

package/src/client.mjs

@@ -29,7 +29,7 @@ export function startDaemon(env = process.env) {
   const p = paths(env);
   const out = openSync(p.log, "a");
   const child = spawn(process.execPath, [fileURLToPath(new URL("./daemon.mjs", import.meta.url))], {
-    detached: true, stdio: ["ignore", out, out], env
+    detached: true, windowsHide: true, stdio: ["ignore", out, out], env
   });
   child.unref();
 }
@@ -55,7 +55,7 @@ export async function call(op, args = {}, { env = process.env, autoStart = true,
     try {
       const configured = Number(env.SFD_TIMEOUT_SECONDS);
       const health = ["ping", "status", "stop", "reload"].includes(op);
-      const waitMinutes = args.waitMinutes ?? (op === "deploy" ? 33 : op === "test" ? 60 : 0);
+      const waitMinutes = args.waitMinutes ?? (["deploy", "retrieve"].includes(op) ? 33 : op === "test" ? 60 : 0);
       const timeoutMs = Number.isFinite(configured) && configured > 0
         ? configured * 1000
         : health ? 3000 : Math.max(120_000, waitMinutes * 60_000 + 60_000);

package/src/daemon.mjs

@@ -4,13 +4,16 @@ import { PROTOCOL, VERSION } from "./version.mjs";
 import { AlreadyRunning, startServer } from "./server.mjs";
 import { paths } from "./paths.mjs";
 import { findSfRoot, sfInfo } from "./sf-root.mjs";
+import { pathToFileURL } from "node:url";
 
 const log = (...args) => console.error(new Date().toISOString(), ...args);
 const p = paths();
 const sf = sfInfo(findSfRoot());
 
 // SFD_HANDLERS_MODULE swaps in stub handlers for tests that must not touch an org.
-const { createHandlers } = await import(process.env.SFD_HANDLERS_MODULE ?? "./handlers.mjs");
+// import() needs a file URL for absolute Windows paths such as C:\\...
+const handlersModule = process.env.SFD_HANDLERS_MODULE ? pathToFileURL(process.env.SFD_HANDLERS_MODULE).href : "./handlers.mjs";
+const { createHandlers } = await import(handlersModule);
 const handlers = createHandlers(sf.root);
 
 // An sf upgrade rewrites its package.json; finish in-flight work and let the next call start fresh.

package/src/format.mjs

@@ -1,3 +1,5 @@
+import { relative, resolve } from "node:path";
+
 // Compact, token-friendly renderings of Salesforce results.
 
 const asArray = x => (x === undefined || x === null ? [] : Array.isArray(x) ? x : [x]);
@@ -54,16 +56,56 @@ export function formatApex(result, { fullLog = false } = {}) {
   if (fullLog) {
     lines.push(log);
   } else {
-    // Keep only USER_DEBUG and fatal lines; the rest of a debug log is noise for agents.
-    for (const line of log.split("\n")) {
-      const m = line.match(/\|USER_DEBUG\|\[(\d+)\]\|\w+\|(.*)$/);
-      if (m) lines.push(`[${m[1]}] ${m[2]}`);
-      else if (/\|FATAL_ERROR\|/.test(line)) lines.push(line.replace(/^.*\|FATAL_ERROR\|/, "FATAL: "));
-    }
+    lines.push(...filterLog(log, { apexOnly: true }));
   }
   return lines.join("\n");
 }
 
+// Anonymous Apex retains its original two-event rendering.
+export function filterLog(text, { apexOnly = false } = {}) {
+  const lines = [];
+  let inLimits = false;
+  for (const line of text.split(/\r?\n/)) {
+    const debug = line.match(/\|USER_DEBUG\|\[(\d+|EXTERNAL)\]\|\w+\|(.*)$/);
+    if (debug && (!apexOnly || debug[1] !== "EXTERNAL")) { lines.push(`[${debug[1]}] ${debug[2]}`); continue; }
+    if (/\|FATAL_ERROR\|/.test(line)) { lines.push(line.replace(/^.*\|FATAL_ERROR\|/, "FATAL: ")); continue; }
+    if (apexOnly) continue;
+    const event = line.match(/\|(EXCEPTION_THROWN|VALIDATION_FAIL|VALIDATION_ERROR|FLOW_ELEMENT_ERROR)(?:\|(.*))?$/);
+    if (event) {
+      const label = event[1] === "EXCEPTION_THROWN" ? "EXCEPTION" : event[1].startsWith("FLOW") ? "FLOW" : "VALIDATION";
+      lines.push(`${label} ${(event[2] ?? "").replaceAll("|", " ")}`.trimEnd());
+      continue;
+    }
+    if (line.includes("|LIMIT_USAGE_FOR_NS|")) { inLimits = true; continue; }
+    if (inLimits && /^\s*Number of |^\s*(Maximum CPU time|Maximum heap size)/.test(line)) {
+      const usage = line.match(/^\s*(.+?):\s*(\d+) out of (\d+)/);
+      if (usage && Number(usage[3]) > 0 && Number(usage[2]) >= Number(usage[3]) / 2) {
+        const name = usage[1].replace(/^Number of /, "").replace(/ queries$/, "").replace(/^Maximum /, "");
+        lines.push(`LIMIT ${name} ${usage[2]}/${usage[3]}`);
+      }
+    } else if (line.includes("|")) inLimits = false;
+  }
+  if (apexOnly) return lines;
+  const deduped = [];
+  for (let i = 0; i < lines.length;) {
+    let end = i + 1;
+    while (lines[end] === lines[i]) end++;
+    deduped.push(lines[i] + (end - i > 1 ? ` ×${end - i}` : ""));
+    i = end;
+  }
+  return deduped;
+}
+
+const logSize = bytes => bytes >= 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${bytes ?? 0} B`;
+
+export function formatLog(log) {
+  return [`${log.operation} ${log.status} ${log.duration ?? 0}ms ${logSize(log.length)}`, ...filterLog(log.body)].join("\n");
+}
+
+export function formatLogList(rows) {
+  return rows.length ? rows.map(row => `${row.Id} ${row.StartTime.replace("T", " ").replace(/\.\d+Z$/, "")} ${row.Operation} ${row.Status} ${logSize(row.LogLength)} ${row.DurationMilliseconds}ms`).join("\n") : "No debug logs found.";
+}
+
 export function formatDeploy(summary, org) {
   const action = summary.checkOnly ? "Validated" : "Deployed";
   const tests = summary.numberTestsTotal > 0
@@ -134,5 +176,66 @@ export function formatTests(summary, org) {
   for (const c of summary.coverage ?? []) {
     lines.push(`  ${c.percentage.padStart(4)} ${c.name}${c.uncoveredLines.length ? ` uncovered: ${c.uncoveredLines.join(",")}` : ""}`);
   }
+  if (summary.logs?.length) {
+    lines.push("Logs:");
+    for (const log of summary.logs) {
+      lines.push(`  ${log.id}`);
+      if (log.body !== undefined) lines.push(...formatLog(log).split("\n").map(line => `    ${line}`));
+    }
+  }
   return lines.join("\n");
 }
+
+// Normalize both SDR file responses and STL change/status rows at the boundary.
+export function summarizeChanges(changes, projectDir, state) {
+  const files = changes.flatMap(c => (c.filenames?.length ? c.filenames : [c.filePath]).map(path => ({
+    state: state ?? c.state ?? (c.deleted ? "Deleted" : c.modified ? "Changed" : "Add"),
+    type: c.type, fullName: c.fullName ?? c.name,
+    path: path ? relative(projectDir, resolve(projectDir, path)) : undefined,
+    ...(c.problem ? { problem: c.problem } : {})
+  })));
+  return [...new Map(files.map(f => [JSON.stringify([f.state, f.type, f.fullName, f.path, f.problem]), f])).values()];
+}
+
+export function summarizeRetrieve(result, projectDir) {
+  const response = result.response;
+  const files = summarizeChanges(result.getFileResponses(), projectDir);
+  return {
+    success: Boolean(response.success) && !files.some(f => f.state === "Failed" || f.problem),
+    status: response.status, id: response.id, files,
+    warnings: asArray(response.messages), conflicts: [], errorMessage: response.errorMessage
+  };
+}
+
+function componentLines(files, conflict = false) {
+  // Collapse only a source file's companion XML; retain bundle files and all failures.
+  const paths = new Set(files.filter(f => !f.problem).map(f => `${f.type}:${f.fullName}:${f.path}`));
+  return files.filter(f => f.problem || !f.path?.endsWith("-meta.xml") ||
+    !paths.has(`${f.type}:${f.fullName}:${f.path.slice(0, -9)}`)).map(f => {
+    const state = String(f.state).toLowerCase();
+    const mark = conflict ? "! conflict" : f.problem || state === "failed" ? "✖" :
+      ["add", "added", "created"].includes(state) ? "+" : ["delete", "deleted"].includes(state) ? "-" : "~";
+    return `  ${mark} ${f.type} ${f.fullName}${f.path ? ` ${f.path}` : ""}${f.problem ? `: ${f.problem}` : ""}`;
+  });
+}
+
+export function formatRetrieve(summary, org) {
+  const count = new Set(summary.conflicts.map(c => `${c.type}:${c.fullName}`)).size;
+  const head = count
+    ? `CONFLICTS: ${count} component${count === 1 ? "" : "s"} changed both locally and in ${org}; rerun with --ignore-conflicts to overwrite`
+    : summary.message ?? (summary.success
+      ? `Retrieved ${summary.files.length} files from ${org}${summary.id ? ` (${summary.id})` : ""}`
+      : `FAILED (${summary.status}) ${org}${summary.id ? ` (${summary.id})` : ""}`);
+  const lines = [head, ...componentLines(summary.files), ...componentLines(summary.conflicts, true)];
+  for (const warning of summary.warnings) lines.push(`  ! ${typeof warning === "string" ? warning : warning.problem ?? JSON.stringify(warning)}`);
+  if (summary.errorMessage) lines.push(`  ✖ ${summary.errorMessage}`);
+  return lines.join("\n");
+}
+
+export function formatTracking(summary) {
+  const lines = [];
+  for (const section of ["local", "remote", "conflicts"]) {
+    if (summary[section].length) lines.push(section, ...componentLines(summary[section], section === "conflicts"));
+  }
+  return lines.join("\n") || "No changes.";
+}

package/src/handlers.mjs

@@ -1,8 +1,71 @@
 import { statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { UsageError } from "./usage-error.mjs";
 import { sfRequire } from "./sf-root.mjs";
-import { compactDescribe, compactQuery, summarizeDeploy, summarizeTests } from "./format.mjs";
+import { compactDescribe, compactQuery, summarizeDeploy, summarizeTests, summarizeRetrieve, summarizeChanges } from "./format.mjs";
+
+const soqlString = value => `'${String(value).replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
+const LOG_FIELDS = "Id, LogUser.Username, Operation, Request, Status, LogLength, StartTime, DurationMilliseconds";
+const LOG_CLOCK_SKEW_MS = 5 * 60 * 1000;
+
+async function currentUser(conn) {
+  const fields = conn.getAuthInfoFields?.();
+  if (fields?.userId) return { id: fields.userId, username: fields.username ?? fields.userId };
+  const identity = await conn.identity();
+  return { id: identity.user_id, username: identity.username };
+}
+
+function logCount(count) {
+  if (!Number.isSafeInteger(count) || count < 1) throw new UsageError("Log count must be a positive integer.");
+  return count;
+}
+
+async function logRows(conn, where = "", count = 10) {
+  return (await conn.query(`SELECT ${LOG_FIELDS} FROM ApexLog ${where ? `WHERE ${where}` : ""} ORDER BY StartTime DESC LIMIT ${logCount(count)}`)).records;
+}
+
+async function logBody(conn, row) {
+  const body = await conn.request(`/services/data/v${conn.getApiVersion()}/sobjects/ApexLog/${row.Id}/Body`, { responseType: "text" });
+  return { id: row.Id, operation: row.Operation, status: row.Status, startTime: row.StartTime,
+    length: row.LogLength, duration: row.DurationMilliseconds, body };
+}
+
+// Preserve the org-write notice even when the subsequent operation fails.
+async function afterTrace(trace, fn) {
+  try { return { ...await fn(), ...(trace ? { trace } : {}) }; }
+  catch (error) {
+    if (trace) error.trace = trace;
+    throw error;
+  }
+}
+
+export async function ensureTrace(conn, userId) {
+  const now = Date.now();
+  const flags = await conn.tooling.query(`SELECT Id, ExpirationDate, StartDate FROM TraceFlag WHERE TracedEntityId = ${soqlString(userId)} AND LogType = 'DEVELOPER_LOG'`);
+  const flag = flags.records.find(f => Date.parse(f.StartDate) <= now && Date.parse(f.ExpirationDate) > now + 300000) ?? flags.records[0];
+  if (flag && Date.parse(flag.StartDate) <= now && Date.parse(flag.ExpirationDate) > now + 300000) {
+    return { action: "existing", id: flag.Id, expires: flag.ExpirationDate };
+  }
+  const dates = { StartDate: new Date(now).toISOString(), ExpirationDate: new Date(now + 1800000).toISOString() };
+  let result;
+  if (flag) {
+    result = await conn.tooling.sobject("TraceFlag").update({ Id: flag.Id, ...dates });
+  } else {
+    const levels = await conn.tooling.query("SELECT Id FROM DebugLevel WHERE DeveloperName = 'SFD' LIMIT 1");
+    let levelId = levels.records[0]?.Id;
+    if (!levelId) {
+      const level = await conn.tooling.sobject("DebugLevel").create({ DeveloperName: "SFD", MasterLabel: "SFD",
+        ApexCode: "FINE", ApexProfiling: "INFO", Callout: "INFO", Database: "INFO", System: "DEBUG",
+        Validation: "INFO", Visualforce: "NONE", Workflow: "INFO", Wave: "NONE", Nba: "NONE" });
+      if (!level.success) throw new Error(`Cannot create debug level: ${JSON.stringify(level.errors)}`);
+      levelId = level.id;
+    }
+    result = await conn.tooling.sobject("TraceFlag").create({ TracedEntityId: userId, LogType: "DEVELOPER_LOG", DebugLevelId: levelId, ...dates });
+  }
+  if (!result.success) throw new Error(`Cannot enable debug logging: ${JSON.stringify(result.errors)}`);
+  return { action: flag ? "extended" : "created", id: flag?.Id ?? result.id, expires: dates.ExpirationDate };
+}
 
 const SESSION_ERRORS = new Set(["INVALID_SESSION_ID", "INVALID_AUTH_HEADER"]);
 
@@ -34,6 +97,15 @@ export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRo
   const projectQueue = serial();
 
   const orgs = new Map();
+  const traces = new Map();
+  const traceQueue = serial();
+  const traceFor = (conn, alias, user, noTrace) => noTrace ? undefined : traceQueue(async () => {
+    const cached = traces.get(alias);
+    if (cached?.userId === user.id && Date.parse(cached.expires) > Date.now() + 300000) return undefined;
+    const trace = await ensureTrace(conn, user.id);
+    traces.set(alias, { ...trace, userId: user.id });
+    return trace.action === "existing" ? undefined : { ...trace, username: user.username };
+  });
   let stamp = authStamp(home);
 
   async function getOrg(alias) {
@@ -41,6 +113,7 @@ export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRo
     if (now !== stamp) {
       stamp = now;
       orgs.clear();
+      traces.clear();
       await core.StateAggregator.clearInstanceAsync();
     }
     if (!orgs.has(alias)) {
@@ -59,6 +132,7 @@ export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRo
     } catch (e) {
       if (!SESSION_ERRORS.has(e.errorCode ?? e.name)) throw e;
       orgs.delete(alias);
+      traces.delete(alias);
       const org = await getOrg(alias);
       return fn(org.getConnection(), org);
     }
@@ -75,6 +149,7 @@ export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRo
 
     reload: async () => {
       orgs.clear();
+      traces.clear();
       await core.StateAggregator.clearInstanceAsync();
       return { reloaded: true };
     },
@@ -135,15 +210,105 @@ export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRo
         return summarizeDeploy(result.response);
       })),
 
-    test: ({ org, classNames, tests, suiteNames, testLevel, codeCoverage, waitMinutes = 60 }) => withConn(org, async conn => {
-      const { TestService } = apex();
-      const service = new TestService(conn);
-      const level = testLevel ?? (classNames?.length || tests?.length || suiteNames?.length ? "RunSpecifiedTests" : "RunLocalTests");
-      // apex-node takes comma-separated strings, as the sf flags do.
-      const csv = list => (list?.length ? list.join(",") : undefined);
-      const payload = await service.buildAsyncPayload(level, csv(tests), csv(classNames), csv(suiteNames));
-      const result = await service.runTestAsynchronous(payload, Boolean(codeCoverage), false, undefined, undefined, Duration.minutes(waitMinutes));
-      return summarizeTests(result);
+    retrieve: ({ org, projectDir, sourcePaths, metadata, manifest, ignoreConflicts = false, waitMinutes = 33 }) =>
+      projectQueue(() => withConn(org, async (conn, o) => {
+        core.SfProject.clearInstances();
+        const project = await core.SfProject.resolve(projectDir);
+        const tracked = await o.tracksSource();
+        const changesOnly = !sourcePaths?.length && !metadata?.length && !manifest;
+        if (changesOnly && !tracked) throw new UsageError("retrieve needs -d, -m or -x on an org without source tracking.");
+        // Handle conflicts and tracking explicitly: daemon requests must not leave lifecycle listeners behind.
+        const st = tracked ? await tracking().SourceTracking.create({ org: o, project, ignoreConflicts, ignoreLocalCache: true }) : undefined;
+        const conflicts = st && !ignoreConflicts ? await st.getConflicts() : [];
+        let cs;
+        let deletedFiles = [];
+        const refusal = entries => ({ success: false, status: "Conflicts", files: [], warnings: [], conflicts: summarizeChanges(entries, projectDir, "Conflict") });
+        if (changesOnly) {
+          // Remote deletes write to disk, so refuse before asking STL to apply any of them.
+          if (conflicts.length) return refusal(conflicts);
+          const targets = await st.maybeApplyRemoteDeletesToLocal(true);
+          cs = targets.componentSetFromNonDeletes;
+          deletedFiles = targets.fileResponsesFromDelete;
+        } else {
+          const packageDirs = project.getUniquePackageDirectories().map(d => d.fullPath);
+          cs = await sdr().ComponentSetBuilder.build({
+            projectDir,
+            sourceapiversion: project.getSfProjectJson().get("sourceApiVersion"),
+            sourcepath: sourcePaths?.length ? sourcePaths : undefined,
+            metadata: metadata?.length ? { metadataEntries: metadata, directoryPaths: packageDirs } : undefined,
+            ...(manifest ? { manifest: { manifestPath: manifest, directoryPaths: packageDirs } } : {})
+          });
+          const selectedConflicts = conflicts.filter(c => cs.has({ type: c.type, fullName: c.name }));
+          if (selectedConflicts.length) return refusal(selectedConflicts);
+        }
+        if (cs.size === 0) {
+          if (!changesOnly) throw new Error("Nothing to retrieve: no components matched.");
+          return { success: true, status: "Succeeded", files: summarizeChanges(deletedFiles, projectDir), warnings: [], conflicts: [],
+            ...(!deletedFiles.length ? { message: "No remote changes to retrieve." } : {}) };
+        }
+        const retrieve = await cs.retrieve({ usernameOrConnection: conn, output: project.getDefaultPackage().fullPath, merge: true, format: "source" });
+        const result = await retrieve.pollStatus({ frequency: Duration.seconds(2), timeout: Duration.minutes(waitMinutes) });
+        if (st && result.response.success) await st.updateTrackingFromRetrieve(result);
+        const summary = summarizeRetrieve(result, projectDir);
+        summary.files.unshift(...summarizeChanges(deletedFiles, projectDir));
+        return summary;
+      })),
+
+    tracking: ({ org, projectDir, local = false, remote = false, conflicts: conflictsOnly = false }) =>
+      projectQueue(() => withConn(org, async (conn, o) => {
+        if (!(await o.tracksSource())) throw new UsageError("tracking requires an org with source tracking.");
+        core.SfProject.clearInstances();
+        const project = await core.SfProject.resolve(projectDir);
+        const st = await tracking().SourceTracking.create({ org: o, project, ignoreLocalCache: true });
+        const rows = conflictsOnly ? [] : await st.getStatus({ local: !remote, remote: !local });
+        return {
+          local: summarizeChanges(rows.filter(r => r.origin === "local" && !r.ignored), projectDir),
+          remote: summarizeChanges(rows.filter(r => r.origin === "remote" && !r.ignored), projectDir),
+          conflicts: summarizeChanges(await st.getConflicts(), projectDir, "Conflict")
+        };
+      })),
+
+    logs: ({ org, count = 10, user, noTrace }) => withConn(org, async conn => {
+      logCount(count);
+      const trace = await traceFor(conn, org, await currentUser(conn), noTrace);
+      return afterTrace(trace, async () => ({
+        records: await logRows(conn, user ? `LogUser.Username = ${soqlString(user)}` : "", count)
+      }));
+    }),
+
+    logGet: ({ org, id, noTrace }) => withConn(org, async conn => {
+      if (id !== "latest" && !/^07L[a-zA-Z0-9]{12}(?:[a-zA-Z0-9]{3})?$/.test(id)) throw new UsageError("logs get needs an ApexLog ID or latest.");
+      const user = await currentUser(conn);
+      const trace = await traceFor(conn, org, user, noTrace);
+      return afterTrace(trace, async () => {
+        const rows = await logRows(conn, id === "latest" ? `LogUserId = ${soqlString(user.id)}` : `Id = ${soqlString(id)}`, 1);
+        if (!rows.length) throw new Error("No debug logs found.");
+        return logBody(conn, rows[0]);
+      });
+    }),
+
+    test: ({ org, classNames, tests, suiteNames, testLevel, codeCoverage, logs, noTrace, waitMinutes = 60 }) => withConn(org, async conn => {
+      const user = logs ? await currentUser(conn) : undefined;
+      const trace = logs ? await traceFor(conn, org, user, noTrace) : undefined;
+      return afterTrace(trace, async () => {
+        const { TestService } = apex();
+        const service = new TestService(conn);
+        const level = testLevel ?? (classNames?.length || tests?.length || suiteNames?.length ? "RunSpecifiedTests" : "RunLocalTests");
+        // apex-node takes comma-separated strings, as the sf flags do.
+        const csv = list => (list?.length ? list.join(",") : undefined);
+        const payload = await service.buildAsyncPayload(level, csv(tests), csv(classNames), csv(suiteNames));
+        const startedAt = new Date(Math.floor((Date.now() - LOG_CLOCK_SKEW_MS) / 1000) * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+        const result = await service.runTestAsynchronous(payload, Boolean(codeCoverage), false, undefined, undefined, Duration.minutes(waitMinutes));
+        const summary = summarizeTests(result);
+        if (logs) {
+          // Pad both bounds for clock skew, rounding outward to whole-second SOQL literals.
+          const finishedAt = new Date(Math.ceil((Date.now() + LOG_CLOCK_SKEW_MS) / 1000) * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+          const rows = await logRows(conn, `LogUserId = ${soqlString(user.id)} AND StartTime >= ${startedAt} AND StartTime <= ${finishedAt}`, 10);
+          summary.logs = summary.failing > 0 || summary.failures.length || summary.setupFailures.length
+            ? await Promise.all(rows.map(row => logBody(conn, row))) : rows.map(row => ({ id: row.Id }));
+        }
+        return summary;
+      });
     })
   };
 }

package/src/hooks.mjs

@@ -0,0 +1,102 @@
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, renameSync, unlinkSync, statSync, constants } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseArgs } from "node:util";
+import { rewrite } from "./rewrite.mjs";
+import { UsageError } from "./usage-error.mjs";
+
+const USAGE = "Usage: sfd hook claude|codex|gemini|check <command>|install|uninstall --agent <agent> [--project]";
+
+const agents = {
+  claude: { directory: ".claude", file: "settings.json", event: "PreToolUse", tool: "Bash" },
+  codex: { directory: ".codex", file: "hooks.json", event: "PreToolUse", tool: "Bash" },
+  gemini: { directory: ".gemini", file: "settings.json", event: "BeforeTool", tool: "run_shell_command" }
+};
+
+export function handle(agent, inputJson, env = process.env) {
+  try {
+    if (env.SFD_HOOK_DISABLE === "1") return "";
+    const config = agents[agent];
+    if (!config) return "";
+    const input = JSON.parse(inputJson);
+    if (input?.tool_name !== config.tool || (input.hook_event_name && input.hook_event_name !== config.event)) return "";
+    if (!input.tool_input || typeof input.tool_input.command !== "string") return "";
+    const result = rewrite(input.tool_input.command);
+    if (result.skip) return "";
+    const updatedInput = { ...input.tool_input, command: result.command };
+    if (agent === "gemini") return JSON.stringify({ hookSpecificOutput: { tool_input: updatedInput } });
+    return JSON.stringify({ hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      ...(agent === "codex" ? { permissionDecision: "allow" } : {}),
+      permissionDecisionReason: result.reason,
+      updatedInput
+    } });
+  } catch { return ""; }
+}
+
+function object(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+
+export function editSettings(action, agent, { project = false, cwd = process.cwd(), home = homedir() } = {}) {
+  const config = agents[agent];
+  if (!config || !["install", "uninstall"].includes(action)) throw new UsageError("Expected install|uninstall --agent claude|codex|gemini [--project]");
+  const file = join(project ? cwd : home, config.directory, config.file);
+  let original, settings = {};
+  try { original = readFileSync(file, "utf8"); settings = JSON.parse(original); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  if (!object(settings) || (settings.hooks !== undefined && !object(settings.hooks))) throw Error(`Invalid hooks settings in ${file}`);
+  const entries = settings.hooks?.[config.event] ?? [];
+  if (!Array.isArray(entries) || entries.some(entry => !object(entry) || !Array.isArray(entry.hooks))) throw Error(`Invalid ${config.event} settings in ${file}`);
+  const isSfd = hook => hook?.type === "command" && typeof hook.command === "string" && new RegExp(`^sfd hook ${agent}(?:\\s|$)`).test(hook.command);
+  const exists = entries.some(entry => entry.hooks.some(isSfd));
+  if ((action === "install") === exists) return { file, changed: false };
+  let updated;
+  if (action === "install") {
+    updated = [...entries, { matcher: config.tool, hooks: [{ type: "command", command: `sfd hook ${agent}` }] }];
+  } else {
+    updated = entries.flatMap(entry => {
+      const hooks = entry.hooks.filter(hook => !isSfd(hook));
+      return hooks.length === entry.hooks.length ? [entry] : hooks.length ? [{ ...entry, hooks }] : [];
+    });
+  }
+  settings.hooks ??= {};
+  settings.hooks[config.event] = updated;
+  mkdirSync(dirname(file), { recursive: true });
+  if (original !== undefined) {
+    try { copyFileSync(file, `${file}.bak`, constants.COPYFILE_EXCL); }
+    catch (error) { if (error.code !== "EEXIST") throw error; }
+  }
+  const temporary = `${file}.${process.pid}.tmp`;
+  try {
+    writeFileSync(temporary, JSON.stringify(settings, null, 2) + "\n", { flag: "wx", mode: original === undefined ? 0o600 : statSync(file).mode & 0o777 });
+    renameSync(temporary, file);
+  } finally {
+    try { unlinkSync(temporary); } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  return { file, changed: true };
+}
+
+export function runHook(argv) {
+  const [action, ...args] = argv;
+  if (action === "--help" || action === "-h") {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  if (Object.hasOwn(agents, action)) {
+    // Adapter errors must never change whether the original tool call can run.
+    try { process.stdout.write(handle(action, readFileSync(0, "utf8"))); } catch { /* no opinion */ }
+    return 0;
+  }
+  if (action === "check") {
+    const result = process.env.SFD_HOOK_DISABLE === "1" ? { skip: "SFD_HOOK_DISABLE=1" } : rewrite(args.join(" "));
+    process.stdout.write(result.skip ? `skip: ${result.skip}\n` : `→ ${result.command}\n`);
+    return result.skip ? 1 : 0;
+  }
+  if (["install", "uninstall"].includes(action)) {
+    const { values } = parseArgs({ args, options: { agent: { type: "string" }, project: { type: "boolean" } } });
+    const result = editSettings(action, values.agent, { project: values.project });
+    process.stdout.write(`${result.changed ? "Updated" : "Unchanged"} ${result.file}\n`);
+    if (action === "install" && values.agent === "codex") process.stdout.write("Review and trust the hook with /hooks in Codex before it can run.\n");
+    return 0;
+  }
+  throw new UsageError(USAGE);
+}

package/src/paths.mjs

@@ -1,16 +1,34 @@
 import { mkdirSync, chmodSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { tmpdir, userInfo } from "node:os";
+import { createHash } from "node:crypto";
 import { join } from "node:path";
 
 // Unix socket paths are capped near 108 bytes, so keep the runtime dir short.
-export function runtimeDir(env = process.env) {
+export function runtimeDir(env = process.env, platform = process.platform) {
+  if (platform === "win32") {
+    const base = env.SFD_RUNTIME_DIR ?? join(env.LOCALAPPDATA ?? tmpdir(), "sfd");
+    mkdirSync(base, { recursive: true });
+    return base;
+  }
   const base = env.SFD_RUNTIME_DIR ?? join(env.XDG_RUNTIME_DIR ?? tmpdir(), `sfd-${process.getuid()}`);
   mkdirSync(base, { recursive: true, mode: 0o700 });
   chmodSync(base, 0o700);
   return base;
 }
 
-export function paths(env = process.env) {
-  const dir = runtimeDir(env);
-  return { dir, socket: join(dir, "sfd.sock"), log: join(dir, "sfd.log"), pid: join(dir, "sfd.pid") };
+// Windows has no Unix sockets in the filesystem; the daemon listens on a named pipe instead.
+// Pipe names are machine-wide, so derive one per user and runtime dir.
+export function socketPath(dir, platform = process.platform) {
+  if (platform !== "win32") return join(dir, "sfd.sock");
+  const id = createHash("sha256").update(`${userInfo().username}\0${dir.toLowerCase()}`).digest("hex").slice(0, 16);
+  return `\\\\.\\pipe\\sfd-${id}`;
+}
+
+export function isPipe(socket) {
+  return socket.startsWith("\\\\.\\pipe\\");
+}
+
+export function paths(env = process.env, platform = process.platform) {
+  const dir = runtimeDir(env, platform);
+  return { dir, socket: socketPath(dir, platform), log: join(dir, "sfd.log"), pid: join(dir, "sfd.pid") };
 }

package/src/rewrite.mjs

@@ -0,0 +1,184 @@
+// This is deliberately a literal-shell subset. Unknown shell syntax stays with sf.
+const quote = value => `'${value.replaceAll("'", "'\\''")}'`;
+const skip = reason => ({ skip: reason });
+
+function lex(source) {
+  const tokens = [];
+  let i = 0;
+  while (i < source.length) {
+    if (/[ \t\r]/.test(source[i])) { i++; continue; }
+    const start = i;
+    const op = /^(?:2>&1|2>\/dev\/null|&&|\|\||>>|<<|[|;&<>\n])/.exec(source.slice(i));
+    if (op) {
+      tokens.push({ op: op[0], start, end: i += op[0].length });
+      continue;
+    }
+    let value = "", mode = "";
+    while (i < source.length) {
+      const c = source[i];
+      if (!mode && /[ \t\r\n|;&<>]/.test(c)) break;
+      if (c === "'" && mode !== '"') { mode = mode === "'" ? "" : "'"; i++; continue; }
+      if (c === '"' && mode !== "'") { mode = mode === '"' ? "" : '"'; i++; continue; }
+      if (c === "\\" && mode !== "'") {
+        if (++i === source.length) throw Error("incomplete escape");
+        if (mode === '"' && !/[\$`"\\]/.test(source[i])) value += "\\";
+        value += source[i++];
+        continue;
+      }
+      if (mode !== "'" && /[$`]/.test(c)) throw Error("shell expansion or command substitution");
+      if (!mode && /[(){}*?\[\]~#]/.test(c)) throw Error("unsupported shell syntax");
+      value += c; i++;
+    }
+    if (mode) throw Error("unclosed quote");
+    tokens.push({ value, start, end: i });
+  }
+  return tokens;
+}
+
+// [sf names, sfd flag (empty means drop), takes value, repeatable]
+const org = ["o target-org", "-o", true];
+const json = ["json", "", false];
+const tooling = ["t use-tooling-api", "--tooling", false];
+const format = ["r result-format", "", true];
+const wait = ["w wait", "-w", true];
+const level = ["l test-level", "-l", true];
+const tests = ["t tests", "-t", true, true];
+const mappings = [
+  { sf: "apex list log", sfd: "logs", flags: [org, json] },
+  { sf: "apex get log", sfd: "logs get", flags: [org, json, ["i log-id", "", true], ["n number", "", true]] },
+  { sf: "data query", sfd: "query", flags: [org, json, tooling, ["q query", "", true], ["all-rows", "--all", false], format], required: "q" },
+  { sf: "apex run test", sfd: "test", flags: [org, json, wait, level, tests, format, ["n class-names", "-n", true, true], ["s suite-names", "-s", true, true], ["c code-coverage", "-c", false], ["y synchronous", "", false]] },
+  { sf: "apex run", sfd: "apex", flags: [org, json, ["f file", "-f", true]] },
+  { sf: "project retrieve start", sfd: "retrieve", flags: [org, json, wait, ["d source-dir", "-d", true, true], ["m metadata", "-m", true, true], ["x manifest", "-x", true], ["c ignore-conflicts", "--ignore-conflicts", false]] },
+  { sf: "project deploy start", sfd: "deploy", flags: [org, json, wait, level, tests, ["d source-dir", "-d", true, true], ["m metadata", "-m", true, true], ["dry-run", "--check-only", false]] },
+  { sf: "sobject describe", sfd: "describe", flags: [org, json, tooling, ["s sobject", "", true]], required: "s" },
+  { sf: "api request rest", sfd: "rest", flags: [org, ["X method", "-X", true], ["b body", "--body", true]], positional: true },
+  { sf: "org display", sfd: "org", flags: [org, json] }
+];
+
+function mapArgs(argv) {
+  const mapping = mappings.find(m => m.sf.split(" ").every((v, i) => argv[i] === v));
+  if (!mapping) return skip("unsupported sf command");
+  const args = argv.slice(mapping.sf.split(" ").length);
+  const seen = new Map(), output = [], positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith("-")) { positionals.push(arg); continue; }
+    const match = /^(?:--([^=]+)|-([A-Za-z]))(?:=(.*))?$/.exec(arg);
+    const name = match?.[1] ?? match?.[2];
+    const spec = mapping.flags.find(f => f[0].split(" ").includes(name));
+    if (!spec) return skip(`unsupported flag ${arg.split("=")[0]}`);
+    const [names, target, takesValue, multiple] = spec;
+    const key = names.split(" ")[0];
+    if (seen.has(key) && !multiple) return skip(`duplicate flag ${arg.split("=")[0]}`);
+    let values = [];
+    if (takesValue) {
+      const value = match[3] ?? args[++i];
+      if (value === undefined || value === "") return skip(`missing value for ${arg}`);
+      if (value.startsWith("-")) return skip(`unsupported value for ${arg}`);
+      values.push(value);
+      if (multiple && match[3] === undefined) {
+        while (args[i + 1] !== undefined && !args[i + 1].startsWith("-")) values.push(args[++i]);
+      }
+    } else if (match[3] !== undefined) return skip(`unsupported boolean value ${arg}`);
+    seen.set(key, values);
+    if (key === "r" && !["human", "json"].includes(values[0])) return skip(`unsupported result format ${values[0]}`);
+    if (key === "w" && (!Number.isFinite(Number(values[0])) || Number(values[0]) <= 0)) return skip("wait must be positive");
+    if (target) {
+      if (takesValue) for (const v of values) output.push(target, quote(v));
+      else output.push(target);
+    }
+  }
+  if (mapping.required && !seen.has(mapping.required)) return skip(`missing required ${mapping.required} flag`);
+  if (mapping.sfd === "deploy" && !seen.has("d") && !seen.has("m")) return skip("deploy needs source-dir or metadata");
+  if (mapping.sfd === "retrieve" && ["d", "m", "x"].filter(key => seen.has(key)).length > 1) return skip("retrieve selectors are mutually exclusive");
+  if (mapping.sfd === "test" && !seen.has("w") && !seen.has("y")) return skip("asynchronous tests need --wait or --synchronous");
+  if (mapping.sfd === "rest") {
+    const method = seen.get("X")?.[0] ?? "GET";
+    if (!["GET", "POST", "PUT", "PATCH", "HEAD", "DELETE", "OPTIONS", "TRACE"].includes(method)) return skip("unsupported REST method");
+    // sf ignores a body with GET; sfd infers POST from a body instead.
+    if (seen.has("b") && method === "GET") return skip("REST body with implicit or explicit GET is unsupported");
+  }
+  if (mapping.positional ? positionals.length !== 1 : positionals.length !== 0) return skip("unsupported positional arguments");
+  let logTarget;
+  if (mapping.sfd === "logs get") {
+    if (seen.has("i") && seen.has("n")) return skip("choose log-id or number");
+    if (seen.has("i")) logTarget = seen.get("i")[0];
+    else if (seen.get("n")?.[0] === "1") logTarget = "latest";
+    else return skip("log get needs log-id or --number 1");
+  }
+  const positional = logTarget ? [logTarget] : mapping.required ? seen.get(mapping.required) : positionals;
+  // Protect sfd's own option parser from values that could be interpreted as options.
+  if (positional.some(v => v.startsWith("-"))) return skip("unsupported positional value");
+  return { command: ["sfd", mapping.sfd, ...positional.map(quote), ...output].join(" "), apex: mapping.sfd === "apex" };
+}
+
+export function rewrite(command) {
+  if (typeof command !== "string" || !command.trim()) return skip("empty command");
+  try {
+    return rewriteShell(command);
+  } catch (error) { return skip(error.message); }
+}
+
+function rewriteShell(command) {
+  // Only remove continuations outside single quotes; the lexer does the rest.
+  let source = "", single = false, double = false;
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    if (c === "\n" && !single && !double) { source += command.slice(i); break; }
+    if (c === "\\" && !single) {
+      if (command[i + 1] === "\n") { i++; continue; }
+      source += c + (command[++i] ?? ""); continue;
+    }
+    if (c === "'" && !double) single = !single;
+    if (c === '"' && !single) double = !double;
+    source += c;
+  }
+  source = source.trimStart();
+  // Heredoc contents are opaque: preserve them byte for byte and require one literal delimiter.
+  const newline = source.indexOf("\n");
+  let body = "";
+  if (newline !== -1) { body = source.slice(newline); source = source.slice(0, newline); }
+  const tokens = lex(source);
+  let stderr = "";
+  while (["2>&1", "2>/dev/null"].includes(tokens.at(-1)?.op)) {
+    stderr = ` ${tokens.pop().op}${stderr}`;
+  }
+  let heredoc = "";
+  const hd = tokens.findIndex(t => t.op === "<<");
+  if (hd !== -1) {
+    const delimiter = tokens[hd + 1];
+    if (!delimiter || delimiter.op || hd + 2 !== tokens.length || !/^[A-Za-z_][\w]*$/.test(delimiter.value)) return skip("unsupported heredoc");
+    const contents = body.slice(1);
+    const lines = (contents.endsWith("\n") ? contents.slice(0, -1) : contents).split("\n");
+    if (lines.at(-1) !== delimiter.value || lines.slice(0, -1).includes(delimiter.value)) return skip("unsupported heredoc terminator");
+    heredoc = source.slice(tokens[hd].start, delimiter.end) + body;
+    tokens.splice(hd);
+  } else if (body.trim()) return skip("unsupported multiline command");
+  while (["2>&1", "2>/dev/null"].includes(tokens.at(-1)?.op)) {
+    stderr = ` ${tokens.pop().op}${stderr}`;
+  }
+  if (tokens.some(t => t.op && !["&&", "|"].includes(t.op))) return skip("output redirection or unsupported shell chain");
+  const chains = tokens.flatMap((t, i) => t.op === "&&" ? [i] : []);
+  let start = 0;
+  if (chains.length) {
+    if (chains.length !== 1 || chains[0] !== 2 || tokens[0].value !== "cd" || !tokens[1].value || tokens[1].value.startsWith("-")) return skip("unsupported && chain");
+    start = 3;
+  }
+  const pipes = tokens.flatMap((t, i) => t.op === "|" ? [i] : []);
+  if (pipes.length) {
+    if (pipes.some(i => i <= start || i === tokens.length - 1 || tokens[i - 1].op)) return skip("unsupported pipeline");
+    // Never rewrite sf whose stdout is consumed, even if a later segment is also sf.
+    for (const i of [start, ...pipes.map(p => p + 1)].slice(0, -1)) {
+      if (tokens[i]?.value === "sf" || tokens[i]?.value?.startsWith("SF_TARGET_ORG=")) return skip("sf output is piped");
+    }
+    start = pipes.at(-1) + 1;
+  }
+  if (tokens[start]?.value?.startsWith("SF_TARGET_ORG=")) start++;
+  if (tokens[start]?.value !== "sf") return skip("not a plain sf invocation (paths, env prefixes and sfdx are unsupported)");
+  if (tokens.slice(start).some(t => t.op)) return skip("unsupported shell operator");
+  const mapped = mapArgs(tokens.slice(start + 1).map(t => t.value));
+  if (mapped.skip) return mapped;
+  if ((pipes.length || heredoc) && !mapped.apex) return skip("stdin is supported only for apex run");
+  return { command: source.slice(0, tokens[start].start) + mapped.command + stderr + (heredoc ? ` ${heredoc}` : ""), reason: "sfd: warm daemon, ~0.3 s" };
+}

package/src/server.mjs

@@ -1,5 +1,6 @@
 import net from "node:net";
 import { chmodSync, unlinkSync } from "node:fs";
+import { isPipe } from "./paths.mjs";
 
 // Newline-delimited JSON over a Unix socket: one request and one response per connection.
 // Responses are {status: 0, result} | {status: 1, name, message} | {restart: true}.
@@ -40,7 +41,7 @@ export async function startServer({ socket, version, handlers, idleMs = 60 * 60_
     draining = reason;
     clearTimeout(idleTimer);
     server.close();
-    try { unlinkSync(socket); } catch {}
+    if (!isPipe(socket)) try { unlinkSync(socket); } catch {}
     maybeExit();
   };
   const armIdle = () => {
@@ -57,7 +58,7 @@ export async function startServer({ socket, version, handlers, idleMs = 60 * 60_
     try {
       return { status: 0, result: await handler(req) };
     } catch (e) {
-      return { status: 1, name: e.name ?? "Error", message: e.message ?? String(e), errorCode: e.errorCode };
+      return { status: 1, name: e.name ?? "Error", message: e.message ?? String(e), errorCode: e.errorCode, ...(e.trace ? { trace: e.trace } : {}) };
     }
   }
 
@@ -90,10 +91,12 @@ export async function startServer({ socket, version, handlers, idleMs = 60 * 60_
   } catch (e) {
     if (e.code !== "EADDRINUSE") throw e;
     if (await probe(socket)) throw new AlreadyRunning("sfd is already running");
+    // A named pipe disappears with its owner, so only a Unix socket file can be stale.
+    if (isPipe(socket)) throw e;
     unlinkSync(socket);
     await listenOnce(server, socket);
   }
-  chmodSync(socket, 0o600);
+  if (!isPipe(socket)) chmodSync(socket, 0o600);
   armIdle();
   return { server, drain };
 }

package/src/sf-root.mjs

@@ -5,17 +5,27 @@ import { createRequire } from "node:module";
 
 // sfd loads @salesforce/core, SDR, apex-node and source-tracking from the installed sf CLI,
 // so auth files, API versions and metadata registries always match what `sf` itself uses.
-export function findSfRoot(env = process.env) {
+export function findSfRoot(env = process.env, platform = process.platform) {
   if (env.SFD_SF_ROOT) return env.SFD_SF_ROOT;
-  const bin = execFileSync("which", ["sf"], { encoding: "utf8" }).trim();
+  const bin = whichSf(platform);
   for (let dir = dirname(realpathSync(bin)); dirname(dir) !== dir; dir = dirname(dir)) {
-    try {
-      if (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name === "@salesforce/cli") return dir;
-    } catch {}
+    // npm installs on Windows put an sf.cmd shim next to node_modules instead of a symlink.
+    for (const candidate of [dir, join(dir, "node_modules", "@salesforce", "cli")]) {
+      try {
+        if (JSON.parse(readFileSync(join(candidate, "package.json"), "utf8")).name === "@salesforce/cli") return candidate;
+      } catch {}
+    }
   }
   throw new Error(`Could not locate the @salesforce/cli install behind ${bin}; set SFD_SF_ROOT.`);
 }
 
+function whichSf(platform) {
+  if (platform !== "win32") return execFileSync("which", ["sf"], { encoding: "utf8" }).trim();
+  // `where` lists every match in PATH order; prefer the cmd shim over the extensionless sh script.
+  const found = execFileSync("where", ["sf"], { encoding: "utf8" }).split(/\r?\n/).filter(Boolean);
+  return found.find(f => /\.(cmd|exe)$/i.test(f)) ?? found[0];
+}
+
 export function sfInfo(root) {
   const file = join(root, "package.json");
   return { root, version: JSON.parse(readFileSync(file, "utf8")).version, mtimeMs: statSync(file).mtimeMs };

package/src/usage-error.mjs

@@ -0,0 +1,3 @@
+export class UsageError extends Error {
+  name = "UsageError";
+}