@kendoo.agentdesk/agentdesk 0.19.1 → 0.19.3

package/CHANGELOG.md

@@ -8,6 +8,27 @@ All user-facing changes to AgentDesk. Each entry is tagged:
 
 Internal refactors, infrastructure changes, and architectural notes are not listed here.
 
+## [Unreleased]
+
+### Added
+- `[UI]` Private-session sharing flow. When someone visits a session URL they don't own, they now see a friendly "Shh… this one's private" page with a one-click "Request access" button instead of a blank error. The session owner sees pending requests in a new header inbox and can grant viewer access for just that session or the whole project. Viewer-granted sessions show up in the teammate's sidebar tagged as a viewer.
+
+## [0.19.3] — 2026-04-19
+
+### Fixed
+- `[CLI]` `agentdesk init` no longer silently saves tracker credentials that fail verification. Previously a typo in the email, a revoked API token, or a wrong tenant URL would print a one-line warning and proceed — leaving the user with a "valid-looking" `.env` that then failed at `agentdesk team` time with a generic "authentication failed" message. Init now prompts to re-enter credentials, save anyway, or cancel, so broken config is caught at the moment it's typed instead of the next time a session is started.
+
+## [0.19.2] — 2026-04-18
+
+### Fixed
+- `[CLI]` Scoped sessions can now `git push` and `gh pr create` end-to-end. Previously the sandbox initialized its scoped GitHub credential helper from server-fetched creds only, ignoring tokens stored in the project's `.env` — so any project that ran `agentdesk init` with the GitHub token saved locally (the documented path) silently spawned a session whose credential helper returned an empty password, and the agent had to ask the operator to push manually.
+
+### Added
+- `[CLI]` Session preflight: a missing GitHub token or an SSH-only `origin` remote now fail at session start with a clean, actionable message instead of degrading silently mid-run.
+
+### Changed
+- `[CLI]` The scoped credential helper reads the GitHub token from a 0600 file instead of interpolating it into a shell script — defends against tokens containing shell metacharacters.
+
 ## [0.19.1] — 2026-04-18
 
 ### Fixed

package/README.md

@@ -64,7 +64,7 @@ agentdesk team -d "Fix the checkout total calculation"
 agentdesk team -d "Add Google OAuth to the login page"
 ```
 
-Watch the session live at [agentdesk.live](https://agentdesk.live). Each session gets a deep link you can share.
+Watch the session live at [agentdesk.live](https://agentdesk.live). Each session gets a deep link you can share — the session ID is visible in the header and sidebar with a one-click copy, alongside the tracker task ID. Teammates who don't have access yet see a friendly "private session" page with a one-click request-access button, and you can grant them viewer access for that session or the whole project from the dashboard.
 
 ## Commands
 
@@ -226,6 +226,7 @@ Once running, a "Run Team" button appears on [agentdesk.live](https://agentdesk.
 
 - **Per-session identity isolation** — every session runs with `HOME` / `GH_CONFIG_DIR` / `XDG_CONFIG_HOME` pointed at a private scratch dir containing only this project's tracker credentials and commit identity. `gh`, `git`, and `ssh` inside the session cannot see your global accounts, other projects' tokens, or keys elsewhere on disk.
 - **Kernel-enforced sandbox when available** — on macOS (`sandbox-exec`) and Linux (`bwrap` / bubblewrap), sessions run with writes restricted to the project dir + scratch home + `/tmp`, and reads denied on known credential locations (`~/.ssh`, `~/.aws`, `~/.config/gh`, `~/.gitconfig`, `~/.netrc`, etc.). If the tool isn't available, sessions fall back to scoped-env isolation with a one-line notice. Opt out for debugging with `AGENTDESK_NO_SANDBOX=1`.
+- **Credentials prerequisite** — scoped sessions push code over HTTPS using a per-project GitHub token. `agentdesk init` saves it to the project's `.env` as `GITHUB_TOKEN`; if you skip that step, the session refuses to start with an actionable message. SSH-only remotes (`git@github.com:...`) are also rejected — the sandbox intentionally isolates `~/.ssh`. Switch the origin to `https://github.com/<owner>/<repo>.git` or run without scoped isolation.
 - **Outbound only** — no ports opened on your machine
 - **Project allowlist** — only runs on projects registered via `agentdesk init`
 - **No arbitrary commands** — only spawns Claude with a fixed set of allowed tools
