@kendoo.agentdesk/agentdesk 0.28.3 → 0.28.4

package/cli/worktree-git.mjs

@@ -0,0 +1,85 @@
+// Agents never write the shared Git database. Git commands use a private mirror;
+// the trusted host imports verified objects and updates only the session branch.
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, lstatSync, readFileSync, writeFileSync, readdirSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+function command(cwd, args, options = {}) {
+  const env = { ...process.env, GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_TERMINAL_PROMPT: "0", GIT_NO_REPLACE_OBJECTS: "1", GIT_NO_LAZY_FETCH: "1" };
+  for (const key of Object.keys(env)) if (/^GIT_(DIR|WORK_TREE|COMMON_DIR|INDEX_FILE|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES|CONFIG_COUNT|CONFIG_KEY_\d+|CONFIG_VALUE_\d+|CONFIG_PARAMETERS)$/.test(key)) delete env[key];
+  return execFileSync("git", ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "-c", "core.alternateRefsCommand=", "-c", "gc.auto=0", "-c", "protocol.allow=never", ...args], {
+    cwd, env, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], timeout: 120000, maxBuffer: 256 * 1024 * 1024, ...options,
+  });
+}
+function validateObjects(gitDir, commonDir) {
+  if (realpathSync(gitDir) !== gitDir) throw new Error("Private Git directory was redirected; manual recovery required.");
+  const visit = path => {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) throw new Error("Private Git object storage contains a symlink; manual recovery required.");
+    if (stat.isDirectory()) for (const name of readdirSync(path)) visit(join(path, name));
+  };
+  visit(join(gitDir, "objects"));
+  const alternates = join(gitDir, "objects", "info", "alternates");
+  if (existsSync(alternates) && readFileSync(alternates, "utf8").trim() !== join(commonDir, "objects")) throw new Error("Private Git object alternates changed; manual recovery required.");
+}
+function regularCopy(from, to) {
+  if (!lstatSync(from).isFile() || lstatSync(from).isSymbolicLink()) throw new Error("Git index is not a regular file; retained for manual review.");
+  if (existsSync(to) && !lstatSync(to).isFile()) throw new Error("Git index destination changed.");
+  copyFileSync(from, to);
+}
+
+export function preparePrivateGit(record, stateDir) {
+  const gitDir = join(stateDir, "git");
+  const ref = `refs/heads/${record.branch}`;
+  const originalGitDir = resolve(record.cwd, command(record.cwd, ["rev-parse", "--git-dir"]).trim());
+  const publishedHead = command(record.repo, ["rev-parse", "--verify", ref]).trim();
+  if (!existsSync(gitDir)) {
+    command(record.repo, ["-c", "protocol.file.allow=always", "clone", "--mirror", "--shared", "--", record.repo, gitDir]);
+    command(record.repo, [`--git-dir=${gitDir}`, "config", "remote.origin.mirror", "false"]);
+    command(record.repo, [`--git-dir=${gitDir}`, "config", "--unset-all", "remote.origin.fetch"]);
+    command(record.repo, [`--git-dir=${gitDir}`, "config", "--add", "remote.origin.fetch", "+refs/heads/*:refs/remotes/origin/*"]);
+    let remote = "";
+    try { remote = command(record.repo, ["remote", "get-url", "origin"]).trim(); } catch {}
+    if (remote) command(record.repo, [`--git-dir=${gitDir}`, "remote", "set-url", "origin", remote]);
+    else command(record.repo, [`--git-dir=${gitDir}`, "remote", "remove", "origin"]);
+    command(record.repo, [`--git-dir=${gitDir}`, "config", "core.bare", "false"]);
+    command(record.repo, [`--git-dir=${gitDir}`, "config", "core.worktree", record.tree]);
+    command(record.repo, [`--git-dir=${gitDir}`, "symbolic-ref", "HEAD", ref]);
+    regularCopy(join(originalGitDir, "index"), join(gitDir, "index"));
+  }
+  const marker = join(stateDir, "..", "git-pending");
+  validateObjects(gitDir, record.commonDir);
+  // Resume a crashed session's private commits/index if the shared branch has
+  // not moved since that session started. Never overwrite its staged work.
+  const pendingHead = existsSync(marker) ? readFileSync(marker, "utf8").trim() : "";
+  if (pendingHead && pendingHead !== publishedHead) throw new Error(`Unpublished Git state conflicts with the shared branch; recover ${gitDir} before resuming.`);
+  const privateHead = command(record.repo, [`--git-dir=${gitDir}`, "rev-parse", "--verify", ref]).trim();
+  if (!pendingHead && privateHead !== publishedHead) throw new Error(`The session branch changed outside AgentDesk. Git state retained at ${gitDir} for review.`);
+  // Refresh the index on resume (the user may have staged files while idle).
+  if (!pendingHead) regularCopy(join(originalGitDir, "index"), join(gitDir, "index"));
+  writeFileSync(marker, publishedHead, { mode: 0o600 });
+  return {
+    env: { GIT_DIR: gitDir, GIT_COMMON_DIR: gitDir, GIT_WORK_TREE: record.tree },
+    publish() {
+      validateObjects(gitDir, record.commonDir);
+      const headRef = command(record.repo, [`--git-dir=${gitDir}`, "symbolic-ref", "HEAD"]).trim();
+      if (headRef !== ref) throw new Error(`Session changed Git branches. Private Git state retained at ${gitDir}.`);
+      const oid = command(record.repo, [`--git-dir=${gitDir}`, "rev-parse", "--verify", `${ref}^{commit}`]).trim();
+      if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(oid)) throw new Error("Invalid session commit");
+      if (oid !== publishedHead) {
+        // pack-objects has no checkout, filter or transport hooks. index-pack
+        // validates content hashes and links before any shared ref is touched.
+        const pack = command(record.repo, [`--git-dir=${gitDir}`, "pack-objects", "--stdout", "--revs"], { input: Buffer.from(`${oid}\n^${publishedHead}\n`), encoding: null });
+        command(record.repo, ["index-pack", "--stdin", "--strict"], { input: pack });
+      }
+      command(record.repo, ["update-ref", ref, oid, publishedHead]);
+      regularCopy(join(gitDir, "index"), join(originalGitDir, "index"));
+      // Empty means synchronized; keep the marker path immutable to the agent.
+      writeFileSync(marker, "", { mode: 0o600 });
+    },
+  };
+}
+
+export function hasUnpublishedGit(stateDir) {
+  try { return !!readFileSync(join(stateDir, "..", "git-pending"), "utf8").trim(); } catch { return false; }
+}

