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

package/dist/backup.js

@@ -13,10 +13,15 @@ import { STATE_SCHEMA, assertStateSupported, readStateSchema } from "./state-sch
 import { withTaskLock } from "./tasks.js";
 var BACKUP_FORMAT = 1;
 var BACKUP_EXTENSION = ".alpbackup";
-var STATE_UNITS = ["state/schema.json", "state/sessions", "state/timeline", "state/receipts", "state/recall.json", "state/pause.json", "state/trust.json", "state/web-workspaces.json"];
+var RESULT_LEDGER = "state/assignment-results.json";
+var RESULT_MARKER = `${RESULT_LEDGER}.initialized`;
+var DESTINATIONS = "worktree-destinations.json";
+var QUARANTINED_DESTINATIONS = "state/worktree-destinations.quarantined.json";
+var STATE_UNITS = [RESULT_LEDGER, RESULT_MARKER, "state/schema.json", "state/sessions", "state/timeline", "state/receipts", "state/recall.json", "state/pause.json", "state/trust.json", "state/web-workspaces.json"];
 var CLEARED_UNITS = ["state/live.json", "state/migration.json"];
 var HOME_UNITS = [
   ...STATE_UNITS,
+  DESTINATIONS,
   "settings.json",
   "library.json",
   "role-skills.json",
@@ -378,6 +383,98 @@ async function holdTaskLocks(roots, work) {
     clearInterval(touch);
   }
 }