@@ -244,7 +245,8 @@ Once running, a "Run Team" button appears on [agentdesk.live](https://agentdesk.
 ## Dashboard Features
 
 - **Live sessions** — watch agents collaborate in real-time
-- **Session deep links** — share a direct URL to any session
+- **Session deep links** — share a direct URL to any session; teammates without access can request it in one click and be granted viewer access per-session or project-wide
+- **Access requests inbox** — pending requests from teammates appear in the dashboard header for quick approval
 - **Handoff status** — see when a session hit a limit and is waiting to resume
 - **Project settings** — configure tracker, team, custom agents, and instructions per project
 - **Account settings** — manage your API key and profile

package/cli/daemon.mjs

@@ -14,6 +14,7 @@ import { buildPrompt } from "./prompt.mjs";
 import { createStreamParser } from "./stream-parser.mjs";
 import { runOrchestrator, runPhasedOrchestrator } from "./orchestrator.mjs";
 import { getRegisteredProjects, registerLocalProject } from "./projects.mjs";
+import { buildTrackerUrl } from "./tracker-url.mjs";
 import { fileURLToPath } from "url";
 import { dirname } from "path";
 
@@ -357,18 +358,8 @@ export async function runDaemon() {
         ? prompt.toLowerCase().replace(/[^a-z0-9\s-]/g, "").trim().replace(/\s+/g, "-").slice(0, 40) || `task-${Date.now().toString(36)}`
         : `daemon-${Date.now().toString(36)}`);
 
-      // Build task link
-      let taskLink = null;
-      if (remoteTaskId) {
-        if (tracker === "linear" && config.linear?.workspace) {
-          taskLink = `https://linear.app/${config.linear.workspace}/issue/${remoteTaskId}`;
-        } else if (tracker === "jira" && config.jira?.baseUrl) {
-          taskLink = `${config.jira.baseUrl.replace(/\/+$/, "")}/browse/${remoteTaskId}`;
-        } else if (tracker === "github") {
-          const repo = config.github?.repo || "";
-          if (repo) taskLink = `https://github.com/${repo}/issues/${remoteTaskId}`;
-        }
-      }
+      // 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);

package/cli/dotenv.mjs

@@ -0,0 +1,22 @@
+// 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).
+
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+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);
+  }
+  return vars;
+}

package/cli/init.mjs

@@ -406,16 +406,54 @@ export async function runInit(cwd, opts = {}) {
     config.github = { repo, login };
   }
 
-  // Verify tracker + fetch available projects to pick from.
+  // Verify tracker + fetch available projects to pick from. If verification
+  // fails (bad email, revoked token, typo in base URL), loop back and let the
+  // user re-enter credentials rather than silently saving broken config.
   let trackerLocation = null;
   if (tracker === "jira") trackerLocation = config.jira?.baseUrl;
