@kendoo.agentdesk/agentdesk 0.19.0 → 0.19.2

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.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
+- `[CLI]` Creating a new task from a description now locks the task to the project configured in settings. The prompt previously told the agent to "create a Jira issue" without naming a project, so Claude was free to pick any project its token had access to. Jira and Linear create-from-description paths now explicitly pass the configured project key / team key and tell the agent not to choose a different one.
+
 ## [0.19.0] — 2026-04-18
 
 ### Changed

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/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/prompt.mjs

@@ -61,9 +61,23 @@ export function buildPrompt({ taskId, taskLink, description, createTask, tracker
   if (createTask && description) {
     let createInstr = "\n\n## CREATE TASK (MANDATORY — FIRST ACTION IN INTAKE)\n\nNo task ID was provided — only a description. Jane MUST create a new task in the tracker as the VERY FIRST action before anything else.\n\n";
     if (tracker === "linear") {
-      createInstr += `Create a Linear issue using the GraphQL API:\n- Endpoint: https://api.linear.app/graphql\n- Auth: Authorization: $LINEAR_API_KEY\n- Set the title based on the description below\n- After creation, use the returned identifier (e.g., KEN-530) as the task ID for the rest of the session\n`;
+      const linearTeamKey = config.linear?.teamKey;
+      createInstr += `Create a Linear issue using the GraphQL API:\n- Endpoint: https://api.linear.app/graphql\n- Auth: Authorization: $LINEAR_API_KEY\n`;
+      if (linearTeamKey) {
+        createInstr += `- **Team: MUST be \`${linearTeamKey}\`.** First resolve the team id: \`{ teams(filter: { key: { eq: "${linearTeamKey}" } }) { nodes { id } } }\`, then pass that id as \`teamId\` in \`issueCreate\`. Do NOT pick any other team, even if your account has access to others.\n`;
+      } else {
+        createInstr += `- ⚠ No Linear team key is configured. Ask the user which team this issue should live in BEFORE creating it.\n`;
+      }
+      createInstr += `- Set the title based on the description below\n- After creation, use the returned identifier (e.g., ${linearTeamKey || "KEN"}-530) as the task ID for the rest of the session\n`;
     } else if (tracker === "jira") {
-      createInstr += `Create a Jira issue:\n- Endpoint: ${config.jira?.baseUrl || ""}/rest/api/3/issue\n- Auth: Basic auth with $JIRA_EMAIL and $JIRA_API_TOKEN\n- Set the summary based on the description below\n- After creation, use the returned key (e.g., PROJ-42) as the task ID for the rest of the session\n`;
+      const jiraProject = config.jira?.project;
+      createInstr += `Create a Jira issue:\n- Endpoint: ${config.jira?.baseUrl || ""}/rest/api/3/issue\n- Auth: Basic auth with $JIRA_EMAIL and $JIRA_API_TOKEN\n`;
+      if (jiraProject) {
+        createInstr += `- **Project: MUST be \`${jiraProject}\`.** Set \`fields.project.key = "${jiraProject}"\` in the create payload. Do NOT pick any other project, even if your account has access to others.\n`;
+      } else {
+        createInstr += `- ⚠ No Jira project key is configured. Ask the user which project this task should live in BEFORE creating it.\n`;
+      }
+      createInstr += `- Set the summary based on the description below\n- After creation, use the returned key (e.g., ${jiraProject || "PROJ"}-42) as the task ID for the rest of the session\n`;
     } else if (tracker === "github") {
       createInstr += `Create a GitHub issue:\n- Run: gh issue create --title "..." --body "..."\n- After creation, use the returned issue number as the task ID for the rest of the session\n`;
     }
@@ -442,9 +456,17 @@ export function buildPhasedPrompt({ phase, taskId, taskLink, description, create
   if (phase === "INTAKE" && createTask && description) {
     let createInstr = "\n\n## CREATE TASK (MANDATORY — FIRST ACTION)\n\nNo task ID was provided. Jane MUST create a new task in the tracker as the VERY FIRST action.\n\n";
     if (tracker === "linear") {
+      const linearTeamKey = config.linear?.teamKey;
       createInstr += `Create a Linear issue using the GraphQL API.\n`;
+      if (linearTeamKey) {
+        createInstr += `**Team MUST be \`${linearTeamKey}\`.** Resolve its id via \`{ teams(filter: { key: { eq: "${linearTeamKey}" } }) { nodes { id } } }\` and pass as \`teamId\` in \`issueCreate\`. Do NOT pick any other team.\n`;
+      }
     } else if (tracker === "jira") {
+      const jiraProject = config.jira?.project;
       createInstr += `Create a Jira issue at ${config.jira?.baseUrl || ""}.\n`;
+      if (jiraProject) {
+        createInstr += `**Project MUST be \`${jiraProject}\`.** Set \`fields.project.key = "${jiraProject}"\` in the create payload. Do NOT pick any other project.\n`;
+      }
     } else if (tracker === "github") {
       createInstr += `Create a GitHub issue: gh issue create --title "..." --body "..."\n`;
     }

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.0",
+  "version": "0.19.2",
   "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"
   },