@anhlp/alp 0.0.1-beta.3 → 0.0.1-beta.4

package/packages/cli/dist/usage.d.ts

@@ -1,3 +1,3 @@
-export const USAGE: "Usage:\n  alp <init|upgrade|update> [directory]\n  alp setup [directory] [--runtime codex|claude|mix] [--prefer claude|codex]\n            [--claude-model M] [--codex-model M] [--claude-supervisor M] [--codex-supervisor M]\n            [--claude-oracle M] [--codex-oracle M]   write Ph\u1EDF/Cafe's agent profiles to .alp/settings.json\n  alp daemon <start|stop|restart>\n  alp daemon status [--json]             liveness and readiness; exit 0 ready, 3 not running, 4 not ready\n  alp daemon <install|uninstall>         run alpd as a login service that restarts after a crash\n  alp acp                                serve ALP to an editor (Zed, JetBrains) over the Agent Client Protocol on stdio\n  alp web [--print]                      open the local web app alpd serves; --print only prints its address\n  alp web pair [--on|--off]              the link that pairs Paseo's app on another device through the relay; --on or --off turns the relay on or off\n  alp doctor [--project DIR] [--fix] [--json]   check this machine and project; --fix repairs what is safe to\n  alp backup [-o FILE] [--project DIR]... [--no-projects] [--stop] [--json]   sessions, settings, library and tasks in one file\n  alp backup verify <file> [--json] | alp backup list [--json]\n  alp restore <file> [--home-only] [--dry-run] [--stop] [--replace-newer] [--json]   checks the whole backup first; keeps what it replaces\n            alpd must be stopped for both; --stop stops it and starts it again after\n  alp run [--agent A] [--team pho|cafe|ID] [--model M] [--mode read-only|workspace-write|full-access] [--thinking T] [--project DIR] [--json] <prompt>\n  alp ps [--all]\n  alp top [session] [--once]\n  alp attach <session> [--json]\n  alp send <session> [--json] <text>\n  alp questions [--json]\n  alp answer <question> <text> | alp answer <question> --dismiss [--reason R]\n  alp log <session> [--json]\n  alp board [--project DIR] [--json]\n  alp <agents|skills|mcp|hooks> [--project DIR] [--json]   the library: built-in, ~/.alp and project entries\n  alp providers [--json]                    ACP and Antigravity providers in your library\n  alp teams [--project DIR] [--json]         teams sessions run in: members, delegation, house rules\n  alp agent <new|edit> <name> [--project [DIR]] [--from A] [-d text] [--provider P] [--model M] [--thinking T] [--mode M]\n            [--skills a,b] [--mcp a,b] [--hooks a,b] [--instructions FILE]\n  alp team <new|edit> <id> [--project [DIR]] [--from ID] [--label L] [-d text] [--main A] [--member name=role]...\n            [--member-model name=M]... [--member-thinking name=T]... [--delegate owner=a,b]... [--max-peers N]\n            [--supervisor A] [--supervisor-model M] [--supervisor-thinking T] [--no-supervisor] [--rules FILE]\n  alp skill new <name> [--project [DIR]] [--from S] [--file FILE]\n  alp mcp add <name> [--project [DIR]] (--command C [--arg A]... [--env K=V]... [--cwd D] | --url U [--header K=V]...)\n  alp hook add <name> [--project [DIR]] --event E --command C [--blocking] [--timeout SEC] [--match-agent A] [--match-label L]\n  alp provider add <id> --command C [--arg A]... [--env K=V]... [--label L] [-d text] [--models a,b]   an ACP agent; use id antigravity for native agy\n  alp provider edit antigravity --read-only-mode instructions|reject   opt into prompt-only read-only for advisory roles\n  alp <agent|team|skill|mcp|hook|provider> <rm|show> <name> [--project [DIR]] | <cp|mv> <from> <to> [--project [DIR]]\n  alp <mcp|hook|provider> test <name> [--project [DIR]]   list an MCP server's tools; run a hook once; initialize a provider\n            without --project, changes go to your library in ~/.alp; built-in agents and teams are never changed\n  alp trust [--project DIR] | --revoke [--project DIR] | --list [--json]   whether the project's hooks may run\n  alp permissions [--project DIR] [--json]   each agent's permission profile\n  alp permissions check <agent> \"<command>\"  what that agent's profile says about a command\n  alp tasks [ready] [--all] [--status S] [--label L] [--project DIR] [--json]\n  alp tasks gates [--json]                 open gates; checks GitHub ones\n  alp tasks compact [--days 30] [--dry-run]\n  alp tasks export [-o file.jsonl]          as beads JSONL\n  alp tasks import [file.jsonl] [--dry-run]  beads JSONL; default .beads/issues.jsonl\n  alp formula list | show <name> | pour <name> [--var k=v]... [--parent ID] [--dry-run]\n  alp task add <title> [-d text] [-p 0-4] [-t task|bug|feature|chore|epic] [--parent ID] [--after ID]... [-l label]... [--path P]... [--from ID]\n  alp task show <id> [--json]\n  alp task report <epic> [--json]           what an epic came to: tasks, time, rework, verification\n  alp task edit <id> [--title T] [-d text] [-p N] [-t type] [-l label]... [--path P]... [-m note]\n  alp task close <id> [--reason done|wontfix|duplicate|superseded] [-m summary] [--unverified \"why\"]\n  alp verify [--project DIR] [--task ID] [--json]   run the project's verify commands; --task records the result\n  alp task reopen <id> [-m note]\n  alp task dep <add|rm> <id> [--after ID]... [--parent ID] [--related ID]...\n  alp task gate add <id> --human \"question\" | --timer +2h|ISO | --pr N|owner/repo#N | --run N|owner/repo#N\n  alp task gate <clear|rm> <id> <gate> [-m note]\n  alp pause [codex|claude] [--now] [-m reason] | alp pause status   hold delegation; --now parks running assignments\n  alp resume [codex|claude]                  lift a pause; parked assignments continue\n  alp language [name | --reset]              the language agents and ALP write to you in; default Vietnamese\n  alp recall <assignment|task> [--project DIR] [--json] <question>   ask a finished assignment about its work\n  alp interrupt <session>";
+export const USAGE: "Usage:\n  alp <init|upgrade|update> [directory]\n  alp setup [directory] [--runtime codex|claude|mix] [--prefer claude|codex]\n            [--claude-model M] [--codex-model M] [--claude-supervisor M] [--codex-supervisor M]\n            [--claude-oracle M] [--codex-oracle M]   write Ph\u1EDF/Cafe's agent profiles to .alp/settings.json\n  alp daemon <start|stop|restart>\n  alp daemon status [--json]             liveness and readiness; exit 0 ready, 3 not running, 4 not ready\n  alp daemon <install|uninstall>         run alpd as a login service that restarts after a crash\n  alp acp                                serve ALP to an editor (Zed, JetBrains) over the Agent Client Protocol on stdio\n  alp web [--print]                      open the ALP web app on this machine (alp-web, loopback); --print only prints its address\n  alp web rotate                         give alp web a new token: open pages lose access; prints the new address\n  alp web pair [--on|--off]              the link that pairs Paseo's app on another device through the relay; --on or --off turns the relay on or off\n  alp terminal <allow [--paseo] --yes|deny [--paseo]|status> [--json]   remote terminals (a shell as you on this host; a workspace is not a sandbox), off by default\n  alp doctor [--project DIR] [--fix] [--json]   check this machine and project; --fix repairs what is safe to\n  alp backup [-o FILE] [--project DIR]... [--no-projects] [--stop] [--json]   sessions, settings, library and tasks in one file\n  alp backup verify <file> [--json] | alp backup list [--json]\n  alp restore <file> [--home-only] [--dry-run] [--stop] [--replace-newer] [--json]   checks the whole backup first; keeps what it replaces\n            alpd must be stopped for both; --stop stops it and starts it again after\n  alp run [--agent A] [--team pho|cafe|ID] [--model M] [--mode read-only|workspace-write|full-access] [--thinking T] [--project DIR] [--json] <prompt>\n  alp schedule create --session ID --at ISO_WITH_OFFSET --prompt TEXT [--project DIR] [--json]\n  alp schedule list [--status pending|delivered|failed|cancelled] [--project DIR] [--json]\n  alp schedule <show|cancel> ID [--project DIR] [--json]   one-shot wake; timer gates only unblock tasks\n  alp ps [--all]\n  alp top [session] [--once]\n  alp attach <session> [--json]\n  alp send <session> [--prompt] [--json] <text>\n            child default: user mail; --prompt: explicit new prompt to a live root or child\n  alp questions [--json]\n  alp answer <question> <text> | alp answer <question> --dismiss [--reason R]\n  alp log <session> [--json]\n  alp board [--project DIR] [--json]\n  alp <agents|skills|mcp|hooks> [--project DIR] [--json]   the library: built-in, ~/.alp and project entries\n  alp providers [--json]                    ACP and Antigravity providers in your library\n  alp teams [--project DIR] [--json]         teams sessions run in: members, delegation, house rules\n  alp agent <new|edit> <name> [--project [DIR]] [--from A] [-d text] [--provider P] [--model M] [--thinking T] [--mode M]\n            [--skills a,b] [--mcp a,b] [--hooks a,b] [--instructions FILE]\n  alp team <new|edit> <id> [--project [DIR]] [--from ID] [--label L] [-d text] [--main A] [--member name=role]...\n            [--member-model name=M]... [--member-thinking name=T]... [--delegate owner=a,b]... [--max-peers N]\n            [--supervisor A] [--supervisor-model M] [--supervisor-thinking T] [--no-supervisor] [--rules FILE]\n  alp skill new <name> [--project [DIR]] [--from S] [--file FILE]\n  alp mcp add <name> [--project [DIR]] (--command C [--arg A]... [--env K=V]... [--cwd D] | --url U [--header K=V]...)\n  alp hook add <name> [--project [DIR]] --event E --command C [--blocking] [--timeout SEC] [--match-agent A] [--match-label L]\n  alp provider add <id> --command C [--arg A]... [--env K=V]... [--label L] [-d text] [--models a,b]   an ACP agent; use id antigravity for native agy\n  alp provider edit antigravity --read-only-mode instructions|reject   opt into prompt-only read-only for advisory roles\n  alp <agent|team|skill|mcp|hook|provider> <rm|show> <name> [--project [DIR]] | <cp|mv> <from> <to> [--project [DIR]]\n  alp <mcp|hook|provider> test <name> [--project [DIR]]   list an MCP server's tools; run a hook once; initialize a provider\n            without --project, changes go to your library in ~/.alp; built-in agents and teams are never changed\n  alp trust [--project DIR] | --revoke [--project DIR] | --list [--json]   whether the project's hooks may run\n  alp permissions [--project DIR] [--json]   each agent's permission profile\n  alp permissions check <agent> \"<command>\"  what that agent's profile says about a command\n  alp tasks [ready] [--all] [--status S] [--label L] [--project DIR] [--json]\n  alp tasks gates [--json]                 open gates; checks GitHub ones\n  alp tasks compact [--days 30] [--dry-run]\n  alp tasks export [-o file.jsonl]          as beads JSONL\n  alp tasks import [file.jsonl] [--dry-run]  beads JSONL; default .beads/issues.jsonl\n  alp formula list | show <name> | pour <name> [--var k=v]... [--parent ID] [--dry-run]\n  alp task add <title> [-d text] [-p 0-4] [-t task|bug|feature|chore|epic] [--parent ID] [--after ID]... [-l label]... [--path P]... [--from ID]\n  alp task show <id> [--json]\n  alp task report <epic> [--json]           what an epic came to: tasks, time, rework, verification\n  alp task edit <id> [--title T] [-d text] [-p N] [-t type] [-l label]... [--path P]... [-m note]\n  alp task close <id> [--reason done|wontfix|duplicate|superseded] [-m summary] [--unverified \"why\"]\n  alp verify [--project DIR] [--task ID] [--json]   run the project's verify commands; --task records the result\n  alp task reopen <id> [-m note]\n  alp task dep <add|rm> <id> [--after ID]... [--parent ID] [--related ID]...\n  alp task gate add <id> --human \"question\" | --timer +2h|ISO | --pr N|owner/repo#N | --run N|owner/repo#N\n  alp task gate <clear|rm> <id> <gate> [-m note]\n  alp pause [codex|claude] [--now] [-m reason] | alp pause status   hold delegation; --now parks running assignments\n  alp resume [codex|claude]                  lift a pause; parked assignments continue\n  alp language [name | --reset]              the language agents and ALP write to you in; default Vietnamese\n  alp recall <assignment|task> [--project DIR] [--json] <question>   ask a finished assignment about its work\n  alp interrupt <session>";
 export class UsageError extends Error {
 }

