@oddessentials/agent-guild 0.33.2 → 0.35.0

package/src/manager/autostart.mjs

@@ -14,6 +14,10 @@
 //   runs a script in the data folder, as on macOS: desktops read Exec lines
 //   by different rules (systemd's autostart generator keeps a backslash that
 //   GLib removes), so the line holds only paths that read the same in all.
+//   Linux also offers a systemd user service that starts the manager when
+//   the computer starts (systemd-service.mjs). One starter at a time: the
+//   setting is a mode, off, sign-in or boot, and choosing one removes the
+//   other, so a sign-in never races the service for the port.
 //
 // Each launcher touches a file in the data folder before it starts Node.js,
 // and `open --sign-in` records whether a manager then answered, so the page
@@ -35,6 +39,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFile } from 'node:child_process';
 import { DEFAULT_PORT } from './config.mjs';
+import { BOOT_NOTE, UNIT_UNSAFE, bootSupported, createBootService, journalCommand, lingerCommand, startupState, systemdRunner, unitPort, userName } from './systemd-service.mjs';
 
 export const ARGS = ['open', '--no-browser', '--sign-in'];
 export const WINDOWS_RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
@@ -61,8 +66,8 @@ export const MAC_NOTE = 'Starts the session manager in the background when you s
 export const LINUX_NOTE = 'Starts the session manager in the background when you sign in to a desktop session on this computer. The page does not open. A computer with no desktop session, such as a server reached over SSH, does not start it. Desktop startup settings list it as Agent Guild.';
 /** Added to LINUX_NOTE when the manager itself was not started from a desktop session. */
 export const LINUX_NO_DESKTOP = 'This manager was not started from a desktop session, so this computer may not have one.';