+  let verified = { ok: true };
   if (tracker) {
-    const verified = await verifyAndPickTrackerProject({ rl, cwd, finalProjectKey, tracker, config, location: trackerLocation });
-    if (!verified.ok) {
-      console.log("  Continuing without tracker verification.");
-      console.log("  You can re-run `agentdesk init` after fixing credentials.");
+    while (true) {
+      verified = await verifyAndPickTrackerProject({ rl, cwd, finalProjectKey, tracker, config, location: trackerLocation });
+      if (verified.ok) break;
       console.log("");
-    } else if (verified.trackerProjectId) {
+      const next = await selectOption(rl, "What now?", [
+        { label: "Re-enter credentials and try again", value: "retry" },
+        { label: "Save config anyway (will need to fix before `agentdesk team`)", value: "skip" },
+        { label: "Cancel init", value: "cancel" },
+      ]);
+      console.log("");
+      if (next.value === "cancel") {
+        rl.close();
+        return;
+      }
+      if (next.value === "skip") break;
+      // Retry: re-prompt only the tracker auth fields, not the whole wizard.
+      if (tracker === "linear") {
+        const key = await promptRequired(rl, "Linear API key");
+        saveEnvVar(cwd, "LINEAR_API_KEY", key);
+        console.log("  ✓ Updated LINEAR_API_KEY in .env");
+        console.log("");
+      } else if (tracker === "jira") {
+        const baseUrl = (await ask(rl, `  Jira tenant URL [${config.jira?.baseUrl || ""}]: `)).trim() || config.jira?.baseUrl;
+        const email = await promptRequired(rl, "Your Atlassian login email");
+        const token = await promptRequired(rl, "Jira API token");
+        saveEnvVar(cwd, "JIRA_EMAIL", email);
+        saveEnvVar(cwd, "JIRA_API_TOKEN", token);
+        if (baseUrl) {
+          config.jira = { ...(config.jira || {}), baseUrl: baseUrl.replace(/\/+$/, "") };
+          trackerLocation = config.jira.baseUrl;
+        }
+        console.log("  ✓ Updated JIRA_EMAIL and JIRA_API_TOKEN in .env");
+        console.log("");
+      } else if (tracker === "github") {
+        const token = await promptRequired(rl, "GitHub token");
+        saveEnvVar(cwd, "GITHUB_TOKEN", token);
+        console.log("  ✓ Updated GITHUB_TOKEN in .env");
+        console.log("");
+      }
+    }
+    if (verified.ok && verified.trackerProjectId) {
       if (tracker === "linear") config.linear = { ...(config.linear || {}), teamKey: verified.trackerProjectId };
       if (tracker === "jira") config.jira = { ...(config.jira || {}), project: verified.trackerProjectId };
       // Use the tracker's project key as the default agentdesk project key.

package/cli/orchestrator.mjs

@@ -9,6 +9,9 @@ import { buildPrompt, buildSoloPrompt, buildPhasedPrompt } from "./prompt.mjs";
 import { createStreamParser } from "./stream-parser.mjs";
 import { createScratchHome } from "./session-sandbox.mjs";
 import { wrapIsolatedSpawn, probeIsolation } from "./session-isolation.mjs";
+import { buildTrackerUrl } from "./tracker-url.mjs";
+import { resolveGitHubCreds, assertPushable, PreflightError } from "./session-preflight.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;
@@ -26,20 +29,6 @@ async function fetchTrackerCredentials(projectName, apiKey, serverUrl) {
   return {};
 }
 
-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;
-}
-
 function timestamp() {
   const d = new Date();
   return [d.getHours(), d.getMinutes(), d.getSeconds()]
@@ -78,19 +67,12 @@ export async function runOrchestrator({
 }) {
   const trackerCreds = await fetchTrackerCredentials(project?.name, apiKey, serverUrl);
 
-  // Build a per-session scratch HOME that isolates THIS project's identity
-  // from the user's global git/gh/ssh state and from other projects'
-  // credentials. Cleanup runs at session end regardless of outcome.
-  const sandbox = createScratchHome({
-    projectId: project?.name,
-    sessionId,
-    creds: trackerCreds,
-    commitIdentity: {
-      name: config?.identityBadge || "AgentDesk",
-      email: trackerCreds.JIRA_EMAIL || `agentdesk@local`,
-    },
-  });
-  const env = { ...process.env, ...loadDotEnv(cwd), ...sandbox.env };
+  // Resolve creds from server + project .env BEFORE building the scratch
+  // HOME, so the sandbox helper writes the right token (or we fail fast
+  // when none is available — see assertPushable below).
+  const resolvedToken = resolveGitHubCreds({ cwd, trackerCreds }).GITHUB_TOKEN;
+  const resolvedCreds = { ...trackerCreds, GITHUB_TOKEN: resolvedToken || trackerCreds.GITHUB_TOKEN };
+
   const startTime = Date.now();
   let totalInputTokens = 0;
   let totalOutputTokens = 0;
@@ -117,6 +99,35 @@ export async function runOrchestrator({
     cliVersion: CLI_VERSION,
   });
 
+  // Preflight: must run AFTER session:start (so the UI has a session to
+  // bind the error to) but BEFORE we touch the scratch sandbox or spawn
+  // the child. Surfaces missing creds / SSH-only remotes as a clean
+  // session error instead of letting the agent silently fail to push.
+  try {
+    assertPushable({ cwd, creds: resolvedCreds, projectName: project?.name });
+  } catch (err) {
+    if (err instanceof PreflightError) {
+      emit({ type: "session:error", code: err.code, message: err.message });
+      emit({ type: "session:end", duration: `${((Date.now() - startTime) / 1000).toFixed(1)}s`, steps: 0, inputTokens: 0, outputTokens: 0, status: "error" });
+      return { duration: "0s", steps: 0, inputTokens: 0, outputTokens: 0, handoff: false, error: err.message };
+    }
+    throw err;
+  }
+
+  // Build a per-session scratch HOME that isolates THIS project's identity
+  // from the user's global git/gh/ssh state and from other projects'
+  // credentials. Cleanup runs at session end regardless of outcome.
+  const sandbox = createScratchHome({
+    projectId: project?.name,
+    sessionId,
+    creds: resolvedCreds,
+    commitIdentity: {
+      name: config?.identityBadge || "AgentDesk",
+      email: resolvedCreds.JIRA_EMAIL || `agentdesk@local`,
+    },
+  });
+  const env = { ...process.env, ...loadDotEnv(cwd), ...sandbox.env };
+
   const initialPhase = soloAgent ? "EXECUTION" : "INTAKE";
   // Non-phased single run spans all phases in one process — use EXECUTION's model
   // as the representative choice (matches where the heavy lifting happens).
@@ -154,15 +165,8 @@ export async function runOrchestrator({
       onSessionUpdate({ taskId: newTaskId, title }) {
         if (newTaskId) {
           const update = { type: "session:update", taskId: newTaskId };
-          // Build a clickable task link from tracker config
-          if (tracker === "linear" && config.linear?.workspace) {
-            update.taskLink = `https://linear.app/${config.linear.workspace}/issue/${newTaskId}`;
-          } else if (tracker === "jira" && config.jira?.baseUrl) {
-            update.taskLink = `${config.jira.baseUrl.replace(/\/+$/, "")}/browse/${newTaskId}`;
-          } else if (tracker === "github") {
-            const repo = config.github?.repo || "";
-            if (repo) update.taskLink = `https://github.com/${repo}/issues/${newTaskId}`;
-          }
+          const taskLink = buildTrackerUrl({ tracker, config, taskId: newTaskId });
+          if (taskLink) update.taskLink = taskLink;
           emit(update);
         }
         if (title) emit({ type: "session:update", title });
@@ -234,7 +238,7 @@ export async function runOrchestrator({
 
 // --- Phased orchestrator: runs 3 sequential Claude processes ---
 
-async function runSinglePhase({ prompt, cwd, env, teamNames, emit, modelArgs = [], scratchHome, sessionId }) {
+async function runSinglePhase({ prompt, cwd, env, teamNames, emit, modelArgs = [], scratchHome, sessionId, tracker, config }) {
   const wrapped = wrapIsolatedSpawn({
     cmd: "claude",
     args: ["-p", prompt, ...modelArgs, "--allowedTools", "Bash,Read,Edit,Write,Glob,Grep", "--verbose", "--output-format", "stream-json"],
@@ -260,7 +264,12 @@ async function runSinglePhase({ prompt, cwd, env, teamNames, emit, modelArgs = [
       onToolUse({ agent, tool, description }) { steps++; emit({ type: "tool:use", agent, tool, description }); },
       onToolResult({ success, summary }) { emit({ type: "tool:result", success, summary }); },
       onSessionUpdate({ taskId: newTaskId, title }) {
-        if (newTaskId) emit({ type: "session:update", taskId: newTaskId });
+        if (newTaskId) {
+          const update = { type: "session:update", taskId: newTaskId };
+          const taskLink = buildTrackerUrl({ tracker, config, taskId: newTaskId });
+          if (taskLink) update.taskLink = taskLink;
+          emit(update);
+        }
         if (title) emit({ type: "session:update", title });
       },
       onSessionEnd({ inputTokens: iT, outputTokens: oT, steps: s }) {
@@ -285,26 +294,15 @@ export async function runPhasedOrchestrator({
 }) {
   const trackerCreds = await fetchTrackerCredentials(project?.name, apiKey, serverUrl);
 
-  const sandbox = createScratchHome({
-    projectId: project?.name,
-    sessionId,
-    creds: trackerCreds,
-    commitIdentity: {
-      name: config?.identityBadge || "AgentDesk",
-      email: trackerCreds.JIRA_EMAIL || `agentdesk@local`,
-    },
-  });
-  const env = { ...process.env, ...loadDotEnv(cwd), ...sandbox.env };
+  // Resolve creds (server + project .env) before any scratch HOME setup
+  // so preflight can fail fast and the sandbox helper bakes the right
+  // token. Server creds win over .env when both are present.
+  const resolvedToken = resolveGitHubCreds({ cwd, trackerCreds }).GITHUB_TOKEN;
+  const resolvedCreds = { ...trackerCreds, GITHUB_TOKEN: resolvedToken || trackerCreds.GITHUB_TOKEN };
+
   const startTime = Date.now();
   const teamNames = teamSections.names;
 
-  const probe = probeIsolation();
-  if (probe.kind !== "none") {
-    console.error(`[agentdesk] session isolation: ${probe.kind}`);
-  } else {
-    console.error(`[agentdesk] hard isolation unavailable (${probe.reason}) — scoped-env only`);
-  }
-
   function timestamp() {
     const d = new Date();
     return [d.getHours(), d.getMinutes(), d.getSeconds()].map(n => String(n).padStart(2, "0")).join(":");
@@ -325,6 +323,38 @@ export async function runPhasedOrchestrator({
     cliVersion: CLI_VERSION,
   });
 
+  // Preflight: AFTER session:start so the UI can bind the error, BEFORE
+  // touching the scratch sandbox or spawning a child. Same contract as
+  // runOrchestrator above.
+  try {
+    assertPushable({ cwd, creds: resolvedCreds, projectName: project?.name });
+  } catch (err) {
+    if (err instanceof PreflightError) {
+      emit({ type: "session:error", code: err.code, message: err.message });
+      emit({ type: "session:end", duration: `${((Date.now() - startTime) / 1000).toFixed(1)}s`, steps: 0, inputTokens: 0, outputTokens: 0, status: "error" });
+      return { duration: "0s", steps: 0, inputTokens: 0, outputTokens: 0, handoff: false, error: err.message };
+    }
+    throw err;
+  }
+
+  const sandbox = createScratchHome({
+    projectId: project?.name,
+    sessionId,
+    creds: resolvedCreds,
+    commitIdentity: {
+      name: config?.identityBadge || "AgentDesk",
+      email: resolvedCreds.JIRA_EMAIL || `agentdesk@local`,
+    },
+  });
+  const env = { ...process.env, ...loadDotEnv(cwd), ...sandbox.env };
+
+  const probe = probeIsolation();
+  if (probe.kind !== "none") {
+    console.error(`[agentdesk] session isolation: ${probe.kind}`);
+  } else {
+    console.error(`[agentdesk] hard isolation unavailable (${probe.reason}) — scoped-env only`);
+  }
+
   const sessionMemoryPath = join(cwd, ".agentdesk", "session-memory.md");
   const reviewVerdictPath = join(cwd, ".agentdesk", "review-verdict.md");
   const MAX_REVIEW_RETRIES = 1; // One execution redo after a failed review, then force SUMMARY.
@@ -357,7 +387,7 @@ export async function runPhasedOrchestrator({
     });
 
     const modelArgs = modelArgsForPhase(phase, config?.phaseModels);
-    const result = await runSinglePhase({ prompt, cwd, env, teamNames, emit, modelArgs, scratchHome: sandbox.home, sessionId });
+    const result = await runSinglePhase({ prompt, cwd, env, teamNames, emit, modelArgs, scratchHome: sandbox.home, sessionId, tracker, config });
 
     if (onChild) onChild(result.child);
 

package/cli/session-preflight.mjs

@@ -0,0 +1,91 @@
+// Session preflight: verify that a scoped session has the credentials
+// and remote configuration it needs to push code, BEFORE we spawn the
+// child Claude process. Failure here surfaces as a clean session error
+// instead of an agent silently asking the operator to push by hand.
+//
+// Two checks today:
+//   1. resolveGitHubCreds: server creds + project .env merged into one
+//      record. Server wins when both are present (consistency across
+//      machines).
+//   2. assertPushable: GITHUB_TOKEN must exist AND the origin remote
+//      (if configured) must be HTTPS. SSH remotes are blocked because
+//      the kernel sandbox denies ~/.ssh — there is no SSH key to read.
+//
+// A repo with no `origin` remote is allowed: agents may add one
+// themselves, and pushing isn't always required for a session.
+
+import { execFileSync } from "child_process";
+import { loadDotEnv } from "./dotenv.mjs";
+
+export class PreflightError extends Error {
+  constructor(message, { code } = {}) {
+    super(message);
+    this.name = "PreflightError";
+    this.code = code || "PREFLIGHT_FAILED";
+  }
+}
+
+// Merge server-fetched tracker creds with the project's .env. Server
+// values win when both are present so a token rotated centrally takes
+// effect without a local edit. Returns { GITHUB_TOKEN, source } where
+// source is "server" | "dotenv" | null.
+export function resolveGitHubCreds({ cwd, trackerCreds = {} } = {}) {
+  const fromServer = trackerCreds.GITHUB_TOKEN || null;
+  const fromDotEnv = cwd ? (loadDotEnv(cwd).GITHUB_TOKEN || null) : null;
+  if (fromServer) return { GITHUB_TOKEN: fromServer, source: "server" };
+  if (fromDotEnv) return { GITHUB_TOKEN: fromDotEnv, source: "dotenv" };
+  return { GITHUB_TOKEN: null, source: null };
+}
+
+// Raw URL of the `origin` remote, or null if no origin is configured
+// (or if git itself isn't installed). We use execFileSync (no shell)
+// so a hostile cwd can't trigger command injection.
+export function getGitRemoteUrl(cwd) {
+  if (!cwd) return null;
+  try {
+    return execFileSync("git", ["-C", cwd, "remote", "get-url", "origin"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf-8",
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// HTTPS remotes are pushable through the credential helper we install
+// in the scratch HOME. SSH remotes (git@host:owner/repo, ssh://...) are
+// not — the sandbox intentionally denies ~/.ssh.
+function isSshRemote(url) {
+  if (!url) return false;
+  if (url.startsWith("ssh://")) return true;
+  // scp-style: user@host:path. Distinguish from https:// by checking for
+  // the colon-before-slash pattern with no scheme.
+  return /^[^@/]+@[^:]+:/.test(url);
+}
+
+// Throws PreflightError with a user-facing `message` when:
+//   - no GITHUB_TOKEN is resolved (and a remote exists OR no remote is
+//     configured — we still warn so the agent can't silently fail later)
+//   - the configured origin is SSH
+// A repo with NO origin remote is allowed when the token is present.
+export function assertPushable({ cwd, creds = {}, projectName = "(unknown)" } = {}) {
+  const remote = getGitRemoteUrl(cwd);
+
+  if (!creds.GITHUB_TOKEN) {
+    throw new PreflightError(
+      `GitHub credentials not found for project "${projectName}". ` +
+      `Scoped sessions need a token to push code and open PRs. ` +
+      `Run 'agentdesk init' to reconfigure, or add GITHUB_TOKEN=<token> to .env in the project root.`,
+      { code: "MISSING_GITHUB_TOKEN" }
+    );
+  }
+
+  if (remote && isSshRemote(remote)) {
+    throw new PreflightError(
+      `Project "${projectName}" uses an SSH git remote (${remote}). ` +
+      `Scoped sessions push over HTTPS — SSH keys are intentionally isolated. ` +
+      `Switch the origin remote to https://<host>/<owner>/<repo>.git, or run this session without scoped isolation.`,
+      { code: "SSH_REMOTE" }
+    );
+  }
+}

package/cli/session-sandbox.mjs

@@ -25,33 +25,43 @@ import { tmpdir } from "os";
 import { randomUUID } from "crypto";
 
 export function createScratchHome({ projectId, sessionId, creds = {}, commitIdentity = {} }) {
+  if (!creds.GITHUB_TOKEN) {
+    // Caller is responsible for running session-preflight before reaching
+    // here. An empty token would mean a silently-broken push later, so
+    // fail loudly instead.
+    throw new Error("createScratchHome called without GITHUB_TOKEN — preflight should have caught this");
+  }
+
   const base = join(tmpdir(), "agentdesk-sessions", `${safe(projectId)}-${sessionId || randomUUID().slice(0, 8)}`);
   const ghConfigDir = join(base, "gh");
   mkdirSync(ghConfigDir, { recursive: true, mode: 0o700 });
 
   // --- gh: a scoped hosts.yml overrides the user's ~/.config/gh/ when we
   //     point GH_CONFIG_DIR at this dir. Only this project's token lives
-  //     here. Falls back to empty (no stored auth) if no token configured.
-  if (creds.GITHUB_TOKEN) {
-    writeFileSync(
-      join(ghConfigDir, "hosts.yml"),
-      `github.com:\n    oauth_token: ${creds.GITHUB_TOKEN}\n    git_protocol: https\n`,
-      { mode: 0o600 }
-    );
-  }
+  //     here.
+  writeFileSync(
+    join(ghConfigDir, "hosts.yml"),
+    `github.com:\n    oauth_token: ${creds.GITHUB_TOKEN}\n    git_protocol: https\n`,
+    { mode: 0o600 }
+  );
 
   // --- git: a scoped gitconfig overrides the user's ~/.gitconfig when we
   //     point GIT_CONFIG_GLOBAL at this file. The credential helper
-  //     script echoes the project's GITHUB_TOKEN for HTTPS pushes so
-  //     git push authenticates as this project's identity — not the
-  //     user's global SSH key or credential manager.
+  //     reads the token from a sibling file (mode 0600) instead of
+  //     interpolating it into a shell string — that way a token with $,
+  //     ", `, or newlines can't break the script or leak via /proc.
+  const tokenPath = join(base, "gh-token.txt");
+  writeFileSync(tokenPath, creds.GITHUB_TOKEN, { mode: 0o600 });
+
   const helperPath = join(base, "gh-credential-helper.sh");
   const helperScript = [
     `#!/usr/bin/env bash`,
     `if [ "$1" = "get" ]; then`,
     `  while IFS= read -r line; do [ -z "$line" ] && break; done`,
     `  echo "username=x-access-token"`,
-    `  echo "password=${creds.GITHUB_TOKEN || ""}"`,
+    `  printf 'password='`,
+    `  cat ${shQuote(tokenPath)}`,
+    `  echo`,
     `fi`,
     ``,
   ].join("\n");
@@ -91,8 +101,8 @@ export function createScratchHome({ projectId, sessionId, creds = {}, commitIden
     GIT_COMMITTER_EMAIL: commitIdentity.email || "agentdesk@local",
     // Explicit GITHUB_TOKEN/GH_TOKEN overrides gh's stored auth (which
     // we've already replaced anyway, but belt + suspenders).
-    GITHUB_TOKEN: creds.GITHUB_TOKEN || "",
-    GH_TOKEN: creds.GITHUB_TOKEN || "",
+    GITHUB_TOKEN: creds.GITHUB_TOKEN,
+    GH_TOKEN: creds.GITHUB_TOKEN,
     // Tracker-specific env — only this project's credentials reach the agent.
     LINEAR_API_KEY: creds.LINEAR_API_KEY || "",
     JIRA_EMAIL: creds.JIRA_EMAIL || "",
@@ -119,3 +129,10 @@ function gitQuote(s) {
   if (/[\s"\\#;]/.test(s)) return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
   return s;
 }
+
+// Shell-quote for embedding a file path into our credential helper script.
+// Single-quote-wrap and escape any embedded single quotes — defends against
+// scratch dirs with spaces or shell metacharacters.
+function shQuote(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}

package/cli/team.mjs

@@ -11,6 +11,7 @@ import { getStoredApiKey } from "./login.mjs";
 import { resolveTeam, generateTeamPrompt } from "./agents.mjs";
 import { runOrchestrator, runPhasedOrchestrator } from "./orchestrator.mjs";
 import { checkTrackerPermissions, resolveCredentialsFromEnv } from "./tracker-check.mjs";
+import { buildTrackerUrl } from "./tracker-url.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CLI_VERSION = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8")).version;
@@ -69,17 +70,7 @@ export async function runTeam(taskId, opts = {}) {
   }
 
   // Build task link (only for existing tasks with a tracker)
-  let taskLink = null;
-  if (!createTask) {
-    if (tracker === "linear" && config.linear?.workspace) {
-      taskLink = `https://linear.app/${config.linear.workspace}/issue/${taskId}`;
-    } else if (tracker === "jira" && config.jira?.baseUrl) {
-      taskLink = `${config.jira.baseUrl.replace(/\/+$/, "")}/browse/${taskId}`;
-    } else if (tracker === "github") {
-      const repo = config.github?.repo || "";
-      if (repo) taskLink = `https://github.com/${repo}/issues/${taskId}`;
-    }
-  }
+  const taskLink = !createTask ? buildTrackerUrl({ tracker, config, taskId }) : null;
   if (tracker) console.log(`Tracker: ${tracker}`);
   if (taskLink) {
     console.log(`Task: ${cyan}${taskLink}${reset}`);
@@ -222,7 +213,11 @@ export async function runTeam(taskId, opts = {}) {
 
   clearInterval(heartbeatInterval);
 
-  if (result.handoff) {
+  if (result.error) {
+    const red = "\x1b[31m";
+    console.log(`\n━━━ ${red}SESSION COULD NOT START${reset} ━━━`);
+    console.log(`  ${result.error}\n`);
+  } else if (result.handoff) {
     const yellow = "\x1b[33m";
     console.log(`\n━━━ ${yellow}HANDOFF${reset} ━━━`);
     console.log(`  Session paused — likely hit Claude rate/context limit.`);
@@ -235,5 +230,5 @@ export async function runTeam(taskId, opts = {}) {
   console.log(`  ${result.duration}  |  ${result.steps} steps${totalTokens ? `  |  ${totalTokens.toLocaleString()} tokens` : ""}\n`);
 
   setTimeout(() => { try { vizWs?.close(); } catch {} }, 500);
-  return 0;
+  return result.error ? 1 : 0;
 }

package/cli/tracker-url.mjs

@@ -0,0 +1,27 @@
+// Build a clickable URL for a tracker task. Single source of truth for
+// Linear/Jira/GitHub URL construction — consumed by daemon.mjs,
+// orchestrator.mjs, and team.mjs.
+
+export function buildTrackerUrl({ tracker, config, taskId }) {
+  if (!tracker || !taskId || !config) return null;
+
+  if (tracker === "linear") {
+    const workspace = config.linear?.workspace;
+    if (!workspace) return null;
+    return `https://linear.app/${workspace}/issue/${taskId}`;
+  }
+
+  if (tracker === "jira") {
+    const baseUrl = config.jira?.baseUrl;
+    if (!baseUrl) return null;
+    return `${baseUrl.replace(/\/+$/, "")}/browse/${taskId}`;
+  }
+
+  if (tracker === "github") {
+    const repo = config.github?.repo;
+    if (!repo) return null;
+    return `https://github.com/${repo}/issues/${taskId}`;
+  }
+
+  return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kendoo.agentdesk/agentdesk",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "description": "AI team orchestrator for Claude Code — run collaborative agent sessions from your terminal",
   "type": "module",
   "bin": {
@@ -22,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",
+    "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",
     "lint:changelog": "node scripts/lint-changelog.mjs",
     "prepublishOnly": "node scripts/lint-changelog.mjs"
   },