@kendoo.agentdesk/agentdesk 0.16.2 → 0.17.0

package/CHANGELOG.md

@@ -8,6 +8,16 @@ All user-facing changes to AgentDesk. Each entry is tagged:
 
 Internal refactors, infrastructure changes, and architectural notes are not listed here.
 
+## [0.17.0] — 2026-04-18
+
+### Added
+- `[CLI]` Each session now runs with a scoped identity. Before spawning, agentdesk builds a private scratch home containing only this project's tracker credentials, git commit identity, and a scoped GitHub credential helper. `gh`, `git`, and `ssh` inside the session see only what we put there — your global accounts, other projects' tokens, and keys outside the scratch dir aren't discovered by default lookups. Prevents accidental cross-project identity use on shared machines.
+
+## [0.16.3] — 2026-04-18
+
+### Changed
+- `[UI]` Docs and Guide pages updated to reflect the new tracker-setup flow: dedicated-user vs personal-account tradeoff, verify-and-echo step, config sync behavior, and the identity-badge field. README aligned with the same copy.
+
 ## [0.16.2] — 2026-04-18
 
 ### Added

package/README.md

@@ -43,7 +43,11 @@ Opens your browser to [agentdesk.live](https://agentdesk.live) where you sign up
 agentdesk init
 ```
 
-This detects your project, asks which task tracker you use (Linear, Jira, GitHub Issues, or none), and saves the config.
+A guided wizard walks you through it: picks up your project type, asks which task tracker you use (Linear, Jira, GitHub Issues, or none), shows the tradeoff between a **dedicated AgentDesk user** and your personal account with step-by-step setup for either, verifies the credentials, echoes "Posting as: …" so you can confirm which identity will appear on tickets, then writes `.agentdesk.json`.
+
+Re-running `agentdesk init` in a project that already has config offers a "tracker only" shortcut. Use `agentdesk init --quick` to skip the narrative copy for scripted setups.
+
+`.agentdesk.json` is kept in sync with the server: every CLI run fetches the authoritative config and rewrites the local file as a credential-free snapshot. Credentials live only on the server, encrypted. If a local edit disagreed with the server's value, a one-line warning lists the overridden fields.
 
 ### 4. Run a team session
 
@@ -89,9 +93,9 @@ agentdesk update                       Update to the latest version
 Settings can be managed in two ways:
 
 1. **Web UI** — go to [agentdesk.live](https://agentdesk.live), select a project, and click the gear icon to configure tracker, team composition, custom agents, commands, and instructions.
-2. **Local file** — `.agentdesk.json` in your project root. Local settings override server settings.
+2. **Local file** — `.agentdesk.json` in your project root. Acts as a credential-free cache of the server config, rewritten on every CLI run. If the server is unreachable, `.agentdesk.json` is used as-is (and never mutated).
 
-The CLI fetches settings from the server at runtime. If the server is unreachable, it falls back to `.agentdesk.json`.
+The server is the source of truth. If you edit `.agentdesk.json` directly while the server has a different value for the same field, the server wins and the CLI prints a one-line warning listing the overridden fields so you notice. To push local edits back up, re-run `agentdesk init` (the wizard writes to the server).
 
 ### Task trackers
 

package/cli/daemon.mjs

@@ -385,6 +385,7 @@ export async function runDaemon() {
         tracker, config,
         project: detected, team, teamSections,
         sessionUrl,
+        sessionId,
         cwd: project.path,
         apiKey,
         serverUrl: agentdeskServer,

package/cli/orchestrator.mjs

@@ -7,6 +7,7 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { buildPrompt, buildSoloPrompt, buildPhasedPrompt } from "./prompt.mjs";
 import { createStreamParser } from "./stream-parser.mjs";
+import { createScratchHome } from "./session-sandbox.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CLI_VERSION = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8")).version;
@@ -72,10 +73,23 @@ function modelLabelForPhase(phase, phaseModels) {
 export async function runOrchestrator({
   taskId, taskLink, description, createTask, tracker, config,
   project, team, teamSections, sessionUrl, cwd,
-  onEvent, apiKey, serverUrl, soloAgent, childStrategy,
+  onEvent, apiKey, serverUrl, soloAgent, childStrategy, sessionId,
 }) {
   const trackerCreds = await fetchTrackerCredentials(project?.name, apiKey, serverUrl);
-  const env = { ...process.env, ...loadDotEnv(cwd), ...trackerCreds };
+
+  // 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 };
   const startTime = Date.now();
   let totalInputTokens = 0;
   let totalOutputTokens = 0;
@@ -200,6 +214,8 @@ export async function runOrchestrator({
     emit({ type: "session:end", duration, steps: totalSteps, inputTokens: totalInputTokens, outputTokens: totalOutputTokens });
   }
 
+  sandbox.cleanup();
+
   return { duration, steps: totalSteps, inputTokens: totalInputTokens, outputTokens: totalOutputTokens, handoff: isHandoff };
 }
 
@@ -245,10 +261,20 @@ async function runSinglePhase({ prompt, cwd, env, teamNames, emit, modelArgs = [
 export async function runPhasedOrchestrator({
   taskId, taskLink, description, createTask, tracker, config,
   project, team, teamSections, sessionUrl, cwd,
-  onEvent, apiKey, serverUrl, onChild,
+  onEvent, apiKey, serverUrl, onChild, sessionId,
 }) {
   const trackerCreds = await fetchTrackerCredentials(project?.name, apiKey, serverUrl);
-  const env = { ...process.env, ...loadDotEnv(cwd), ...trackerCreds };
+
+  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 };
   const startTime = Date.now();
   const teamNames = teamSections.names;
 
@@ -366,5 +392,7 @@ export async function runPhasedOrchestrator({
     emit({ type: "session:end", duration, steps: totalSteps, inputTokens: totalInputTokens, outputTokens: totalOutputTokens });
   }
 
+  sandbox.cleanup();
+
   return { duration, steps: totalSteps, inputTokens: totalInputTokens, outputTokens: totalOutputTokens, handoff };
 }

package/cli/session-sandbox.mjs

@@ -0,0 +1,121 @@
+// Per-session scratch HOME for identity isolation.
+//
+// When a session runs, we point HOME / GH_CONFIG_DIR / XDG_CONFIG_HOME at a
+// private scratch directory containing only this project's git + gh config.
+// This means `gh`, `git`, `ssh` inside the session see only the identity we
+// put there — the user's global accounts, other projects' tokens, or keys
+// in the real $HOME aren't discovered by default lookups.
+//
+// This is Tier 1 (scoped-env). It prevents accidental cross-project use.
+// Tier 2 (sandbox-exec / bwrap) layers a kernel-enforced boundary on top.
+
+import { mkdirSync, writeFileSync, chmodSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { randomUUID } from "crypto";
+
+// Build a session scratch HOME. Returns { home, env, cleanup }.
+//   projectId        — identifier used to make the dir path readable
+//   sessionId        — unique per session; guarantees parallel sessions don't collide
+//   creds            — { LINEAR_API_KEY?, JIRA_EMAIL?, JIRA_API_TOKEN?, GITHUB_TOKEN? }
+//   commitIdentity   — { name, email } for git user.* (falls back to sensible defaults)
+//
+// The caller spawns the Claude child with:
+//   { ...process.env, ...env }
+// …and MUST call cleanup() when the session ends (success, crash, signal).
+export function createScratchHome({ projectId, sessionId, creds = {}, commitIdentity = {} }) {
+  const base = join(tmpdir(), "agentdesk-sessions", `${safe(projectId)}-${sessionId || randomUUID().slice(0, 8)}`);
+  mkdirSync(base, { recursive: true, mode: 0o700 });
+  mkdirSync(join(base, ".config"), { recursive: true, mode: 0o700 });
+  mkdirSync(join(base, ".config", "gh"), { recursive: true, mode: 0o700 });
+
+  // --- gh: scoped hosts.yml with only this project's GitHub token ---
+  if (creds.GITHUB_TOKEN) {
+    const hostsPath = join(base, ".config", "gh", "hosts.yml");
+    const hostsYaml =
+      `github.com:\n` +
+      `    oauth_token: ${creds.GITHUB_TOKEN}\n` +
+      `    git_protocol: https\n`;
+    writeFileSync(hostsPath, hostsYaml, { mode: 0o600 });
+  }
+
+  // --- git: scoped gitconfig with commit identity and a credential helper
+  //     that echoes this token for github.com HTTPS pushes. This bypasses
+  //     macOS Keychain, SSH keys, and the global git-credential-manager. ---
+  const helperPath = join(base, "gh-credential-helper.sh");
+  const helperScript = [
+    `#!/usr/bin/env bash`,
+    `# Per-session credential helper. Echoes the scoped GitHub token to git`,
+    `# so HTTPS pushes authenticate as this session's identity, regardless of`,
+    `# the user's global git-credential state.`,
+    `if [ "$1" = "get" ]; then`,
+    `  while IFS= read -r line; do [ -z "$line" ] && break; done`,
+    `  echo "username=x-access-token"`,
+    `  echo "password=${creds.GITHUB_TOKEN || ""}"`,
+    `fi`,
+    ``,
+  ].join("\n");
+  writeFileSync(helperPath, helperScript, { mode: 0o700 });
+
+  const gitconfig = [
+    `[user]`,
+    `\tname = ${gitQuote(commitIdentity.name || "AgentDesk")}`,
+    `\temail = ${gitQuote(commitIdentity.email || "agentdesk@local")}`,
+    ``,
+    `[credential "https://github.com"]`,
+    `\thelper = ${gitQuote(helperPath)}`,
+    ``,
+    // Stop the global credential helper (osxkeychain, gcm, libsecret) from
+    // being consulted. Our helper above is the only one.
+    `[credential]`,
+    `\thelper = `,
+    `\thelper = ${gitQuote(helperPath)}`,
+    ``,
+  ].join("\n");
+  writeFileSync(join(base, ".gitconfig"), gitconfig, { mode: 0o600 });
+
+  // --- Scoped env for the child process ---
+  const env = {
+    HOME: base,
+    XDG_CONFIG_HOME: join(base, ".config"),
+    GH_CONFIG_DIR: join(base, ".config", "gh"),
+
+    // Explicit GITHUB_TOKEN overrides gh's stored auth (which we've
+    // already replaced with our hosts.yml, but belt + suspenders).
+    GITHUB_TOKEN: creds.GITHUB_TOKEN || "",
+    GH_TOKEN: creds.GITHUB_TOKEN || "",
+
+    // Linear / Jira — only this project's credentials travel into the session.
+    LINEAR_API_KEY: creds.LINEAR_API_KEY || "",
+    JIRA_EMAIL: creds.JIRA_EMAIL || "",
+    JIRA_API_TOKEN: creds.JIRA_API_TOKEN || "",
+  };
+
+  // Drop empty-string entries so child processes don't see ambiguous empty vars.
+  for (const k of Object.keys(env)) if (env[k] === "") delete env[k];
+
+  let cleaned = false;
+  function cleanup() {
+    if (cleaned) return;
+    cleaned = true;
+    try { if (existsSync(base)) rmSync(base, { recursive: true, force: true }); } catch {}
+  }
+
+  // Best-effort cleanup if the parent process exits without an explicit call.
+  // Don't hijack SIGINT/SIGTERM — the daemon has its own signal handling and
+  // each session registering a process.exit() handler would kill the daemon
+  // as soon as one session saw a signal. /tmp is cleaned by the OS anyway.
+  process.once("exit", cleanup);
+
+  return { home: base, env, cleanup };
+}
+
+function safe(s) {
+  return String(s || "unknown").replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 40);
+}
+
+function gitQuote(s) {
+  // git config values: wrap in quotes if they contain whitespace or shell-sensitive chars.
+  if (/[\s"\\#;]/.test(s)) return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  return s;
+}

package/cli/team.mjs

@@ -210,6 +210,7 @@ export async function runTeam(taskId, opts = {}) {
   const result = await orchestrate({
     taskId, taskLink, description, createTask, tracker, config,
     project, team, teamSections, sessionUrl, cwd,
+    sessionId,
     onEvent: vizSend,
     apiKey,
     serverUrl: agentdeskServer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kendoo.agentdesk/agentdesk",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "AI team orchestrator for Claude Code — run collaborative agent sessions from your terminal",
   "type": "module",
   "bin": {