-/** Characters that systemd's autostart generator and GLib read differently in an Exec line. */
-const EXEC_UNSAFE = /["`$\\]/;
+/** Linux startup modes. */
+export const MODES = ['off', 'sign-in', 'boot'];
 
 const failure = (message) => Object.assign(new Error(message), { status: 500, code: 'autostart_failed' });
 
@@ -318,6 +323,9 @@ async function clearSignIns(dataDir) {
  * @param {string|null} [opts.unavailable]  a reason autostart cannot be offered, which turns it off here
  * @param {(args: string[]) => Promise<{ status: number, stdout: string, stderr: string }>} [opts.reg]  reg.exe, replaceable in tests
  * @param {(args: string[]) => Promise<{ status: number, stdout: string, stderr: string }>} [opts.launchctl]  launchctl, replaceable in tests
+ * @param {(command: string, args: string[]) => Promise<object>} [opts.systemd]  systemctl and journalctl on Linux, replaceable in tests
+ * @param {string} [opts.lingerDir]  where systemd records lingering users, replaceable in tests
+ * @param {number} [opts.pid]  this manager, which the service state compares with systemd's
  */
 export function createAutostart({
   platform = process.platform,
@@ -333,6 +341,10 @@ export function createAutostart({
   reg = runCommand(path.win32.join(env.SystemRoot || env.SYSTEMROOT || env.WINDIR || 'C:\\Windows', 'System32', 'reg.exe')),
   uid = process.getuid?.(),
   launchctl = runCommand('/bin/launchctl'),
+  user = userName(uid),
+  systemd = systemdRunner({ uid, env }),
+  lingerDir,
+  pid = process.pid,
 }) {
   const entryExecPath = platform === 'win32' ? execPath : stableExecPath(execPath);
   const attempt = path.join(dataDir, SIGN_IN_ATTEMPT);
@@ -340,6 +352,9 @@ export function createAutostart({
   let note = null;
   let unusable = null;
   let refreshError = null;
+  /** The systemd user service, on a Linux that can offer it. */
+  let boot = null;
+  let bootRefreshError = null;
   let queue = Promise.resolve();
   /** One change or check at a time, so two clicks cannot interleave their writes. */
   const serial = (fn) => {
@@ -424,13 +439,15 @@ export function createAutostart({
         await fs.promises.rm(launcher, { force: true });
       },
     };
-  } else if (platform === 'linux' && !(env.WSL_DISTRO_NAME || /microsoft|wsl/i.test(release))) {
+  } else if (bootSupported({ platform, env, release })) {
     const file = path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'autostart', 'agent-guild.desktop');
     const launcher = path.join(dataDir, LINUX_LAUNCHER);
-    const unsafe = [entryExecPath, script, file, launcher, log, attempt].find((p) => EXEC_UNSAFE.test(p));
+    const service = createBootService({ env, home, user, uid, dataDir, run: systemd, ...(lingerDir && { lingerDir }) });
+    const unsafe = [entryExecPath, script, file, launcher, log, attempt, ...service.paths].find((p) => UNIT_UNSAFE.test(p));
     if (unsafe) {
-      unusable = `Not available because this path holds a character (", \`, $ or \\) that desktops read differently in a startup entry: ${unsafe}`;
+      unusable = `Not available because this path holds a character (", \`, $, \\ or a line break) that desktops and systemd read differently in a startup entry: ${unsafe}`;
     } else {
+      boot = service;
       const desktop = env.XDG_CURRENT_DESKTOP || env.WAYLAND_DISPLAY || env.DISPLAY;
       note = desktop ? LINUX_NOTE : `${LINUX_NOTE} ${LINUX_NO_DESKTOP}`;
       target = {
@@ -455,10 +472,25 @@ export function createAutostart({
     : unavailable || unusable || (platform === 'linux' ? 'Not available in WSL. Start Agent Guild from Windows to launch it at sign-in.'
       : 'Not available on this operating system.');
 
+  const FAILED = new Set(['failed', 'port-in-use']);
+  /** The service's side of a Linux description: its state, and the commands that are the next step. */
+  const describeBoot = async () => {
+    const read = await boot.read();
+    const base = { note: BOOT_NOTE, user, linger: read.linger };
+    if (!read.reachable) return { ...base, available: false, enabled: false, reason: read.reason, state: null, commands: [] };
+    const state = startupState(read.show, { pid, port: unitPort(await boot.text()) });
+    const commands = [];
+    if (read.enabled && FAILED.has(state.kind)) commands.push(journalCommand());
+    if (read.enabled && !read.linger) commands.push(lingerCommand(user));
+    return { ...base, available: true, enabled: read.enabled, reason: read.enabled ? bootRefreshError : null, state, commands };
+  };
+  const modeOf = (signIn, bootOn) => (signIn && bootOn ? 'both' : bootOn ? 'boot' : signIn ? 'sign-in' : 'off');
+
   const describe = async () => {
     if (!target) return { available: false, enabled: false, reason };
     try {
       const enabled = await target.enabled();
+      const linux = boot ? await describeBoot() : null;
       return {
         available: true,
         enabled,
@@ -467,38 +499,90 @@ export function createAutostart({
         // An unreadable record never keeps the setting from being turned off.
         lastRun: enabled ? await lastSignIn(dataDir).catch(() => null) : null,
         log,
+        ...(linux && { mode: modeOf(enabled, linux.enabled), boot: linux }),
       };
     } catch (err) {
       return { available: false, enabled: false, reason: `Could not read the startup setting: ${err.message}` };
     }
   };
 
-  return {
-    describe: () => serial(describe),
-    /** Turns autostart on or off and resolves to the new description. */
-    set: (enabled) => serial(async () => {
-      if (!target) throw Object.assign(new Error(reason), { status: 409, code: 'autostart_unavailable' });
+  /**
+   * Makes `mode` the one starter. The new one is added and confirmed before
+   * the old one goes, and nothing here starts or stops a manager: a service
+   * takes over at the manager's next restart or the computer's next start.
+   */
+  const apply = async (mode) => {
+    const signedIn = await target.enabled().catch(() => false);
+    // A fresh start says it has not run yet rather than report an earlier time it was on.
+    if (mode !== 'sign-in' || !signedIn) await clearSignIns(dataDir);
+    if (mode === 'boot') {
+      const read = await boot.read();
+      if (!read.reachable) throw Object.assign(new Error(read.reason), { status: 409, code: 'autostart_unavailable' });
       try {
-        // A fresh start says it has not run yet rather than report an earlier time it was on.
-        if (!enabled || !(await target.enabled().catch(() => false))) await clearSignIns(dataDir);
-        await (enabled ? target.enable() : target.disable());
-        refreshError = null;
-        const state = await describe();
-        if (!state.available || state.enabled !== enabled) throw failure(state.reason || 'Could not verify the startup setting.');
-        return state;
+        await boot.write(command());
+        await boot.reload();
+        await boot.enable();
+        if (!(await boot.read()).enabled) throw failure('systemd did not enable the unit.');
       } catch (err) {
-        throw err.code === 'autostart_failed' ? err : failure(`Could not change the startup setting: ${err.message}`);
+        // Leave no half-made unit behind; the sign-in entry, if any, is still in place.
+        if (!read.enabled) await boot.remove().catch(() => {});
+        throw err;
       }
+      await target.disable();
+      return;
+    }
+    await (mode === 'sign-in' ? target.enable() : target.disable());
+    if (boot) await boot.remove();
+  };
+
+  /** Applies the mode `pick` resolves to, inside the queue, and checks the result against what the OS reports. */
+  const change = (pick) => serial(async () => {
+    if (!target) throw Object.assign(new Error(reason), { status: 409, code: 'autostart_unavailable' });
+    const mode = await pick();
+    if (mode === 'boot' && !boot) throw Object.assign(new Error('Starting when the computer starts is offered only on Linux with systemd.'), { status: 409, code: 'autostart_unavailable' });
+    try {
+      await apply(mode);
+      refreshError = null;
+      bootRefreshError = null;
+      const state = await describe();
+      const done = boot ? state.mode === mode : state.enabled === (mode === 'sign-in');
+      if (!state.available || !done) throw failure(state.reason || 'Could not verify the startup setting.');
+      return state;
+    } catch (err) {
+      throw err.code === 'autostart_failed' || err.code === 'autostart_unavailable' ? err : failure(`Could not change the startup setting: ${err.message}`);
+    }
+  });
+
+  return {
+    describe: () => serial(describe),
+    /**
+     * Turns the sign-in entry on or off and resolves to the new description.
+     * On Linux, on means the sign-in mode, and off keeps a service that is on.
+     */
+    set: (enabled) => change(async () => {
+      if (enabled) return 'sign-in';
+      return boot && ['boot', 'both'].includes((await describe()).mode) ? 'boot' : 'off';
     }),
-    /** Points an entry that is on at this manager's Node.js, package and port. */
+    /** Linux: makes `mode` (off, sign-in or boot) the one way the manager starts. Elsewhere boot is unavailable. */
+    setMode: (mode) => change(async () => mode),
+    /** Points what is on at this manager's Node.js, package and port. */
     refresh: () => serial(async () => {
+      let first = null;
       try {
         if (target && await target.enabled()) await target.write();
         refreshError = null;
       } catch (err) {
         refreshError = `Could not update the sign-in entry: ${err.message}`;
-        throw err;
+        first = err;
+      }
+      try {
+        if (boot && (await boot.read()).enabled && await boot.write(command())) await boot.reload();
+        bootRefreshError = null;
+      } catch (err) {
+        bootRefreshError = `Could not update the systemd unit: ${err.message}`;
+        first ??= err;
       }
+      if (first) throw first;
     }),
   };
 }

package/src/manager/environment-pins.mjs

@@ -0,0 +1,289 @@
+// Project pin files only. A pin is what a file asks for, never proof that a
+// runtime is installed or which binary a shell would execute.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const PIN_LIMIT = 64 * 1024;
+export const PIN_TEXT_MAX = 128;
+
+export const PIN_NAMES = [
+  '.nvmrc', '.node-version', '.python-version', 'package.json', 'pyproject.toml',
+  'rust-toolchain.toml', 'rust-toolchain', 'go.mod', 'global.json', '.tool-versions',
+];
+
+const TOOL_VERSIONS = {
+  node: ['tool-versions-node', 'Node.js'],
+  nodejs: ['tool-versions-node', 'Node.js'],
+  python: ['tool-versions-python', 'Python'],
+  go: ['tool-versions-go', 'Go'],
+  golang: ['tool-versions-go', 'Go'],
+  rust: ['tool-versions-rust', 'Rust'],
+  dotnet: ['tool-versions-dotnet', '.NET SDK'],
+  'dotnet-sdk': ['tool-versions-dotnet', '.NET SDK'],
+};
+
+function pin(id, label, source, status, version = null, detail = null) {
+  return { id, label, source, version, status, detail };
+}
+
+function configured(id, label, source, version) {
+  const text = typeof version === 'string' ? version.trim() : '';
+  if (!text) return pin(id, label, source, 'invalid', null, 'The pin is empty.');
+  if (text.length > PIN_TEXT_MAX) return pin(id, label, source, 'invalid', null, 'The pin is longer than 128 characters.');
+  return pin(id, label, source, 'configured', text);
+}
+
+function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+function versionLine(text) {
+  for (const raw of stripBom(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    return line;
+  }
+  return null;
+}
+
+function textPin(id, label, source, text) {
+  const line = versionLine(text);
+  if (line === null) return [pin(id, label, source, 'invalid', null, 'The pin file has no version.')];
+  return [configured(id, label, source, line)];
+}
+
+function packagePins(text) {
+  let data;
+  try { data = JSON.parse(stripBom(text)); } catch {
+    return [pin('package-json', 'package.json', 'package.json', 'invalid', null, 'package.json could not be read as JSON.')];
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return [pin('package-json', 'package.json', 'package.json', 'invalid', null, 'package.json could not be read as JSON.')];
+  }
+  const pins = [];
+  if (data.engines !== undefined) {
+    if (!data.engines || typeof data.engines !== 'object' || Array.isArray(data.engines)) {
+      pins.push(pin('engines', 'package.json', 'package.json', 'invalid', null, 'engines is not an object.'));
+    } else {
+      for (const [key, id, label] of [['node', 'engines-node', 'Node.js'], ['npm', 'engines-npm', 'npm']]) {
+        if (data.engines[key] === undefined) continue;
+        if (typeof data.engines[key] !== 'string') pins.push(pin(id, label, 'package.json', 'invalid', null, `engines.${key} is not a string.`));
+        else pins.push(configured(id, label, 'package.json', data.engines[key]));
+      }
+    }
+  }
+  if (data.packageManager !== undefined) {
+    if (typeof data.packageManager !== 'string') pins.push(pin('package-manager', 'packageManager', 'package.json', 'invalid', null, 'packageManager is not a string.'));
+    else {
+      const name = data.packageManager.split('@')[0].trim();
+      pins.push(configured('package-manager', name || 'packageManager', 'package.json', data.packageManager));
+    }
+  }
+  return pins;
+}
+
+function pythonRequires(text) {
+  const lines = stripBom(text).split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith('#'));
+  const keys = lines.filter((line) => /^requires-python\s*=/.test(line));
+  if (!keys.length) return [];
+  if (keys.length !== 1) return [pin('requires-python', 'Python', 'pyproject.toml', 'invalid', null, 'requires-python is not a single-line string.')];
+  const match = /^requires-python\s*=\s*(["'])([^"']+)\1\s*(?:#.*)?$/.exec(keys[0]);
+  if (!match) return [pin('requires-python', 'Python', 'pyproject.toml', 'invalid', null, 'requires-python is not a single-line string.')];
+  return [configured('requires-python', 'Python', 'pyproject.toml', match[2])];
+}
+
+function rustToml(text) {
+  let section = '';
+  let channel = null;
+  let saw = false;
+  let bad = false;
+  for (const raw of stripBom(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const heading = /^\[([^\]]+)\]$/.exec(line);
+    if (heading) {
+      section = heading[1].trim();
+      if (section === 'toolchain') saw = true;
+      continue;
+    }
+    if (section !== 'toolchain' || !/^channel\s*=/.test(line)) continue;
+    const match = /^channel\s*=\s*(["'])([^"']+)\1\s*(?:#.*)?$/.exec(line);
+    if (!match || channel !== null) bad = true;
+    else channel = match[2];
+  }
+  if (bad || (saw && channel === null)) return [pin('rust-toolchain', 'Rust', 'rust-toolchain.toml', 'invalid', null, 'rust-toolchain channel is not a single-line string.')];
+  return channel === null ? [] : [configured('rust-toolchain', 'Rust', 'rust-toolchain.toml', channel)];
+}
+
+function rustFile(text) {
+  const line = versionLine(text);
+  if (line === null) return [pin('rust-toolchain-file', 'Rust', 'rust-toolchain', 'invalid', null, 'The pin file has no version.')];
+  if (line.startsWith('[')) return [pin('rust-toolchain-file', 'Rust', 'rust-toolchain', 'invalid', null, 'rust-toolchain is not a single version line.')];
+  return [configured('rust-toolchain-file', 'Rust', 'rust-toolchain', line)];
+}
+
+function goMod(text) {
+  let language = null;
+  let toolchain = null;
+  let bad = false;
+  for (const raw of stripBom(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('//')) continue;
+    if (/^go\s/.test(line)) {
+      const match = /^go\s+(\S+)$/.exec(line);
+      if (!match || language !== null) bad = true;
+      else language = match[1];
+    } else if (/^toolchain\s/.test(line)) {
+      const match = /^toolchain\s+(\S+)$/.exec(line);
+      if (!match || toolchain !== null) bad = true;
+      else toolchain = match[1];
+    }
+  }
+  if (bad) return [pin('go-mod', 'Go', 'go.mod', 'invalid', null, 'go.mod has a version line that could not be read.')];
+  const pins = [];
+  if (language) pins.push(configured('go-language', 'Go language', 'go.mod', language));
+  if (toolchain) pins.push(configured('go-toolchain', 'Go toolchain', 'go.mod', toolchain));
+  return pins;
+}
+
+function globalJson(text) {
+  let data;
+  try { data = JSON.parse(stripBom(text)); } catch {
+    return [pin('global-json', '.NET SDK', 'global.json', 'invalid', null, 'global.json could not be read as JSON.')];
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data) || data.sdk === undefined) return [];
+  if (!data.sdk || typeof data.sdk !== 'object' || Array.isArray(data.sdk) || typeof data.sdk.version !== 'string') {
+    return [pin('global-json', '.NET SDK', 'global.json', 'invalid', null, 'sdk.version is not a string.')];
+  }
+  return [configured('global-json', '.NET SDK', 'global.json', data.sdk.version)];
+}
+
+function toolVersions(text) {
+  const pins = [];
+  const used = new Set();
+  let bad = false;
+  for (const raw of stripBom(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const gap = line.search(/\s/);
+    const name = (gap === -1 ? line : line.slice(0, gap)).toLowerCase();
+    const known = TOOL_VERSIONS[name];
+    if (!known) continue;
+    const version = gap === -1 ? '' : line.slice(gap).trim();
+    if (!version) bad = true;
+    else {
+      let id = known[0];
+      let n = 2;
+      while (used.has(id)) id = `${known[0]}-${n++}`;
+      used.add(id);
+      pins.push(configured(id, known[1], '.tool-versions', version));
+    }
+  }
+  if (bad) return [pin('tool-versions', '.tool-versions', '.tool-versions', 'invalid', null, '.tool-versions has a line that could not be read.')];
+  return pins;
+}
+
+const PARSERS = {
+  '.nvmrc': (text) => textPin('nvmrc', 'Node.js', '.nvmrc', text),
+  '.node-version': (text) => textPin('node-version', 'Node.js', '.node-version', text),
+  '.python-version': (text) => textPin('python-version', 'Python', '.python-version', text),
+  'package.json': packagePins,
+  'pyproject.toml': pythonRequires,
+  'rust-toolchain.toml': rustToml,
+  'rust-toolchain': rustFile,
+  'go.mod': goMod,
+  'global.json': globalJson,
+  '.tool-versions': toolVersions,
+};
+
+function inside(file, root) {
+  const child = path.resolve(file);
+  const base = path.resolve(root);
+  const left = process.platform === 'win32' ? child.toLowerCase() : child;
+  const right = process.platform === 'win32' ? base.toLowerCase() : base;
+  return left.startsWith(right.endsWith(path.sep) ? right : right + path.sep);
+}
+
+const FILE_LABELS = {
+  '.nvmrc': 'Node.js', '.node-version': 'Node.js', '.python-version': 'Python', 'package.json': 'package.json',
+  'pyproject.toml': 'Python', 'rust-toolchain.toml': 'Rust', 'rust-toolchain': 'Rust', 'go.mod': 'Go',
+  'global.json': '.NET SDK', '.tool-versions': '.tool-versions',
+};
+
+function readPin(file, realRoot) {
+  const name = path.basename(file);
+  const label = FILE_LABELS[name] || name;
+  let listed;
+  try { listed = fs.lstatSync(file); } catch (err) {
+    if (err.code === 'ENOENT') return { identity: { name, state: 'absent' } };
+    return { identity: { name, state: 'rejected' }, failure: pin(name, label, name, 'unreadable', null, 'The pin file could not be read.') };
+  }
+  let real = file;
+  if (listed.isSymbolicLink()) {
+    try { real = fs.realpathSync(file); } catch {
+      return { identity: { name, state: 'rejected' }, failure: pin(name, label, name, 'unreadable', null, 'The pin file could not be read.') };
+    }
+    if (!inside(real, realRoot)) {
+      return { identity: { name, state: 'rejected' }, failure: pin(name, label, name, 'unreadable', null, 'The pin is outside the project folder.') };
+    }
+  }
+  let stat;
+  try { stat = fs.statSync(real); } catch {
+    return { identity: { name, state: 'rejected' }, failure: pin(name, label, name, 'unreadable', null, 'The pin file could not be read.') };
+  }
+  if (!stat.isFile()) {
+    return { identity: { name, state: 'rejected' }, failure: pin(name, label, name, 'unreadable', null, 'The pin is not a file.') };
+  }
+  if (stat.size > PIN_LIMIT) {
+    return { identity: { name, state: 'file', mtimeMs: stat.mtimeMs, size: stat.size }, failure: pin(name, label, name, 'unreadable', null, 'The pin file is larger than 64 KiB.') };
+  }
+  return { identity: { name, state: 'file', mtimeMs: stat.mtimeMs, size: stat.size }, file: real };
+}
+
+/** Pins and file identity for one project folder. Does not change the process working directory. */
+export function scanPins(cwd, { identityOnly = false } = {}) {
+  if (typeof cwd !== 'string' || !path.isAbsolute(cwd)) return { error: 'Could not read the project pins.' };
+  let root;
+  try { root = fs.statSync(cwd); } catch { return { error: 'Could not read the project pins.' }; }
+  if (!root.isDirectory()) return { error: 'Could not read the project pins.' };
+  let realRoot;
+  try { realRoot = fs.realpathSync(cwd); } catch { return { error: 'Could not read the project pins.' }; }
+  const identity = [];
+  const pins = [];
+  for (const name of PIN_NAMES) {
+    const read = readPin(path.join(cwd, name), realRoot);
+    identity.push(read.identity);
+    if (identityOnly) continue;
+    if (read.failure) pins.push(read.failure);
+    else if (read.file) {
+      let text;
+      try { text = fs.readFileSync(read.file); } catch {
+        pins.push(pin(name, FILE_LABELS[name] || name, name, 'unreadable', null, 'The pin file could not be read.'));
+        continue;
+      }
+      if (text.length > PIN_LIMIT) {
+        pins.push(pin(name, FILE_LABELS[name] || name, name, 'unreadable', null, 'The pin file is larger than 64 KiB.'));
+        continue;
+      }
+      pins.push(...PARSERS[name](text.toString('utf8')));
+    }
+  }
+  return { identity: JSON.stringify(identity), ...(identityOnly ? {} : { pins }), cwd: process.cwd() };
+}
+
+/** A working folder for a project check. Empty input is refused and does not become the home directory. */
+export function resolveProjectCwd(cwd, { homedir = os.homedir, stat = fs.statSync } = {}) {
+  if (typeof cwd !== 'string' || !cwd.trim()) {
+    throw Object.assign(new Error('A working folder is required.'), { status: 400, code: 'cwd_required' });
+  }
+  let dir = cwd.trim();
+  if (dir === '~' || dir.startsWith('~/') || dir.startsWith('~\\')) dir = path.join(homedir(), dir.slice(1));
+  dir = path.resolve(dir);
+  let info;
+  try { info = stat(dir); } catch {
+    throw Object.assign(new Error(`working directory does not exist: ${dir}`), { status: 400, code: 'bad_cwd' });
+  }
+  if (!info.isDirectory()) throw Object.assign(new Error(`working directory is not a folder: ${dir}`), { status: 400, code: 'bad_cwd' });
+  return dir;
+}

package/src/manager/environment-probe.mjs

@@ -5,6 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { resolveCommand, killWindowsTree } from './command-resolver.mjs';
+import { scanPins } from './environment-pins.mjs';
 
 export const RUNTIMES = [
   { id: 'node', label: 'Node.js', command: 'node', args: ['--version'], pattern: /^v(\d+\.\d+\.\d+(?:-[\w.-]+)?)\s*$/m },
@@ -213,6 +214,16 @@ export async function releaseScanDirectory(cwd, kills = [], {
   } catch { /* a leftover lock must not fail the scan */ }
 }
 
+if ((process.argv[2] === '--scan-pins' || process.argv[2] === '--pin-identity') && process.send) {
+  // Read the named folder by absolute path. Never chdir into it: a project
+  // directory can activate tools on entry, and this check must not.
+  const started = process.cwd();
+  const result = scanPins(process.argv[3], { identityOnly: process.argv[2] === '--pin-identity' });
+  process.send({ ...result, cwd: process.cwd() });
+  if (process.cwd() !== started) process.chdir(started);
+  process.send({ done: true });
+}
+
 if (process.argv[2] === '--scan-environment' && process.send) {
   // A fresh temporary directory contains no project files. Manager env is
   // retained; no selected shell, project or session is inspected or changed.