@kendoo.agentdesk/agentdesk 0.27.0 → 0.28.1

package/cli/config.mjs

@@ -58,8 +58,13 @@ async function fetchServerConfig(projectName, apiKey, serverUrl) {
   }
 }
 
+// opts.readOnly — return the merged view without the two side effects
+// (auto-heal push to the server, rewrite of .agentdesk.json). Setup wizards
+// use this: they read the config at the top of the flow, before the user has
+// confirmed anything, and must not mutate disk or server state on the way in.
+// Runtime callers (`team`, `daemon`) leave it off so the cache stays fresh.
 export async function loadConfig(dir, opts = {}) {
-  const { apiKey, serverUrl, projectName, silent = false } = opts;
+  const { apiKey, serverUrl, projectName, silent = false, readOnly = false } = opts;
   const configPath = join(dir, ".agentdesk.json");
 
   // Load local .agentdesk.json
@@ -101,7 +106,7 @@ export async function loadConfig(dir, opts = {}) {
   // no row at all or a partial row), push the merged config up so the
   // server catches up. Fire-and-forget — we already have the right
   // answer in `config` for the current caller.
-  const shouldHeal = localConfig && apiKey && serverUrl && projectName && (
+  const shouldHeal = !readOnly && localConfig && apiKey && serverUrl && projectName && (
     !serverConfig || hasFieldsServerLacks(localConfig, serverConfig)
   );
   if (shouldHeal) {
@@ -113,7 +118,7 @@ export async function loadConfig(dir, opts = {}) {
   // actually fetched from the server — offline runs must not silently
   // mutate the user's local file. With mergeNonNull above, we're
   // guaranteed this write never strips existing local fields.
-  if (serverConfig) {
+  if (serverConfig && !readOnly) {
     writeLocalConfig(configPath, config);
   }
 
@@ -137,14 +142,34 @@ function hasFieldsServerLacks(local, server) {
   return false;
 }
 
+// The fields PUT /api/projects/:id/settings accepts. Anything else makes the
+// server reject the whole request with 400 "Unknown fields", and the local
+// merged config carries at least `projectKey` (the project's own id) — so
+// every heal-sync and init push used to fail silently, and the server never
+// learned the Jira project / Linear team the wizard had picked.
+const SETTINGS_FIELDS = [
+  "tracker", "linear", "jira", "github", "team", "commands", "projectAgents",
+  "instructions", "screenshots", "phaseModels", "identityBadge",
+];
+
+export function toSettingsPayload(config) {
+  const clean = stripCredentials(config || {});
+  const out = {};
+  for (const key of SETTINGS_FIELDS) {
+    if (clean[key] !== undefined) out[key] = clean[key];
+  }
+  return out;
+}
+
 // Push a config object to the server. Caller is responsible for deciding when.
+// The payload is reduced to the settings fields the server accepts.
 export async function pushConfig(apiKey, serverUrl, projectName, payload) {
   if (!apiKey || !serverUrl || !projectName) return { ok: false, error: "missing_auth" };
   try {
     const res = await fetch(`${serverUrl}/api/projects/${projectName}/settings`, {
       method: "PUT",
       headers: { "Content-Type": "application/json", "x-api-key": apiKey },
-      body: JSON.stringify(payload),
+      body: JSON.stringify(toSettingsPayload(payload)),
       signal: AbortSignal.timeout(5000),
     });
     if (!res.ok) {

package/cli/daemon.mjs

@@ -1,18 +1,16 @@
 // `agentdesk daemon` — local background daemon for UI-triggered sessions
 
-import { spawn } from "child_process";
 import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from "fs";
 import { createInterface } from "readline";
 import { join } from "path";
-import { randomUUID } from "crypto";
 import WebSocket from "ws";
 import { detectProject } from "./detect.mjs";
 import { loadConfig } from "./config.mjs";
 import { getStoredApiKey, ensureAccountIdentity } from "./login.mjs";
-import { resolveTeam, generateTeamPrompt } from "./agents.mjs";
-import { buildPrompt } from "./prompt.mjs";
-import { createStreamParser } from "./stream-parser.mjs";
-import { runOrchestrator, runPhasedOrchestrator } from "./orchestrator.mjs";
+import { resolveTeam } from "./agents.mjs";
+import { runSession } from "./engine/session.mjs";
+import { killTree } from "./proc.mjs";
+import { loadDotEnv } from "./dotenv.mjs";
 import { getRegisteredProjects, registerLocalProject, claimLocalProjects } from "./projects.mjs";
 import { buildTrackerUrl } from "./tracker-url.mjs";
 import { fileURLToPath } from "url";
@@ -60,22 +58,6 @@ class RingBuffer {
   get length() { return this.items.length; }
 }
 
-// --- Dot-env loader ---
-
-function loadDotEnv(dir) {
-  const envPath = join(dir, ".env");
-  if (!existsSync(envPath)) return {};
-  const vars = {};
-  for (const line of readFileSync(envPath, "utf-8").split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    const eq = trimmed.indexOf("=");
-    if (eq === -1) continue;
-    vars[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
-  }
-  return vars;
-}
-
 // --- Metadata logger ---
 
 function logSessionMetadata(sessionId, metadata) {
@@ -404,7 +386,7 @@ async function confirmIncomingSession({ project, taskId, prompt }) {
 
   // 4. Session handling
 
-  async function handleStartSession({ sessionId, projectId, taskId: remoteTaskId, prompt, phased, screenshots: screenshotsOverride }) {
+  async function handleStartSession({ sessionId, projectId, taskId: remoteTaskId, prompt, screenshots: screenshotsOverride }) {
     // Validate project against local allowlist
     const project = projects.find(p => p.id === projectId);
     if (!project) {
@@ -435,7 +417,16 @@ async function confirmIncomingSession({ project, taskId, prompt }) {
       return;
     }
     // Claim the slot immediately (before any await) to prevent race conditions
-    activeSession = { sessionId, projectId, child: null, startedAt: Date.now(), filePathsTouched: new Set() };
+    activeSession = {
+      sessionId, projectId,
+      child: null,
+      // Cancelling must stop the whole phase pipeline, not just the child that
+      // happens to be running: killing one phase's child would otherwise let
+      // the loop advance and spawn the next phase.
+      abort: new AbortController(),
+      startedAt: Date.now(),
+      filePathsTouched: new Set(),
+    };
 
     console.log(`  ${green}Starting session${reset} ${dim}${sessionId}${reset}`);
     console.log(`  Project: ${project.name} ${dim}(${project.path})${reset}`);
@@ -460,25 +451,31 @@ async function confirmIncomingSession({ project, taskId, prompt }) {
       // Build task link (only when a real tracker task ID was provided)
       const taskLink = remoteTaskId ? buildTrackerUrl({ tracker, config, taskId: remoteTaskId }) : null;
 
-      // Resolve team
       const team = resolveTeam(config);
-      const teamSections = generateTeamPrompt(team, { tracker, config });
 
       const sessionUrl = `${agentdeskServer}/sessions/${sessionId}`;
 
-      // Run orchestrator
-      const orchestrate = phased ? runPhasedOrchestrator : runOrchestrator;
-      const result = await orchestrate({
+      // Run the engine (real subagents, one query per phase). The server may
+      // still send `phased`; every session is phased now.
+      const sessionAbort = activeSession.abort;
+      const result = await runSession({
         taskId, taskLink,
         description: prompt || "",
         createTask: !remoteTaskId && !!prompt && !!tracker,
         tracker, config,
-        project: detected, team, teamSections,
+        project: detected, team,
         sessionUrl,
         sessionId,
         cwd: project.path,
         apiKey,
         serverUrl: agentdeskServer,
+        abortSignal: sessionAbort.signal,
+        // Hand the live child up so cancel/shutdown can actually kill it.
+        // This was never wired: activeSession.child stayed null forever, so
+        // every cancel reported "stopped" while Claude kept writing to the repo.
+        onChild: (child) => {
+          if (activeSession?.sessionId === sessionId) activeSession.child = child;
+        },
         onEvent: (() => {
           // Stagger agent messages for real-time feel, flush on non-message events
           const MSG_STAGGER_MS = 400;
@@ -504,6 +501,9 @@ async function confirmIncomingSession({ project, taskId, prompt }) {
 
           return (event) => {
             if (!activeSession || activeSession.sessionId !== sessionId) return;
+            // A cancelled session already sent its terminal event; the
+            // orchestrator's own unwind must not send a second one.
+            if (activeSession.cancelled) return;
 
             if (event.type === "agent:message") {
               msgQueue.push(event);
@@ -528,12 +528,21 @@ async function confirmIncomingSession({ project, taskId, prompt }) {
         })(),
       });
 
-      console.log(`  ${green}Session complete${reset} ${dim}${sessionId}${reset} (${result.duration}, ${result.steps} steps)`);
+      const outcome = result.status || (result.handoff ? "handoff" : "complete");
+      const clean = outcome === "complete";
+      console.log(
+        `  ${clean ? green : yellow}Session ${outcome}${reset} ${dim}${sessionId}${reset} (${result.duration}, ${result.steps} steps)`
+      );
 
       logSessionMetadata(sessionId, {
         sessionId, projectId,
         startedAt, endedAt: Date.now(),
-        duration: result.duration, exitCode: 0, steps: result.steps,
+        duration: result.duration,
+        // Was hardcoded to 0, so the metadata log claimed every session
+        // exited cleanly regardless of what actually happened.
+        exitCode: clean ? 0 : 1,
+        status: outcome,
+        steps: result.steps,
         filePathsTouched: [...filePathsTouched],
       });
 
@@ -547,24 +556,43 @@ async function confirmIncomingSession({ project, taskId, prompt }) {
     }
   }
 
-  function killChild(child) {
-    if (!child) return;
-    try { child.kill("SIGTERM"); } catch {}
-    // Force kill if SIGTERM doesn't work within 5 seconds
-    setTimeout(() => {
-      try { if (!child.killed) child.kill("SIGKILL"); } catch {}
-    }, 5000);
+  // Tear down a session's work: signal the orchestrator loop to stop enqueuing
+  // phases, then kill the running child's whole process group. Both halves are
+  // required — killing the child alone just makes the loop start the next phase.
+  function stopSessionWork(session) {
+    if (!session) return;
+    try { session.abort?.abort(); } catch {}
+    killTree(session.child);
   }
 
   function handleCancelSession({ sessionId }) {
     if (activeSession?.sessionId === sessionId) {
       console.log(`  ${yellow}Cancelling session${reset} ${dim}${sessionId}${reset}`);
       const duration = `${((Date.now() - activeSession.startedAt) / 1000).toFixed(1)}s`;
-      killChild(activeSession.child);
-      // Clear active session BEFORE sending session:end — this prevents
-      // the orchestrator's onEvent callback from sending a duplicate
-      activeSession = null;
+
+      // Mark rather than clear. Nulling activeSession here would free the
+      // concurrency slot immediately — while the child is still inside its
+      // SIGTERM grace period — letting a second session start against the same
+      // working tree. The slot is released where it always was: after the
+      // orchestrator await unwinds, which cancellation now guarantees.
+      activeSession.cancelled = true;
+      stopSessionWork(activeSession);
+
+      // The `cancelled` flag also suppresses the orchestrator's own
+      // session:end, so this stays the single terminal event for the session.
       sendBuffered(sessionId, { type: "session:end", duration, steps: 0, inputTokens: 0, outputTokens: 0, status: "stopped" });
+
+      // Safety valve: if the child somehow never dies, don't wedge the daemon
+      // into rejecting every future session.
+      const wedged = activeSession;
+      const timer = setTimeout(() => {
+        if (activeSession === wedged) {
+          console.log(`  ${red}Cancelled session did not exit — releasing slot${reset}`);
+          killTree(wedged.child, { graceMs: 0 });
+          activeSession = null;
+        }
+      }, 30000);
+      timer.unref?.();
     }
   }
 
@@ -576,7 +604,7 @@ async function confirmIncomingSession({ project, taskId, prompt }) {
     clearTimeout(reconnectTimer);
 
     if (activeSession) {
-      killChild(activeSession.child);
+      stopSessionWork(activeSession);
     }
 
     send({ type: "daemon:disconnect" });

package/cli/dotenv.mjs

@@ -1,22 +1,105 @@
-// Minimal .env reader used by orchestrator + preflight. Does not interpret
-// quotes or escapes — matches the pre-existing behavior of the duplicated
-// loaders in cli/team.mjs, cli/init.mjs, and cli/daemon.mjs (which we are
-// NOT consolidating in this PR — out of scope).
+// The one .env reader/writer for the CLI.
+//
+// There used to be five copies of the loader (here, setup-helpers, bootstrap,
+// daemon, team) and two of the writer. None stripped quotes, so a perfectly
+// conventional line like
+//
+//     GITHUB_TOKEN="ghp_abc123"
+//
+// produced a token with literal quote characters in it and a baffling 401 from
+// GitHub. A fix had to be applied five times to land. Every caller now imports
+// from here.
+//
+// Deliberately minimal: quotes are stripped, `export KEY=…` is tolerated,
+// comments and blanks are skipped. Escape sequences and `${VAR}` interpolation
+// are NOT interpreted — a token is an opaque string and must round-trip as-is.
 
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, chmodSync } from "fs";
 import { join } from "path";
 
+export function parseDotEnv(text) {
+  const vars = {};
+  for (const rawLine of String(text ?? "").split(/\r?\n/)) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    if (line.startsWith("export ")) line = line.slice(7).trim();
+
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+
+    const key = line.slice(0, eq).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+
+    let value = line.slice(eq + 1).trim();
+    const quote = value[0];
+    if ((quote === '"' || quote === "'") && value.length >= 2 && value.endsWith(quote)) {
+      value = value.slice(1, -1);
+    }
+    vars[key] = value;
+  }
+  return vars;
+}
+
 export function loadDotEnv(dir) {
   if (!dir) return {};
   const envPath = join(dir, ".env");
   if (!existsSync(envPath)) return {};
-  const vars = {};
-  for (const line of readFileSync(envPath, "utf-8").split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    const eq = trimmed.indexOf("=");
-    if (eq === -1) continue;
-    vars[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
+  try {
+    return parseDotEnv(readFileSync(envPath, "utf-8"));
+  } catch {
+    return {};
   }
-  return vars;
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// Upsert KEY=value in <dir>/.env, preserving every other line verbatim.
+//
+// The file ends up mode 0600 whether it was just created or already existed —
+// `writeFileSync`'s `mode` option only applies on creation, so an existing
+// world-readable .env would otherwise stay world-readable after we drop a
+// GitHub token into it.
+export function saveEnvVar(dir, key, value) {
+  const envPath = join(dir, ".env");
+  let content = existsSync(envPath) ? readFileSync(envPath, "utf-8") : "";
+  const re = new RegExp(`^(?:export\\s+)?${escapeRegex(key)}=.*$`, "m");
+  const entry = `${key}=${value}`;
+  if (re.test(content)) {
+    content = content.replace(re, entry);
+  } else {
+    content += `${content && !content.endsWith("\n") ? "\n" : ""}${entry}\n`;
+  }
+  writeFileSync(envPath, content, { mode: 0o600 });
+  try { chmodSync(envPath, 0o600); } catch {}
+  return envPath;
+}
+
+// Make sure each of `entries` is listed in <dir>/.gitignore. Returns the
+// entries that had to be added (empty when everything was already covered).
+//
+// Matching is deliberately loose about the forms people actually write —
+// `.env`, `/.env`, `.agentdesk`, `.agentdesk/` — and deliberately NOT clever
+// about globs: `.env*` is not treated as covering `.env`, because a rule we
+// can't reason about is a rule we shouldn't rely on for a credential file.
+export function ensureGitignored(dir, entries) {
+  const path = join(dir, ".gitignore");
+  const existing = existsSync(path) ? readFileSync(path, "utf-8") : "";
+  const present = new Set(
+    existing.split(/\r?\n/).map(l => l.trim().replace(/^\//, "").replace(/\/$/, "")).filter(Boolean)
+  );
+
+  const added = [];
+  for (const entry of entries) {
+    const norm = entry.replace(/^\//, "").replace(/\/$/, "");
+    if (present.has(norm)) continue;
+    added.push(entry);
+    present.add(norm);
+  }
+  if (added.length === 0) return added;
+
+  const nl = existing && !existing.endsWith("\n") ? "\n" : "";
+  writeFileSync(path, `${existing}${nl}${added.join("\n")}\n`);
+  return added;
 }

package/cli/engine/agents/index.mjs

@@ -0,0 +1,152 @@
+// Persona registry → Agent SDK definitions.
+//
+// The team (cli/agents.mjs BUILT_IN_AGENTS + project customisations via
+// resolveTeam) becomes, per phase:
+//   - one lead definition — Jane — that the main thread runs *as* (Options.agent),
+//     with the Agent tool and nothing else. She cannot touch code because the
+//     tools do not exist in her session.
+//   - one AgentDefinition per engineering role, with the tool list that role
+//     needs in that phase and nothing more.
+//
+// Tool lists are the enforcement; prompts describe intent. hooks.mjs is the
+// belt to these braces.
+
+import { BUILT_IN_AGENTS } from "../../agents.mjs";
+
+export const LEAD = "Jane";
+export const READ_ONLY = Object.freeze(["Read", "Grep", "Glob"]);
+const RO_BASH = Object.freeze([...READ_ONLY, "Bash"]);
+const FULL = Object.freeze(["Read", "Edit", "Write", "Bash", "Grep", "Glob"]);
+
+// Which built-in agents take part in each phase, and with which tools.
+export const PHASE_ROSTER = Object.freeze({
+  INTAKE:    { Dennis: RO_BASH },
+  PLAN:      { Dennis: READ_ONLY, Sam: READ_ONLY, Vera: READ_ONLY, Luna: READ_ONLY, Mark: READ_ONLY, Nora: READ_ONLY },
+  EXECUTION: { Dennis: FULL, Sam: READ_ONLY, Vera: FULL, Bart: RO_BASH, Luna: RO_BASH, Mark: READ_ONLY, Nora: FULL },
+  // Reviewers read the diff cold and may run read-only commands (tests, git
+  // log). None of them can edit — fixes happen back in EXECUTION.
+  REVIEW:    { Sam: READ_ONLY, Bart: RO_BASH, Vera: RO_BASH },
+  SUMMARY:   { Dennis: RO_BASH },
+});
+
+// Phases where project-defined custom agents (config.projectAgents) join.
+const CUSTOM_AGENT_PHASES = new Set(["PLAN", "EXECUTION"]);
+
+// Today's defaults: REVIEW and SUMMARY on haiku, the rest on the CLI default.
+// `phaseModels` values are "opus" | "sonnet" | "haiku" | "default" | undefined.
+export function modelForPhase(phase, phaseModels = {}) {
+  const choice = phaseModels?.[phase];
+  if (choice && choice !== "default") return choice;
+  if (phase === "REVIEW" || phase === "SUMMARY") return "haiku";
+  return undefined; // let the SDK/CLI pick its default
+}
+
+const PHASE_GUIDANCE = {
+  INTAKE: "Phase INTAKE: gather the task, its attachments and the repo context. Report facts. Do not plan the implementation and do not write code.",
+  PLAN: "Phase PLAN: assess the approach from your role's angle and report a concrete plan contribution. Do not modify any files.",
+  EXECUTION: "Phase EXECUTION: do your role's part of the plan. Verify every claim with an observation (command output, test result, rendered page) before reporting it.",
+  REVIEW: "Phase REVIEW: you are reviewing a diff you did not write. Report concrete findings with file:line. Be strict but not pedantic — only real gaps against the task and the plan. Do not modify anything.",
+  SUMMARY: "Phase SUMMARY: execute exactly the tracker writes the lead dictates and confirm each with the command's output.",
+};
+
+function executionTasks(a) {
+  const tasks = a.execution?.tasks;
+  if (!Array.isArray(tasks) || tasks.length === 0) return "";
+  return `\nYour execution checklist:\n${tasks.map((t, i) => `${i + 1}. ${t}`).join("\n")}\n`;
+}
+
+export function agentSystemPrompt(a, phase) {
+  return [
+    `You are ${a.name}, ${a.role} on an AgentDesk software team led by ${LEAD}.`,
+    `Role: ${a.description}.`,
+    a.groundRules ? `Ground rules: ${a.groundRules}` : "",
+    a.codePrinciple ? `Code principle: ${a.codePrinciple}` : "",
+    "",
+    PHASE_GUIDANCE[phase] || "",
+    phase === "EXECUTION" ? executionTasks(a) : "",
+    "",
+    "No announcement without observation: never claim something is done, passes, or works unless you ran the check and read its output. If the observation is out of reach, say so plainly.",
+    `Report back to ${LEAD} concisely. You may prefix a message with [THINK], [ACT], [ARGUE] or [AGREE] to make your stance clear.`,
+  ].filter(l => l !== null && l !== undefined).join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+function rosterLine(name, def) {
+  return `- ${name} (${def.role}) — ${def.description}. Tools: ${def.tools.join(", ")}.`;
+}
+
+export function leadSystemPrompt(roster, phase) {
+  const jane = BUILT_IN_AGENTS.Jane;
+  const lines = Object.entries(roster).map(([n, d]) => rosterLine(n, d));
+  return [
+    `You are ${LEAD}, ${jane.role}. ${jane.description}.`,
+    "",
+    "You coordinate; you do not build. You have exactly one tool — Agent — and you use it to delegate to the team. You never read files, run commands, or edit anything yourself; when you need technical information, ask an agent for it.",
+    "Always delegate with run_in_background: false. A backgrounded agent's own tool calls cannot be approved, so it will be unable to do anything.",
+    "Your language is product-only: user stories, acceptance criteria, scope, priorities, stakeholder impact.",
+    "",
+    `Team available in phase ${phase}:`,
+    ...lines,
+    "",
+    "When you delegate, give the agent everything it needs in the prompt: the task, the relevant decisions so far, and exactly what to report back. Agents start with no memory of this conversation.",
+    "When an agent reports, relay the substance in one to three lines and move on. Never claim a result you did not receive from an agent.",
+    "Announce a new task id, if you create one, on its own line as `TASK_ID: <id>`, and a short session title as `SESSION_TITLE: <title>`.",
+  ].join("\n");
+}
+
+// Solo mode: the named agent IS the main thread, with the full tool set and
+// no subagents. Its system prompt is the phase template (renderSoloPrompt), so
+// the AgentDefinition prompt stays a short identity line.
+export function soloDefinition(agent) {
+  const def = {
+    description: `${agent.role}: ${agent.description}`,
+    prompt: `You are ${agent.name}, ${agent.role}. You work alone on the task given to you, end to end.`,
+    tools: [...FULL],
+  };
+  return { agents: { [agent.name]: def }, allowedTools: [...FULL], lead: agent.name };
+}
+
+// team        — resolveTeam(config) output (array of { name, role, description, ... })
+// phase       — one of PHASES
+// phaseModels — config.phaseModels
+// Returns { agents: Record<name, AgentDefinition>, allowedTools: string[], lead: "Jane" }
+export function agentsForPhase({ phase, team, phaseModels = {} }) {
+  const roster = PHASE_ROSTER[phase] || {};
+  const subagentModel = (phase === "REVIEW" || phase === "SUMMARY") ? modelForPhase(phase, phaseModels) : "inherit";
+
+  const agents = {};
+  for (const a of team) {
+    if (a.name === LEAD) continue;
+    const isBuiltIn = !!BUILT_IN_AGENTS[a.name];
+    let tools;
+    if (isBuiltIn) {
+      tools = roster[a.name];
+      if (!tools) continue; // this role has no part in this phase
+    } else {
+      if (!CUSTOM_AGENT_PHASES.has(phase)) continue;
+      tools = Array.isArray(a.tools) && a.tools.length ? a.tools : READ_ONLY;
+    }
+    agents[a.name] = {
+      description: `${a.role}: ${a.description}`,
+      prompt: agentSystemPrompt(a, phase),
+      tools: [...tools],
+      model: subagentModel,
+      role: a.role,
+    };
+  }
+
+  // Strip our bookkeeping field before handing definitions to the SDK.
+  const sdkAgents = {};
+  for (const [name, def] of Object.entries(agents)) {
+    sdkAgents[name] = { description: def.description, prompt: def.prompt, tools: def.tools, model: def.model };
+  }
+  sdkAgents[LEAD] = {
+    description: `${BUILT_IN_AGENTS.Jane.role}: ${BUILT_IN_AGENTS.Jane.description}`,
+    prompt: leadSystemPrompt(agents, phase),
+    tools: ["Agent"],
+  };
+
+  const allowed = new Set(["Agent"]);
+  for (const def of Object.values(sdkAgents)) for (const t of def.tools) allowed.add(t);
+
+  return { agents: sdkAgents, allowedTools: [...allowed], lead: LEAD };
+}

package/cli/engine/claude-auth.mjs

@@ -0,0 +1,72 @@
+// Can a *standalone* Claude process authenticate on this machine?
+//
+// Setup used to check GitHub and the tracker and never Claude itself, so a
+// new user reached their first session and got "Not logged in" from deep
+// inside the engine. An interactive `claude` working in the user's terminal
+// is not proof: it may be inheriting auth from a parent session that our
+// child processes cannot reach.
+//
+// The check runs the same binary the engine will spawn, with the same
+// scrubbed environment, and reads `claude auth status`.
+
+import { execFile } from "child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "path";
+import { stripParentSessionVars } from "./env.mjs";
+
+export function bundledClaudePath() {
+  const platformPkg = `@anthropic-ai/claude-agent-sdk-${process.platform}-${process.arch}`;
+  try {
+    const pkgDir = dirname(createRequire(import.meta.url).resolve(`${platformPkg}/package.json`));
+    return join(pkgDir, process.platform === "win32" ? "claude.exe" : "claude");
+  } catch {
+    return null;
+  }
+}
+
+export function claudeBinary(env = process.env) {
+  return env.AGENTDESK_CLAUDE_PATH || bundledClaudePath() || "claude";
+}
+
+export const CLAUDE_LOGIN_HINT = [
+  "Claude Code has no login that a standalone session can use.",
+  "Fix one of:",
+  "  • run `claude auth login` in this terminal (if you use account profiles,",
+  "    the same CLAUDE_CONFIG_DIR you will run agentdesk with), then re-run;",
+  "  • or add ANTHROPIC_API_KEY=<key> to the project's .env.",
+].join("\n");
+
+function run(exec, bin, args, env, timeoutMs) {
+  return new Promise(resolve => {
+    exec(bin, args, { env, timeout: timeoutMs, maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+      resolve({ err, stdout: String(stdout || ""), stderr: String(stderr || "") });
+    });
+  });
+}
+
+// Returns { ok, method, detail, hint? }.
+//   env  — the environment the session child will get (dotenv + sandbox applied)
+//   exec — injectable for tests (child_process.execFile signature)
+export async function checkClaudeAuth({ env = process.env, exec = execFile, timeoutMs = 10000 } = {}) {
+  if (env.ANTHROPIC_API_KEY) return { ok: true, method: "api-key", detail: "ANTHROPIC_API_KEY" };
+
+  const bin = claudeBinary(env);
+  const { err, stdout } = await run(exec, bin, ["auth", "status"], stripParentSessionVars(env), timeoutMs);
+
+  if (err && !stdout) {
+    const detail = err.code === "ENOENT"
+      ? `Claude binary not found (${bin})`
+      : `could not run \`claude auth status\` (${err.message || err.code})`;
+    return { ok: false, method: "unknown", detail, hint: CLAUDE_LOGIN_HINT };
+  }
+
+  let status;
+  try { status = JSON.parse(stdout); } catch {
+    return { ok: false, method: "unknown", detail: "unexpected output from `claude auth status`", hint: CLAUDE_LOGIN_HINT };
+  }
+
+  if (status.loggedIn === true) {
+    return { ok: true, method: status.authMethod || "oauth", detail: status.email || status.authMethod || "logged in" };
+  }
+  return { ok: false, method: "none", detail: "not logged in", hint: CLAUDE_LOGIN_HINT };
+}