@xingular/harness 0.1.2 → 0.1.4

package/dist/cli.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 
+// src/cli.ts
+import { resolve as resolve9 } from "node:path";
+
 // src/core/bus.ts
 var Bus = class {
   listeners = /* @__PURE__ */ new Set();
@@ -887,9 +890,9 @@ var Accounts = class {
     const interaction = {
       signal: controller.signal,
       notify: (notification) => event(notification),
-      prompt: (prompt2) => new Promise((resolve9, reject) => {
+      prompt: (prompt2) => new Promise((resolve10, reject) => {
         const promptId = randomUUID2();
-        login.prompts.set(promptId, { resolve: resolve9, reject });
+        login.prompts.set(promptId, { resolve: resolve10, reject });
         prompt2.signal?.addEventListener("abort", () => {
           login.prompts.delete(promptId);
           event({ type: "promptClosed", promptId });
@@ -4622,14 +4625,14 @@ var piResolver = async ({ cwd, agentDir, install: install3, packages }) => {
   const settings = pi.SettingsManager.create(cwd, agentDir);
   const shared = new Set((settings.getGlobalSettings().packages ?? []).map((entry) => typeof entry === "string" ? entry : entry.source));
   const manager2 = () => new pi.DefaultPackageManager({ cwd, agentDir, settingsManager: settings, builtinExtensions: [...PI_BUILTINS] });
-  const resolve9 = (installing) => manager2().resolve(async (source2) => installing && shared.has(source2) ? "install" : "skip");
+  const resolve10 = (installing) => manager2().resolve(async (source2) => installing && shared.has(source2) ? "install" : "skip");
   let resolved2;
   try {
-    resolved2 = install3 ? await withoutInstallScripts(() => resolve9(true)) : await resolve9(false);
+    resolved2 = install3 ? await withoutInstallScripts(() => resolve10(true)) : await resolve10(false);
   } catch (error) {
     if (!install3) throw error;
     log("a plugin package could not be installed", error instanceof Error ? error.message : String(error));
-    resolved2 = await resolve9(false);
+    resolved2 = await resolve10(false);
   }
   const found = [];
   const add = (paths) => {
@@ -6249,8 +6252,8 @@ var cancelActive = null;
 function listenForCallback(expectedState, clientName) {
   return new Promise((ready, failed) => {
     let settle;
-    const result = new Promise((resolve9, reject) => {
-      settle = { resolve: resolve9, reject };
+    const result = new Promise((resolve10, reject) => {
+      settle = { resolve: resolve10, reject };
     });
     result.catch(() => void 0);
     const server = createServer((request2, response3) => {
@@ -6274,7 +6277,7 @@ function listenForCallback(expectedState, clientName) {
       clearTimeout(timer);
       failed(new HarnessError("invalid_request", error.code === "EADDRINUSE" ? `Port ${MCP_OAUTH_PORT} is in use. Finish or cancel the other sign-in, or quit the program using that port, then try again.` : "The sign-in listener could not start."));
     });
-    const closed = new Promise((resolve9) => server.once("close", resolve9));
+    const closed = new Promise((resolve10) => server.once("close", resolve10));
     const close = () => {
       clearTimeout(timer);
       if (cancelActive === cancel) cancelActive = null;
@@ -6459,7 +6462,7 @@ var UNATTENDED_SCOPE = "plugin-hooks";
 var ConnectedApps = class {
   constructor(options2) {
     this.options = options2;
-    this.connections = new Connections(options2.stateDir, options2.secrets, options2.bus, () => options2.env.dataRoot);
+    this.connections = new Connections(options2.stateDir, options2.secrets, options2.bus, () => options2.env.root);
     this.oauth = {
       clientName: options2.env.productName,
       load: (id) => this.connections.oauthLoad(id),
@@ -8479,7 +8482,7 @@ var RunRegistry = class {
         }
         emit("approval.requested", { approvalId, ...payload });
         emit("status.changed", { status: "waiting_for_approval" });
-        return new Promise((resolve9) => {
+        return new Promise((resolve10) => {
           const timer = timeoutMs ? setTimeout(() => this.approvals.get(approvalId)?.resolve("denied"), timeoutMs) : null;
           this.approvals.set(approvalId, {
             runId,
@@ -8488,7 +8491,7 @@ var RunRegistry = class {
               this.approvals.delete(approvalId);
               emit("approval.resolved", { approvalId, decision });
               emit("status.changed", { status: waitingStatus() });
-              resolve9(decision);
+              resolve10(decision);
             }
           });
         });
@@ -8499,7 +8502,7 @@ var RunRegistry = class {
         if (finished || this.nativeCleared.delete(questionId)) return Promise.resolve({ selected: [] });
         emit("question.requested", { questionId, ...payload });
         emit("status.changed", { status: "waiting_for_input" });
-        return new Promise((resolve9) => {
+        return new Promise((resolve10) => {
           this.questions.set(questionId, {
             runId,
             input,
@@ -8507,7 +8510,7 @@ var RunRegistry = class {
               this.questions.delete(questionId);
               emit("question.answered", { questionId, ...answer });
               emit("status.changed", { status: waitingStatus() });
-              resolve9(answer);
+              resolve10(answer);
             }
           });
         });
@@ -8586,7 +8589,7 @@ var RunRegistry = class {
   }
   /** Interrupts every live run, giving each a moment to stop cleanly. */
   async interruptAll(timeoutMs = 3e3) {
-    await Promise.race([Promise.allSettled(this.activeRunIds().map((id) => this.interrupt(id))), new Promise((resolve9) => setTimeout(resolve9, timeoutMs))]);
+    await Promise.race([Promise.allSettled(this.activeRunIds().map((id) => this.interrupt(id))), new Promise((resolve10) => setTimeout(resolve10, timeoutMs))]);
   }
   resolveApproval(runId, approvalId, decision) {
     if (decision !== "approved" && decision !== "denied" && decision !== "native") throw new HarnessError("invalid_request", "Unknown decision.");
@@ -8786,7 +8789,7 @@ ${text6}`);
 async function waitForChildren(root, runId, signal) {
   while (!signal?.aborted) {
     if (settled(root, runId)) return true;
-    await new Promise((resolve9) => setTimeout(resolve9, 250));
+    await new Promise((resolve10) => setTimeout(resolve10, 250));
   }
   return false;
 }
@@ -8867,11 +8870,11 @@ var MAX_TEXT = 4e3;
 var clip2 = (text6) => text6.length > MAX_TEXT ? `${text6.slice(0, MAX_TEXT)}\u2026` : text6;
 function dismissable(answer, fallback, options2) {
   if (!options2?.signal && !options2?.timeout) return answer;
-  return new Promise((resolve9) => {
+  return new Promise((resolve10) => {
     let timer;
     const done = (value) => {
       if (timer) clearTimeout(timer);
-      resolve9(value);
+      resolve10(value);
     };
     if (options2.signal?.aborted) return done(fallback);
     options2.signal?.addEventListener("abort", () => done(fallback), { once: true });
@@ -9564,7 +9567,7 @@ function connectionFromEnv(env = process.env) {
   return { socket, token };
 }
 function request(connection, body2, what, timeoutMs) {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const stream = createConnection(connection.socket);
     let buffer = "";
     let settled2 = false;
@@ -9590,7 +9593,7 @@ function request(connection, body2, what, timeoutMs) {
         if (reply.error) {
           const error = typeof reply.error === "string" ? { message: reply.error } : reply.error;
           finish(() => reject(new SocketError(error.code ?? "error", error.message ?? `${what} failed.`)));
-        } else finish(() => resolve9(reply.result));
+        } else finish(() => resolve10(reply.result));
       } catch {
         finish(() => reject(new SocketError("invalid_reply", "The harness sent an unreadable reply.")));
       }
@@ -9794,15 +9797,15 @@ var TerminalController = class {
     if (this.disposed) throw new HarnessError("terminal_not_ready", "Reopen the terminal before sending instructions.");
     if (this.activeRun || this.delivery) throw new HarnessError("session_busy", "This terminal has an active task or delivery.");
     const deadline = Date.now() + READY_TIMEOUT_MS;
-    while (!this.ready && !this.startupError && !this.disposed && Date.now() < deadline) await new Promise((resolve9) => setTimeout(resolve9, 50));
+    while (!this.ready && !this.startupError && !this.disposed && Date.now() < deadline) await new Promise((resolve10) => setTimeout(resolve10, 50));
     if (this.disposed) throw new HarnessError("terminal_not_ready", "The terminal stopped during initialization.");
     if (this.startupError) throw new HarnessError("terminal_not_ready", this.startupError);
     if (!this.ready) throw new HarnessError("terminal_not_ready", `The native telemetry handshake is missing (${this.startupPhase}). Inspect the terminal sign-in or trust screen.`);
     if (this.dirty) throw new HarnessError("terminal_has_draft", "The terminal contains user input. Submit or clear it before handing back control.");
     let timer;
-    const ack = new Promise((resolve9, reject) => {
+    const ack = new Promise((resolve10, reject) => {
       timer = setTimeout(() => reject(new HarnessError("delivery_uncertain", "The native prompt acknowledgement was not received. Inspect the terminal; this instruction will not be resent.")), ACK_TIMEOUT_MS);
-      this.delivery = { runId, text: text6, resolve: resolve9, reject };
+      this.delivery = { runId, text: text6, resolve: resolve10, reject };
     });
     void ack.catch(() => {
     });
@@ -9918,18 +9921,44 @@ var TerminalController = class {
 };
 
 // src/terminal/socket.ts
-import { createHash as createHash7 } from "node:crypto";
-import { chmodSync as chmodSync10, mkdirSync as mkdirSync12, rmSync as rmSync8 } from "node:fs";
+import { createHash as createHash7, randomBytes } from "node:crypto";
+import { chmodSync as chmodSync10, mkdirSync as mkdirSync12, rmSync as rmSync8, statSync as statSync6 } from "node:fs";
 import { createServer as createServer2 } from "node:net";
 import { tmpdir } from "node:os";
 import { dirname as dirname12, join as join37 } from "node:path";
 var MAX_REQUEST_BYTES = 1024 * 1024;
 var MAX_SOCKET_PATH = 100;
 function socketPath(stateDir) {
+  if (process.platform === "win32") return `\\\\.\\pipe\\xingular-harness-${randomBytes(12).toString("hex")}`;
   const path3 = join37(stateDir, "run", "harness.sock");
   if (Buffer.byteLength(path3) <= MAX_SOCKET_PATH) return path3;
   return join37(tmpdir(), `xh-${createHash7("sha256").update(path3).digest("hex").slice(0, 16)}.sock`);
 }
+var isPipePath = (path3) => path3.startsWith("\\\\.\\pipe\\");
+function refusedBind(path3, error) {
+  const code = error?.code;
+  if (code !== "EACCES" && code !== "EPERM") return error;
+  if (isPipePath(path3)) {
+    return new HarnessError(
+      "session_socket_denied",
+      `The session pipe ${path3} could not be created (${code}).`,
+      "Start the harness again from your own user session. If it keeps failing, report this code and the Windows version."
+    );
+  }
+  let folder;
+  try {
+    const stat = statSync6(dirname12(path3));
+    folder = `${dirname12(path3)} is owned by uid ${stat.uid} with mode ${(stat.mode & 511).toString(8)}`;
+  } catch {
+    folder = `${dirname12(path3)} could not be read`;
+  }
+  const uid = process.getuid?.() ?? "unknown";
+  return new HarnessError(
+    "session_socket_denied",
+    `The session socket ${path3} could not be created (${code}). ${folder}; this process runs as uid ${uid}.`,
+    "Run the harness from your own terminal, as the user that owns its state folder, or choose a state folder you own with --state."
+  );
+}
 var SessionSocket = class {
   constructor(path3, handlers) {
     this.path = path3;
@@ -10025,22 +10054,26 @@ var SessionSocket = class {
   }
   /** Binds the socket once; later calls wait for the same bind. */
   listen() {
-    this.listening ??= new Promise((resolve9, reject) => {
-      mkdirSync12(dirname12(this.path), { recursive: true, mode: 448 });
-      rmSync8(this.path, { force: true });
+    this.listening ??= new Promise((resolve10, reject) => {
+      if (!isPipePath(this.path)) {
+        mkdirSync12(dirname12(this.path), { recursive: true, mode: 448 });
+        rmSync8(this.path, { force: true });
+      }
       const server = createServer2((client) => this.serve(client));
       server.once("error", (error) => {
         this.listening = null;
-        reject(error);
+        reject(refusedBind(this.path, error));
       });
       server.listen(this.path, () => {
-        try {
-          chmodSync10(this.path, 384);
-        } catch (error) {
-          log("session socket permissions", error instanceof Error ? error.message : String(error));
+        if (!isPipePath(this.path)) {
+          try {
+            chmodSync10(this.path, 384);
+          } catch (error) {
+            log("session socket permissions", error instanceof Error ? error.message : String(error));
+          }
         }
         this.server = server;
-        resolve9();
+        resolve10();
       });
     });
     return this.listening;
@@ -10051,8 +10084,8 @@ var SessionSocket = class {
     this.server = null;
     this.listening = null;
     for (const client of this.clients) client.destroy();
-    if (server) await new Promise((resolve9) => server.close(() => resolve9()));
-    rmSync8(this.path, { force: true });
+    if (server) await new Promise((resolve10) => server.close(() => resolve10()));
+    if (!isPipePath(this.path)) rmSync8(this.path, { force: true });
   }
 };
 
@@ -10558,7 +10591,7 @@ import { join as join41, resolve as resolve7 } from "node:path";
 import { createInterface } from "node:readline/promises";
 
 // src/plugins/install.ts
-import { existsSync as existsSync15, mkdirSync as mkdirSync15, renameSync as renameSync8, statSync as statSync6 } from "node:fs";
+import { existsSync as existsSync15, mkdirSync as mkdirSync15, renameSync as renameSync8, statSync as statSync7 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { basename as basename8, isAbsolute as isAbsolute5, join as join40, resolve as resolve6 } from "node:path";
 function normalizeSource(input) {
@@ -10578,7 +10611,7 @@ async function manager(harness) {
 var changed = (harness) => harness.bus.emit({ type: "plugins.changed" });
 async function install2(harness, params) {
   const source2 = normalizeSource(params.source);
-  if (isAbsolute5(source2) && !(existsSync15(source2) && statSync6(source2).isDirectory())) throw invalid("That folder does not exist.");
+  if (isAbsolute5(source2) && !(existsSync15(source2) && statSync7(source2).isDirectory())) throw invalid("That folder does not exist.");
   await ensureAdopted(harness);
   const before = new Set((await list2(harness, params)).map((plugin) => plugin.id));
   const { settings, packages } = await manager(harness);
@@ -10888,7 +10921,7 @@ var RpcPeer = class {
   /** Asks the host to perform a named operation. */
   callHost(call, params, timeoutMs = 3e4) {
     const id = `s${++this.nextCallId}`;
-    return new Promise((resolve9, reject) => {
+    return new Promise((resolve10, reject) => {
       const timer = setTimeout(() => {
         this.pendingCalls.delete(id);
         reject(new HarnessError("host_timeout", `The host did not answer ${call}.`));
@@ -10896,7 +10929,7 @@ var RpcPeer = class {
       this.pendingCalls.set(id, {
         resolve: (value) => {
           clearTimeout(timer);
-          resolve9(value);
+          resolve10(value);
         },
         reject: (error) => {
           clearTimeout(timer);
@@ -10947,7 +10980,7 @@ var RpcPeer = class {
 };
 
 // src/server/methods.ts
-import { readFileSync as readFileSync20, statSync as statSync7 } from "node:fs";
+import { readFileSync as readFileSync20, statSync as statSync8 } from "node:fs";
 import { basename as basename9 } from "node:path";
 
 // src/memory/graph.ts
@@ -11161,7 +11194,7 @@ function methods(harness) {
     "wiki.sources": () => listSources(wikiDir2()),
     "wiki.ingest": (params) => {
       const path3 = text5(params, "path");
-      if (statSync7(path3).size > MAX_SOURCE_BYTES) throw invalid("Sources larger than 50 MB are not imported.");
+      if (statSync8(path3).size > MAX_SOURCE_BYTES) throw invalid("Sources larger than 50 MB are not imported.");
       const source2 = maintenance.ingest(optional2(params, "name") ?? basename9(path3), readFileSync20(path3), optional2(params, "namespace") ?? LIBRARY_NAMESPACE);
       harness.bus.emit({ type: "wiki.changed" });
       return source2;
@@ -11327,7 +11360,7 @@ function attach3(harness, peer) {
 import { spawn as nodeSpawn } from "node:child_process";
 import { createHash as createHash8, randomUUID as randomUUID8 } from "node:crypto";
 import { homedir as homedir6 } from "node:os";
-import { join as join42, resolve as resolve8 } from "node:path";
+import { isAbsolute as isAbsolute6, join as join42, resolve as resolve8 } from "node:path";
 function standaloneArguments(argv) {
   const command = argv[0];
   if (!command || command.startsWith("--") || command === "-h") return argv;
@@ -11339,14 +11372,19 @@ function parseStandaloneOptions(argv, home = homedir6(), cwd = process.cwd()) {
     dataRoot: join42(root, "data"),
     stateDir: join42(root, "state")
   };
+  const given = /* @__PURE__ */ new Set();
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
     if (argument !== "--data" && argument !== "--state") throw new Error(`Unknown standalone option: ${argument}`);
     const value = argv[index + 1];
     if (!value || value.startsWith("--")) throw new Error(`${argument} needs a directory path.`);
     paths[argument === "--data" ? "dataRoot" : "stateDir"] = resolve8(cwd, value);
+    given.add(argument);
     index += 1;
   }
+  if (!isAbsolute6(home) && !(given.has("--data") && given.has("--state"))) {
+    throw new Error(`The home folder "${home}" is not an absolute path, so the default data and state folders cannot be placed. Set HOME to your home folder, or pass --data and --state with absolute folders.`);
+  }
   return paths;
 }
 function processEnvironment(overrides) {
@@ -11451,15 +11489,16 @@ function flags(argv) {
 }
 function serveCommand(argv) {
   const { values: values2, switches } = flags(argv);
-  const stateDir = values2.state?.[0];
-  if (!stateDir) {
+  const stateArgument = values2.state?.[0];
+  if (!stateArgument) {
     process.stderr.write("serve needs --state <dir>.\n");
     return Promise.resolve(2);
   }
+  const stateDir = resolve9(stateArgument);
   const peer = new RpcPeer(stdioTransport());
   const options2 = {
     stateDir,
-    dataRoot: values2.data?.[0] ?? null,
+    dataRoot: values2.data?.[0] ? resolve9(values2.data[0]) : null,
     productName: values2.name?.[0],
     builtins: values2.builtins,
     ...switches.has("host-secrets") ? { secrets: remoteSecrets(peer) } : {},
@@ -11469,12 +11508,12 @@ function serveCommand(argv) {
   const harness = createHarness(options2);
   if (switches.has("host-tools")) harness.sessions.provide(remoteTools(peer));
   attach3(harness, peer);
-  return new Promise((resolve9) => {
+  return new Promise((resolve10) => {
     let closing = false;
     const shutdown = () => {
       if (closing) return;
       closing = true;
-      void Promise.race([harness.close(), new Promise((done) => setTimeout(done, 5e3))]).then(() => resolve9(0));
+      void Promise.race([harness.close(), new Promise((done) => setTimeout(done, 5e3))]).then(() => resolve10(0));
     };
     peer.handle("harness.shutdown", () => void setImmediate(shutdown));
     process.stdin.on("end", shutdown);

package/package.json

@@ -1,14 +1,21 @@
 {
   "name": "@xingular/harness",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "Xingular Harness — a Pi agent harness with multi-account sign-in, a compiled system prompt, a memory lifecycle (Wiki), tools, MCP, and skills",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tanntnny/xingular-harness.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": "./src/index.ts",
     "./*": "./src/*"
   },
   "bin": {
-    "xingular-harness": "./dist/cli.js"
+    "xingular-harness": "dist/cli.js"
   },
   "scripts": {
     "build": "esbuild src/cli.ts --bundle --platform=node --target=node22 --format=esm --packages=external --outfile=dist/cli.js && esbuild src/terminal/piExtension.ts --bundle --platform=node --target=node22 --format=esm --packages=external --outfile=dist/terminal-pi.js",

package/src/cli.ts

@@ -7,6 +7,8 @@
 //   xingular-harness wiki <command>     Memory and Wiki, from inside a terminal session.
 //   xingular-harness mcp <command>      Connected apps, from inside a terminal session.
 //   xingular-harness plugins <command>  List, install, switch and trust plugins.
+import { resolve } from 'node:path'
+
 import { log } from './core/bus'
 import { createHarness, type HarnessOptions } from './harness'
 import { runPluginsCli, terminalAsk } from './plugins/cli'
@@ -50,15 +52,17 @@ function flags(argv: string[]): { values: Record<string, string[]>; switches: Se
 
 function serveCommand(argv: string[]): Promise<number> {
   const { values, switches } = flags(argv)
-  const stateDir = values.state?.[0]
-  if (!stateDir) {
+  const stateArgument = values.state?.[0]
+  if (!stateArgument) {
     process.stderr.write('serve needs --state <dir>.\n')
     return Promise.resolve(2)
   }
+  // The socket path is built from this folder, so a relative one would depend on where the host ran.
+  const stateDir = resolve(stateArgument)
   const peer = new RpcPeer(stdioTransport())
   const options: HarnessOptions = {
     stateDir,
-    dataRoot: values.data?.[0] ?? null,
+    dataRoot: values.data?.[0] ? resolve(values.data[0]) : null,
     productName: values.name?.[0],
     builtins: values.builtins,
     ...(switches.has('host-secrets') ? { secrets: remoteSecrets(peer) } : {}),

package/src/mcp/scopeMigration.test.ts

@@ -0,0 +1,79 @@
+import { createHash } from 'node:crypto'
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import * as attachments from '../plugins/attachments'
+import { migrateConnectionScopes, rollbackConnectionScopeMigration } from './scopeMigration'
+
+const roots: string[] = []
+function fixture(): { root: string; stateDir: string; sessionPath: string } {
+  const base = mkdtempSync(join(tmpdir(), 'xingular-scope-migration-'))
+  roots.push(base)
+  const root = join(base, 'data')
+  const stateDir = join(base, 'state')
+  mkdirSync(join(root, 'config'), { recursive: true })
+  mkdirSync(join(root, 'sessions', 'agent'), { recursive: true })
+  mkdirSync(stateDir, { recursive: true })
+  const sessionPath = join(root, 'sessions', 'agent', 'thread.json')
+  writeFileSync(sessionPath, Buffer.from('{ "session": "keep these bytes\\nexactly" }\n'))
+  mkdirSync(join(root, 'agents', 'agent-a'), { recursive: true })
+  writeFileSync(join(root, 'agents', 'agent-a', 'agent.md'), Buffer.from('tools: [read, bash, mcp_call_tool]\n'))
+  return { root, stateDir, sessionPath }
+}
+
+function digest(path: string): string {
+  return createHash('sha256').update(readFileSync(path)).digest('hex')
+}
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+describe('connector scope migration', () => {
+  it('moves scopes, verifies assignments, keeps session bytes, and restores exact backups', () => {
+    const { root, stateDir, sessionPath } = fixture()
+    const sessionHash = digest(sessionPath)
+    const agentToolsPath = join(root, 'agents', 'agent-a', 'agent.md')
+    const agentToolsHash = digest(agentToolsPath)
+    const connectionBytes = Buffer.from(`[{"id":"linear","name":"Linear","kind":"remote","enabled":true,"global":true,"agentIds":["agent-a"],"excludedAgentIds":["agent-b"],"projectIds":["project-a"],"excludedProjectIds":["project-b"],"url":"https://mcp.example"}]\n`)
+    const oldAttachmentsBytes = Buffer.from('{"version":1,"global":{"on":["existing"],"off":[]},"agents":{},"projects":{},"settings":{"keep":{"x":1}}}\n')
+    const connectionsPath = join(stateDir, 'connections.json')
+    const attachmentsPath = join(root, 'config', 'plugin-attachments.json')
+    writeFileSync(connectionsPath, connectionBytes)
+    writeFileSync(attachmentsPath, oldAttachmentsBytes)
+
+    const result = migrateConnectionScopes(root, stateDir)
+    expect(result).toMatchObject({ status: 'complete', connectionCount: 1, scopeAssignmentCount: 5, hadAttachments: true })
+    const saved = JSON.parse(readFileSync(connectionsPath, 'utf8'))[0]
+    expect(saved).toMatchObject({ id: 'linear', url: 'https://mcp.example' })
+    for (const key of ['global', 'agentIds', 'excludedAgentIds', 'projectIds', 'excludedProjectIds']) expect(saved).not.toHaveProperty(key)
+
+    const migrated = attachments.load(root)
+    expect(migrated.global.on).toContain('connected-apps/connection/linear')
+    expect(migrated.agents['agent-a'].on).toContain('connected-apps/connection/linear')
+    expect(migrated.agents['agent-b'].off).toContain('connected-apps/connection/linear')
+    expect(migrated.projects['project-a'].on).toContain('connected-apps/connection/linear')
+    expect(migrated.projects['project-b'].off).toContain('connected-apps/connection/linear')
+    expect(digest(sessionPath)).toBe(sessionHash)
+    expect(digest(agentToolsPath)).toBe(agentToolsHash)
+    expect(readFileSync(join(stateDir, 'connections.pre-capability-scope.json'))).toEqual(connectionBytes)
+    expect(readFileSync(join(root, 'config', 'plugin-attachments.pre-capability-scope.json'))).toEqual(oldAttachmentsBytes)
+
+    rollbackConnectionScopeMigration(root, stateDir)
+    expect(readFileSync(connectionsPath)).toEqual(connectionBytes)
+    expect(readFileSync(attachmentsPath)).toEqual(oldAttachmentsBytes)
+    expect(digest(sessionPath)).toBe(sessionHash)
+    expect(digest(agentToolsPath)).toBe(agentToolsHash)
+  })
+
+  it('is idempotent after completion without rewriting session data', () => {
+    const { root, stateDir, sessionPath } = fixture()
+    writeFileSync(join(stateDir, 'connections.json'), '[{"id":"linear","global":false}]\n')
+    const before = digest(sessionPath)
+    const first = migrateConnectionScopes(root, stateDir)
+    expect(migrateConnectionScopes(root, stateDir)).toEqual(first)
+    expect(digest(sessionPath)).toBe(before)
+  })
+})

package/src/mcp/service.test.ts

@@ -181,7 +181,7 @@ describe('connected apps for a session', () => {
     const saved = await harness.apps.save({ ...local, command: '/missing/mcp-fixture' })
     const result = await harness.apps.list(granted)
     expect(result.tools).toEqual([])
-    expect(result.errors[0].message).toContain('Settings')
+    expect(result.errors[0].message).toContain('Capability → Connectors')
     expect(harness.apps.connections.find(saved.id).error).toContain('executable and arguments')
   })
 

package/src/mcp/service.ts

@@ -134,7 +134,7 @@ export class ConnectedApps implements SessionBroker {
   private brokered: BrokeredTools | null = null
 
   constructor(private readonly options: ConnectedAppsOptions) {
-    this.connections = new Connections(options.stateDir, options.secrets, options.bus, () => options.env.dataRoot)
+    this.connections = new Connections(options.stateDir, options.secrets, options.bus, () => options.env.root)
     this.oauth = {
       clientName: options.env.productName,
       load: (id) => this.connections.oauthLoad(id),

package/src/terminal/socket.test.ts

@@ -0,0 +1,71 @@
+import { chmodSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { createConnection } from 'node:net'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+import { SessionSocket, socketPath } from './socket'
+
+const handlers = { memory: () => '', apps: async () => null }
+
+/** Runs `body` as if on another operating system; `process.platform` is read at call time. */
+function onPlatform<T>(platform: NodeJS.Platform, body: () => T): T {
+  const original = Object.getOwnPropertyDescriptor(process, 'platform')!
+  Object.defineProperty(process, 'platform', { value: platform })
+  try {
+    return body()
+  } finally {
+    Object.defineProperty(process, 'platform', original)
+  }
+}
+
+describe('session socket path', () => {
+  it('keeps the socket file in the state folder on Unix', () => {
+    expect(onPlatform('darwin', () => socketPath('/tmp/state'))).toBe(join('/tmp/state', 'run', 'harness.sock'))
+  })
+
+  it('uses a named pipe on Windows, with a random name each time', () => {
+    const first = onPlatform('win32', () => socketPath('C:\\Users\\someone\\.xingular-harness\\state'))
+    const second = onPlatform('win32', () => socketPath('C:\\Users\\someone\\.xingular-harness\\state'))
+    expect(first).toMatch(/^\\\\\.\\pipe\\xingular-harness-[0-9a-f]{24}$/)
+    expect(second).not.toBe(first)
+  })
+})
+
+describe('session socket', () => {
+  it.skipIf(process.platform !== 'win32')('listens on a named pipe and answers a request on Windows', async () => {
+    const socket = new SessionSocket(socketPath('unused'), handlers)
+    await socket.listen()
+    try {
+      const reply = await new Promise<string>((resolve, reject) => {
+        const client = createConnection(socket.path)
+        let buffer = ''
+        client.on('connect', () => client.write('{"token":"nope","call":"wiki.read"}\n'))
+        client.on('data', (chunk) => (buffer += chunk.toString('utf8')))
+        client.on('end', () => resolve(buffer))
+        client.on('error', reject)
+      })
+      expect(JSON.parse(reply)).toMatchObject({ error: { code: 'unauthorized' } })
+    } finally {
+      await socket.close()
+    }
+  })
+
+  it('names the folder and the user when the operating system refuses to create the socket', async () => {
+    // Root can write anywhere, so the refusal cannot be produced there.
+    if (process.platform === 'win32' || process.getuid?.() === 0) return
+    const base = mkdtempSync(join(tmpdir(), 'sock-'))
+    const run = join(base, 'run')
+    mkdirSync(run)
+    chmodSync(run, 0o500)
+    try {
+      await expect(new SessionSocket(join(run, 'harness.sock'), handlers).listen()).rejects.toMatchObject({
+        code: 'session_socket_denied',
+        message: expect.stringMatching(/could not be created \((?:EACCES|EPERM)\)\. .*mode 500; this process runs as uid \d+\./)
+      })
+    } finally {
+      chmodSync(run, 0o700)
+      rmSync(base, { recursive: true, force: true })
+    }
+  })
+})

package/src/terminal/socket.ts

@@ -1,10 +1,10 @@
 // The session socket: how a process the harness did not start in-process (the `pi` command in
 // a terminal, with its extension and the `agentx-wiki` / `agentx-mcp` commands) reaches the
-// session it belongs to. Owner-only Unix socket, newline-delimited JSON, one request per
-// connection. Each terminal session holds a random token bound to its caller, its connected-apps
-// grant, and its controller; the token stops working when the terminal ends.
-import { createHash } from 'node:crypto'
-import { chmodSync, mkdirSync, rmSync } from 'node:fs'
+// session it belongs to. Owner-only Unix socket (a named pipe on Windows), newline-delimited JSON,
+// one request per connection. Each terminal session holds a random token bound to its caller, its
+// connected-apps grant, and its controller; the token stops working when the terminal ends.
+import { createHash, randomBytes } from 'node:crypto'
+import { chmodSync, mkdirSync, rmSync, statSync } from 'node:fs'
 import { createServer, type Server, type Socket } from 'node:net'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
@@ -42,12 +42,47 @@ const MAX_REQUEST_BYTES = 1024 * 1024
 /** macOS refuses a socket path longer than 103 bytes. */
 const MAX_SOCKET_PATH = 100
 
+/**
+ * Windows has no socket files for Node's `net`: it listens on a named pipe, which lives in a
+ * machine-wide namespace. A random name keeps another local process from guessing it and standing
+ * in front of the session; the token still decides what a caller may do.
+ */
 export function socketPath(stateDir: string): string {
+  if (process.platform === 'win32') return `\\\\.\\pipe\\xingular-harness-${randomBytes(12).toString('hex')}`
   const path = join(stateDir, 'run', 'harness.sock')
   if (Buffer.byteLength(path) <= MAX_SOCKET_PATH) return path
   return join(tmpdir(), `xh-${createHash('sha256').update(path).digest('hex').slice(0, 16)}.sock`)
 }
 
+/** A named pipe has no folder, file mode, or owner to check or clean up. */
+const isPipePath = (path: string): boolean => path.startsWith('\\\\.\\pipe\\')
+
+/** Names the folder and the user when the operating system refuses the socket, so the cause shows. */
+function refusedBind(path: string, error: unknown): unknown {
+  const code = (error as { code?: unknown } | null)?.code
+  if (code !== 'EACCES' && code !== 'EPERM') return error
+  if (isPipePath(path)) {
+    return new HarnessError(
+      'session_socket_denied',
+      `The session pipe ${path} could not be created (${code}).`,
+      'Start the harness again from your own user session. If it keeps failing, report this code and the Windows version.'
+    )
+  }
+  let folder: string
+  try {
+    const stat = statSync(dirname(path))
+    folder = `${dirname(path)} is owned by uid ${stat.uid} with mode ${(stat.mode & 0o777).toString(8)}`
+  } catch {
+    folder = `${dirname(path)} could not be read`
+  }
+  const uid = process.getuid?.() ?? 'unknown'
+  return new HarnessError(
+    'session_socket_denied',
+    `The session socket ${path} could not be created (${code}). ${folder}; this process runs as uid ${uid}.`,
+    'Run the harness from your own terminal, as the user that owns its state folder, or choose a state folder you own with --state.'
+  )
+}
+
 export class SessionSocket {
   private server: Server | null = null
   private listening: Promise<void> | null = null
@@ -150,18 +185,22 @@ export class SessionSocket {
   /** Binds the socket once; later calls wait for the same bind. */
   listen(): Promise<void> {
     this.listening ??= new Promise<void>((resolve, reject) => {
-      mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
-      rmSync(this.path, { force: true })
+      if (!isPipePath(this.path)) {
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
+        rmSync(this.path, { force: true })
+      }
       const server = createServer((client) => this.serve(client))
       server.once('error', (error) => {
         this.listening = null
-        reject(error)
+        reject(refusedBind(this.path, error))
       })
       server.listen(this.path, () => {
-        try {
-          chmodSync(this.path, 0o600)
-        } catch (error) {
-          log('session socket permissions', error instanceof Error ? error.message : String(error))
+        if (!isPipePath(this.path)) {
+          try {
+            chmodSync(this.path, 0o600)
+          } catch (error) {
+            log('session socket permissions', error instanceof Error ? error.message : String(error))
+          }
         }
         this.server = server
         resolve()
@@ -177,6 +216,6 @@ export class SessionSocket {
     this.listening = null
     for (const client of this.clients) client.destroy()
     if (server) await new Promise<void>((resolve) => server.close(() => resolve()))
-    rmSync(this.path, { force: true })
+    if (!isPipePath(this.path)) rmSync(this.path, { force: true })
   }
 }

package/src/terminal/standalone.test.ts

@@ -67,6 +67,11 @@ describe('standalone terminal startup', () => {
     expect(() => parseStandaloneOptions(['--model', 'unknown'])).toThrow('Unknown standalone option: --model')
   })
 
+  it('refuses default folders under a home that is not a folder path, and accepts explicit absolute folders', () => {
+    expect(() => parseStandaloneOptions([], 'HOME', '/work/project')).toThrow('is not an absolute path')
+    expect(parseStandaloneOptions(['--data', '/data', '--state', '/state'], 'HOME', '/work/project')).toEqual({ dataRoot: '/data', stateDir: '/state' })
+  })
+
   it('starts Pi in the current directory, creates the first isolated account, and cleans up on exit', async () => {
     const home = temporaryDirectory('harness-standalone-')
     const cwd = temporaryDirectory('harness-cwd-')

package/src/terminal/standalone.ts

@@ -3,7 +3,7 @@
 import { spawn as nodeSpawn } from 'node:child_process'
 import { createHash, randomUUID } from 'node:crypto'
 import { homedir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { isAbsolute, join, resolve } from 'node:path'
 
 import { createHarness, type Harness, type HarnessOptions } from '../harness'
 import type { TerminalLaunch } from './terminals'
@@ -36,15 +36,23 @@ export function parseStandaloneOptions(argv: string[], home = homedir(), cwd = p
     stateDir: join(root, 'state')
   }
 
+  const given = new Set<string>()
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index]
     if (argument !== '--data' && argument !== '--state') throw new Error(`Unknown standalone option: ${argument}`)
     const value = argv[index + 1]
     if (!value || value.startsWith('--')) throw new Error(`${argument} needs a directory path.`)
     paths[argument === '--data' ? 'dataRoot' : 'stateDir'] = resolve(cwd, value)
+    given.add(argument)
     index += 1
   }
 
+  // A home that is not a folder path (for example HOME set to the word "HOME") would put the
+  // defaults, and the session socket, in whatever folder the command was started from.
+  if (!isAbsolute(home) && !(given.has('--data') && given.has('--state'))) {
+    throw new Error(`The home folder "${home}" is not an absolute path, so the default data and state folders cannot be placed. Set HOME to your home folder, or pass --data and --state with absolute folders.`)
+  }
+
   return paths
 }