@cloudcli-ai/cloudcli 1.37.3 → 1.37.4

package/server/shared/interfaces.ts

@@ -1,5 +1,6 @@
 import type {
   AnyRecord,
+  BackgroundTaskSummary,
   FetchHistoryOptions,
   FetchHistoryResult,
   LLMProvider,
@@ -17,6 +18,7 @@ import type {
   ProviderRuntimePermissionGateway,
   ProviderRuntimeWriter,
   UpsertProviderMcpServerInput,
+  WorkflowAgentActivity,
 } from '@/shared/types.js';
 
 //----------------- PROVIDER CONTRACT INTERFACES ------------
@@ -36,6 +38,19 @@ export interface IProviderRuntime {
   ): Promise<unknown>;
   abort(sessionId: string): boolean | Promise<boolean>;
   permissions?: ProviderRuntimePermissionGateway;
+  /**
+   * Sessions with background tasks still outstanding, whether or not their
+   * turn has ended. Only a runtime that keeps its process open past a turn for
+   * such work has anything to report; the others leave this undefined and the
+   * running-sessions list falls back to chat runs alone.
+   */
+  listBackgroundWork?(): Array<{ sessionId: string; tasks: BackgroundTaskSummary[] }>;
+  /**
+   * Stops one outstanding background task. Resolves false when the session has
+   * no live process or that process is not tracking the task — it already
+   * settled, or the id was never one of its own.
+   */
+  stopBackgroundTask?(sessionId: string, taskId: string): Promise<boolean>;
 }
 
 /**
@@ -216,6 +231,20 @@ export interface IProviderSessions {
    * gateway branches on.
    */
   rewindSession?(sessionId: string, keepThroughId: string | null): Promise<void>;
+
+  /**
+   * Reads what one agent of a workflow run did, from the transcript the run
+   * wrote for it, with the status its journal gives it. Returns `null` when the
+   * run left no transcript for that agent.
+   *
+   * Implemented only by providers whose runtime spawns workflow agents; its
+   * absence is what makes an agent's timeline unavailable in the card.
+   */
+  readWorkflowAgentActivity?(
+    sessionId: string,
+    runId: string,
+    agentId: string,
+  ): Promise<WorkflowAgentActivity | null>;
 }
 
 // ---------------------------

package/server/shared/message-unification.ts