+async function prepareWorkspaceRestore(home, root, units, warnings) {
+  const relevant = [RESULT_LEDGER, RESULT_MARKER, DESTINATIONS, "state/sessions", "state/web-workspaces.json"];
+  const restorable = units.filter((unit) => unit.path !== QUARANTINED_DESTINATIONS);
+  if (!units.some((unit) => relevant.includes(unit.path))) return restorable;
+  for (const base of [home, root]) {
+    const info = await lstat(path.join(base, "state")).catch((error) => {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    if (info && !info.isDirectory()) throw invalid("workspace state must be a real directory");
+  }
+  const result = restorable.filter((unit) => ![RESULT_LEDGER, RESULT_MARKER, DESTINATIONS, "state/web-workspaces.json"].includes(unit.path));
+  async function regular(base, unit, declared) {
+    if (declared && declared.kind === "absent") return void 0;
+    const file = path.join(base, unit);
+    const info = await lstat(file).catch((error) => {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    if (!info) {
+      if (declared) throw invalid(`${unit} is declared but missing from the backup`);
+      return void 0;
+    }
+    if (!info.isFile()) throw invalid(`${unit} must be a regular file for a workspace restore`);
+    return readFile(file, "utf8");
+  }
+  const incoming = async (unit) => {
+    const declared = units.find((entry) => entry.path === unit);
+    return declared ? regular(root, unit, declared) : void 0;
+  };
+  const owners = /* @__PURE__ */ new Map();
+  let hasLedger = false;
+  for (const text of [await incoming(RESULT_LEDGER), await regular(home, RESULT_LEDGER)]) {
+    if (text === void 0) continue;
+    let value;
+    try {
+      value = JSON.parse(text);
+    } catch {
+      throw invalid("assignment result ledger is not readable JSON; repair it before restoring");
+    }
+    const absolute = (value2) => typeof value2 === "string" && path.isAbsolute(value2);
+    if (value?.version !== 1 || !Array.isArray(value.workspaces) || !value.workspaces.every(absolute) || !Array.isArray(value.results) || !value.results.every((entry) => entry && typeof entry.assignmentId === "string" && absolute(entry.checkout) && (entry.worktree === void 0 || absolute(entry.worktree))))
+      throw invalid("assignment result ledger has an unsupported or invalid shape");
+    hasLedger = true;
+    for (const entry of value.results) {
+      const owner = { assignmentId: entry.assignmentId, checkout: entry.checkout, ...entry.worktree === void 0 ? {} : { worktree: entry.worktree } };
+      const previous = owners.get(owner.assignmentId);
+      if (previous && JSON.stringify(previous) !== JSON.stringify(owner)) throw invalid("assignment result ownership conflicts with current data; reconcile it before restoring");
+      owners.set(owner.assignmentId, owner);
+    }
+  }
+  const markers = [await incoming(RESULT_MARKER), await regular(home, RESULT_MARKER)];
+  if (markers.some((text) => text !== void 0 && text !== "1\n")) throw invalid("assignment result initialized marker is invalid");
+  await mkdir(path.join(root, "state"), { recursive: true, mode: 448 });
+  if (hasLedger) await writeAtomic(path.join(root, RESULT_LEDGER), JSON.stringify({ version: 1, workspaces: [], results: [...owners.values()] }) + "\n");
+  result.push({ path: RESULT_LEDGER, kind: hasLedger ? "file" : "absent" });
+  const initialized = markers.some((text) => text !== void 0);
+  if (initialized) await writeAtomic(path.join(root, RESULT_MARKER), "1\n");
+  result.push({ path: RESULT_MARKER, kind: initialized ? "file" : "absent" });
+  const mappings = await incoming(DESTINATIONS);
+  if (mappings !== void 0) {
+    await writeAtomic(path.join(root, QUARANTINED_DESTINATIONS), mappings);
+    result.push({ path: QUARANTINED_DESTINATIONS, kind: "file" });
+  }
+  result.push({ path: DESTINATIONS, kind: "absent" });
+  const registryUnit = "state/web-workspaces.json";
+  const registryDeclaration = units.find((unit) => unit.path === registryUnit);
+  const registryText = registryDeclaration ? await incoming(registryUnit) : await regular(home, registryUnit);
+  if (registryText !== void 0) {
+    let registry;
+    try {
+      registry = JSON.parse(registryText);
+    } catch {
+      throw invalid("workspace registry is not readable JSON; repair it before restoring");
+    }
+    const epoch = `restore-${randomBytes(16).toString("hex")}`;
+    let revoked = false;
+    const revoke = (value) => {
+      if (!value || typeof value !== "object") return;
+      if (Object.hasOwn(value, "grantEpoch")) {
+        value.grantEpoch = epoch;
+        revoked = true;
+      }
+      for (const child of Object.values(value)) revoke(child);
+    };
+    revoke(registry);
+    await writeAtomic(path.join(root, registryUnit), revoked ? JSON.stringify(registry) + "\n" : registryText);
+    result.push({ path: registryUnit, kind: "file" });
+  } else if (registryDeclaration) result.push({ path: registryUnit, kind: "absent" });
+  if (hasLedger || initialized || mappings !== void 0 || await exists(path.join(home, DESTINATIONS))) warnings.push("Workspace restore retains assignment owners but clears checkout birth certification; old targets require an audited migration. Worktree destination mappings are inactive and require explicit host approval; archived mapping evidence is in state/worktree-destinations.quarantined.json. Historical checkout grants remain revoked after reapproval.");
+  return result;
+}
 async function restoreBackup({ home, file, projects = true, safety = true, clearLive = true, replaceNewer = false, by = "alp", beforeSwap }) {
   const interrupted = await recoverInterruptedRestore(home);
   try {
@@ -392,6 +489,7 @@ async function restoreBackup({ home, file, projects = true, safety = true, clear
   const warnings = [];
   const areaBase = (area) => area === "home" ? home : header.projects[Number(area.slice(8))].root;
   const directories = [];
+  let homeUnits;
   const journal = { version: 1, id, file: path.resolve(file), by, startedAt: (/* @__PURE__ */ new Date()).toISOString(), phase: "staging", units: [], staging: [], created: [], locks: [] };
   const record = () => writeAtomic(journalFile(home), JSON.stringify(journal) + "\n");
   const abandon = async () => {
@@ -443,6 +541,7 @@ async function restoreBackup({ home, file, projects = true, safety = true, clear
         };
       }
     });
+    homeUnits = await prepareWorkspaceRestore(home, staging.get("home"), header.units, warnings);
     for (const [directory, mode] of directories.reverse()) if (Number.isSafeInteger(mode)) await chmod(directory, mode & 511 | 448).catch(() => {
     });
   } catch (error) {
@@ -463,8 +562,8 @@ async function restoreBackup({ home, file, projects = true, safety = true, clear
   const plan = [];
   for (const [area, root] of staging) {
     const base = areaBase(area);
-    const units = area === "home" ? header.units : header.projects[Number(area.slice(8))].units;
-    const known = area === "home" ? HOME_UNITS : PROJECT_UNITS;
+    const units = area === "home" ? homeUnits : header.projects[Number(area.slice(8))].units;
+    const known = area === "home" ? [...HOME_UNITS, QUARANTINED_DESTINATIONS] : PROJECT_UNITS;
     for (const unit of units) {
       if (!known.includes(unit.path)) {
         warnings.push(`${unit.path} is not a unit this ALP restores; left as it is`);
@@ -489,7 +588,7 @@ async function restoreBackup({ home, file, projects = true, safety = true, clear
   let safetyFile;
   if (safety) {
     try {
-      safetyFile = await automaticBackup(home, "pre-restore", { units: header.units.map((unit) => unit.path).filter((unit) => HOME_UNITS.includes(unit)), projects: roots, by });
+      safetyFile = await automaticBackup(home, "pre-restore", { units: [.../* @__PURE__ */ new Set([...header.units.map((unit) => unit.path), ...homeUnits.map((unit) => unit.path)])].filter((unit) => HOME_UNITS.includes(unit) || unit === QUARANTINED_DESTINATIONS), projects: roots, by });
     } catch (error) {
       await abandon();
       throw new AlpError("RESTORE_SAFETY_BACKUP_FAILED", `could not save the current data before restoring (${error?.message ?? error}); nothing was changed`, { cause: error });

package/dist/index.d.ts

@@ -28,3 +28,4 @@ export * as user_settings from "./user-settings.js";
 export * as validation from "./validation.js";
 export * as verify from "./verify.js";
 export * as workflow from "./workflow.js";
+export * as user_worktree from "./user-worktree.js";

package/dist/index.js

@@ -29,6 +29,7 @@ import * as user_settings from "./user-settings.js";
 import * as validation from "./validation.js";
 import * as verify from "./verify.js";
 import * as workflow from "./workflow.js";
+import * as user_worktree from "./user-worktree.js";
 export {
   adapter,
   atomic,
@@ -57,6 +58,7 @@ export {
   trust,
   upgrade,
   user_settings,
+  user_worktree,
   validation,
   verify,
   workflow

package/dist/migrations.js

@@ -78,7 +78,7 @@ async function migrateState(home, { by = "alp", migrations = MIGRATIONS, target
         throw new AlpError("STATE_MIGRATION_ROLLBACK_FAILED", `state migration ${step.name} failed (${error?.message ?? error}) and putting the state back from ${backup} failed too (${rollback?.message ?? rollback}); the next start tries the migration again. See docs/alp/data-recovery.md`, { cause: error });
       }
       await rm(migrationFile(home), { force: true });
-      throw new AlpError("STATE_MIGRATION_FAILED", `state migration ${step.name} (schema ${step.from} \u2192 ${step.to}) failed: ${error?.message ?? error}; the state was put back from ${backup} and is unchanged. See docs/alp/data-recovery.md`, { cause: error });
+      throw new AlpError("STATE_MIGRATION_FAILED", `state migration ${step.name} (schema ${step.from} \u2192 ${step.to}) failed: ${error?.message ?? error}; data was restored from ${backup} with workspace authority checks. See docs/alp/data-recovery.md`, { cause: error });
     }
     await writeStateSchema(home, step.to, by);
     await rm(migrationFile(home), { force: true });

package/dist/user-worktree.d.ts

@@ -0,0 +1,29 @@
+export function repositoryIdentity(directory: any): Promise<{
+    gitDir: string;
+    commonDir: string;
+    branch: string | null;
+}>;
+/** User workspace primitives. Assignment cleanup's force/rm semantics must never be used here. */
+export function userWorktreeGit({ executable, timeoutMs, maxBytes }?: {
+    executable?: string | undefined;
+    timeoutMs?: number | undefined;
+    maxBytes?: number | undefined;
+}): {
+    facts: (source: any) => Promise<{
+        commonDir: string;
+        gitDir: string;
+        head: any;
+        branch: any;
+    }>;
+    inspect: (source: any, target: any, branch: any) => Promise<any>;
+    assertClean: (target: any) => Promise<void>;
+    checkoutFacts(directory: any): Promise<{
+        isGit: true;
+        repoRoot: any;
+        currentBranch: any;
+        remoteUrl: any;
+        isDirty: boolean;
+    }>;
+    create(source: any, parent: any, name: any, branch: any, head: any): Promise<string>;
+    remove(source: any, target: any, branch: any): Promise<void>;
+};

package/dist/user-worktree.js

@@ -0,0 +1,242 @@
+// packages/core/src/user-worktree.js
+import { spawn } from "node:child_process";
+import { lstat, realpath, open } from "node:fs/promises";
+import path from "node:path";
+import { constants } from "node:fs";
+async function control(file) {
+  const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.nlink !== 1 || info.size > 4096) throw new Error("Invalid Git administrative file");
+    const bytes = Buffer.alloc(4097);
+    const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+    if (bytesRead > 4096) throw new Error("Git administrative file exceeds limit");
+    return bytes.subarray(0, bytesRead).toString("utf8").replace(/\r?\n$/, "");
+  } finally {
+    await handle.close();
+  }
+}
+async function repositoryIdentity(directory) {
+  if (await realpath(directory) !== directory) throw new Error("Repository root is not canonical");
+  const entry = path.join(directory, ".git");
+  const info = await lstat(entry);
+  let gitDir;
+  if (info.isDirectory()) gitDir = await realpath(entry);
+  else {
+    const value = await control(entry);
+    if (!value.startsWith("gitdir: ") || /[\r\n\0]/.test(value)) throw new Error("Invalid Git control link");
+    gitDir = await realpath(path.resolve(directory, value.slice(8)));
+  }
+  const commonEntry = path.join(gitDir, "commondir");
+  const hasCommon = await lstat(commonEntry).catch((error) => {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  });
+  const commonDir = hasCommon ? await realpath(path.resolve(gitDir, await control(commonEntry))) : gitDir;
+  if (gitDir !== commonDir) {
+    if (path.dirname(gitDir) !== path.join(commonDir, "worktrees") || path.resolve(gitDir, await control(path.join(gitDir, "gitdir"))) !== entry)
+      throw new Error("Git worktree backlink changed");
+  }
+  const head = await control(path.join(gitDir, "HEAD"));
+  const branch = head.startsWith("ref: refs/heads/") ? head.slice(16) : null;
+  if (branch !== null && (!branch || /[\r\n\0]/.test(branch))) throw new Error("Invalid branch reference");
+  return { gitDir, commonDir, branch };
+}
+function userWorktreeGit({ executable = "/usr/bin/git", timeoutMs = 15e3, maxBytes = 2 * 1024 * 1024 } = {}) {
+  if (process.platform === "win32") throw new Error("User worktree operations are unavailable on this host");
+  if (!path.isAbsolute(executable)) throw new Error("Git executable must be host configured and absolute");
+  const disabled = [
+    "-c",
+    "core.hooksPath=/dev/null",
+    "-c",
+    "core.fsmonitor=false",
+    "-c",
+    "core.untrackedCache=false",
+    "-c",
+    "core.pager=cat",
+    "-c",
+    "maintenance.auto=false",
+    "-c",
+    "gc.auto=0",
+    "-c",
+    "protocol.allow=never",
+    "-c",
+    "submodule.recurse=false"
+  ];
+  const env = {
+    PATH: "/usr/bin:/bin",
+    GIT_CONFIG_NOSYSTEM: "1",
+    GIT_CONFIG_GLOBAL: "/dev/null",
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_OPTIONAL_LOCKS: "0",
+    LANG: "C",
+    LC_ALL: "C"
+  };
+  async function raw(cwd, args, extra = []) {
+    return new Promise((resolve, reject) => {
+      const child = spawn(executable, [...disabled, ...extra, ...args], {
+        cwd,
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        detached: true
+      });
+      let size = 0;
+      let overflow = false;
+      const stdout = [];
+      const stderr = [];
+      const kill = () => {
+        try {
+          process.kill(-child.pid, "SIGKILL");
+        } catch {
+          child.kill("SIGKILL");
+        }
+      };
+      const timer = setTimeout(() => {
+        overflow = true;
+        kill();
+      }, timeoutMs);
+      const collect = (sink) => (chunk) => {
+        size += chunk.length;
+        if (size > maxBytes) {
+          overflow = true;
+          kill();
+        } else sink.push(chunk);
+      };
+      child.stdout.on("data", collect(stdout));
+      child.stderr.on("data", collect(stderr));
+      child.once("error", (error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+      child.once("close", (code) => {
+        clearTimeout(timer);
+        if (overflow) reject(new Error("Git operation exceeded its host limit"));
+        else
+          resolve({
+            code,
+            stdout: Buffer.concat(stdout).toString("utf8"),
+            stderr: Buffer.concat(stderr).toString("utf8")
+          });
+      });
+    });
+  }
+  async function filterOverrides(cwd) {
+    const filters = await raw(cwd, [
+      "config",
+      "--null",
+      "--name-only",
+      "--get-regexp",
+      "^filter\\..*\\.(smudge|clean|process|required)$"
+    ]);
+    if (filters.code !== 0 && filters.code !== 1) throw new Error("Cannot inspect repository filters");
+    const neutral = filters.stdout.split("\0").filter(Boolean).flatMap((key) => ["-c", `${key}=${key.endsWith(".required") ? "false" : ""}`]);
+    return neutral;
+  }
+  async function run(cwd, args, extra = []) {
+    return raw(cwd, args, [...await filterOverrides(cwd), ...extra]);
+  }
+  async function checked(cwd, args, extra = []) {
+    const result = await run(cwd, args, extra);
+    if (result.code !== 0) throw new Error("Git workspace operation refused");
+    return result.stdout.trim();
+  }
+  async function directory(value) {
+    const canonical = await realpath(value);
+    if (canonical !== value || !(await lstat(value)).isDirectory())
+      throw new Error("Workspace paths must be canonical directories");
+    return canonical;
+  }
+  async function facts(source) {
+    await directory(source);
+    const top = await checked(source, ["rev-parse", "--show-toplevel"]);
+    if (await realpath(top) !== source) throw new Error("Workspace must be a repository top level");
+    const commonDir = await realpath(
+      await checked(source, ["rev-parse", "--path-format=absolute", "--git-common-dir"])
+    );
+    const identity = await repositoryIdentity(source);
+    if (identity.commonDir !== commonDir) throw new Error("Repository identity changed");
+    const head = await checked(source, ["rev-parse", "--verify", "HEAD"]);
+    const branch = await run(source, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    return { commonDir, gitDir: identity.gitDir, head, branch: branch.code === 0 ? branch.stdout.trim() : null };
+  }
+  async function list(source) {
+    const result = await checked(source, ["worktree", "list", "--porcelain", "-z"]);
+    return result.split("\0\0").filter(Boolean).map(
+      (block) => Object.fromEntries(
+        block.split("\0").filter(Boolean).map((line) => {
+          const i = line.indexOf(" ");
+          return i < 0 ? [line, true] : [line.slice(0, i), line.slice(i + 1)];
+        })
+      )
+    );
+  }
+  async function inspect(source, target, branch) {
+    const row = (await list(source)).find((row2) => row2.worktree === target);
+    if (!row) return void 0;
+    await directory(target);
+    if (row.branch !== `refs/heads/${branch}` || row.locked || row.prunable)
+      throw new Error("Managed worktree identity changed");
+    const origin = await facts(source);
+    const destination = await facts(target);
+    if (origin.commonDir !== destination.commonDir) throw new Error("Managed worktree repository changed");
+    return row;
+  }
+  async function assertClean(target) {
+    const flags = await checked(target, ["ls-files", "-v", "-z"]);
+    if (flags.split("\0").some((row) => row && (row[0] === "S" || /[a-z]/.test(row[0]))))
+      throw new Error("Worktree has hidden index state");
+    if ((await checked(target, ["ls-files", "--stage", "-z"])).split("\0").some((row) => row.startsWith("160000 ")))
+      throw new Error("Worktree has submodules");
+    if ((await checked(target, ["status", "--porcelain=v1", "--untracked-files=all", "--ignored"])).length)
+      throw new Error("Worktree contains uncommitted or ignored files");
+  }
+  return {
+    facts,
+    inspect,
+    assertClean,
+    async checkoutFacts(directory2) {
+      const canonical = await realpath(directory2);
+      const repoRoot = await checked(canonical, ["rev-parse", "--show-toplevel"]);
+      const branch = await run(canonical, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+      const remote = await run(canonical, ["config", "--get", "remote.origin.url"]);
+      const status = await checked(canonical, ["status", "--porcelain=v1", "--untracked-files=all"]);
+      return {
+        isGit: (
+          /** @type {const} */
+          true
+        ),
+        repoRoot,
+        currentBranch: branch.code === 0 ? branch.stdout.trim() : null,
+        remoteUrl: remote.code === 0 ? remote.stdout.trim() || null : null,
+        isDirty: !!status
+      };
+    },
+    async create(source, parent, name, branch, head) {
+      await directory(parent);
+      if (!/^wks_[0-9a-f]{16}$/.test(name) || branch !== `alp/workspace/${name}` || !/^[0-9a-f]{40,64}$/.test(head))
+        throw new Error("Invalid generated worktree identity");
+      const target = path.join(parent, name);
+      if (await lstat(target).catch((error) => {
+        if (error.code === "ENOENT") return void 0;
+        throw error;
+      }))
+        throw new Error("Worktree destination already exists");
+      await checked(source, ["worktree", "add", "--quiet", "--no-checkout", "-b", branch, target, head]);
+      await checked(target, ["reset", "--hard", "--no-recurse-submodules", head]);
+      if (!await inspect(source, target, branch)) throw new Error("Worktree creation needs reconciliation");
+      return target;
+    },
+    async remove(source, target, branch) {
+      if (!await inspect(source, target, branch)) throw new Error("Managed worktree is missing");
+      await assertClean(target);
+      await checked(source, ["worktree", "remove", target], await filterOverrides(target));
+      if ((await list(source)).some((row) => row.worktree === target))
+        throw new Error("Worktree removal needs reconciliation");
+    }
+  };
+}
+export {
+  repositoryIdentity,
+  userWorktreeGit
+};

package/dist/validation.js

@@ -147,8 +147,9 @@ function validateUserSettings(settings, source) {
   }
   if (settings.web !== void 0) {
     check(object(settings.web), "web must be an object");
-    const extra = Object.keys(settings.web).find((field) => !["enabled", "port", "relay"].includes(field));
-    check(!extra, `unsupported web field '${extra}'; use enabled, port or relay`);
+    const extra = Object.keys(settings.web).find((field) => !["enabled", "port", "relay", "permissions"].includes(field));
+    check(!extra, `unsupported web field '${extra}'; use enabled, port, relay or permissions`);
+    if (settings.web.permissions !== void 0) check(Array.isArray(settings.web.permissions) && settings.web.permissions.every((entry) => typeof entry === "string" && /^[a-z][a-z.]*$/.test(entry)), "web.permissions must be a list of permission names, such as files.read");
     const relay = settings.web.relay;
     if (relay !== void 0) {
       check(object(relay), "web.relay must be an object");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhlp/alp-core",
-  "version": "0.0.1-beta.3",
+  "version": "0.0.1-beta.4",
   "type": "module",
   "description": "ALP core module",
   "files": [
@@ -284,7 +284,7 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@anhlp/alp-protocol": "0.0.1-beta.3"
+    "@anhlp/alp-protocol": "0.0.1-beta.4"
   },
   "scripts": {
     "build": "node ../../scripts/build-workspace.mjs core",

package/src/backup.js

@@ -34,7 +34,12 @@ export const BACKUP_FORMAT = 1;
 export const BACKUP_EXTENSION = '.alpbackup';
 
 /** alpd's state: sessions, their timelines and receipts, and the runtime's durable state. */
-export const STATE_UNITS = ['state/schema.json', 'state/sessions', 'state/timeline', 'state/receipts', 'state/recall.json', 'state/pause.json', 'state/trust.json', 'state/web-workspaces.json'];
+const RESULT_LEDGER = 'state/assignment-results.json';
+const RESULT_MARKER = `${RESULT_LEDGER}.initialized`;
+const DESTINATIONS = 'worktree-destinations.json';
+// Evidence only: the daemon never loads mapping authority from this path.
+const QUARANTINED_DESTINATIONS = 'state/worktree-destinations.quarantined.json';
+export const STATE_UNITS = [RESULT_LEDGER, RESULT_MARKER, 'state/schema.json', 'state/sessions', 'state/timeline', 'state/receipts', 'state/recall.json', 'state/pause.json', 'state/trust.json', 'state/web-workspaces.json'];
 /**
  * Live work (running assignments alpd continues after a restart) and the journal of an
  * unfinished migration are never backed up: a restore of the state removes them, so restored
@@ -43,7 +48,7 @@ export const STATE_UNITS = ['state/schema.json', 'state/sessions', 'state/timeli
 export const CLEARED_UNITS = ['state/live.json', 'state/migration.json'];
 /** Everything a backup of $ALP_HOME holds: the state, the user's settings and library, boards and assignment logs. */
 export const HOME_UNITS = [
-  ...STATE_UNITS,
+  ...STATE_UNITS, DESTINATIONS,
   'settings.json', 'library.json', 'role-skills.json', 'lessons.md',
   'agents', 'skills', 'teams', 'hooks', 'mcp', 'providers', 'formulas',
   'boards', 'runs',
@@ -396,6 +401,94 @@ async function holdTaskLocks(roots, work) {
   finally { clearInterval(touch); }
 }
 
+/**
+ * Restore ownership evidence, never checkout birth certification or host authority.
+ * Paths in an archive cannot establish the identity of an old or moved checkout. Keep
+ * every retained owner (including work after the snapshot), but require audited adoption
+ * for old targets. The host must explicitly approve mappings again; archived bytes are
+ * kept privately as evidence only. All replacements join the ordinary rollback journal.
+ */
+async function prepareWorkspaceRestore(home, root, units, warnings) {
+  const relevant = [RESULT_LEDGER, RESULT_MARKER, DESTINATIONS, 'state/sessions', 'state/web-workspaces.json'];
+  // Only the transform may stage quarantine; archive-declared copies are never activated.
+  const restorable = units.filter(unit => unit.path !== QUARANTINED_DESTINATIONS);
+  if (!units.some(unit => relevant.includes(unit.path))) return restorable;
+  for (const base of [home, root]) {
+    const info = await lstat(path.join(base, 'state')).catch(error => { if (error.code === 'ENOENT') return undefined; throw error; });
+    if (info && !info.isDirectory()) throw invalid('workspace state must be a real directory');
+  }
+  const result = restorable.filter(unit => ![RESULT_LEDGER, RESULT_MARKER, DESTINATIONS, 'state/web-workspaces.json'].includes(unit.path));
+  async function regular(base, unit, declared) {
+    if (declared && declared.kind === 'absent') return undefined;
+    const file = path.join(base, unit);
+    const info = await lstat(file).catch(error => { if (error.code === 'ENOENT') return undefined; throw error; });
+    if (!info) {
+      if (declared) throw invalid(`${unit} is declared but missing from the backup`);
+      return undefined;
+    }
+    if (!info.isFile()) throw invalid(`${unit} must be a regular file for a workspace restore`);
+    return readFile(file, 'utf8');
+  }
+  const incoming = async unit => {
+    const declared = units.find(entry => entry.path === unit);
+    return declared ? regular(root, unit, declared) : undefined;
+  };
+  const owners = new Map();
+  let hasLedger = false;
+  for (const text of [await incoming(RESULT_LEDGER), await regular(home, RESULT_LEDGER)]) {
+    if (text === undefined) continue;
+    let value;
+    try { value = JSON.parse(text); } catch { throw invalid('assignment result ledger is not readable JSON; repair it before restoring'); }
+    const absolute = value => typeof value === 'string' && path.isAbsolute(value);
+    if (value?.version !== 1 || !Array.isArray(value.workspaces) || !value.workspaces.every(absolute) ||
+        !Array.isArray(value.results) || !value.results.every(entry => entry && typeof entry.assignmentId === 'string' &&
+          absolute(entry.checkout) && (entry.worktree === undefined || absolute(entry.worktree))))
+      throw invalid('assignment result ledger has an unsupported or invalid shape');
+    hasLedger = true;
+    for (const entry of value.results) {
+      const owner = { assignmentId: entry.assignmentId, checkout: entry.checkout, ...(entry.worktree === undefined ? {} : { worktree: entry.worktree }) };
+      const previous = owners.get(owner.assignmentId);
+      if (previous && JSON.stringify(previous) !== JSON.stringify(owner)) throw invalid('assignment result ownership conflicts with current data; reconcile it before restoring');
+      owners.set(owner.assignmentId, owner);
+    }
+  }
+  const markers = [await incoming(RESULT_MARKER), await regular(home, RESULT_MARKER)];
+  if (markers.some(text => text !== undefined && text !== '1\n')) throw invalid('assignment result initialized marker is invalid');
+  await mkdir(path.join(root, 'state'), { recursive: true, mode: 0o700 });
+  if (hasLedger) await writeAtomic(path.join(root, RESULT_LEDGER), JSON.stringify({ version: 1, workspaces: [], results: [...owners.values()] }) + '\n');
+  result.push({ path: RESULT_LEDGER, kind: hasLedger ? 'file' : 'absent' });
+  const initialized = markers.some(text => text !== undefined);
+  if (initialized) await writeAtomic(path.join(root, RESULT_MARKER), '1\n');
+  result.push({ path: RESULT_MARKER, kind: initialized ? 'file' : 'absent' });
+  const mappings = await incoming(DESTINATIONS);
+  if (mappings !== undefined) {
+    await writeAtomic(path.join(root, QUARANTINED_DESTINATIONS), mappings);
+    result.push({ path: QUARANTINED_DESTINATIONS, kind: 'file' });
+  }
+  result.push({ path: DESTINATIONS, kind: 'absent' });
+  const registryUnit = 'state/web-workspaces.json';
+  const registryDeclaration = units.find(unit => unit.path === registryUnit);
+  const registryText = registryDeclaration ? await incoming(registryUnit) : await regular(home, registryUnit);
+  if (registryText !== undefined) {
+    let registry;
+    try { registry = JSON.parse(registryText); } catch { throw invalid('workspace registry is not readable JSON; repair it before restoring'); }
+    // Reapproval of the same mapping ID must not reactivate historical token grants.
+    // Rotate epochs in rows, pending native intents and cached receipt results alike.
+    const epoch = `restore-${randomBytes(16).toString('hex')}`;
+    let revoked = false;
+    const revoke = value => {
+      if (!value || typeof value !== 'object') return;
+      if (Object.hasOwn(value, 'grantEpoch')) { value.grantEpoch = epoch; revoked = true; }
+      for (const child of Object.values(value)) revoke(child);
+    };
+    revoke(registry);
+    await writeAtomic(path.join(root, registryUnit), revoked ? JSON.stringify(registry) + '\n' : registryText);
+    result.push({ path: registryUnit, kind: 'file' });
+  } else if (registryDeclaration) result.push({ path: registryUnit, kind: 'absent' });
+  if (hasLedger || initialized || mappings !== undefined || await exists(path.join(home, DESTINATIONS))) warnings.push('Workspace restore retains assignment owners but clears checkout birth certification; old targets require an audited migration. Worktree destination mappings are inactive and require explicit host approval; archived mapping evidence is in state/worktree-destinations.quarantined.json. Historical checkout grants remain revoked after reapproval.');
+  return result;
+}
+
 /**
  * Restores a backup over `home` and, with `projects`, over the projects it holds whose
  * roots exist. The current data is checked first: a home in a state schema newer than
@@ -419,6 +512,7 @@ export async function restoreBackup({ home, file, projects = true, safety = true
   const warnings = [];
   const areaBase = area => area === 'home' ? home : header.projects[Number(area.slice(8))].root;
   const directories = [];
+  let homeUnits;
   // The journal exists from the first staged file on, so a crash at any point leaves nothing behind.
   const journal = { version: 1, id, file: path.resolve(file), by, startedAt: new Date().toISOString(), phase: 'staging', units: [], staging: [], created: [], locks: [] };
   const record = () => writeAtomic(journalFile(home), JSON.stringify(journal) + '\n');
@@ -452,6 +546,7 @@ export async function restoreBackup({ home, file, projects = true, safety = true
         };
       },
     });
+    homeUnits = await prepareWorkspaceRestore(home, staging.get('home'), header.units, warnings);
     // Directory modes last, deepest first, once nothing more is written into them.
     for (const [directory, mode] of directories.reverse()) if (Number.isSafeInteger(mode)) await chmod(directory, mode & 0o777 | 0o700).catch(() => {});
   } catch (error) {
@@ -472,8 +567,8 @@ export async function restoreBackup({ home, file, projects = true, safety = true
   const plan = [];
   for (const [area, root] of staging) {
     const base = areaBase(area);
-    const units = area === 'home' ? header.units : header.projects[Number(area.slice(8))].units;
-    const known = area === 'home' ? HOME_UNITS : PROJECT_UNITS;
+    const units = area === 'home' ? homeUnits : header.projects[Number(area.slice(8))].units;
+    const known = area === 'home' ? [...HOME_UNITS, QUARANTINED_DESTINATIONS] : PROJECT_UNITS;
     for (const unit of units) {
       if (!known.includes(unit.path)) { warnings.push(`${unit.path} is not a unit this ALP restores; left as it is`); continue; }
       const target = path.join(base, ...unit.path.split('/'));
@@ -497,7 +592,7 @@ export async function restoreBackup({ home, file, projects = true, safety = true
   let safetyFile;
   if (safety) {
     try {
-      safetyFile = await automaticBackup(home, 'pre-restore', { units: header.units.map(unit => unit.path).filter(unit => HOME_UNITS.includes(unit)), projects: roots, by });
+      safetyFile = await automaticBackup(home, 'pre-restore', { units: [...new Set([...header.units.map(unit => unit.path), ...homeUnits.map(unit => unit.path)])].filter(unit => HOME_UNITS.includes(unit) || unit === QUARANTINED_DESTINATIONS), projects: roots, by });
     } catch (error) {
       await abandon();
       throw new AlpError('RESTORE_SAFETY_BACKUP_FAILED', `could not save the current data before restoring (${error?.message ?? error}); nothing was changed`, { cause: error });

package/src/index.js

@@ -29,3 +29,4 @@ export * as user_settings from './user-settings.js';
 export * as validation from './validation.js';
 export * as verify from './verify.js';
 export * as workflow from './workflow.js';
+export * as user_worktree from './user-worktree.js';

package/src/migrations.js

@@ -98,7 +98,7 @@ export async function migrateState(home, { by = 'alp', migrations = MIGRATIONS,
         throw new AlpError('STATE_MIGRATION_ROLLBACK_FAILED', `state migration ${step.name} failed (${error?.message ?? error}) and putting the state back from ${backup} failed too (${rollback?.message ?? rollback}); the next start tries the migration again. See docs/alp/data-recovery.md`, { cause: error });
       }
       await rm(migrationFile(home), { force: true });
-      throw new AlpError('STATE_MIGRATION_FAILED', `state migration ${step.name} (schema ${step.from} → ${step.to}) failed: ${error?.message ?? error}; the state was put back from ${backup} and is unchanged. See docs/alp/data-recovery.md`, { cause: error });
+      throw new AlpError('STATE_MIGRATION_FAILED', `state migration ${step.name} (schema ${step.from} → ${step.to}) failed: ${error?.message ?? error}; data was restored from ${backup} with workspace authority checks. See docs/alp/data-recovery.md`, { cause: error });
     }
     await writeStateSchema(home, step.to, by);
     await rm(migrationFile(home), { force: true });

package/src/user-worktree.js

@@ -0,0 +1,259 @@
+import { spawn } from 'node:child_process';
+import { lstat, realpath, open } from 'node:fs/promises';
+import path from 'node:path';
+import { constants } from 'node:fs';
+
+/** Bounded, no-follow administrative reads; no Git process is needed to re-check a grant. */
+async function control(file) {
+  const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.nlink !== 1 || info.size > 4096) throw new Error('Invalid Git administrative file');
+    const bytes = Buffer.alloc(4097);
+    const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+    if (bytesRead > 4096) throw new Error('Git administrative file exceeds limit');
+    return bytes
+      .subarray(0, bytesRead)
+      .toString('utf8')
+      .replace(/\r?\n$/, '');
+  } finally {
+    await handle.close();
+  }
+}
+export async function repositoryIdentity(directory) {
+  if ((await realpath(directory)) !== directory) throw new Error('Repository root is not canonical');
+  const entry = path.join(directory, '.git');
+  const info = await lstat(entry);
+  let gitDir;
+  if (info.isDirectory()) gitDir = await realpath(entry);
+  else {
+    const value = await control(entry);
+    if (!value.startsWith('gitdir: ') || /[\r\n\0]/.test(value)) throw new Error('Invalid Git control link');
+    gitDir = await realpath(path.resolve(directory, value.slice(8)));
+  }
+  const commonEntry = path.join(gitDir, 'commondir');
+  const hasCommon = await lstat(commonEntry).catch((error) => {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  });
+  const commonDir = hasCommon ? await realpath(path.resolve(gitDir, await control(commonEntry))) : gitDir;
+  if (gitDir !== commonDir) {
+    if (
+      path.dirname(gitDir) !== path.join(commonDir, 'worktrees') ||
+      path.resolve(gitDir, await control(path.join(gitDir, 'gitdir'))) !== entry
+    )
+      throw new Error('Git worktree backlink changed');
+  }
+  const head = await control(path.join(gitDir, 'HEAD'));
+  const branch = head.startsWith('ref: refs/heads/') ? head.slice(16) : null;
+  if (branch !== null && (!branch || /[\r\n\0]/.test(branch))) throw new Error('Invalid branch reference');
+  return { gitDir, commonDir, branch };
+}
+
+/** User workspace primitives. Assignment cleanup's force/rm semantics must never be used here. */
+export function userWorktreeGit({ executable = '/usr/bin/git', timeoutMs = 15_000, maxBytes = 2 * 1024 * 1024 } = {}) {
+  if (process.platform === 'win32') throw new Error('User worktree operations are unavailable on this host');
+  if (!path.isAbsolute(executable)) throw new Error('Git executable must be host configured and absolute');
+  const disabled = [
+    '-c',
+    'core.hooksPath=/dev/null',
+    '-c',
+    'core.fsmonitor=false',
+    '-c',
+    'core.untrackedCache=false',
+    '-c',
+    'core.pager=cat',
+    '-c',
+    'maintenance.auto=false',
+    '-c',
+    'gc.auto=0',
+    '-c',
+    'protocol.allow=never',
+    '-c',
+    'submodule.recurse=false'
+  ];
+  // No inherited Git context, PATH or user/system config. Repository config is data, never a program.
+  const env = {
+    PATH: '/usr/bin:/bin',
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: '/dev/null',
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_OPTIONAL_LOCKS: '0',
+    LANG: 'C',
+    LC_ALL: 'C'
+  };
+  async function raw(cwd, args, extra = []) {
+    return new Promise((resolve, reject) => {
+      const child = spawn(executable, [...disabled, ...extra, ...args], {
+        cwd,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        detached: true
+      });
+      let size = 0;
+      let overflow = false;
+      const stdout = [];
+      const stderr = [];
+      const kill = () => {
+        try {
+          process.kill(-child.pid, 'SIGKILL');
+        } catch {
+          child.kill('SIGKILL');
+        }
+      };
+      const timer = setTimeout(() => {
+        overflow = true;
+        kill();
+      }, timeoutMs);
+      const collect = (sink) => (chunk) => {
+        size += chunk.length;
+        if (size > maxBytes) {
+          overflow = true;
+          kill();
+        } else sink.push(chunk);
+      };
+      child.stdout.on('data', collect(stdout));
+      child.stderr.on('data', collect(stderr));
+      child.once('error', (error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+      child.once('close', (code) => {
+        clearTimeout(timer);
+        if (overflow) reject(new Error('Git operation exceeded its host limit'));
+        else
+          resolve({
+            code,
+            stdout: Buffer.concat(stdout).toString('utf8'),
+            stderr: Buffer.concat(stderr).toString('utf8')
+          });
+      });
+    });
+  }
+  async function filterOverrides(cwd) {
+    // Status/removal may run clean/process filters as well as creation's smudge filter.
+    const filters = await raw(cwd, [
+      'config',
+      '--null',
+      '--name-only',
+      '--get-regexp',
+      '^filter\\..*\\.(smudge|clean|process|required)$'
+    ]);
+    if (filters.code !== 0 && filters.code !== 1) throw new Error('Cannot inspect repository filters');
+    const neutral = filters.stdout
+      .split('\0')
+      .filter(Boolean)
+      .flatMap((key) => ['-c', `${key}=${key.endsWith('.required') ? 'false' : ''}`]);
+    return neutral;
+  }
+  async function run(cwd, args, extra = []) {
+    return raw(cwd, args, [...(await filterOverrides(cwd)), ...extra]);
+  }
+  async function checked(cwd, args, extra = []) {
+    const result = await run(cwd, args, extra);
+    if (result.code !== 0) throw new Error('Git workspace operation refused');
+    return result.stdout.trim();
+  }
+  async function directory(value) {
+    const canonical = await realpath(value);
+    if (canonical !== value || !(await lstat(value)).isDirectory())
+      throw new Error('Workspace paths must be canonical directories');
+    return canonical;
+  }
+  async function facts(source) {
+    await directory(source);
+    const top = await checked(source, ['rev-parse', '--show-toplevel']);
+    if ((await realpath(top)) !== source) throw new Error('Workspace must be a repository top level');
+    const commonDir = await realpath(
+      await checked(source, ['rev-parse', '--path-format=absolute', '--git-common-dir'])
+    );
+    const identity = await repositoryIdentity(source);
+    if (identity.commonDir !== commonDir) throw new Error('Repository identity changed');
+    const head = await checked(source, ['rev-parse', '--verify', 'HEAD']);
+    const branch = await run(source, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+    return { commonDir, gitDir: identity.gitDir, head, branch: branch.code === 0 ? branch.stdout.trim() : null };
+  }
+  async function list(source) {
+    const result = await checked(source, ['worktree', 'list', '--porcelain', '-z']);
+    return result
+      .split('\0\0')
+      .filter(Boolean)
+      .map((block) =>
+        Object.fromEntries(
+          block
+            .split('\0')
+            .filter(Boolean)
+            .map((line) => {
+              const i = line.indexOf(' ');
+              return i < 0 ? [line, true] : [line.slice(0, i), line.slice(i + 1)];
+            })
+        )
+      );
+  }
+  async function inspect(source, target, branch) {
+    const row = (await list(source)).find((row) => row.worktree === target);
+    if (!row) return undefined;
+    await directory(target);
+    if (row.branch !== `refs/heads/${branch}` || row.locked || row.prunable)
+      throw new Error('Managed worktree identity changed');
+    const origin = await facts(source);
+    const destination = await facts(target);
+    if (origin.commonDir !== destination.commonDir) throw new Error('Managed worktree repository changed');
+    return row;
+  }
+  async function assertClean(target) {
+    const flags = await checked(target, ['ls-files', '-v', '-z']);
+    if (flags.split('\0').some((row) => row && (row[0] === 'S' || /[a-z]/.test(row[0]))))
+      throw new Error('Worktree has hidden index state');
+    if ((await checked(target, ['ls-files', '--stage', '-z'])).split('\0').some((row) => row.startsWith('160000 ')))
+      throw new Error('Worktree has submodules');
+    // Ignored data is user data too. Never force a delete or fall back to recursive rm.
+    if ((await checked(target, ['status', '--porcelain=v1', '--untracked-files=all', '--ignored'])).length)
+      throw new Error('Worktree contains uncommitted or ignored files');
+  }
+  return {
+    facts,
+    inspect,
+    assertClean,
+    async checkoutFacts(directory) {
+      const canonical = await realpath(directory);
+      const repoRoot = await checked(canonical, ['rev-parse', '--show-toplevel']);
+      const branch = await run(canonical, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+      const remote = await run(canonical, ['config', '--get', 'remote.origin.url']);
+      const status = await checked(canonical, ['status', '--porcelain=v1', '--untracked-files=all']);
+      return {
+        isGit: /** @type {const} */ (true),
+        repoRoot,
+        currentBranch: branch.code === 0 ? branch.stdout.trim() : null,
+        remoteUrl: remote.code === 0 ? remote.stdout.trim() || null : null,
+        isDirty: !!status
+      };
+    },
+    async create(source, parent, name, branch, head) {
+      await directory(parent);
+      if (!/^wks_[0-9a-f]{16}$/.test(name) || branch !== `alp/workspace/${name}` || !/^[0-9a-f]{40,64}$/.test(head))
+        throw new Error('Invalid generated worktree identity');
+      const target = path.join(parent, name);
+      if (
+        await lstat(target).catch((error) => {
+          if (error.code === 'ENOENT') return undefined;
+          throw error;
+        })
+      )
+        throw new Error('Worktree destination already exists');
+      await checked(source, ['worktree', 'add', '--quiet', '--no-checkout', '-b', branch, target, head]);
+      // Conditional gitdir/onbranch config is resolved in the new checkout before materialization.
+      await checked(target, ['reset', '--hard', '--no-recurse-submodules', head]);
+      if (!(await inspect(source, target, branch))) throw new Error('Worktree creation needs reconciliation');
+      return target;
+    },
+    async remove(source, target, branch) {
+      if (!(await inspect(source, target, branch))) throw new Error('Managed worktree is missing');
+      await assertClean(target);
+      await checked(source, ['worktree', 'remove', target], await filterOverrides(target));
+      if ((await list(source)).some((row) => row.worktree === target))
+        throw new Error('Worktree removal needs reconciliation');
+    }
+  };
+}

package/src/validation.js

@@ -167,8 +167,10 @@ export function validateUserSettings(settings, source) {
   }
   if (settings.web !== undefined) {
     check(object(settings.web), 'web must be an object');
-    const extra = Object.keys(settings.web).find(field => !['enabled', 'port', 'relay'].includes(field));
-    check(!extra, `unsupported web field '${extra}'; use enabled, port or relay`);
+    const extra = Object.keys(settings.web).find(field => !['enabled', 'port', 'relay', 'permissions'].includes(field));
+    check(!extra, `unsupported web field '${extra}'; use enabled, port, relay or permissions`);
+    // Gateway permissions `alp web` adds to its default grant; alp-web checks each name against the gateway's list.
+    if (settings.web.permissions !== undefined) check(Array.isArray(settings.web.permissions) && settings.web.permissions.every(entry => typeof entry === 'string' && /^[a-z][a-z.]*$/.test(entry)), 'web.permissions must be a list of permission names, such as files.read');
     // The relay that lets Paseo's app reach alpd from another device (ALPD §64).
     const relay = settings.web.relay;
     if (relay !== undefined) {