package/packages/cli/dist/usage.js

@@ -8,18 +8,24 @@ var USAGE = `Usage:
   alp daemon status [--json]             liveness and readiness; exit 0 ready, 3 not running, 4 not ready
   alp daemon <install|uninstall>         run alpd as a login service that restarts after a crash
   alp acp                                serve ALP to an editor (Zed, JetBrains) over the Agent Client Protocol on stdio
-  alp web [--print]                      open the local web app alpd serves; --print only prints its address
+  alp web [--print]                      open the ALP web app on this machine (alp-web, loopback); --print only prints its address
+  alp web rotate                         give alp web a new token: open pages lose access; prints the new address
   alp web pair [--on|--off]              the link that pairs Paseo's app on another device through the relay; --on or --off turns the relay on or off
+  alp terminal <allow [--paseo] --yes|deny [--paseo]|status> [--json]   remote terminals (a shell as you on this host; a workspace is not a sandbox), off by default
   alp doctor [--project DIR] [--fix] [--json]   check this machine and project; --fix repairs what is safe to
   alp backup [-o FILE] [--project DIR]... [--no-projects] [--stop] [--json]   sessions, settings, library and tasks in one file
   alp backup verify <file> [--json] | alp backup list [--json]
   alp restore <file> [--home-only] [--dry-run] [--stop] [--replace-newer] [--json]   checks the whole backup first; keeps what it replaces
             alpd must be stopped for both; --stop stops it and starts it again after
   alp run [--agent A] [--team pho|cafe|ID] [--model M] [--mode read-only|workspace-write|full-access] [--thinking T] [--project DIR] [--json] <prompt>
+  alp schedule create --session ID --at ISO_WITH_OFFSET --prompt TEXT [--project DIR] [--json]
+  alp schedule list [--status pending|delivered|failed|cancelled] [--project DIR] [--json]
+  alp schedule <show|cancel> ID [--project DIR] [--json]   one-shot wake; timer gates only unblock tasks
   alp ps [--all]
   alp top [session] [--once]
   alp attach <session> [--json]
-  alp send <session> [--json] <text>
+  alp send <session> [--prompt] [--json] <text>
+            child default: user mail; --prompt: explicit new prompt to a live root or child
   alp questions [--json]
   alp answer <question> <text> | alp answer <question> --dismiss [--reason R]
   alp log <session> [--json]

package/packages/cli/dist/web-service.d.ts

@@ -0,0 +1,38 @@
+/** The alp-web service script beside this CLI; a clear error when this CLI was built without it. */
+export function alpWebEntry(): string;
+/**
+ * The process that owns alp web's lock, if it is proven safe to stop; else why not. `kind` says
+ * whether waiting can help: `transient` (an owner still starting has not published web.json yet),
+ * `foreign` (proven not to be the integration: another user's, another boot's, or a reused pid) or
+ * `unknown` (it cannot be proven either way, for example without ps or on Windows).
+ *
+ * The reuse proof compares the lock's wall-clock `startedAt` with the process's start from ps: a
+ * wall clock stepped back by more than two seconds after the lock was written could make a reused
+ * pid look older than the lock. A step forward only refuses.
+ * @param {string} home
+ * @returns {Promise<{ pid: number, app: unknown } | { reason: string, alive: boolean, kind?: 'transient' | 'foreign' | 'unknown' }>}
+ */
+export function webOwner(home: string): Promise<{
+    pid: number;
+    app: unknown;
+} | {
+    reason: string;
+    alive: boolean;
+    kind?: "transient" | "foreign" | "unknown";
+}>;
+/**
+ * Stops the Paseo integration from before its rename when it still runs as integration `web` (its
+ * web.json has no `app: 'alp-web'`), so alp-web can take the lock and web.port. Returns the pid it
+ * stopped. A process that cannot be proven to be that integration is left alone.
+ * @param {string} home
+ */
+export function stopPreRenamePaseo(home: string): Promise<number | undefined>;
+/**
+ * Stops whatever runs as integration `web` (alp-web, or the Paseo integration from before its
+ * rename), waiting up to `timeoutMs` for a starting owner to publish what proves it. Resolves once
+ * no live process owns the lock; refuses at once an owner that is foreign or cannot be proven.
+ * @param {string} home @param {number} [timeoutMs]
+ */
+export function stopWebService(home: string, timeoutMs?: number): Promise<number | undefined>;
+/** The opening of the message for a web lock held by a process alp would not stop. @param {string} home */
+export function refusal(home: string): string;

package/packages/cli/dist/web-service.js

@@ -0,0 +1,119 @@
+// packages/cli/src/web-service.js
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { bootTime, readLock } from "@anhlp/alp-client/index";
+import { distributionEntry } from "./paths.js";
+var execFileAsync = promisify(execFile);
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function alpWebEntry() {
+  const entry = fileURLToPath(distributionEntry("alp-web.js"));
+  if (!existsSync(entry)) throw new Error(`alp web is not built: ${entry} is missing. Build the CLI (npm run build in the ALP checkout) or reinstall ALP.`);
+  return entry;
+}
+var readJson = async (file) => JSON.parse(await readFile(file, "utf8"));
+async function processStart(pid) {
+  try {
+    const { stdout } = await execFileAsync("ps", ["-o", "etime=", "-p", String(pid)], { encoding: "utf8", timeout: 5e3 });
+    const match = /^\s*(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)\s*$/.exec(stdout);
+    if (!match) return void 0;
+    const [, days = "0", hours = "0", minutes, seconds] = match;
+    const elapsed = ((Number(days) * 24 + Number(hours)) * 60 + Number(minutes)) * 60 + Number(seconds);
+    return Date.now() - elapsed * 1e3;
+  } catch {
+    return void 0;
+  }
+}
+async function webOwner(home) {
+  const lockFile = path.join(home, "integrations", "web.lock");
+  const infoFile = path.join(home, "web.json");
+  let lock, lockInfo;
+  try {
+    lockInfo = await lstat(lockFile);
+    lock = await readJson(lockFile);
+  } catch {
+    return { reason: `${lockFile} is missing or unreadable`, alive: false };
+  }
+  if (!lockInfo.isFile() || !Number.isSafeInteger(lock?.pid) || lock.pid <= 0 || typeof lock.bootTime !== "number" || !Number.isFinite(Date.parse(lock.startedAt))) {
+    return { reason: `${lockFile} is not a complete integration lock`, alive: false };
+  }
+  const { pid } = lock;
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    if (error?.code === "ESRCH") return { reason: `its pid ${pid} has exited`, alive: false };
+    if (error?.code === "EPERM") return { reason: `pid ${pid} belongs to another user`, alive: true, kind: "foreign" };
+    return { reason: `pid ${pid} cannot be signalled (${error?.code ?? error})`, alive: true, kind: "unknown" };
+  }
+  const refuse = (reason, kind) => ({ reason, alive: true, kind });
+  if (process.platform === "win32") return refuse("alp does not stop it on Windows", "unknown");
+  const uid = process.getuid?.();
+  if (lockInfo.uid !== uid) return refuse("its lock is not yours", "foreign");
+  if (Math.abs(lock.bootTime - bootTime()) > 30) return refuse("its lock is from another boot", "foreign");
+  if (pid === process.pid || pid === (await readLock(home).catch(() => void 0))?.pid) return refuse(`pid ${pid} is not an integration`, "foreign");
+  const started = await processStart(pid);
+  if (started === void 0) return refuse(`the start time of pid ${pid} is unknown`, "unknown");
+  if (started > Date.parse(lock.startedAt) + 2e3) return refuse(`pid ${pid} started after the lock was written (a reused pid)`, "foreign");
+  let info, infoStat;
+  try {
+    infoStat = await lstat(infoFile);
+    info = await readJson(infoFile);
+  } catch {
+    return refuse(`${infoFile} is missing or unreadable`, "transient");
+  }
+  if (info?.pid !== pid) return refuse(`${infoFile} names another process than the lock`, "transient");
+  if (!infoStat.isFile() || infoStat.uid !== uid) return refuse(`${infoFile} is not yours`, "foreign");
+  return { pid, app: info.app };
+}
+async function terminate(pid, what, timeoutMs = 2e4) {
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (error) {
+    if (error?.code === "ESRCH") return;
+    throw error;
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      process.kill(pid, 0);
+    } catch (error) {
+      if (error?.code === "ESRCH") return;
+    }
+    await sleep(100);
+  }
+  throw new Error(`${what} (pid ${pid}) did not stop within ${timeoutMs / 1e3} s of SIGTERM; stop it, then run the command again`);
+}
+var isAlpWeb = (app) => app === "alp-web";
+var PASEO_BEFORE_RENAME = "The Paseo integration from before its rename";
+async function stopPreRenamePaseo(home) {
+  const owner = await webOwner(home);
+  if (!("pid" in owner) || isAlpWeb(owner.app)) return void 0;
+  await terminate(owner.pid, PASEO_BEFORE_RENAME);
+  return owner.pid;
+}
+async function stopWebService(home, timeoutMs = 3e4) {
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    const owner = await webOwner(home);
+    if ("pid" in owner) {
+      await terminate(owner.pid, isAlpWeb(owner.app) ? "alp web" : PASEO_BEFORE_RENAME);
+      return owner.pid;
+    }
+    if (!owner.alive) return void 0;
+    if (owner.kind !== "transient" || Date.now() >= deadline) throw new Error(`${refusal(home)} (${owner.reason}); stop it, then run the command again`);
+    await sleep(200);
+  }
+}
+function refusal(home) {
+  return `${path.join(home, "integrations", "web.lock")} is held by a process that alp cannot prove is alp web or the Paseo integration from before its rename, so it was left running`;
+}
+export {
+  alpWebEntry,
+  refusal,
+  stopPreRenamePaseo,
+  stopWebService,
+  webOwner
+};

package/packages/client/README.md

@@ -11,13 +11,18 @@ and setup helpers.
 - `@anhlp/alp-client` (Node): everything above plus `connect`, `AlpClient`, `connectSocket`,
   `ensureDaemon`, the private-socket checks and lock helpers, unchanged for existing callers.
 - `@anhlp/alp-client/ipc` (Node): `createSocketTransport` for a Unix socket or named pipe.
+- `@anhlp/alp-client/integration-lock` (Node): `createIntegrationLock(home, name)`, the single-owner
+  lock of one integration service at `<home>/integrations/<name>.lock`, serialized by the exclusive
+  guard directory `<name>.lock.reclaim`. Each instance is single-use (`acquire`, then `setReady` and
+  `release` while it owns the lock); its recovery rules are in
+  [docs/modular-monorepo.md](../../docs/modular-monorepo.md).
 
 Timeouts and aborts end only the caller's wait, and nothing is ever resent after a disconnect.
 See [docs/alp/client-sdk.md](../../docs/alp/client-sdk.md) for the transport contract, the
 request lifecycle, the old-to-new API table and what still waits on the protocol (Task 06) and
 the gateway (Task 08).
 
-`startIntegration` discovers an optional integration's descriptor and starts it detached with `--service`, so the entry writes its own log; discovery and the selected `ALP_HOME` are pinned by tests. Restarting is non-destructive: a daemon left running by an older install is reported as older than the current CLI and is never killed in place.
+`startIntegration({ name, entry, home, args })` (or `startIntegration(name)`; `name` defaults to `web`) discovers an optional integration's descriptor and starts it detached with `--service` and then `args`, so the entry writes its own log; discovery and the selected `ALP_HOME` are pinned by tests. `name` is a single lowercase path segment (`assertIntegrationName`). With `entry`, that script runs with the current Node and no descriptor, environment or PATH discovery happens; a missing entry is an error even when a live owner would be reused. `web` is alp-web, the service of the ALP CLI (`alp web`): it is never discovered, so it needs its `entry`, and `"web": { "enabled": false }` in the home's settings refuses it and no other integration. Everything once registered under `web` (`integrations/web.json`, the `alp-web-integration` binary, `ALP_WEB_INTEGRATION`) is the Paseo integration from before its rename; `discoverIntegration('paseo')` reads `ALP_PASEO_INTEGRATION`, then `ALP_WEB_INTEGRATION` for one release, then `ALP_INTEGRATION_ENTRY`. Errors name the integration, the entry and its log under `<home>/logs/integrations`. Either way a live owner of `integrations/<name>.lock` is reused, and the call resolves once that lock is ready and `<home>/<name>.json` names the same pid. Restarting is non-destructive: a daemon left running by an older install is reported as older than the current CLI and is never killed in place.
 
 Build: `npm run build --workspace=@anhlp/alp-client`. Test: `npm run test --workspace=@anhlp/alp-client`.
 

package/packages/client/dist/index.d.ts

@@ -21,6 +21,13 @@ export function findDaemonEntry({ home, env, candidates }?: {
     env?: NodeJS.ProcessEnv | undefined;
     candidates?: (string | undefined)[] | undefined;
 }): Promise<string | undefined>;
+/**
+ * Integration names are single lowercase path segments: they name `<home>/integrations/<name>.lock`,
+ * its guard and `<home>/<name>.json`. Returns the name, or throws a TypeError.
+ * @param {unknown} name
+ * @returns {string}
+ */
+export function assertIntegrationName(name: unknown): string;
 /** Wall-clock boot time; a lock from an earlier boot is stale even if its pid is reused. */
 export function bootTime(): number;
 export function readLock(home: any): Promise<any>;
@@ -95,8 +102,34 @@ export function ensureDaemon({ home, entry, env, execPath, timeoutMs, lifecycleL
     timeoutMs?: number | undefined;
     lifecycleLocked?: boolean | undefined;
 }): Promise<any>;
-export function discoverIntegration(name?: string, options?: {}): Promise<string | undefined>;
-export function startIntegration(nameOrOptions?: string): Promise<any>;
+/**
+ * The entry of integration `name`: an environment override, a descriptor under the home or a
+ * distribution root, or an `alp-<name>-integration` binary. Discovery never returns an entry for
+ * `web`: that name belongs to alp-web, which ships with the CLI and is started with its explicit
+ * entry. Everything once registered under `web` (the descriptor `integrations/web.json`, the
+ * `alp-web-integration` binary, `ALP_WEB_INTEGRATION`) is the Paseo integration from before its
+ * rename to `paseo`, which must never run under the web lock. `ALP_WEB_INTEGRATION` is read for
+ * `paseo` only, after `ALP_PASEO_INTEGRATION`, for one release (like the alp-web-integration alias).
+ * @param {string} [name]
+ * @param {{ home?: string }} [options]
+ */
+export function discoverIntegration(name?: string, options?: {
+    home?: string;
+}): Promise<string | undefined>;
+/**
+ * Starts integration `name` (default `web`) detached with `--service` (then `args`) unless its lock
+ * already names a live owner, then waits until its ready lock and `<home>/<name>.json` name the same
+ * pid. `entry` names the script to run with this Node and skips descriptor, environment and PATH
+ * discovery; `web` (alp-web) is never discovered, so it needs its entry. `"web": { "enabled": false }`
+ * in the home's settings.json refuses `web` only.
+ * @param {string | { name?: string, entry?: string, home?: string, args?: string[] }} [nameOrOptions]
+ */
+export function startIntegration(nameOrOptions?: string | {
+    name?: string;
+    entry?: string;
+    home?: string;
+    args?: string[];
+}): Promise<any>;
 export * from "./portable.js";
 export { createSocketTransport } from "./ipc.js";
 /**
@@ -110,6 +143,8 @@ export class AlpClient extends AlpRpcClient {
      * @param {import('./rpc/client.js').AlpRpcClientOptions & import('./ipc.js').SocketTransportOptions} [options]
      */
     constructor(socket: import("node:net").Socket, { maxFrame, maxBufferedBytes, ...options }?: import("./rpc/client.js").AlpRpcClientOptions & import("./ipc.js").SocketTransportOptions);
+    /** Host features captured by connect's handshake. @type {readonly string[]} */
+    capabilities: readonly string[];
 }
 import { AlpRpcClient } from './rpc/client.js';
 export { PROTOCOL_VERSION, MAX_FRAME, AlpRpcError, encodeFrame } from "@anhlp/alp-protocol";

package/packages/client/dist/index.js

@@ -98,6 +98,10 @@ async function findDaemonEntry({ home = alpHome(), env = process.env, candidates
   }
   return void 0;
 }
+function assertIntegrationName(name) {
+  if (typeof name !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(name)) throw new TypeError(`Invalid integration name: ${JSON.stringify(name)}`);
+  return name;
+}
 function bootTime() {
   return Math.round((Date.now() - os.uptime() * 1e3) / 1e3);
 }
@@ -144,6 +148,8 @@ async function releaseDaemonLock(home) {
   });
 }
 var AlpClient = class extends AlpRpcClient {
+  /** Host features captured by connect's handshake. @type {readonly string[]} */
+  capabilities = [];
   /**
    * @param {import('node:net').Socket} socket a connected or connecting socket; the client owns it
    * @param {import('./rpc/client.js').AlpRpcClientOptions & import('./ipc.js').SocketTransportOptions} [options]
@@ -172,7 +178,8 @@ async function connectSocket(socketPath, options) {
 async function connect(socketPath, client = { name: "alp", version: "0" }, options = {}) {
   const connection = new AlpClient(await openSocket(socketPath), options);
   try {
-    await hello(connection, client);
+    const greeting = await hello(connection, client);
+    connection.capabilities = Object.freeze(Array.isArray(greeting.capabilities) ? greeting.capabilities.filter((value) => typeof value === "string") : []);
   } catch (error) {
     connection.close();
     throw error;
@@ -346,7 +353,7 @@ async function integrationCandidateFromHome(home, name) {
   return await isFile(legacy) ? legacy : void 0;
 }
 function integrationBinaryName(name) {
-  return name === "web" ? "alp-web-integration" : `alp-${name}-integration`;
+  return `alp-${name}-integration`;
 }
 async function distributionRoots() {
   const roots = [];
@@ -366,10 +373,12 @@ async function distributionRoots() {
   return [...new Set(roots)];
 }
 async function discoverIntegration(name = "web", options = {}) {
+  assertIntegrationName(name);
+  if (name === "web") return void 0;
   const envCandidates = [
-    process.env.ALP_WEB_INTEGRATION,
-    process.env.ALP_INTEGRATION_ENTRY,
-    name !== "web" ? process.env[`ALP_${name.toUpperCase()}_INTEGRATION`] : void 0
+    process.env[`ALP_${name.toUpperCase()}_INTEGRATION`],
+    name === "paseo" ? process.env.ALP_WEB_INTEGRATION : void 0,
+    process.env.ALP_INTEGRATION_ENTRY
   ].filter(Boolean);
   for (const candidate of envCandidates) if (await isFile(candidate)) return candidate;
   const home = options?.home ? path.resolve(options.home) : alpHome();
@@ -398,21 +407,46 @@ function integrationAlive(lock) {
   if (typeof lock.bootTime === "number" && Math.abs(lock.bootTime - bootTime()) > 30) return false;
   return true;
 }
+function integrationText(name, home) {
+  const logs = path.join(home, "logs", "integrations");
+  if (name === "web") return {
+    what: "alp web",
+    log: path.join(logs, "alp-web.log"),
+    missing: "alp web runs the alp-web service of the ALP CLI, which is started with its entry (packages/cli/dist/alp-web.js); run `alp web`"
+  };
+  if (name === "paseo") return {
+    what: "The Paseo integration",
+    log: path.join(logs, "paseo.log"),
+    missing: "The Paseo integration is an optional integration package. Install it (for example `npm install -g @anhlp/alp-paseo@beta`), then run the command again."
+  };
+  return {
+    what: `ALP integration ${name}`,
+    log: path.join(logs, `${name}.log`),
+    missing: `ALP integration ${name} is not installed: no ALP_${name.toUpperCase()}_INTEGRATION, descriptor <home>/integrations/${name}.json or alp-${name}-integration binary was found.`
+  };
+}
 async function startIntegration(nameOrOptions = "web") {
   const options = typeof nameOrOptions === "string" ? { name: nameOrOptions } : nameOrOptions ?? {};
-  const name = options.name ?? "web";
+  const name = assertIntegrationName(options.name ?? "web");
+  if (options.entry !== void 0 && (typeof options.entry !== "string" || !options.entry)) throw new TypeError("startIntegration entry must be a non-empty path");
+  const args = options.args ?? [];
+  if (!Array.isArray(args) || !args.every((arg) => typeof arg === "string")) throw new TypeError("startIntegration args must be a list of strings");
   const fs = await import("node:fs/promises");
   const pathMod = await import("node:path");
   const home = options.home ? pathMod.resolve(options.home) : alpHome();
+  const text = integrationText(name, home);
+  const explicit = options.entry !== void 0 ? pathMod.resolve(options.entry) : void 0;
+  if (explicit !== void 0 && !await isFile(explicit)) throw new Error(`${text.what}: integration entry not found: ${explicit}`);
   const lockPath = pathMod.join(home, "integrations", `${name}.lock`);
   const webPath = pathMod.join(home, `${name}.json`);
-  let settings = {};
-  try {
-    settings = JSON.parse(await fs.readFile(pathMod.join(home, "settings.json"), "utf8"));
-  } catch {
-  }
-  if (settings?.web?.enabled === false) {
-    throw new Error('ALP web app is disabled by settings ("web.enabled": false).');
+  const started = explicit ? ` (entry ${explicit})` : "";
+  if (name === "web") {
+    let settings = {};
+    try {
+      settings = JSON.parse(await fs.readFile(pathMod.join(home, "settings.json"), "utf8"));
+    } catch {
+    }
+    if (settings?.web?.enabled === false) throw new Error('alp web is disabled by settings ("web.enabled": false).');
   }
   const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
   const readLock2 = async () => {
@@ -440,20 +474,18 @@ async function startIntegration(nameOrOptions = "web") {
       await sleep(100);
     }
     const lock = await readLock2();
-    if (lock && !lock.ready) throw new Error("ALP web integration started but did not become ready; see ~/.alp/logs/integrations/paseo.log");
-    if (!lock) throw new Error("ALP web app is provided by an optional integration package. Install it (for example `npm install -g @anhlp/alp-paseo@beta`) and run `alp web` again.");
-    throw new Error("ALP web integration did not publish a matching web.json lock");
+    if (lock && !lock.ready) throw new Error(`${text.what}${started} started but did not become ready; see ${text.log}`);
+    if (!lock) throw new Error(explicit ? `${text.what}${started} did not start; see ${text.log}` : text.missing);
+    throw new Error(`${text.what}${started} did not publish a ${name}.json matching its lock; see ${text.log}`);
   }
   const existing = await readLock2();
   if (existing && integrationAlive(existing)) {
     return waitForReady();
   }
-  const entry = await discoverIntegration(name, { home });
-  if (!entry) {
-    throw new Error("ALP web app is provided by an optional integration package. Install it (for example `npm install -g @anhlp/alp-paseo@beta`) and run `alp web` again.");
-  }
+  const entry = explicit ?? await discoverIntegration(name, { home });
+  if (!entry) throw new Error(text.missing);
   const { spawn: spawn2 } = await import("node:child_process");
-  const child = spawn2(process.execPath, [entry, "--service"], { stdio: "ignore", detached: true, env: { ...process.env, ALP_HOME: home } });
+  const child = spawn2(process.execPath, [entry, "--service", ...args], { stdio: "ignore", detached: true, env: { ...process.env, ALP_HOME: home } });
   let spawnError = null;
   child.on("error", (error) => {
     spawnError = error;
@@ -466,7 +498,7 @@ async function startIntegration(nameOrOptions = "web") {
   if (spawnError) throw spawnError;
   await sleep(150);
   if (spawnError) throw spawnError;
-  if (exited) throw new Error("ALP web integration failed to start; see ~/.alp/logs/integrations/paseo.log");
+  if (exited) throw new Error(`${text.what}${explicit ? started : ` (${entry})`} failed to start; see ${text.log}`);
   return waitForReady();
 }
 export {
@@ -477,6 +509,7 @@ export {
   PROTOCOL_VERSION,
   acquireDaemonLock,
   alpHome,
+  assertIntegrationName,
   assertPrivateDirectory,
   assertPrivateSocket,
   bootTime,

package/packages/client/dist/integration-lock.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @typedef {{ pid: number, bootTime: number, startedAt: string, ready: boolean, lockVersion?: number, owner?: string }} IntegrationLockRecord
+ * @typedef {{
+ *   acquire(): Promise<{ acquired: boolean, lock: IntegrationLockRecord }>,
+ *   setReady(ready: boolean): Promise<boolean>,
+ *   release(): Promise<boolean>,
+ * }} IntegrationLock
+ */
+/**
+ * The single-owner lock of one integration service, at `<home>/integrations/<name>.lock`, with its
+ * mutation guard `<name>.lock.reclaim`. Each instance is single-use: acquire once, then setReady and
+ * release while it owns the lock.
+ *
+ * Single-host, same PID namespace, private local filesystem only. Never reap the mutation guard.
+ * @param {string} home the ALP_HOME the integration runs under
+ * @param {string} name the integration name, for example `web`
+ * @returns {IntegrationLock}
+ */
+export function createIntegrationLock(home: string, name: string): IntegrationLock;
+export type IntegrationLockRecord = {
+    pid: number;
+    bootTime: number;
+    startedAt: string;
+    ready: boolean;
+    lockVersion?: number;
+    owner?: string;
+};
+export type IntegrationLock = {
+    acquire(): Promise<{
+        acquired: boolean;
+        lock: IntegrationLockRecord;
+    }>;
+    setReady(ready: boolean): Promise<boolean>;
+    release(): Promise<boolean>;
+};