@kendoo.agentdesk/agentdesk 0.27.0 → 0.28.1

package/cli/phase-loop.mjs

@@ -0,0 +1,78 @@
+// Pure decision logic for the phased orchestrator loop.
+//
+// Extracted from orchestrator.mjs so the control flow that decides "did this
+// session actually succeed" is unit-testable without spawning Claude. Every
+// function here is pure or filesystem-read-only; nothing spawns, emits, or
+// mutates session state.
+
+import { existsSync, readFileSync, renameSync, unlinkSync } from "fs";
+
+export const PHASES = ["INTAKE", "PLAN", "EXECUTION", "REVIEW", "SUMMARY"];
+
+// One execution redo after a failed review, then the session ends unresolved.
+export const MAX_REVIEW_RETRIES = 1;
+
+// Absolute ceiling on phase runs. The review loop re-enqueues phases, so a bug
+// in verdict parsing must not be able to spin forever burning tokens. With
+// MAX_REVIEW_RETRIES=1 a legitimate run tops out at 7 (5 + EXECUTION + REVIEW).
+export const MAX_PHASE_RUNS = 10;
+
+// Classify the first line of `.agentdesk/review-verdict.md`.
+//
+// FAIL CLOSED: anything that is not an explicit APPROVED is treated as
+// unapproved. A REVIEW phase that crashed, hit a limit, or simply forgot to
+// write the file must never be indistinguishable from one that passed.
+export function reviewOutcome(raw) {
+  if (raw == null) return "MISSING";
+  const firstLine = String(raw).trim().split(/\r?\n/)[0]?.trim().toUpperCase() ?? "";
+  if (!firstLine) return "MISSING";
+  if (/^NEEDS_MORE_WORK\b/.test(firstLine)) return "NEEDS_MORE_WORK";
+  if (/^APPROVED\b/.test(firstLine)) return "APPROVED";
+  // Unrecognised content is not approval.
+  return "MISSING";
+}
+
+export function readReviewVerdict(path) {
+  try {
+    if (!existsSync(path)) return "MISSING";
+    return reviewOutcome(readFileSync(path, "utf-8"));
+  } catch {
+    return "MISSING";
+  }
+}
+
+// A phase run failed if the process exited non-zero, full stop.
+//
+// This used to be gated on `!existsSync(session-memory.md)`, which made it
+// dead code: INTAKE writes that file, so from phase one onward no crash was
+// ever detected and every broken session reported "complete".
+export function phaseFailed({ exitCode, aborted }) {
+  if (aborted) return false; // cancellation is not a crash — reported separately
+  return exitCode !== 0;
+}
+
+// Terminal status for the session, in precedence order.
+export function finalStatus({ aborted, crashed, reviewResolved }) {
+  if (aborted) return "stopped";
+  if (crashed) return "handoff";
+  // Review never reached APPROVED — a human has to pick this up. Reuses the
+  // existing "handoff" status rather than inventing one the dashboard and
+  // server store would not recognise.
+  if (!reviewResolved) return "handoff";
+  return "complete";
+}
+
+// Move a previous run's session memory aside so it cannot leak into this one.
+//
+// Kept (as .prev.md) rather than deleted: it is the only artifact explaining
+// what a crashed prior session believed it had done.
+export function archiveStaleMemory(sessionMemoryPath) {
+  try {
+    if (!existsSync(sessionMemoryPath)) return false;
+    renameSync(sessionMemoryPath, `${sessionMemoryPath.replace(/\.md$/, "")}.prev.md`);
+    return true;
+  } catch {
+    try { unlinkSync(sessionMemoryPath); return true; } catch {}
+    return false;
+  }
+}

package/cli/proc.mjs