package/cli/worktree-options.mjs

@@ -0,0 +1,18 @@
+export function parseWorkspaceArgs(args) {
+  const remaining = [];
+  const workspace = { enabled: true };
+  const values = { "--base-branch": "baseBranch", "--branch": "branch", "--existing-branch": "branch", "--resume-worktree": "resumeId" };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--no-worktree") workspace.enabled = false;
+    else if (values[arg]) {
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error(`${arg} requires a value`);
+      workspace[values[arg]] = value;
+      if (arg === "--existing-branch") workspace.branchMode = "existing";
+    } else remaining.push(arg);
+  }
+  if (!workspace.enabled && (workspace.branch || workspace.baseBranch || workspace.resumeId)) throw new Error("Worktree options cannot be combined with --no-worktree");
+  if (workspace.resumeId && (workspace.branch || workspace.baseBranch)) throw new Error("--resume-worktree cannot be combined with --branch, --existing-branch, or --base-branch");
+  return { remaining, workspace };
+}

package/cli/worktrees.mjs

@@ -0,0 +1,295 @@
+// Local workspace lifecycle. Paths are derived locally, never accepted from the server.
+import { execFileSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, relative, dirname } from "node:path";
+import { hasUnpublishedGit } from "./worktree-git.mjs";
+
+export const REMINDER_AGE = 14 * 24 * 60 * 60 * 1000;
+const hash = value => createHash("sha256").update(value).digest("hex").slice(0, 24);
+function git(cwd, args) {
+  const env = { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+  for (const key of ["GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES"]) delete env[key];
+  for (const key of Object.keys(env)) if (key.startsWith("GIT_CONFIG_")) delete env[key];
+  env.GIT_CONFIG_NOSYSTEM = "1";
+  env.GIT_CONFIG_GLOBAL = "/dev/null";
+  return execFileSync("git", args, { cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30000 }).trim();
+}
+function rootPath(root) { return root || join(homedir(), ".agentdesk", "workspaces"); }
+function read(path) { return JSON.parse(readFileSync(path, "utf8")); }
+function unlinkIfPresent(path) {
+  try { unlinkSync(path); } catch (error) { if (error.code !== "ENOENT") throw error; }
+}
+function save(path, data) {
+  const temp = `${path}.${randomUUID()}.tmp`;
+  writeFileSync(temp, JSON.stringify(data, null, 2), { mode: 0o600 });
+  renameSync(temp, path);
+}
+function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return true;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code !== "ESRCH"; }
+}
+function groupAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return true;
+  try { process.kill(-pid, 0); return true; } catch (error) { return error.code !== "ESRCH"; }
+}
+function leaseAlive(owner) {
+  return owner.unknownChild || (!owner.quarantined && alive(owner.pid)) ||
+    (owner.childPids || []).some(pid => alive(pid) || groupAlive(pid));
+}
+export function workspaceActive(record) {
+  if (record.leasePath) {
+    try { return !!leaseAlive(read(record.leasePath)); }
+    catch (error) { return error.code !== "ENOENT"; }
+  }
+  return !!record.pid && alive(record.pid);
+}
+
+export function repositoryInfo(cwd) {
+  const repo = realpathSync(git(cwd, ["rev-parse", "--show-toplevel"]));
+  const commonDir = realpathSync(resolve(cwd, git(cwd, ["rev-parse", "--git-common-dir"])));
+  const branches = git(cwd, ["for-each-ref", "--format=%(refname:short)", "refs/heads", "refs/remotes"]).split("\n").filter(Boolean);
+  let currentBranch = "";
+  try { currentBranch = git(cwd, ["symbolic-ref", "--short", "HEAD"]); } catch {}
+  return { repo, commonDir, branches, currentBranch };
+}
+
+function branchRef(cwd, name, localOnly = false) {
+  if (typeof name !== "string" || !name || name.startsWith("-") || name.length > 200) throw new Error("Choose a valid branch name.");
+  git(cwd, ["check-ref-format", `refs/heads/${name}`]);
+  for (const ref of [`refs/heads/${name}`, ...(localOnly ? [] : [`refs/remotes/${name}`])]) {
+    try { git(cwd, ["show-ref", "--verify", ref]); return ref; } catch {}
+  }
+  throw new Error(`Branch "${name}" does not exist locally. Fetch it first.`);
+}
+
+export function listWorkspaces({ root, projectPaths } = {}) {
+  const dir = rootPath(root);
+  if (!existsSync(dir)) return [];
+  const allowed = projectPaths?.map(p => realpathSync(p));
+  return readdirSync(dir).filter(n => /^[a-f0-9]{24}\.json$/.test(n)).flatMap(name => {
+    try {
+      const record = read(join(dir, name));
+      if (allowed && !allowed.includes(record.sourceCwd)) return [];
+      return [record];
+    } catch { return []; }
+  });
+}
+
+export function getWorkspace(id, { root, projectPaths } = {}) {
+  const record = read(join(rootPath(root), `${hash(id)}.json`));
+  if (record.id !== id || (projectPaths && !projectPaths.some(p => realpathSync(p) === record.sourceCwd))) throw new Error("Workspace not found for this project.");
+  return record;
+}
+
+// A filesystem lease protects the same directory across daemon and CLI processes.
+function acquire(cwd, root) {
+  const path = join(rootPath(root), `${hash(cwd)}.lock`);
+  const token = randomUUID();
+  const unknownChildren = new Set();
+  const owned = () => {
+    try { return read(path).token === token; } catch { return false; }
+  };
+  const update = change => {
+    if (!owned()) throw new Error("Workspace lease ownership changed.");
+    save(path, { ...read(path), ...change });
+  };
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      writeFileSync(path, JSON.stringify({ pid: process.pid, token, childPids: [] }), { flag: "wx", mode: 0o600 });
+      return {
+        path, token,
+        hasLiveChildren() {
+          if (!owned()) return true;
+          return !!leaseAlive({ ...read(path), quarantined: true });
+        },
+        release(beforeRelease) {
+          if (!owned()) return false;
+          let owner;
+          try { owner = read(path); } catch (error) { if (error.code === "ENOENT") return false; throw error; }
+          if (leaseAlive({ ...owner, quarantined: true })) return false;
+          beforeRelease?.();
+          unlinkIfPresent(path);
+          return true;
+        },
+        trackChild(child) {
+          const owner = read(path);
+          // Retain every group leader until the lease ends: descendants can
+          // survive their parent. PID reuse errs on the side of retaining work.
+          if (!Number.isInteger(child.pid) || child.pid <= 0) {
+            if (child.exitCode == null && child.signalCode == null) {
+              unknownChildren.add(child);
+              update({ unknownChild: true });
+              child.once("close", () => {
+                unknownChildren.delete(child);
+                if (owned()) update({ unknownChild: unknownChildren.size > 0 });
+              });
+            }
+          } else update({ childPids: [...new Set([...owner.childPids, child.pid])] });
+        },
+        quarantine() { update({ quarantined: true, quarantinedAt: Date.now() }); },
+      };
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      let owner;
+      try { owner = read(path); } catch (error) { if (error.code === "ENOENT") continue; throw error; }
+      if (leaseAlive(owner)) throw new Error(owner.quarantined
+        ? "This workspace is quarantined until its processes exit."
+        : "This workspace already has a running session.");
+      unlinkIfPresent(path);
+    }
+  }
+  throw new Error("Could not acquire workspace.");
+}
+
+// Called on daemon startup and periodically afterwards. Never kill a PID from
+// disk (it may have been reused); only ESRCH is evidence that it is gone.
+export function recoverWorkspaceLocks({ root } = {}) {
+  const dir = rootPath(root);
+  const result = { released: 0, retained: 0 };
+  if (!existsSync(dir)) return result;
+  for (const name of readdirSync(dir).filter(n => /^[a-f0-9]{24}\.lock$/.test(n))) {
+    const path = join(dir, name);
+    try {
+      const original = readFileSync(path, "utf8");
+      const owner = JSON.parse(original);
+      if (leaseAlive(owner)) { result.retained++; continue; }
+      // Don't clear metadata or unlink a replacement lease from a newer run.
+      if (readFileSync(path, "utf8") !== original) continue;
+      for (const record of listWorkspaces({ root })) {
+        if (`${hash(record.tree || record.cwd)}.lock` !== name) continue;
+        if (record.leaseToken && record.leaseToken !== owner.token) continue;
+        save(join(dir, `${hash(record.id)}.json`), { ...record, pid: null, quarantined: false, lastActivityAt: Date.now() });
+      }
+      if (readFileSync(path, "utf8") === original) { unlinkSync(path); result.released++; }
+    } catch { result.retained++; } // Malformed or inaccessible locks fail closed.
+  }
+  return result;
+}
+
+export function prepareWorkspace({ cwd, sessionId, projectId, taskId, workspace = {}, root }) {
+  const sourceCwd = realpathSync(cwd);
+  if (workspace.resumeId && (workspace.branch || workspace.baseBranch)) throw new Error("Resuming a worktree cannot change its branch or starting branch.");
+  const requestedDir = rootPath(root);
+  mkdirSync(requestedDir, { recursive: true, mode: 0o700 });
+  const dir = realpathSync(requestedDir);
+  if (workspace.branchMode !== undefined && !["new", "existing"].includes(workspace.branchMode)) throw new Error("Invalid branch mode.");
+  if (workspace.enabled !== false && workspace.branchMode === "existing" && !workspace.branch) throw new Error("Choose an existing local branch.");
+  if (workspace.enabled === false) {
+    let leasePath = sourceCwd;
+    try { leasePath = repositoryInfo(sourceCwd).repo; } catch {}
+    const lease = acquire(leasePath, root);
+    return { cwd: sourceCwd, record: null, ...lease };
+  }
+  let record;
+  if (workspace.resumeId) {
+    record = getWorkspace(workspace.resumeId, { root, projectPaths: [sourceCwd] });
+    if (record.removedAt) throw new Error("This worktree was removed. Start a new session on its retained branch.");
+    const info = verifyWorktree(record);
+    if (info.currentBranch !== record.branch) throw new Error("Worktree branch changed; restore the session branch before resuming.");
+  } else {
+    const info = repositoryInfo(sourceCwd);
+    const baseRef = branchRef(sourceCwd, workspace.baseBranch || info.currentBranch);
+    const id = sessionId || randomUUID();
+    if (existsSync(join(dir, `${hash(id)}.json`))) throw new Error("This session already has a workspace. Resume it explicitly.");
+    const branch = workspace.branch || `agentdesk/${(taskId || "task").replace(/[^a-zA-Z0-9-]/g, "-").slice(0, 40)}-${randomUUID().slice(0, 8)}`;
+    git(sourceCwd, ["check-ref-format", "--branch", branch]);
+    const tree = join(dir, hash(id), "tree");
+    mkdirSync(join(dir, hash(id)), { recursive: true, mode: 0o700 });
+    const existing = workspace.branchMode === "existing";
+    if (existing) branchRef(sourceCwd, branch, true);
+    // No --force: Git rejects a branch already checked out in any other worktree.
+    try {
+      git(sourceCwd, ["worktree", "add", ...(existing ? [] : ["-b", branch]), "--", tree, existing ? branch : baseRef]);
+    } catch (error) {
+      throw new Error(`Could not create worktree: ${String(error.stderr || error.message).trim()}`);
+    }
+    record = { id, projectId, taskId, sourceCwd, repo: info.repo, commonDir: info.commonDir, tree: realpathSync(tree), cwd: join(realpathSync(tree), relative(info.repo, sourceCwd)), branch, baseRef,
+      baseCommit: git(tree, ["rev-parse", baseRef]), createdAt: Date.now(), lastActivityAt: Date.now() };
+    save(join(dir, `${hash(id)}.json`), record);
+  }
+  const lease = acquire(record.tree || record.cwd, root);
+  record = { ...record, pid: process.pid, leasePath: lease.path, leaseToken: lease.token,
+    quarantined: false, lastActivityAt: Date.now(), archived: false };
+  const recordPath = join(dir, `${hash(record.id)}.json`);
+  save(recordPath, record);
+  const stateDir = join(dir, hash(record.id), "state");
+  mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  let released = false;
+  return {
+    cwd: record.cwd, record, stateDir,
+    trackChild: lease.trackChild,
+    hasLiveChildren: lease.hasLiveChildren,
+    quarantine() {
+      lease.quarantine();
+      save(recordPath, { ...read(recordPath), quarantined: true });
+    },
+    release() {
+      if (released) return;
+      released = lease.release(() => save(recordPath, { ...read(recordPath), pid: null, quarantined: false, lastActivityAt: Date.now() }));
+    },
+  };
+}
+
+function verifyWorktree(record) {
+  if (!existsSync(record.cwd)) throw new Error("Worktree directory is missing; retained for manual review.");
+  const info = repositoryInfo(record.cwd);
+  if (info.repo !== realpathSync(record.tree || record.cwd) || info.commonDir !== record.commonDir || info.repo === record.repo) throw new Error("Worktree identity changed; manual review required.");
+  const entries = git(record.repo, ["worktree", "list", "--porcelain", "-z"]).split("\0");
+  if (!entries.includes(`worktree ${record.tree || record.cwd}`)) throw new Error("Worktree is no longer registered.");
+  return info;
+}
+
+export function inspectWorkspace(record, now = Date.now(), { heldLease = false } = {}) {
+  // Cleanup holds its own lease while inspecting; that isn't an active session.
+  const active = !heldLease && workspaceActive(record);
+  const reminder = !active && !record.removedAt && now - record.lastActivityAt >= REMINDER_AGE;
+  if (record.removedAt) return { ...record, active: false, safe: false, reminder: false, reason: "Worktree removed; branch retained." };
+  if (active) return { ...record, active, safe: false, reminder: false,
+    reason: record.quarantined ? "Cancellation timed out; quarantined until its processes exit." : "Session is running." };
+  try {
+    const info = verifyWorktree(record);
+    if (hasUnpublishedGit(join(dirname(record.tree || record.cwd), "state"))) throw new Error("Private Git state has unpublished work; manual recovery required.");
+    // Include ignored files: even an ignored .env or build artifact may contain valuable work.
+    if (git(record.tree || record.cwd, ["status", "--porcelain=v1", "--untracked-files=all", "--ignored"])) throw new Error("Uncommitted, untracked, or ignored files remain.");
+    if (info.currentBranch !== record.branch) throw new Error("The worktree branch changed; manual review required.");
+    git(record.repo, ["show-ref", "--verify", record.baseRef]);
+    if (`refs/heads/${record.branch}` === record.baseRef) throw new Error("Session branch is also the starting branch; merge into another branch before cleanup.");
+    try { git(record.cwd, ["merge-base", "--is-ancestor", "HEAD", record.baseRef]); }
+    catch { throw new Error("Commits have not been merged into the starting branch."); }
+    return { ...record, active, safe: true, reminder, reason: "Clean and merged into the starting branch." };
+  } catch (error) {
+    return { ...record, active, safe: false, reminder, reason: error.message };
+  }
+}
+
+export function cleanupWorkspace(id, { root, projectPaths, discard = false, confirmation, archive = false } = {}) {
+  let record = getWorkspace(id, { root, projectPaths });
+  if (record.removedAt) return inspectWorkspace(record);
+  if (workspaceActive(record)) throw new Error("Stop the session before removing its worktree.");
+  const lease = acquire(record.tree || record.cwd, root);
+  try {
+    const info = verifyWorktree(record);
+    if (info.currentBranch !== record.branch) throw new Error("Worktree branch changed; restore it before removing the worktree.");
+    const status = inspectWorkspace(record, Date.now(), { heldLease: true });
+    if (archive) {
+      record = { ...record, archived: true };
+      save(join(rootPath(root), `${hash(id)}.json`), record);
+    }
+    if (!status.safe && !discard) return { ...status, archived: record.archived };
+    if (discard && confirmation !== record.branch) throw new Error("Type the branch name to confirm discarding files. The branch itself will be kept.");
+    // Git checks locks, submodules and dirt again. Only explicit discard may force removal.
+    git(record.repo, ["worktree", "remove", ...(discard ? ["--force"] : []), "--", record.tree || record.cwd]);
+    record = { ...record, removedAt: Date.now(), pid: null };
+    save(join(rootPath(root), `${hash(id)}.json`), record);
+    return inspectWorkspace(record);
+  } finally { lease.release(); }
+}
+
+export function workspaceGitPaths(cwd) {
+  try {
+    const common = realpathSync(resolve(cwd, git(cwd, ["rev-parse", "--git-common-dir"])));
+    return relative(cwd, common).startsWith("..") ? [common] : [];
+  } catch { return []; }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kendoo.agentdesk/agentdesk",
-  "version": "0.28.3",
+  "version": "0.28.4",
   "description": "AI team orchestrator for Claude Code — run collaborative agent sessions from your terminal",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "bin/",
     "cli/",
+    "shared/",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -21,7 +22,7 @@
     "server": "node server/index.mjs",
     "build": "vite build",
     "preview": "vite preview",
-    "test": "node --test tests/server.test.mjs tests/agents.test.mjs tests/homepage.test.mjs tests/sessionUtils.test.mjs tests/tracker-url.test.mjs tests/session-preflight.test.mjs tests/access.test.mjs tests/project-ownership.test.mjs tests/random-hex.test.mjs tests/projects-registry.test.mjs tests/phase-loop.test.mjs tests/proc.test.mjs tests/crypto.test.mjs tests/dotenv.test.mjs tests/update-check.test.mjs tests/setup-helpers.test.mjs tests/project-key.test.mjs tests/tracker-project.test.mjs tests/tracker-check.test.mjs tests/config.test.mjs tests/engine-env.test.mjs tests/engine-events.test.mjs tests/engine-verdict.test.mjs tests/engine-hooks.test.mjs tests/engine-agents.test.mjs tests/session-isolation.test.mjs tests/engine-session.test.mjs tests/engine-prompts.test.mjs tests/engine-schemas.test.mjs tests/engine-claude-auth.test.mjs",
+    "test": "node --test tests/server.test.mjs tests/agents.test.mjs tests/homepage.test.mjs tests/sessionUtils.test.mjs tests/tracker-url.test.mjs tests/session-preflight.test.mjs tests/access.test.mjs tests/project-ownership.test.mjs tests/random-hex.test.mjs tests/projects-registry.test.mjs tests/phase-loop.test.mjs tests/proc.test.mjs tests/crypto.test.mjs tests/dotenv.test.mjs tests/update-check.test.mjs tests/setup-helpers.test.mjs tests/project-key.test.mjs tests/tracker-project.test.mjs tests/tracker-check.test.mjs tests/config.test.mjs tests/engine-env.test.mjs tests/engine-events.test.mjs tests/engine-verdict.test.mjs tests/engine-hooks.test.mjs tests/engine-agents.test.mjs tests/session-isolation.test.mjs tests/engine-session.test.mjs tests/engine-prompts.test.mjs tests/engine-schemas.test.mjs tests/engine-claude-auth.test.mjs tests/worktrees.test.mjs tests/workspaces-api.test.mjs tests/engine-outcome.test.mjs tests/session-outcomes.test.mjs tests/outcome-hydration.test.mjs tests/mobile-outcomes.test.mjs tests/session-queue.test.mjs",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-include='cli/**' --test-coverage-include='server/**' --test-coverage-lines=60 --test-coverage-branches=62 tests/*.test.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",

package/shared/outcomes.mjs

@@ -0,0 +1,41 @@
+// Shared wire/storage validation. No credentials or raw tool output belong here.
+export function normalizeOutcome(value) {
+  if (!value || !["pr_created", "replied"].includes(value.kind) ||
+      !["github", "jira", "linear"].includes(value.provider)) return null;
+  for (const key of ["container", "externalId", "actionId", "taskId"]) {
+    if (typeof value[key] !== "string" || !value[key] || value[key].length > 300 || /[\x00-\x1f]/.test(value[key])) return null;
+  }
+  if (!Number.isSafeInteger(value.observedAt) || value.observedAt <= 0) return null;
+  let url;
+  try { url = new URL(value.url); } catch { return null; }
+  if (url.protocol !== "https:" || url.username || url.password || url.port || value.url.length > 2000) return null;
+  if (value.provider === "github") {
+    if (!/^[\w.-]+\/[\w.-]+$/.test(value.container) || url.hostname !== "github.com" || url.search) return null;
+    if (value.kind === "pr_created") {
+      if (!/^\d+$/.test(value.externalId) || url.pathname !== `/${value.container}/pull/${value.externalId}` || url.hash) return null;
+    } else {
+      if (!/^\d+$/.test(value.taskId) || !/^\d+$/.test(value.externalId) ||
+          url.pathname !== `/${value.container}/issues/${value.taskId}` || url.hash !== `#issuecomment-${value.externalId}`) return null;
+    }
+  } else if (value.provider === "jira") {
+    if (value.kind !== "replied" || !/^\d+$/.test(value.externalId) || !/^[A-Z][A-Z0-9_]*-\d+$/.test(value.taskId) ||
+        url.origin !== value.container || url.pathname !== `/browse/${value.taskId}` ||
+        url.search !== `?focusedCommentId=${value.externalId}` || url.hash) return null;
+  } else if (value.kind !== "replied" || url.hostname !== "linear.app" ||
+      !/^[\w-]+$/.test(value.container) || !/^[\w-]+$/.test(value.externalId) ||
+      !url.pathname.startsWith(`/${value.container}/issue/${value.taskId}/`) || !url.hash || url.search) return null;
+  const id = [value.kind, value.provider, value.container, value.externalId].map(encodeURIComponent).join(":");
+  return { id, kind: value.kind, provider: value.provider, container: value.container,
+    externalId: value.externalId, actionId: value.actionId, taskId: value.taskId,
+    url: url.href, observedAt: value.observedAt,
+    ...(typeof value.branch === "string" && value.branch.length <= 300 ? { branch: value.branch } : {}) };
+}
+
+export function mergeOutcomes(existing = [], incoming = []) {
+  const found = new Map();
+  for (const raw of [...(Array.isArray(existing) ? existing : []), ...(Array.isArray(incoming) ? incoming : [])]) {
+    const outcome = normalizeOutcome(raw);
+    if (outcome && !found.has(outcome.id)) found.set(outcome.id, outcome);
+  }
+  return [...found.values()];
+}

package/shared/session-status.mjs

@@ -0,0 +1,6 @@
+// Running consumes execution capacity. Open also includes queued work and a
+// human handoff: neither may disappear through generic inactive cleanup.
+export const RUNNING_SESSION_STATUSES = new Set(["active", "stale"]);
+export const OPEN_SESSION_STATUSES = new Set(["queued", "active", "stale", "handoff"]);
+export const isRunningSession = status => RUNNING_SESSION_STATUSES.has(status);
+export const isOpenSession = status => OPEN_SESSION_STATUSES.has(status);