@@ -322,7 +322,7 @@ function truncateOutput(value: string): string {
  * only a single oversized string — a file body or an encoded image — is ever
  * the thing making it large.
  */
-function truncateNestedOutput(value: unknown): unknown {
+export function truncateNestedOutput(value: unknown): unknown {
   if (typeof value === 'string') {
     return truncateOutput(value);
   }

package/server/shared/tests/read-only-roots.test.ts

@@ -0,0 +1,139 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, realpath, rm, symlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test, { after } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+// The Claude projects root is derived from `os.homedir()` when the utils module
+// is first imported, so HOME has to point at the fixture home *before* that
+// import runs. The fixture lives beside this file rather than under the temp
+// directory: a home under `/tmp` would put everything under a read-only root
+// and make the escape tests pass for the wrong reason.
+const testDirectory = path.dirname(fileURLToPath(import.meta.url));
+const fixtureRoot = await realpath(await mkdtemp(path.join(testDirectory, 'read-only-roots-fixture-')));
+const fixtureHome = path.join(fixtureRoot, 'home');
+const claudeProjectsRoot = path.join(fixtureHome, '.claude', 'projects');
+// Under no read-only root: not the temp directory, not the Claude projects dir.
+const outsideDirectory = path.join(fixtureRoot, 'outside');
+await mkdir(claudeProjectsRoot, { recursive: true });
+await mkdir(outsideDirectory);
+
+const previousHome = process.env.HOME;
+const previousUserProfile = process.env.USERPROFILE;
+process.env.HOME = fixtureHome;
+process.env.USERPROFILE = fixtureHome;
+
+const { resolvePathUnderRoots, resolveReadOnlyRootPath, validateWorkspacePath } = await import('@/shared/utils.js');
+
+after(async () => {
+  if (previousHome === undefined) {
+    delete process.env.HOME;
+  } else {
+    process.env.HOME = previousHome;
+  }
+  if (previousUserProfile === undefined) {
+    delete process.env.USERPROFILE;
+  } else {
+    process.env.USERPROFILE = previousUserProfile;
+  }
+  await rm(fixtureRoot, { recursive: true, force: true });
+});
+
+test('a path under the system temp directory resolves as readable', async () => {
+  const temporaryDirectory = await mkdtemp(path.join(os.tmpdir(), 'read-only-root-'));
+
+  try {
+    const filePath = path.join(temporaryDirectory, 'agent.output');
+    await writeFile(filePath, 'agent output', 'utf8');
+
+    // A background command's log is quoted straight out of the transcript, so
+    // this exact shape has to resolve.
+    const resolvedDirectory = await resolveReadOnlyRootPath(temporaryDirectory);
+    assert.ok(resolvedDirectory);
+    assert.equal(await resolveReadOnlyRootPath(filePath), path.join(resolvedDirectory, 'agent.output'));
+  } finally {
+    await rm(temporaryDirectory, { recursive: true, force: true });
+  }
+});
+
+test('a background agent output link resolves to its transcript under the Claude projects directory', async () => {
+  const temporaryDirectory = await mkdtemp(path.join(os.tmpdir(), 'read-only-root-'));
+
+  try {
+    // Claude writes `/tmp/claude-<uid>/<project>/<session>/tasks/<task>.output`
+    // as a symlink to the agent's transcript under `~/.claude/projects`.
+    const transcriptDirectory = path.join(claudeProjectsRoot, '-home-user-project', 'session-1', 'subagents');
+    await mkdir(transcriptDirectory, { recursive: true });
+    const transcriptPath = path.join(transcriptDirectory, 'agent-1.jsonl');
+    await writeFile(transcriptPath, '{"type":"assistant"}\n', 'utf8');
+
+    const tasksDirectory = path.join(temporaryDirectory, 'tasks');
+    await mkdir(tasksDirectory);
+    const outputLink = path.join(tasksDirectory, 'task-1.output');
+    await symlink(transcriptPath, outputLink);
+
+    assert.equal(await resolveReadOnlyRootPath(outputLink), transcriptPath);
+    assert.equal(await resolveReadOnlyRootPath(transcriptPath), transcriptPath);
+  } finally {
+    await rm(temporaryDirectory, { recursive: true, force: true });
+  }
+});
+
+test('the temp directory stays read-only: it is still not a valid workspace location', async () => {
+  const temporaryDirectory = await mkdtemp(path.join(os.tmpdir(), 'read-only-root-'));
+
+  try {
+    // Being browsable must not make it writable — the write policy is
+    // `validateWorkspacePath` and it does not consult the read-only roots.
+    const validation = await validateWorkspacePath(temporaryDirectory);
+    assert.equal(validation.valid, false);
+  } finally {
+    await rm(temporaryDirectory, { recursive: true, force: true });
+  }
+});
+
+test('paths outside the read-only roots do not resolve', async () => {
+  assert.equal(await resolveReadOnlyRootPath(outsideDirectory), null);
+  assert.equal(await resolveReadOnlyRootPath('/etc/passwd'), null);
+  assert.equal(await resolveReadOnlyRootPath('relative/path'), null);
+  assert.equal(await resolveReadOnlyRootPath(''), null);
+});
+
+test('a symlink planted in the temp directory cannot read outside every root', async () => {
+  const temporaryDirectory = await mkdtemp(path.join(os.tmpdir(), 'read-only-root-'));
+
+  try {
+    await writeFile(path.join(outsideDirectory, 'secret.txt'), 'secret', 'utf8');
+    const escapeLink = path.join(temporaryDirectory, 'escape');
+    await symlink(outsideDirectory, escapeLink);
+
+    // The name is under a read-only root but the file is not, so resolving the
+    // link before comparing is what keeps this closed.
+    assert.equal(await resolveReadOnlyRootPath(escapeLink), null);
+    assert.equal(await resolveReadOnlyRootPath(path.join(escapeLink, 'secret.txt')), null);
+  } finally {
+    await rm(temporaryDirectory, { recursive: true, force: true });
+  }
+});
+
+test('a root that does not exist does not stop later roots from matching', async () => {
+  const temporaryDirectory = await mkdtemp(path.join(os.tmpdir(), 'read-only-root-'));
+
+  try {
+    // `/tmp` does not exist on Windows; the temp directory listed after it
+    // must still be checked rather than the whole search giving up.
+    const missingRoot = path.join(fixtureRoot, 'missing');
+    assert.equal(await resolvePathUnderRoots(temporaryDirectory, [missingRoot]), null);
+    assert.equal(
+      await resolvePathUnderRoots(temporaryDirectory, [missingRoot, os.tmpdir()]),
+      await realpath(temporaryDirectory),
+    );
+  } finally {
+    await rm(temporaryDirectory, { recursive: true, force: true });
+  }
+});
+
+test('traversal out of the temp directory does not resolve', async () => {
+  assert.equal(await resolveReadOnlyRootPath(`${os.tmpdir()}/../etc/passwd`), null);
+});

package/server/shared/tests/strip-ansi-sequences.test.ts

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { stripAnsiSequences } from '@/shared/utils.js';
+
+test('strips the SGR colors a CLI writes around its own warnings', () => {
+  const styled = '\u001B[93m\u001B[1m! \u001B[0m\u001B[0mpermission requested: external_directory';
+  assert.equal(stripAnsiSequences(styled), '! permission requested: external_directory');
+});
+
+test('strips CSI cursor control, including the 8-bit introducer', () => {
+  assert.equal(stripAnsiSequences('a\u001B[2Kb\u001B[?25lc'), 'abc');
+  assert.equal(stripAnsiSequences('a\u009B31mb'), 'ab');
+});
+
+test('strips an OSC sequence with either terminator, without eating the rest', () => {
+  assert.equal(stripAnsiSequences('\u001B]0;title\u0007done'), 'done');
+  assert.equal(stripAnsiSequences('\u001B]8;;https://example.com\u001B\\link'), 'link');
+});
+
+test('strips other ECMA-48 escape sequences such as charset selection', () => {
+  assert.equal(stripAnsiSequences('\u001B(Bplain'), 'plain');
+});
+
+test('leaves text without escape sequences untouched', () => {
+  assert.equal(stripAnsiSequences('plain [93m-looking text'), 'plain [93m-looking text');
+});
+
+test('strips a CSI sequence that carries a private parameter byte', () => {
+  assert.equal(stripAnsiSequences('a\u001B[>cb'), 'ab');
+});
+
+test('stops an unterminated OSC at the next escape, so later styling still strips', () => {
+  assert.equal(
+    stripAnsiSequences('\u001B]0;unterminated\u001B[31mred\u001B[0m'),
+    '0;unterminatedred',
+  );
+});
+
+test('reduces a styling-only chunk to an empty string', () => {
+  assert.equal(stripAnsiSequences('\u001B[0m\u001B[2K'), '');
+});

package/server/shared/types.ts

@@ -94,6 +94,13 @@ export type ProviderModelOption = {
 export type ProviderModelsDefinition = {
   OPTIONS: ProviderModelOption[];
   DEFAULT: string;
+  /**
+   * Reasoning-effort levels a custom entry of this catalog may declare, weakest
+   * first; empty for providers without effort support. The Providers service
+   * sets it on merged catalogs from the capability matrix, so the model
+   * library offers the same levels on every machine. Adapter catalogs omit it.
+   */
+  EFFORT_LEVELS?: string[];
 };
 
 /**
@@ -110,6 +117,22 @@ export type CustomProviderModelRecord = {
   modelId: string;
   model: string;
   sortOrder: number;
+  /** NULL for rows that never declared effort levels, including pre-existing rows. */
+  effort: CustomProviderModelEffort | null;
+};
+
+/**
+ * Reasoning-effort levels a user declared for one custom model.
+ *
+ * `values` holds unique, non-empty level ids drawn from the levels the
+ * provider's predefined models declare, and is never empty (an empty
+ * declaration is stored as NULL). `default`, when present, is one of `values`
+ * and documents the level the provider applies when the composer sends
+ * `Default`, mirroring `ProviderModelOption['effort'].default`.
+ */
+export type CustomProviderModelEffort = {
+  values: string[];
+  default?: string;
 };
 
 /**
@@ -122,6 +145,12 @@ export type CustomProviderModelRecord = {
 export type CustomProviderModelInput = {
   id: string;
   model: string;
+  /**
+   * Optional reasoning-effort declaration. `undefined` leaves stored metadata
+   * untouched on update (and stores none on create) so clients that predate
+   * effort metadata keep working; `null` clears it.
+   */
+  effort?: CustomProviderModelEffort | null;
 };
 
 // ---------------------------
@@ -190,7 +219,8 @@ export type MessageKind =
   | 'permission_cancelled'
   | 'session_created'
   | 'history_truncated'
-  | 'task_notification';
+  | 'task_notification'
+  | 'task_status';
 
 /**
  * Event kinds added by the chat gateway layer on top of provider message kinds.
@@ -258,6 +288,24 @@ export type SessionUpsertedEvent = {
  * Every provider-specific message must be converted into this shape before being
  * emitted outside provider-specific modules.
  */
+/**
+ * A compaction, as the transcript records it.
+ *
+ * `running` is the status the CLI sends when it starts compacting, `done` the
+ * boundary it sends when it has, `failed` a compaction that did not finish.
+ * The token counts and duration only come with a boundary.
+ */
+export type CompactionInfo = {
+  phase: 'running' | 'done' | 'failed';
+  /** Whether the user asked for it or the context window did. */
+  trigger?: 'manual' | 'auto';
+  /** Tokens the conversation held before and after, when the boundary reports them. */
+  preTokens?: number;
+  postTokens?: number;
+  durationMs?: number;
+  error?: string | null;
+};
+
 export type NormalizedMessage = {
   id: string;
   /**
@@ -280,6 +328,15 @@ export type NormalizedMessage = {
   seq?: number;
   role?: 'user' | 'assistant';
   content?: string;
+  /**
+   * The model that produced this assistant message, as the provider reported
+   * it on the transcript row (today: Claude's `message.model`, e.g.
+   * `claude-opus-5`). Absent on user turns — no provider records which model a
+   * request went out with — and absent when the provider named a placeholder
+   * such as `<synthetic>`, so a locally-fabricated notice is never labelled
+   * with a model it did not run on.
+   */
+  model?: string;
   /**
    * Optional display-oriented metadata used by providers that need to expose
    * richer transcript artifacts without introducing a brand-new message kind.
@@ -295,6 +352,8 @@ export type NormalizedMessage = {
   isLocalCommand?: boolean;
   isLocalCommandStdout?: boolean;
   isCompactSummary?: boolean;
+  /** Set on the row that stands in for a compaction, so the UI can draw it as one. */
+  compact?: CompactionInfo;
   images?: unknown;
   /** Non-image files attached to a user turn after provider history normalization. */
   files?: unknown;
@@ -326,14 +385,149 @@ export type NormalizedMessage = {
   subagentTools?: SubagentActivity[];
   /** Identity and lifecycle of the subagent this `tool_use` spawned. */
   subagent?: SubagentInfo;
+  /** The workflow run this `tool_use` launched, read from its journal on disk. */
+  workflow?: WorkflowInfo;
   /** Stored memory the reply drew on, when the provider reports it. */
   memoryCitations?: MemoryCitation[];
   toolUseResult?: unknown;
   sequence?: number;
   rowid?: number;
+  /**
+   * `task_status` fields: one lifecycle event of a background task the live
+   * run is tracking. `taskId` is the provider's task handle; `toolUseId` names
+   * the call that launched it and is absent on `updated`, which the SDK keys by
+   * task id alone. `status` and `summary` above carry the event's own.
+   */
+  event?: 'started' | 'progress' | 'updated' | 'notification';
+  taskId?: string;
+  toolUseId?: string;
+  taskType?: string;
+  workflowName?: string;
+  description?: string;
+  usage?: TaskUsage;
+  outputFile?: string;
+  /** A workflow's `progress` only: where each agent the run spawned stands. */
+  agents?: WorkflowAgentProgress[];
   [key: string]: unknown;
 };
 
+/**
+ * What a background task has spent so far, as the CLI reports it on
+ * `task_progress` and `task_notification`.
+ */
+export type TaskUsage = {
+  totalTokens: number;
+  toolUses: number;
+  durationMs: number;
+};
+
+/**
+ * One background task a live session still has outstanding — a spawned
+ * agent, a workflow run or a backgrounded command — as the runtime tracks it
+ * from the stream's `task_started` until the event that settles it.
+ *
+ * `taskId` is the handle a stop request names; `toolUseId` is the call that
+ * launched it, which is how the client pairs the task with its card.
+ * `startedAt` is the server clock at `task_started`, so a session whose turn
+ * has ended can still report how long its work has been going.
+ */
+export type BackgroundTaskSummary = {
+  taskId: string;
+  toolUseId: string;
+  taskType: string;
+  description: string;
+  workflowName?: string;
+  startedAt: number;
+  /**
+   * The task was launched by a subagent or workflow agent, not by the
+   * session's own turn: its `toolUseId` names a call in that agent's
+   * transcript, so no card in this session's transcript matches it. Listed so
+   * it can still be stopped; not counted as the session's own work.
+   */
+  nested?: boolean;
+};
+
+/**
+ * Where one agent of a running workflow stands, as the SDK reports it on the
+ * run's `task_progress` events.
+ *
+ * An entry the script has queued but not yet started has no `agentId` and is
+ * identified by `index` alone; once the agent runs, `agentId` names the
+ * transcript it writes. `lastToolName` and `lastToolSummary` are the agent's
+ * own latest tool call — unlike the event's task-level `last_tool_name`, which
+ * for a workflow is the current agent's label.
+ */
+export type WorkflowAgentProgress = {
+  index: number;
+  label?: string;
+  /** The title of the script phase the agent runs under, when it has one. */
+  phase?: string;
+  agentId?: string;
+  model?: string;
+  state: 'queued' | 'running' | 'done' | 'failed';
+  startedAt?: number;
+  lastToolName?: string;
+  lastToolSummary?: string;
+  promptPreview?: string;
+  tokens?: number;
+  toolCalls?: number;
+  durationMs?: number;
+  resultPreview?: string;
+};
+
+/**
+ * One workflow agent's recorded timeline, read from its transcript on demand
+ * when the card is opened — the SDK never streams an agent's own rows to the
+ * parent session, so this is the only way to see what it did.
+ *
+ * `activityCount` is the full length of the timeline; `activity` is capped
+ * for transport like a subagent's `subagentTools`.
+ */
+export type WorkflowAgentActivity = {
+  agent: {
+    id: string;
+    label?: string;
+    model?: string;
+    status: 'running' | 'completed' | 'failed' | 'stopped';
+  };
+  activity: SubagentActivity[];
+  activityCount: number;
+};
+
+/**
+ * One agent a workflow run spawned, as its journal records it.
+ *
+ * `label` and `phase` are whatever the script passed when it spawned the
+ * agent; older scripts passed neither. An agent with a `started` record and no
+ * `result` or `failed` one is still running as far as the journal knows.
+ */
+export type WorkflowAgentInfo = {
+  id: string;
+  label?: string;
+  phase?: string;
+  /** `stopped` is an agent the journal never settled although the run itself has — abandoned by a stop or a resume that re-ran the step. */
+  status: 'running' | 'completed' | 'failed' | 'stopped';
+};
+
+/**
+ * A `Workflow` tool call's run, attached to the `tool_use` that launched it.
+ *
+ * `status` follows the same rule as a background agent's: the task
+ * notification's word when one exists, else `running` only while the process
+ * that launched it is still up, else `stopped`. The agent list and counts come
+ * from `<transcriptDir>/journal.jsonl`; both are empty when the run left no
+ * journal behind (a fork copies only the parent's transcript).
+ */
+export type WorkflowInfo = {
+  runId: string;
+  name: string;
+  description?: string;
+  status: 'running' | 'completed' | 'failed' | 'stopped';
+  agents: WorkflowAgentInfo[];
+  agentCounts: { total: number; completed: number; failed: number; running: number; stopped: number };
+  scriptPath?: string;
+};
+
 /**
  * One stored memory an assistant reply drew on.
  *
@@ -380,7 +574,8 @@ export type SubagentActivity = {
  * that it is whatever the provider reported — Claude's task notification
  * carries one — and `completed` when the provider reported nothing. A failed
  * tool call *inside* the agent is not a failed agent, so it is never inferred
- * from the transcript.
+ * from the transcript. A background agent whose session process ended before
+ * it reported is `stopped`: no outcome exists and none is coming.
  */
 export type SubagentInfo = {
   /** Provider-native agent id — Claude `agentId`, Codex `agent_thread_id`. */
@@ -391,7 +586,7 @@ export type SubagentInfo = {
   type?: string;
   /** One-line task summary shown in the collapsed header. */
   description?: string;
-  status: 'running' | 'completed' | 'failed';
+  status: 'running' | 'completed' | 'failed' | 'stopped';
   /** Model the subagent ran on, when the provider records it. */
   model?: string;
   /**
@@ -413,7 +608,6 @@ export type ProviderRuntimeWriter = {
   setSessionId?(sessionId: string): void;
   userId?: string | number | null;
   isWebSocketWriter?: boolean;
-  isSSEStreamWriter?: boolean;
 };
 
 export type ProviderPermissionDecision = {
@@ -443,6 +637,15 @@ export type ProviderRuntimeContext = {
   getProviderModels(): Promise<ProviderModelsDefinition>;
   normalizeMessage(raw: unknown, sessionId: string | null): NormalizedMessage[];
   isProviderInstalled(): Promise<boolean>;
+  /**
+   * Builds the SDK query for a run. Production leaves this unset and the
+   * runtime uses the SDK's own; tests supply a scripted stream so the hold
+   * and background-work paths can be driven without a CLI process.
+   */
+  createQuery?: (input: { prompt: AsyncIterable<unknown>; options: AnyRecord }) => AsyncIterable<unknown> & {
+    interrupt(): Promise<void>;
+    stopTask?(taskId: string): Promise<void>;
+  };
 };
 
 export type ProviderRunFunction = (
@@ -667,6 +870,29 @@ export type UpsertProviderMcpServerInput = {
 
 // ---------------------------
 //----------------- PROVIDER AUTH TYPES ------------
+/**
+ * Records that an API-key style credential is taking precedence over a
+ * still-valid subscription login in `~/.claude/.credentials.json`.
+ *
+ * Claude Code always prefers `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_API_KEY` over
+ * the OAuth login written by `claude /login`, so when both exist every request
+ * is billed to the key (pay-as-you-go) rather than the subscription — usually
+ * without the user realising it. The Claude auth provider fills this in so the
+ * settings UI can say which variable won and where it was found; the fix
+ * differs per source (unset the variable and restart the server for
+ * `process_env`, edit the `env` block of `~/.claude/settings.json` for
+ * `settings_file`). It is never set when the login in the credentials file is
+ * missing or expired, because then nothing is being bypassed.
+ */
+export type ProviderAuthSubscriptionOverride = {
+  /** The environment variable Claude Code is using instead of the login. */
+  variable: 'ANTHROPIC_API_KEY' | 'ANTHROPIC_AUTH_TOKEN';
+  /** Where that variable was found: the server process env or the settings.json env block. */
+  source: 'process_env' | 'settings_file';
+  /** Email recorded in the credentials file for the bypassed login, when known. */
+  subscriptionEmail: string | null;
+};
+
 /**
  * Authentication status result returned by provider health checks.
  *
@@ -680,6 +906,12 @@ export type ProviderAuthStatus = {
   email: string | null;
   method: string | null;
   error?: string;
+  /**
+   * Present only when `method` is `api_key` and a valid subscription login is
+   * being bypassed; see ProviderAuthSubscriptionOverride. Omitted otherwise so
+   * existing consumers that never look for it are unaffected.
+   */
+  subscriptionOverride?: ProviderAuthSubscriptionOverride;
 };
 
 // ---------------------------
@@ -763,12 +995,13 @@ export type WorkspacePathValidationResult = {
 };
 
 // ---------------------------
-//----------------- GIT WORKTREE MANAGEMENT ------------
+//----------------- GIT COMMAND EXECUTION AND WORKTREE MANAGEMENT ------------
 /**
  * Captured output of one completed `git` invocation.
  *
- * Returned by `GitCommandRunner` implementations so worktree services can read
- * both streams without caring about process plumbing.
+ * Returned by `GitCommandRunner` and `GitProcessRunner` implementations so the
+ * git and worktree services can read both streams without caring about
+ * process plumbing.
  */
 export type GitCommandResult = {
   stdout: string;
@@ -785,6 +1018,20 @@ export type GitCommandResult = {
  */
 export type GitCommandRunner = (args: string[], cwd: string) => Promise<GitCommandResult>;
 
+/**
+ * Executes `command args...` inside `options.cwd` and resolves with the captured output.
+ *
+ * This is the `spawnAsync` shape the Git routes module injects into its typed
+ * services (branch deletion, branch compare) so their tests can substitute a
+ * fake runner. Like `GitCommandRunner`, the promise must reject on a non-zero
+ * exit code, with `stderr` attached to the error when available.
+ */
+export type GitProcessRunner = (
+  command: string,
+  args: string[],
+  options: { cwd: string },
+) => Promise<GitCommandResult>;
+
 /**
  * One entry parsed from `git worktree list --porcelain`.
  *
@@ -1108,6 +1355,13 @@ export type FileTreeProjectGateway = {
 export type FileTreeWorkspaceGateway = {
   rootPath: string;
   validatePath(candidatePath: string): Promise<WorkspacePathValidationResult>;
+  /**
+   * Resolves a path readable outside the workspace root — the system temp
+   * directory and the Claude projects directory — or `null` when it is not
+   * one. Read-only: the write policy is `validatePath` and it does not consult
+   * this.
+   */
+  resolveReadOnlyRootPath(candidatePath: string): Promise<string | null>;
 };
 
 /**