@kendoo.agentdesk/agentdesk 0.26.0 → 0.28.0

package/cli/session-isolation.mjs

@@ -22,8 +22,8 @@
 // "scoped env" rather than "kernel boundary."
 
 import { execSync } from "child_process";
-import { existsSync, writeFileSync } from "fs";
-import { join } from "path";
+import {  writeFileSync } from "fs";
+import { join, dirname } from "path";
 import { platform, homedir } from "os";
 
 // Detect which kernel-isolation tool is usable. Cached after first probe.
@@ -65,7 +65,12 @@ function legacyMode() {
 // Build the spawn arguments for an isolated claude invocation. Takes the
 // original command/args/options and returns the wrapped form, plus a flag
 // indicating which isolation mode is active.
-export function wrapIsolatedSpawn({ cmd, args, cwd, scratchHome, sessionId }) {
+//
+// extraReadPaths: additional directories to expose read-only under the strict
+// policy. The engine passes the Agent SDK's bundled Claude binary here — it
+// lives under an npm prefix (global or the project's node_modules), which the
+// deny-default allowlist does not necessarily cover.
+export function wrapIsolatedSpawn({ cmd, args, cwd, scratchHome, extraReadPaths = [] }) {
   const probe = probeIsolation();
   if (probe.kind === "none") {
     return { cmd, args, isolation: { kind: "none", reason: probe.reason } };
@@ -77,7 +82,7 @@ export function wrapIsolatedSpawn({ cmd, args, cwd, scratchHome, sessionId }) {
     const profilePath = join(scratchHome, "sandbox.sb");
     const profile = policyKind === "legacy"
       ? macosProfileLegacy({ cwd, scratchHome })
-      : macosProfileStrict({ cwd, scratchHome });
+      : macosProfileStrict({ cwd, scratchHome, extraReadPaths });
     writeFileSync(profilePath, profile, { mode: 0o600 });
     return {
       cmd: "sandbox-exec",
@@ -89,7 +94,7 @@ export function wrapIsolatedSpawn({ cmd, args, cwd, scratchHome, sessionId }) {
   if (probe.kind === "bwrap") {
     const bwrap = policyKind === "legacy"
       ? bwrapArgsLegacy({ cwd, scratchHome })
-      : bwrapArgsStrict({ cwd, scratchHome });
+      : bwrapArgsStrict({ cwd, scratchHome, extraReadPaths });
     return {
       cmd: "bwrap",
       args: [...bwrap, cmd, ...args],
@@ -110,9 +115,20 @@ function sbString(s) {
 // paths and capabilities legitimate tools need. Anything under $HOME that
 // isn't explicitly allowed is unreadable — that includes ~/Documents,
 // browser cookie stores, other projects' .env files, etc.
-function macosProfileStrict({ cwd, scratchHome }) {
+function macosProfileStrict({ cwd, scratchHome, extraReadPaths = [] }) {
   const home = homedir();
 
+  // AD-65: Claude walks up from cwd (git root, CLAUDE.md, project lookups) and
+  // aborts if an ancestor directory node is unreadable. Grant the directory
+  // nodes themselves (literal = stat + listing), NOT their contents.
+  const ancestorDirs = [];
+  for (let dir = cwd; ; ) {
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    ancestorDirs.push(parent);
+    dir = parent;
+  }
+
   // Tool installations and caches users typically need read access to. If a
   // path doesn't exist we still list it — sandbox-exec ignores missing paths.
   const userToolPaths = [
@@ -150,6 +166,33 @@ function macosProfileStrict({ cwd, scratchHome }) {
     `(allow file-read* file-write* (subpath ${sbString(cwd)}))`,
     `(allow file-read* file-write* (subpath ${sbString(scratchHome)}))`,
     ``,
+    `; Root directory + top-level symlinks (/etc → /private/etc, /var, /tmp).`,
+    `; dyld stats "/" during process startup on modern macOS; denying it aborts`,
+    `; every child before main() (AD-65).`,
+    `(allow file-read* (literal "/") (literal "/etc") (literal "/var") (literal "/tmp"))`,
+    ``,
+    `; Ancestor directory nodes of cwd — dir listing/stat only, not contents (AD-65).`,
+    ...ancestorDirs.map(p => `(allow file-read* (literal ${sbString(p)}))`),
+    ``,
+    `; Claude's own state — it authenticates and persists session state here.`,
+    `(allow file-read* file-write* (subpath ${sbString(join(home, ".claude"))}))`,
+    `(allow file-read* file-write* (prefix ${sbString(join(home, ".claude.json"))}))`,
+    `(allow file-read* file-write* (subpath ${sbString(join(home, ".config", "claude"))}))`,
+    // Account profiles: CLAUDE_CONFIG_DIR relocates all of the above. Without
+    // this a profile user's child cannot read its own credentials and reports
+    // "Not logged in" inside the sandbox.
+    ...(process.env.CLAUDE_CONFIG_DIR
+      ? [`(allow file-read* file-write* (subpath ${sbString(process.env.CLAUDE_CONFIG_DIR)}))`]
+      : []),
+    ``,
+    `; macOS Keychain — Claude Code stores its OAuth session there. The Security`,
+    `; framework opens the login keychain database directly; with it denied the`,
+    `; child reports "Not logged in" even when the machine is logged in.`,
+    `(allow file-read* (subpath ${sbString(join(home, "Library", "Keychains"))}))`,
+    `(allow file-read* (subpath "/private/var/db/mds"))`,
+    `(allow file-read* file-write* (subpath "/private/var/folders"))`,
+    `(allow ipc-posix-shm)`,
+    ``,
     `; System binaries and libraries — read-only.`,
     `(allow file-read* (subpath "/usr"))`,
     `(allow file-read* (subpath "/bin"))`,
@@ -182,12 +225,15 @@ function macosProfileStrict({ cwd, scratchHome }) {
     `; readable from inside the sandbox.`,
     ...userToolPaths.map(p => `(allow file-read* file-write* (subpath ${sbString(p)}))`),
     ``,
+    `; Caller-supplied read-only paths (e.g. the Agent SDK's bundled Claude binary).`,
+    ...extraReadPaths.filter(Boolean).map(p => `(allow file-read* (subpath ${sbString(p)}))`),
+    ``,
   ].join("\n");
 }
 
 // Pre-AD-30 denylist — kept as opt-in fallback via AGENTDESK_SANDBOX_LEGACY=1
 // in case the strict policy breaks a tool we haven't accounted for.
-function macosProfileLegacy({ cwd, scratchHome }) {
+function macosProfileLegacy() {
   const home = homedir();
   const denyPathsSubpath = [
     join(home, ".ssh"),
@@ -227,7 +273,7 @@ function macosProfileLegacy({ cwd, scratchHome }) {
 // AD-30 strict allowlist via bwrap. Read-only binds for system paths, --tmpfs
 // over $HOME so nothing on the user's home directory is visible by default,
 // then re-expose specific tool dirs that exist as read-only binds.
-function bwrapArgsStrict({ cwd, scratchHome }) {
+function bwrapArgsStrict({ cwd, scratchHome, extraReadPaths = [] }) {
   const home = homedir();
   const args = [
     "--die-with-parent",
@@ -254,6 +300,12 @@ function bwrapArgsStrict({ cwd, scratchHome }) {
     "--bind", scratchHome, scratchHome,
     // Network is intentionally NOT unshared — agents need tracker APIs and git.
   ];
+  // Claude's own state under $HOME (blanked by the tmpfs above) — and the
+  // relocated equivalent when the user runs an account profile.
+  for (const p of [join(home, ".claude"), join(home, ".config", "claude"), process.env.CLAUDE_CONFIG_DIR]) {
+    if (p) args.push("--bind-try", p, p);
+  }
+  args.push("--bind-try", join(home, ".claude.json"), join(home, ".claude.json"));
 
   // Tool dirs the user typically has in $HOME — re-expose only if present.
   // `--ro-bind-try` is a no-op if the source path doesn't exist.
@@ -272,12 +324,16 @@ function bwrapArgsStrict({ cwd, scratchHome }) {
   for (const p of userToolPaths) {
     args.push("--ro-bind-try", p, p);
   }
+  // Caller-supplied read-only paths (e.g. the Agent SDK's bundled Claude binary).
+  for (const p of extraReadPaths.filter(Boolean)) {
+    args.push("--ro-bind-try", p, p);
+  }
 
   return args;
 }
 
 // Pre-AD-30 denylist via bwrap (--bind / / + tmpfs over deny paths).
-function bwrapArgsLegacy({ cwd, scratchHome }) {
+function bwrapArgsLegacy() {
   const home = homedir();
   const denyPaths = [
     join(home, ".ssh"),

package/cli/session-sandbox.mjs

@@ -23,6 +23,7 @@ import { mkdirSync, writeFileSync, rmSync, existsSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
 import { randomUUID } from "crypto";
+import { installExitGuards, onTerminate } from "./proc.mjs";
 
 // AD-46: refuse any value with embedded newlines before it lands in YAML or
 // gitconfig. Real GitHub PATs / emails / names won't have them, but a server-
@@ -130,9 +131,20 @@ export function createScratchHome({ projectId, sessionId, creds = {}, commitIden
     cleaned = true;
     try { if (existsSync(base)) rmSync(base, { recursive: true, force: true }); } catch {}
   }
+  // `exit` alone does not fire on a signalled termination, which left the
+  // scratch HOME — containing a 0600 GitHub token and the tracker
+  // credentials — on disk whenever the daemon was stopped with SIGTERM or
+  // Ctrl-C. installExitGuards owns the signal handlers for the whole CLI so
+  // that this cleanup and the child teardown cannot race each other.
+  installExitGuards();
+  const unterminate = onTerminate(cleanup);
   process.once("exit", cleanup);
 
-  return { home: base, env, cleanup };
+  return {
+    home: base,
+    env,
+    cleanup: () => { unterminate(); cleanup(); },
+  };
 }
 
 function safe(s) {

package/cli/setup-helpers.mjs

@@ -2,38 +2,16 @@
 // `agentdesk bootstrap`. Kept here so the two entry commands can compose
 // the same building blocks without importing from each other.
 
-import { existsSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { existsSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "fs";
 import { join } from "path";
-import { execSync, execFileSync } from "child_process";
+import { execFileSync } from "child_process";
 import { checkTrackerPermissions, resolveCredentialsFromEnv } from "./tracker-check.mjs";
 import { assertPushable, PreflightError, getGitRemoteUrl } from "./session-preflight.mjs";
+import { checkClaudeAuth } from "./engine/claude-auth.mjs";
 
-// ---------- .env read/write ----------
-
-export function loadDotEnv(dir) {
-  const envPath = join(dir, ".env");
-  const out = {};
-  if (!existsSync(envPath)) return out;
-  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) out[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
-  }
-  return out;
-}
-
-export function saveEnvVar(dir, key, value) {
-  const envPath = join(dir, ".env");
-  let content = existsSync(envPath) ? readFileSync(envPath, "utf-8") : "";
-  const re = new RegExp(`^${key}=.*$`, "m");
-  if (re.test(content)) {
-    content = content.replace(re, `${key}=${value}`);
-  } else {
-    content += `${content && !content.endsWith("\n") ? "\n" : ""}${key}=${value}\n`;
-  }
-  writeFileSync(envPath, content);
-}
+// .env read/write lives in dotenv.mjs (single implementation, quote-aware,
+// 0600 on write). Re-exported so existing importers keep working.
+export { loadDotEnv, saveEnvVar, ensureGitignored } from "./dotenv.mjs";
 
 // ---------- Git detection + parsing ----------
 
@@ -45,7 +23,9 @@ export function parseGitHubRef(input) {
   // Reject non-github hosts early.
   if (/^(https?:\/\/|git@|ssh:\/\/)/.test(s) && !/github\.com/i.test(s)) return null;
   // SSH / HTTPS / short form — pull out owner/repo from the tail.
-  const m = s.match(/(?:github\.com[:/])?([^/@:\s]+)\/([^/.\s]+?)(?:\.git)?\/?$/i);
+  // The repo segment allows dots: `vercel/next.js`, `socketio/socket.io`.
+  // The lazy quantifier plus optional `.git` keeps `next.js.git` → `next.js`.
+  const m = s.match(/(?:github\.com[:/])?([^/@:\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i);
   if (!m) return null;
   return { owner: m[1], repo: m[2] };
 }
@@ -109,17 +89,50 @@ export async function checkGitHubRepoAccess(token, owner, repo) {
 
 // ---------- Clone ----------
 
+// The directory itself is the root of a git checkout (not a plain
+// subdirectory inside some other checkout). Returns the root path or null.
+function checkoutRoot(dir) {
+  try {
+    const top = execFileSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+      stdio: ["ignore", "pipe", "ignore"], encoding: "utf-8",
+    }).trim();
+    return realpathSync(top) === realpathSync(dir) ? top : null;
+  } catch { return null; }
+}
+
+// <cwd>/<repo> when that directory is already a checkout whose origin is
+// github.com/<owner>/<repo> (case-insensitive), else null. Lets `init` reuse
+// a clone that is already in place — the common case when the wizard is run
+// from the directory that contains the clone — instead of refusing to clone
+// over it.
+export function findExistingClone({ cwd, owner, repo }) {
+  const targetDir = join(cwd, repo);
+  if (!existsSync(targetDir) || !checkoutRoot(targetDir)) return null;
+  const { ownerRepo } = detectGitRepo(targetDir);
+  if (!ownerRepo) return null;
+  return ownerRepo.toLowerCase() === `${owner}/${repo}`.toLowerCase() ? targetDir : null;
+}
+
 // Clone github.com/<owner>/<repo> into <cwd>/<repo> using the provided token.
 // Token is embedded in the URL via the x-access-token username (GitHub's
 // documented pattern). Disables terminal prompts so a bad token fails fast
 // instead of hanging waiting for a password.
+// If <cwd>/<repo> is already a checkout of that repo it is returned as-is and
+// nothing is cloned.
 export function cloneRepoWithToken({ cwd, owner, repo, token }) {
   const targetDir = join(cwd, repo);
-  if (existsSync(targetDir)) {
-    const entries = readdirSync(targetDir);
-    if (entries.length > 0) {
-      throw new Error(`./${repo} already exists and is not empty — remove it or run from another directory`);
-    }
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+    if (findExistingClone({ cwd, owner, repo })) return targetDir;
+    // Something else lives there. Say what, so the user knows whether to
+    // remove it or to cd into the right clone.
+    const isCheckout = !!checkoutRoot(targetDir);
+    const other = isCheckout ? detectGitRepo(targetDir).ownerRepo : null;
+    const what = !isCheckout
+      ? "is not a git checkout"
+      : other
+        ? `is a checkout of ${other}, not ${owner}/${repo}`
+        : "is a git checkout with no GitHub origin";
+    throw new Error(`./${repo} already exists and ${what} — remove it, or cd into the right clone and re-run \`agentdesk init\``);
   }
   const url = `https://x-access-token:${token}@github.com/${owner}/${repo}.git`;
   // Execute with env override so we don't echo the token into the user's
@@ -128,9 +141,33 @@ export function cloneRepoWithToken({ cwd, owner, repo, token }) {
     stdio: "inherit",
     env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
   });
+
+  // git stores the clone URL verbatim as `remote.origin.url`, so without this
+  // the token sits in plaintext in .git/config for the life of the checkout —
+  // long after it has been rotated. Sessions authenticate through the
+  // credential helper in session-sandbox.mjs; the remote never needed it.
+  execFileSync("git", ["-C", targetDir, "remote", "set-url", "origin", cleanGitHubUrl(owner, repo)], {
+    stdio: "ignore",
+  });
   return targetDir;
 }
 
+export function cleanGitHubUrl(owner, repo) {
+  return `https://github.com/${owner}/${repo}.git`;
+}
+
+// Remove any `user:secret@` userinfo from the origin remote of an existing
+// checkout. Returns true when something was stripped. Used by `init` to
+// repair clones made by versions that embedded the token in the URL.
+export function stripRemoteCredentials(dir) {
+  const url = getGitRemoteUrl(dir);
+  if (!url) return false;
+  const m = url.match(/^(https?:\/\/)[^@/]+@(.+)$/);
+  if (!m) return false;
+  execFileSync("git", ["-C", dir, "remote", "set-url", "origin", `${m[1]}${m[2]}`], { stdio: "ignore" });
+  return true;
+}
+
 // ---------- Access checks (summary checklist) ----------
 
 export async function checkAgentDeskAccess(apiKey, serverUrl) {
@@ -149,12 +186,16 @@ export async function checkAgentDeskAccess(apiKey, serverUrl) {
 // Run all three access checks for the final summary and return the results.
 // No prompts — the caller decides whether to abort or let the user save
 // anyway based on the outcome.
-export async function runAccessChecks({ apiKey, serverUrl, cwd, config, creds }) {
-  const results = { agentdesk: null, github: null, tracker: null };
+export async function runAccessChecks({ apiKey, serverUrl, cwd, config, creds, authCheck = checkClaudeAuth }) {
+  const results = { agentdesk: null, claude: null, github: null, tracker: null };
 
   // agentdesk.live
   results.agentdesk = await checkAgentDeskAccess(apiKey, serverUrl);
 
+  // Claude Code itself — a standalone login, with the project's .env applied
+  // (so an ANTHROPIC_API_KEY there counts).
+  results.claude = await authCheck({ env: { ...process.env, ...(creds || {}) } });
+
   // GitHub — token presence + (if we know the repo) push access
   if (creds?.GITHUB_TOKEN) {
     const login = await fetchGitHubLogin(creds.GITHUB_TOKEN);
@@ -209,6 +250,12 @@ export function printAccessChecks(results, { tracker } = {}) {
   } else {
     console.log(`    ✗ agentdesk.live    ${results.agentdesk?.error || "unknown error"}`);
   }
+  if (results.claude?.ok) {
+    console.log(`    ✓ Claude Code       ${results.claude.detail || "logged in"}`);
+  } else if (results.claude) {
+    console.log(`    ✗ Claude Code       ${results.claude.detail || "not logged in"}`);
+    for (const line of String(results.claude.hint || "").split("\n")) if (line) console.log(`                        ${line}`);
+  }
   if (results.github?.ok) {
     const detail = [
       results.github.login ? `@${results.github.login}` : null,

package/cli/team.mjs

@@ -1,34 +1,19 @@
 // `agentdesk team <TASK-ID> [--description "..."]` — run a team session
 
-import { existsSync, readFileSync } from "fs";
-import { join, dirname } from "path";
+import { dirname } from "path";
 import { randomUUID } from "crypto";
 import { fileURLToPath } from "url";
 import WebSocket from "ws";
 import { detectProject } from "./detect.mjs";
 import { loadConfig } from "./config.mjs";
 import { getStoredApiKey } from "./login.mjs";
-import { resolveTeam, generateTeamPrompt } from "./agents.mjs";
-import { runOrchestrator, runPhasedOrchestrator } from "./orchestrator.mjs";
+import { resolveTeam } from "./agents.mjs";
+import { runSession } from "./engine/session.mjs";
 import { checkTrackerPermissions, resolveCredentialsFromEnv } from "./tracker-check.mjs";
 import { buildTrackerUrl } from "./tracker-url.mjs";
+import { loadDotEnv } from "./dotenv.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const CLI_VERSION = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8")).version;
-
-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;
-}
 
 export async function runTeam(taskId, opts = {}) {
   const cyan = "\x1b[36m";
@@ -85,9 +70,7 @@ export async function runTeam(taskId, opts = {}) {
     console.log(`Child strategy: ${opts.childStrategy}`);
   }
 
-  // Resolve team and generate dynamic prompt sections
   const team = resolveTeam(config);
-  const teamSections = generateTeamPrompt(team, { tracker, config });
 
   // --- Verify tracker permissions before starting session ---
   if (tracker) {
@@ -209,24 +192,48 @@ export async function runTeam(taskId, opts = {}) {
     }
   }, 30000);
 
-  const orchestrate = opts.phased ? runPhasedOrchestrator : runOrchestrator;
-  const result = await orchestrate({
-    taskId, taskLink, description, createTask, tracker, config,
-    project, team, teamSections, sessionUrl, cwd,
-    sessionId,
-    onEvent: vizSend,
-    apiKey,
-    serverUrl: agentdeskServer,
-    soloAgent: opts.soloAgent || null,
-    childStrategy: opts.childStrategy || null,
-  });
-
-  clearInterval(heartbeatInterval);
+  // Children are spawned into their own process group so a cancel can take the
+  // whole tree down. That also means they no longer receive the terminal's
+  // Ctrl-C, so the signal has to be forwarded deliberately.
+  const abort = new AbortController();
+  const onSigint = () => {
+    console.log(`\n  Stopping session — terminating Claude...`);
+    abort.abort();
+  };
+  process.on("SIGINT", onSigint);
+
+  let result;
+  try {
+    result = await runSession({
+      taskId, taskLink, description, createTask, tracker, config,
+      project, team, sessionUrl, cwd,
+      sessionId,
+      onEvent: vizSend,
+      apiKey,
+      serverUrl: agentdeskServer,
+      soloAgent: opts.soloAgent || null,
+      childStrategy: opts.childStrategy || null,
+      abortSignal: abort.signal,
+    });
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+    clearInterval(heartbeatInterval);
+  }
 
   if (result.error) {
     const red = "\x1b[31m";
     console.log(`\n━━━ ${red}SESSION COULD NOT START${reset} ━━━`);
     console.log(`  ${result.error}\n`);
+  } else if (result.aborted) {
+    const yellow = "\x1b[33m";
+    console.log(`\n━━━ ${yellow}STOPPED${reset} ━━━`);
+    console.log(`  Cancelled — Claude terminated.`);
+    console.log(`  Resume with: ${cyan}agentdesk team ${taskId}${reset}\n`);
+  } else if (result.status === "handoff" && result.reviewResolved === false) {
+    const yellow = "\x1b[33m";
+    console.log(`\n━━━ ${yellow}NEEDS REVIEW${reset} ━━━`);
+    console.log(`  Review did not approve the work — this session is NOT complete.`);
+    console.log(`  Check the branch before merging.\n`);
   } else if (result.handoff) {
     const yellow = "\x1b[33m";
     console.log(`\n━━━ ${yellow}HANDOFF${reset} ━━━`);

package/cli/tracker-check.mjs

@@ -2,6 +2,7 @@
 // Checks: read tasks, create tasks, update tasks
 
 import { execFileSync } from "child_process";
+import { trackerNeedsProject, getTrackerProject, missingTrackerProjectError } from "./tracker-project.mjs";
 
 // AD-29: any external string (repo name, ref, etc.) must be regex-validated
 // before it goes into a child process. Even with execFile, an upstream caller
@@ -14,9 +15,18 @@ const LINEAR_API = "https://api.linear.app/graphql";
  * Check tracker permissions. Returns { ok, errors[] }.
  * Each error is a string describing what permission is missing.
  */
-export async function checkTrackerPermissions({ tracker, config, credentials }) {
+// `requireProject` (default true): a Linear team key / Jira project key is
+// part of a working configuration — without it, create-from-description
+// sessions file tasks in whatever project the token can reach. Only the
+// init wizard's credential step, which runs before the project is picked,
+// turns this off.
+export async function checkTrackerPermissions({ tracker, config, credentials, requireProject = true }) {
   if (!tracker) return { ok: true, errors: [] };
 
+  if (requireProject && trackerNeedsProject(tracker) && !getTrackerProject(tracker, config)) {
+    return { ok: false, errors: [missingTrackerProjectError(tracker)] };
+  }
+
   switch (tracker) {
     case "linear":
       return checkLinear(config.linear || {}, credentials);
@@ -29,7 +39,7 @@ export async function checkTrackerPermissions({ tracker, config, credentials })
   }
 }
 
-async function checkLinear({ teamKey, workspace }, creds) {
+async function checkLinear({ teamKey }, creds) {
   const apiKey = creds.LINEAR_API_KEY;
   if (!apiKey) return { ok: false, errors: ["Missing LINEAR_API_KEY — configure it in the AgentDesk dashboard or .env"] };
 

package/cli/tracker-project.mjs

@@ -0,0 +1,93 @@
+// Tracker project binding (Linear team key / Jira project key) for
+// `agentdesk init`.
+//
+// The binding is the one project-wide setting that `init` must never leave
+// empty: without it the create-from-description prompt cannot pin the
+// project, so the agent files tasks wherever its token can reach. Before
+// this module the wizard only asked for it in new mode, and only when the
+// credential check succeeded; existing mode copied whatever the server had
+// (often nothing) and moved on without a word.
+//
+// `resolveTrackerProject` is the single decision point for step 9 of the
+// wizard. Prompts are injected so the decision table is unit-testable.
+
+export function trackerNeedsProject(tracker) {
+  return tracker === "linear" || tracker === "jira";
+}
+
+export function trackerProjectLabel(tracker) {
+  return tracker === "linear" ? "Linear team key (e.g. KEN)" : "Jira project key (e.g. PROJ)";
+}
+
+export function trackerProjectNoun(tracker) {
+  return tracker === "linear" ? "team" : "project";
+}
+
+// The configured team/project id, or null.
+export function getTrackerProject(tracker, config) {
+  if (tracker === "linear") return config?.linear?.teamKey || null;
+  if (tracker === "jira") return config?.jira?.project || null;
+  return null;
+}
+
+// Return a copy of `config` with the team/project id set on the right block.
+export function setTrackerProject(tracker, config, id) {
+  const out = { ...(config || {}) };
+  if (tracker === "linear") out.linear = { ...(out.linear || {}), teamKey: id };
+  if (tracker === "jira") out.jira = { ...(out.jira || {}), project: id };
+  return out;
+}
+
+export function missingTrackerProjectError(tracker) {
+  return tracker === "linear"
+    ? "Missing Linear team key — run 'agentdesk init' to pick the team"
+    : "Missing Jira project key — run 'agentdesk init' to pick the project";
+}
+
+// Decide the tracker project for the wizard.
+//
+//   tracker         "linear" | "jira" | "github" | null
+//   isExisting      wizard mode
+//   serverProject   the id the server already has (existing mode), or null
+//   verified        true when the credential check passed (a listing is possible)
+//   listProjects    async () => [{ id, name }] | null   (only called when verified)
+//   promptSelect    async ({ message, choices }) => value
+//   promptRequired  async (label) => string
+//
+// Returns { id, name, source } where source is:
+//   "server"  — existing mode, server already had it (read-only)
+//   "picked"  — chosen from the tracker's list
+//   "typed"   — entered by hand (no list available, or creds not verified)
+//   "none"    — tracker has no project concept (github / no tracker)
+//
+// A tracker that needs a project NEVER returns null here: the previous
+// wizard gated the prompt on the credential check, and "Save anyway" then
+// skipped the question entirely.
+export async function resolveTrackerProject({
+  tracker, isExisting, serverProject, verified,
+  listProjects, promptSelect, promptRequired,
+}) {
+  if (!trackerNeedsProject(tracker)) return { id: null, name: null, source: "none" };
+
+  if (isExisting && serverProject) {
+    return { id: serverProject, name: serverProject, source: "server" };
+  }
+
+  const noun = trackerProjectNoun(tracker);
+  if (verified) {
+    const items = (await listProjects()) || [];
+    if (items.length > 0) {
+      const pickedId = await promptSelect({
+        message: `Pick the ${noun} this project maps to`,
+        choices: items.map(it => ({ name: it.name, value: it.id })),
+      });
+      const name = items.find(it => it.id === pickedId)?.name || pickedId;
+      return { id: pickedId, name, source: "picked" };
+    }
+  }
+
+  // Both trackers use upper-case keys (KEN-12, PROJ-34); normalise so a
+  // lower-case entry doesn't produce a key the tracker won't recognise.
+  const id = String(await promptRequired(trackerProjectLabel(tracker))).trim().toUpperCase();
+  return { id, name: id, source: "typed" };
+}

package/cli/update-check.mjs

@@ -0,0 +1,62 @@
+// Update-check policy for the CLI entry point.
+//
+// Pure functions, so the rules about when a newer release is allowed to stop
+// the CLI from running are testable without touching the npm registry.
+//
+// The previous inline logic treated a MINOR bump as breaking and exited 1.
+// That meant the moment 0.28.0 was published, every `agentdesk daemon` that
+// restarted — a process specifically meant to run unattended — refused to
+// start until a human ran `agentdesk update`. It also ran before `--version`
+// and `help` were handled, so `agentdesk --version` needed network access and
+// could fail.
+
+// Commands that must never be blocked by an available update.
+//   - daemon: unattended; a hard exit here is an outage, not a nudge.
+//   - update/version/help: the user is trying to find out about or fix the
+//     very thing we'd be blocking on.
+const NEVER_BLOCK = new Set(["daemon", "update", "version", "--version", "-v", "help", "--help"]);
+
+// Commands where the check is pure noise — they should not even fetch.
+const SKIP_CHECK = new Set(["version", "--version", "-v", "help", "--help", "update", undefined, ""]);
+
+export function parseVersion(v) {
+  const m = String(v ?? "").trim().match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+
+// "none" | "patch" | "minor" | "major" | "behind-registry"
+//
+// "behind-registry" covers a local build that is NEWER than what npm has
+// (a pre-release checkout). The old code reported that as "update available
+// 0.27.0 → 0.26.0", which is backwards.
+export function classifyUpdate(current, latest) {
+  const c = parseVersion(current);
+  const l = parseVersion(latest);
+  if (!c || !l) return "none";
+
+  if (l.major > c.major) return "major";
+  if (l.major < c.major) return "behind-registry";
+  if (l.minor > c.minor) return "minor";
+  if (l.minor < c.minor) return "behind-registry";
+  if (l.patch > c.patch) return "patch";
+  if (l.patch < c.patch) return "behind-registry";
+  return "none";
+}
+
+export function shouldSkipCheck(command, env = process.env) {
+  if (env.AGENTDESK_SKIP_UPDATE_CHECK === "1") return true;
+  return SKIP_CHECK.has(command);
+}
+
+// Decide what to do with a classification for a given command.
+// Returns { action: "none" | "warn" | "block" }.
+//
+// Only a MAJOR bump blocks, and only for interactive commands. Semver says a
+// minor release is backward compatible; treating it as breaking punishes
+// every user for every feature release.
+export function updateAction(command, classification) {
+  if (classification === "none" || classification === "behind-registry") return { action: "none" };
+  if (classification === "major" && !NEVER_BLOCK.has(command)) return { action: "block" };
+  return { action: "warn" };
+}