@@ -0,0 +1,131 @@
+// Process-tree termination for spawned Claude children.
+//
+// Why this exists: `claude` is not a leaf process. It spawns Bash
+// grandchildren that write to the project working tree. Signalling only the
+// direct child leaves those grandchildren running — which is precisely the
+// state a cancel is meant to prevent. So children are spawned detached (their
+// own process group) and torn down by group.
+//
+// Every spawned child is also tracked here so that an unexpected parent exit
+// (SIGINT from the terminal, daemon shutdown) does not orphan a Claude process
+// that keeps committing and pushing after the dashboard says the session is
+// over. This matters more than usual because the scratch HOME is deleted on
+// exit — an orphaned child would keep running with its credentials yanked
+// out from under it, mid-push.
+
+const live = new Set();
+
+// Send `sig` to the child's whole process group, falling back to the single
+// pid when the child was not detached or the group is already gone.
+function signalGroup(pid, sig) {
+  try {
+    process.kill(-pid, sig);
+    return true;
+  } catch {}
+  try {
+    process.kill(pid, sig);
+    return true;
+  } catch {}
+  return false;
+}
+
+export function hasExited(child) {
+  return !child || child.exitCode !== null || child.signalCode !== null;
+}
+
+// SIGTERM the tree, then SIGKILL anything still alive after `graceMs`.
+// Returns true when a signal was actually delivered.
+export function killTree(child, { graceMs = 5000 } = {}) {
+  if (hasExited(child) || !child.pid) return false;
+
+  const pid = child.pid;
+  const delivered = signalGroup(pid, "SIGTERM");
+  if (!delivered) return false;
+
+  const timer = setTimeout(() => {
+    if (!hasExited(child)) signalGroup(pid, "SIGKILL");
+  }, graceMs);
+  // Never let the force-kill timer hold the event loop open.
+  timer.unref?.();
+  child.once("close", () => clearTimeout(timer));
+
+  return true;
+}
+
+// Register a child for teardown-on-parent-exit. Returns an untrack function.
+export function trackChild(child) {
+  if (!child) return () => {};
+  live.add(child);
+  const drop = () => live.delete(child);
+  child.once("close", drop);
+  return drop;
+}
+
+export function killAllTracked({ graceMs = 0 } = {}) {
+  for (const child of [...live]) {
+    live.delete(child);
+    // On a hard parent exit there is no time to wait out a grace period —
+    // the exit handler runs synchronously and the timer would never fire.
+    if (graceMs === 0) {
+      if (!hasExited(child) && child.pid) signalGroup(child.pid, "SIGKILL");
+    } else {
+      killTree(child, { graceMs });
+    }
+  }
+}
+
+export function trackedCount() {
+  return live.size;
+}
+
+// Cleanups that must run before the process goes away — currently the scratch
+// HOME teardown, which holds live credentials on disk.
+//
+// Centralised here so there is exactly one set of signal handlers. Registering
+// them in several modules means whichever one calls process.exit() first wins
+// and the others silently never run.
+const terminators = new Set();
+
+export function onTerminate(fn) {
+  terminators.add(fn);
+  return () => terminators.delete(fn);
+}
+
+function runTerminators() {
+  for (const fn of [...terminators]) {
+    terminators.delete(fn);
+    try { fn(); } catch {}
+  }
+}
+
+let installed = false;
+// Idempotent: multiple orchestrator runs in one process share one set of hooks.
+export function installExitGuards() {
+  if (installed) return;
+  installed = true;
+
+  process.once("exit", () => {
+    // Children first: they must not outlive the credentials they are using.
+    killAllTracked({ graceMs: 0 });
+    runTerminators();
+  });
+
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(sig, () => {
+      // Defer to the app's own handler when there is one: `agentdesk team`
+      // and the daemon both shut down gracefully on SIGINT (abort the run,
+      // report the real status, close the socket). Exiting from here would
+      // preempt that and leave the server showing a session that never ended.
+      //
+      // This listener is a last resort for the case where nothing else is
+      // handling the signal — without it, Node's default disposition
+      // terminates the process without running `exit` handlers at all, and
+      // every spawned Claude is orphaned.
+      if (process.listenerCount(sig) > 1) return;
+
+      killAllTracked({ graceMs: 0 });
+      runTerminators();
+      process.exit(sig === "SIGINT" ? 130 : 143);
+    });
+  }
+}

package/cli/project-key.mjs

@@ -0,0 +1,56 @@
+// Project key derivation and collision handling for `agentdesk init`.
+//
+// A project key is the server-side id and the URL segment for a project. New
+// mode derives it from the tracker team/project (e.g. Linear team "KEN" →
+// "ken"), which reads well but is not unique: two repos mapped to the same
+// team derive the same key, and the second `PUT /settings` silently
+// overwrote the first repo's configuration. resolveProjectKey detects that
+// and qualifies the key with the repo name instead.
+//
+// Pure functions; the caller fetches `existing` from the server.
+
+export function slugify(s) {
+  return String(s ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+export function deriveProjectKey({ trackerId, repoShort }) {
+  return slugify(trackerId || repoShort || "project");
+}
+
+const norm = r => (r ? String(r).toLowerCase() : null);
+
+// existing: [{ id, repo }] — every project on the account with its
+// configured github.repo (null when unknown).
+//
+// A key is only a collision when it is taken by a project whose repo is
+// known AND different from ours. Same repo means this IS our project being
+// re-initialised (`init --force-full` to re-push settings), and reusing the
+// key is the intended behaviour. Unknown repo on either side is treated as
+// "ours" too: a project with no GitHub repo cannot run sessions, so there is
+// nothing there to clobber.
+export function resolveProjectKey({ baseKey, repo, repoShort, existing = [] }) {
+  const ours = norm(repo);
+  const byId = new Map(existing.map(p => [p.id, { id: p.id, repo: norm(p.repo) }]));
+
+  const takenByOtherRepo = key => {
+    const hit = byId.get(key);
+    if (!hit) return null;
+    if (!ours || !hit.repo || hit.repo === ours) return null;
+    return hit;
+  };
+
+  const first = takenByOtherRepo(baseKey);
+  if (!first) return { key: baseKey, renamed: false };
+
+  const qualified = slugify(`${baseKey}-${repoShort || "repo"}`);
+  if (!takenByOtherRepo(qualified)) {
+    return { key: qualified, renamed: true, collidedWith: first };
+  }
+  for (let n = 2; n < 100; n++) {
+    const candidate = `${qualified}-${n}`;
+    if (!takenByOtherRepo(candidate)) {
+      return { key: candidate, renamed: true, collidedWith: first };
+    }
+  }
+  return { key: `${qualified}-${Date.now()}`, renamed: true, collidedWith: first };
+}