@zgeoff/atc 2.16.0 → 2.17.0

package/src/daemon/materialize-workspace.ts

@@ -3,18 +3,22 @@ import { dirname, join, resolve } from 'node:path';
 import { DaemonError } from '../protocol/daemon-error';
 import type { ErrorCode } from '../protocol/protocol';
 import type { SpawnWorkspaceSource } from '../protocol/request-param-schemas';
+import type { InvalidGitTransports } from '../shared/collect-workspaces-config';
 import type { SessionID } from '../shared/session-id';
 import type { StateStore } from '../store/state-store';
 import type { MaterializationPhase, SessionWorkspace } from '../store/workspace-materialization';
 import { checkURLCredentials } from '../workspace/check-url-credentials';
 import { createWorkspaceClone } from '../workspace/create-workspace-clone';
+import { expandGitShorthand } from '../workspace/expand-git-shorthand';
 import { normalizeGitURL } from '../workspace/normalize-git-url';
 import { readWorkspaceTar } from '../workspace/read-workspace-tar';
 import { REPOSITORY_ENV_VARS } from '../workspace/repository-env-vars';
+import { resolveGitURL } from '../workspace/resolve-git-url';
 import { resolvePathSource } from '../workspace/resolve-path-source';
 import { runGit } from '../workspace/run-git';
 import { sanitizeWorkspaceClone } from '../workspace/sanitize-workspace-clone';
 import type { ExecutionProvider } from './execution-provider';
+import { requireGitTransports } from './require-git-transports';
 
 interface MaterializeRequest {
   readonly sessionID: SessionID;
@@ -39,6 +43,10 @@ interface MaterializeDeps {
   // The directory on the daemon's host that holds each clone's staging
   // directory while the workspace is built.
   readonly stagingRoot: string;
+
+  // The transports a source may use and git may fetch over, or the invalid
+  // list the config holds, which refuses every source that needs git.
+  readonly gitTransports: readonly string[] | InvalidGitTransports;
 }
 
 type MaterializedWorkspace = { readonly kind: 'in_place' } | ReadyWorkspace;
@@ -203,7 +211,9 @@ async function runMaterialization(
   updateProgress: ProgressTracker,
   secret: string | null,
 ): Promise<Omit<ReadyWorkspace, 'withheldEnv'>> {
-  const pinned = await resolveSource(request.source, staging);
+  const transports = requireGitTransports(deps.gitTransports, { phase: 'resolving' });
+
+  const pinned = await resolveSource(request.source, staging, transports);
 
   // What is recorded and returned is scrubbed of the credential, even
   // where a caller's own ref happens to spell it.
@@ -213,7 +223,7 @@ async function runMaterialization(
   await claimTargetDir(request, deps, updateProgress);
   await recordPhase(request, deps, updateProgress, 'cloning', { repoURL, ref });
 
-  const clone = await createCleanClone(pinned, join(staging, 'clone'));
+  const clone = await createCleanClone(pinned, join(staging, 'clone'), transports);
 
   // The archive is in memory, so the clone leaves the daemon's host before
   // the target is touched.
@@ -251,8 +261,10 @@ interface PinnedSource {
   readonly cloneURL: string;
   readonly repoURL: string;
 
-  // The ref or commit the clone checks out, and the branch or tag recorded.
+  // The ref or commit the clone checks out, the commit it is pinned to when
+  // the ref only names its branch, and the branch or tag recorded.
   readonly checkout: string;
+  readonly sha?: string | undefined;
   readonly ref: string | null;
   readonly credential: { readonly kind: 'env'; readonly name: string } | undefined;
   readonly warnings: readonly string[];
@@ -263,7 +275,11 @@ interface PinnedSource {
  * not a pushed, complete, credential-free repository. A path source pins
  * its pushed HEAD; a git source keeps its ref, which the clone pins.
  */
-async function resolveSource(source: SpawnWorkspaceSource, staging: string): Promise<PinnedSource> {
+async function resolveSource(
+  source: SpawnWorkspaceSource,
+  staging: string,
+  transports: readonly string[],
+): Promise<PinnedSource> {
   if (source.kind === 'path') {
     // The origin is checked as configured, before resolving it applies any
     // rewrite: a rewrite the checkout's own config holds expands it too.
@@ -271,6 +287,7 @@ async function resolveSource(source: SpawnWorkspaceSource, staging: string): Pro
 
     const resolved = await resolvePathSource(source.path, {
       allowDirty: source.allowDirty ?? 'refuse',
+      transports,
     });
 
     if (!resolved.ok) {
@@ -289,22 +306,19 @@ async function resolveSource(source: SpawnWorkspaceSource, staging: string): Pro
     };
   }
 
-  await requireNoURLCredentials(source.url, staging);
+  // The clone fetches the URL it records, so the spawn API's `owner/repo`
+  // shorthand reaches the repository it expands to.
+  const resolved = await resolveGitURL(expandGitShorthand(source.url), staging, transports);
 
-  // The clone fetches the URL it records, so an `owner/repo` shorthand
-  // reaches the repository it expands to.
-  const normalized = normalizeGitURL(source.url);
-
-  if (!normalized.ok) {
-    throw new DaemonError(normalized.code, normalized.message, { phase: 'resolving' });
+  if (!resolved.ok) {
+    throw new DaemonError(resolved.code, resolved.message, { phase: 'resolving' });
   }
 
-  await requireNoURLCredentials(normalized.url, staging);
-
   return {
-    cloneURL: normalized.url,
-    repoURL: normalized.url,
-    checkout: source.sha ?? source.ref ?? '',
+    cloneURL: resolved.url,
+    repoURL: resolved.url,
+    checkout: source.ref ?? source.sha ?? '',
+    sha: source.ref === undefined ? undefined : source.sha,
     ref: source.ref ?? null,
     credential: source.credentialRef,
     warnings: [],
@@ -400,10 +414,20 @@ interface CleanClone {
  * Clones the pinned source into a staging directory on the daemon's host,
  * sanitizes it, and reads it back as a tar archive.
  */
-async function createCleanClone(pinned: PinnedSource, dir: string): Promise<CleanClone> {
+async function createCleanClone(
+  pinned: PinnedSource,
+  dir: string,
+  transports: readonly string[],
+): Promise<CleanClone> {
   const clone = await createWorkspaceClone({
-    source: { kind: 'git', url: pinned.cloneURL, ref: pinned.checkout },
+    source: {
+      kind: 'git',
+      url: pinned.cloneURL,
+      ref: pinned.checkout,
+      ...(pinned.sha === undefined ? {} : { sha: pinned.sha }),
+    },
     dir,
+    transports,
     ...(pinned.credential === undefined ? {} : { credential: pinned.credential }),
   });
 

package/src/daemon/require-git-transports.ts

@@ -0,0 +1,23 @@
+import { DaemonError } from '../protocol/daemon-error';
+import type { InvalidGitTransports } from '../shared/collect-workspaces-config';
+
+/**
+ * The transports git may fetch over, or the refusal of a git operation
+ * when the configured list is invalid: the daemon then runs no git at all,
+ * and the error quotes the config errors it printed at startup, with
+ * `data` as its detail.
+ */
+export function requireGitTransports(
+  policy: readonly string[] | InvalidGitTransports,
+  data?: Readonly<Record<string, unknown>>,
+): readonly string[] {
+  if ('invalid' in policy) {
+    throw new DaemonError(
+      'git_transports_invalid',
+      `workspaces.gitTransports in config.json is invalid, so the daemon runs no git: ${policy.invalid}`,
+      data,
+    );
+  }
+
+  return policy;
+}

package/src/mcp/require-daemon-features.ts

@@ -19,6 +19,8 @@ const FEATURE_USES: Readonly<Record<DaemonFeature, string>> = {
   'report.get': 'atc_report_get',
   'request.principal': 'the target limits of a remote MCP client',
   'spawn.workspace': "atc_session_spawn's workspace",
+  sources: 'sources.list and sources.interpret',
+  'git.probe': 'git.probe',
 };
 
 /**

package/src/protocol/daemon-features.ts

@@ -56,6 +56,14 @@ export const DAEMON_FEATURES = [
 
   // `report.get` exists.
   'report.get',
+
+  // `sources.list` and `sources.interpret` exist, and `agents.list` returns
+  // `sources`.
+  'sources',
+
+  // `git.probe` exists, and `session.spawn` takes a git workspace with both
+  // `ref` and `sha`.
+  'git.probe',
 ] as const;
 
 export type DaemonFeature = (typeof DAEMON_FEATURES)[number];

package/src/protocol/protocol.ts

@@ -34,6 +34,7 @@ const ERROR_CODES = [
   'workspace_dirty',
   'no_origin',
   'invalid_git_url',
+  'git_transports_invalid',
   'unpushed_head',
   'credential_in_url',
   'credential_missing',
@@ -44,6 +45,7 @@ const ERROR_CODES = [
   'workspace_exists',
   'transfer_failed',
   'workspace_mismatch',
+  'github_unavailable',
   'host_unavailable',
   'auth_not_configured',
   'host_leased',

package/src/protocol/request-param-schemas.ts

@@ -32,15 +32,30 @@ const CREDENTIAL_REF = z.strictObject({
   name: z.string().regex(/^[A-Za-z_]\w*$/u, 'a credentialRef names an environment variable'),
 });
 
+// A git workspace's repository URL, which git must never read as an option.
+const GIT_URL = z
+  .string({ error: 'a git workspace requires a url' })
+  .min(1, 'a git workspace requires a url')
+  .refine((url) => !url.startsWith('-'), 'a git workspace url must not start with -');
+
+// A git workspace's branch or tag, which git must never read as an option.
+const GIT_REF = z
+  .string()
+  .min(1, 'a git workspace ref must not be empty')
+  .refine((ref) => !ref.startsWith('-'), 'a git workspace ref must not start with -');
+
+const GIT_SHA = z.string().regex(COMMIT_ID, 'a git workspace sha is a full commit id');
+
 /**
  * Where a spawn's working directory comes from, materialized as a clean
  * checkout into the spawn's `cwd` on its execution target. A `path` source
  * is a directory on the daemon's host, resolved to its origin URL and
  * pushed HEAD; `allowDirty: 'warn'` resolves a tree with uncommitted
  * changes to HEAD and leaves the changes behind with a warning. A `git`
- * source is a repository URL with exactly one of a branch or tag `ref` or
- * a full commit `sha`, and an optional `credentialRef` naming the daemon
- * environment variable that holds its token.
+ * source is a repository URL with a branch or tag `ref`, a full commit
+ * `sha`, or both, and an optional `credentialRef` naming the daemon
+ * environment variable that holds its token. With both, the sha is the
+ * commit checked out and the ref is recorded as what it was resolved from.
  */
 const WORKSPACE_SOURCE = z.discriminatedUnion('kind', [
   z.strictObject({
@@ -53,23 +68,33 @@ const WORKSPACE_SOURCE = z.discriminatedUnion('kind', [
   z
     .strictObject({
       kind: z.literal('git'),
-      url: z
-        .string({ error: 'a git workspace requires a url' })
-        .min(1, 'a git workspace requires a url')
-        .refine((url) => !url.startsWith('-'), 'a git workspace url must not start with -'),
-      ref: z
-        .string()
-        .min(1, 'a git workspace ref must not be empty')
-        .refine((ref) => !ref.startsWith('-'), 'a git workspace ref must not start with -')
-        .optional(),
-      sha: z.string().regex(COMMIT_ID, 'a git workspace sha is a full commit id').optional(),
+      url: GIT_URL,
+      ref: GIT_REF.optional(),
+      sha: GIT_SHA.optional(),
       credentialRef: CREDENTIAL_REF.optional(),
     })
-    .refine((source) => (source.ref === undefined) !== (source.sha === undefined), {
-      message: 'a git workspace takes exactly one of ref or sha',
+    .refine((source) => source.ref !== undefined || source.sha !== undefined, {
+      message: 'a git workspace takes a ref, a sha, or both',
     }),
 ]);
 
+// The execution target a request acts for; absent is the default target.
+const TARGET = z
+  .string({ error: 'target must be a non-empty target id' })
+  .min(1, 'target must be a non-empty target id')
+  .optional();
+
+// The id of a source the daemon offers the spawn picker.
+const SOURCE_ID = z
+  .string({ error: 'source must be a source id' })
+  .min(1, 'source must be a source id')
+  .max(64, 'source must be a source id');
+
+// Text a source reads, at most 4096 characters.
+const SOURCE_TEXT = z
+  .string({ error: 'source text must be a string' })
+  .max(4096, 'source text must be at most 4096 characters');
+
 export type SpawnWorkspaceSource = z.infer<typeof WORKSPACE_SOURCE>;
 
 // The refusal of a terminal size outside the range a terminal takes.
@@ -88,6 +113,33 @@ export const REQUEST_PARAM_SCHEMAS = {
   'session.list': z.object({}),
   'dirs.list': z.object({}),
   'agents.list': z.object({}),
+
+  // One source's candidates for a spawn to the target, under the scope the
+  // source defines and filtered by text when it filters.
+  'sources.list': z.object({
+    source: SOURCE_ID,
+    target: TARGET,
+    scope: SOURCE_TEXT.min(1, 'scope must be non-empty').optional(),
+    text: SOURCE_TEXT.optional(),
+  }),
+
+  // What one source reads typed input as, for a spawn to the target.
+  'sources.interpret': z.object({ source: SOURCE_ID, input: SOURCE_TEXT, target: TARGET }),
+
+  // Whether the daemon's host can read a git workspace source the way a
+  // spawn to the target would, with its refs and the commit a ref or sha
+  // selects; at most one of the two.
+  'git.probe': z
+    .object({
+      url: GIT_URL,
+      ref: GIT_REF.optional(),
+      sha: GIT_SHA.optional(),
+      credentialRef: CREDENTIAL_REF.optional(),
+      target: TARGET,
+    })
+    .refine((probe) => probe.ref === undefined || probe.sha === undefined, {
+      message: 'git.probe takes at most one of ref or sha',
+    }),
   'fleet.list': z.object({}),
   'fleet.restore': z.object({
     cols: buildTerminalSize(80),

package/src/shared/collect-workspaces-config.ts

@@ -0,0 +1,105 @@
+import { DEFAULT_GIT_TRANSPORTS } from './default-git-transports';
+import { isRecord } from './report';
+
+/**
+ * Where workspace sources come from: the GitHub owner whose repositories
+ * the spawn picker lists by default, or null to list the gh account's own;
+ * the ids of the sources the picker offers, in order, or null for the
+ * default order; and the git transports the daemon fetches over.
+ */
+export interface WorkspacesConfig {
+  readonly githubOwner: string | null;
+  readonly sources: readonly string[] | null;
+  readonly gitTransports: readonly string[] | InvalidGitTransports;
+}
+
+/**
+ * A transport list the config holds that atc cannot use, with the config
+ * errors it raised. The daemon runs no git while the list is invalid.
+ */
+export interface InvalidGitTransports {
+  readonly invalid: string;
+}
+
+interface CollectedWorkspacesConfig {
+  readonly workspaces: WorkspacesConfig;
+
+  // The config problems the section holds, one line each.
+  readonly errors: readonly string[];
+}
+
+// A GitHub account or organization login.
+const GITHUB_OWNER_PATTERN = /^[A-Za-z\d][A-Za-z\d-]{0,38}$/u;
+
+/**
+ * Reads the `workspaces` section of config.json. An owner that is not a
+ * GitHub login is dropped, so a typo lists the gh account's own
+ * repositories instead of failing, and a source order that is not a list
+ * of ids falls back to the default order. A transport list that is not a
+ * list of transports atc allows is a config error, and the list is then
+ * invalid, never the default, so the daemon runs no git until it is fixed.
+ * An empty list is valid and allows no transport.
+ */
+export function collectWorkspacesConfig(raw: unknown): CollectedWorkspacesConfig {
+  const owner = isRecord(raw) ? raw['githubOwner'] : undefined;
+  const sources = isRecord(raw) ? raw['sources'] : undefined;
+  const rawTransports = isRecord(raw) ? raw['gitTransports'] : undefined;
+  const transports = collectGitTransports(rawTransports);
+
+  return {
+    workspaces: {
+      githubOwner: typeof owner === 'string' && GITHUB_OWNER_PATTERN.test(owner) ? owner : null,
+      sources:
+        Array.isArray(sources) &&
+        sources.every((id): id is string => typeof id === 'string' && id !== '')
+          ? sources
+          : null,
+      gitTransports: transports.transports,
+    },
+    errors: transports.errors,
+  };
+}
+
+// The git transports a config may allow: the defaults, and the two
+// opt-ins.
+const KNOWN_TRANSPORTS: ReadonlySet<string> = new Set(['https', 'ssh', 'http', 'file']);
+
+// Transports that run a command or read a descriptor on the daemon's host.
+const REFUSED_TRANSPORTS: ReadonlySet<string> = new Set(['ext', 'fd']);
+
+function collectGitTransports(raw: unknown): {
+  readonly transports: readonly string[] | InvalidGitTransports;
+  readonly errors: readonly string[];
+} {
+  if (raw === undefined) {
+    return { transports: DEFAULT_GIT_TRANSPORTS, errors: [] };
+  }
+
+  const fallback = 'the daemon runs no git until it is fixed';
+
+  if (!Array.isArray(raw)) {
+    const error = `workspaces.gitTransports is not a list of git transports; ${fallback}`;
+
+    return { transports: { invalid: error }, errors: [error] };
+  }
+
+  const errors = raw.flatMap((name: unknown) => {
+    if (typeof name === 'string' && REFUSED_TRANSPORTS.has(name)) {
+      return [
+        `workspaces.gitTransports holds '${name}', which atc never allows because it runs a command or reads a descriptor on the daemon host; ${fallback}`,
+      ];
+    }
+
+    if (typeof name !== 'string' || !KNOWN_TRANSPORTS.has(name)) {
+      return [
+        `workspaces.gitTransports holds ${JSON.stringify(name)}, which is not a git transport atc allows; ${fallback}`,
+      ];
+    }
+
+    return [];
+  });
+
+  return errors.length === 0
+    ? { transports: raw.filter((name): name is string => typeof name === 'string'), errors }
+    : { transports: { invalid: errors.join('; ') }, errors };
+}

package/src/shared/config.ts

@@ -11,6 +11,9 @@ import type { HooksConfig } from './collect-hooks';
 import { collectPrincipals } from './collect-principals';
 import { collectTargets } from './collect-targets';
 import type { TargetConfig, TargetConfigError } from './collect-targets';
+import { collectWorkspacesConfig } from './collect-workspaces-config';
+import type { WorkspacesConfig } from './collect-workspaces-config';
+import { DEFAULT_GIT_TRANSPORTS } from './default-git-transports';
 import { formatJSONKind } from './format-json-kind';
 import { isRecord } from './report';
 import { resolveHomeDir } from './resolve-home-dir';
@@ -23,6 +26,7 @@ export interface Config {
   codexBin: string;
   codexArgs: string[];
   dirs: DirsConfig;
+  workspaces: WorkspacesConfig;
   gateways: GatewayConfig[];
   hooks: HooksConfig;
   leader: LeaderKey;
@@ -40,6 +44,9 @@ export interface Config {
   // principals, which leaves every principal the implicit local target.
   principals: ReadonlyMap<string, readonly string[]> | null;
   principalErrors: readonly string[];
+
+  // The workspace config problems, one line each.
+  workspaceErrors: readonly string[];
 }
 
 /**
@@ -63,6 +70,7 @@ const DEFAULTS: Config = {
   codexBin: 'codex',
   codexArgs: [],
   dirs: { roots: [] },
+  workspaces: { githubOwner: null, sources: null, gitTransports: DEFAULT_GIT_TRANSPORTS },
   gateways: [],
   hooks: {},
   leader: { code: 0, label: '^Space' },
@@ -71,6 +79,7 @@ const DEFAULTS: Config = {
   targetErrors: [],
   principals: null,
   principalErrors: [],
+  workspaceErrors: [],
 };
 
 const configDir = join(resolveHomeDir(), '.config', 'atc');
@@ -101,6 +110,7 @@ const CONFIG_SCHEMA = z.object({
   codexBin: buildOptionalString(),
   codexArgs: buildOptionalStringArray(),
   dirs: z.unknown().optional(),
+  workspaces: z.unknown().optional(),
   gateways: z.unknown().optional(),
   hooks: z.unknown().optional(),
   leader: buildOptionalString(),
@@ -200,6 +210,7 @@ export function renderDefaultConfig(): string {
     targetErrors: _errors,
     principals: _principals,
     principalErrors: _principalErrors,
+    workspaceErrors: _workspaceErrors,
     ...written
   } = DEFAULTS;
 
@@ -239,6 +250,7 @@ export function parseConfig(raw: unknown, file: string = configFile): Config {
   const codexBin = parsed.data.codexBin ?? DEFAULTS.codexBin;
   const codexArgs = parsed.data.codexArgs ?? DEFAULTS.codexArgs;
   const dirs = { roots: collectDirRoots(parsed.data.dirs) };
+  const workspaces = collectWorkspacesConfig(parsed.data.workspaces);
   const gateways = collectGateways(parsed.data.gateways, claudeBin, claudeArgs);
   const hooks = collectHooks(parsed.data.hooks);
   const targets = collectTargets(parsed.data.targets, parsed.data.defaultTarget);
@@ -255,6 +267,7 @@ export function parseConfig(raw: unknown, file: string = configFile): Config {
     codexBin,
     codexArgs,
     dirs,
+    workspaces: workspaces.workspaces,
     gateways,
     hooks,
     leader,
@@ -263,6 +276,7 @@ export function parseConfig(raw: unknown, file: string = configFile): Config {
     targetErrors: targets.errors,
     principals: principals.principals,
     principalErrors: principals.errors,
+    workspaceErrors: workspaces.errors,
   };
 }
 

package/src/shared/default-git-transports.ts

@@ -0,0 +1,5 @@
+/**
+ * The git transports the daemon fetches workspace sources over when the
+ * config sets none.
+ */
+export const DEFAULT_GIT_TRANSPORTS: readonly string[] = ['https', 'ssh'];

package/src/shared/is-git-url.ts

@@ -0,0 +1,11 @@
+// A URL with a scheme, an scp-style `user@host:path`, or an absolute path.
+const GIT_URL_PATTERN = /^(?:[a-z][a-z\d+.-]*:\/\/|[^@/:\s]+@[^@/:\s]+:|\/)/iu;
+
+/**
+ * Whether typed text is a git repository URL in a form git itself reads:
+ * one with a scheme, the scp-style `user@host:path`, or an absolute path
+ * to a repository on the daemon's host.
+ */
+export function isGitURL(input: string): boolean {
+  return GIT_URL_PATTERN.test(input.trim());
+}

package/src/sources/build-sources.ts

@@ -0,0 +1,40 @@
+import type { SourceProvider } from './types';
+
+// The order sources take when the config gives none.
+const DEFAULT_SOURCE_ORDER = ['dirs', 'github', 'git'];
+
+interface BuiltSources {
+  readonly sources: readonly SourceProvider[];
+
+  // The ids a configured order holds that no available source has.
+  readonly missing: readonly string[];
+}
+
+/**
+ * The sources the spawn picker offers, in the configured order, else the
+ * default one. A source the order leaves out is not offered, and an id
+ * with no available source is skipped, so a source that cannot run on
+ * this host is simply not offered; a configured order reports such ids as
+ * missing.
+ */
+export function buildSources(
+  available: readonly SourceProvider[],
+  order: readonly string[] | null,
+): BuiltSources {
+  const byID = new Map(available.map((source) => [source.id, source]));
+
+  const sources: SourceProvider[] = [];
+  const missing: string[] = [];
+
+  for (const id of new Set(order ?? DEFAULT_SOURCE_ORDER)) {
+    const source = byID.get(id);
+
+    if (source !== undefined) {
+      sources.push(source);
+    } else if (order !== null) {
+      missing.push(id);
+    }
+  }
+
+  return { sources, missing };
+}

package/src/sources/collect-builtin-sources.ts

@@ -0,0 +1,41 @@
+import { buildDirsSource } from './dirs/build-dirs-source';
+import { buildGitSource } from './git/build-git-source';
+import { buildGitHubSource } from './github/build-github-source';
+import type { SourceProvider } from './types';
+
+interface BuiltinSourceOptions {
+  // The configured directory roots.
+  readonly roots: readonly string[];
+
+  // The GitHub owner a listing without a scope lists, or null for the gh
+  // account's own repositories.
+  readonly githubOwner: string | null;
+
+  // The gh executable: a name looked up on PATH, or a path.
+  readonly ghBin: string;
+
+  // The daemon user's home directory.
+  readonly homeDir: string;
+
+  // zoxide's frecency list on the daemon's host.
+  readonly collectZoxideDirs: () => Promise<string[]>;
+}
+
+/**
+ * The built-in sources this host can run, each with its services: the
+ * directories on the daemon's host, GitHub when gh is on this host, and
+ * a typed git URL, which needs nothing beyond git.
+ */
+export function collectBuiltinSources(options: BuiltinSourceOptions): SourceProvider[] {
+  return [
+    buildDirsSource({
+      roots: options.roots,
+      collectZoxideDirs: options.collectZoxideDirs,
+      homeDir: options.homeDir,
+    }),
+    ...(Bun.which(options.ghBin) === null
+      ? []
+      : [buildGitHubSource({ bin: options.ghBin, owner: options.githubOwner })]),
+    buildGitSource(),
+  ];
+}

package/src/sources/dirs/build-dirs-source.ts

@@ -0,0 +1,70 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { collectRootDirs } from '../../shared/collect-root-dirs';
+import type { SourceInterpretation, SourceProvider } from '../types';
+
+// What the source reads besides the spawn history a request brings.
+interface DirsSourceServices {
+  // The configured roots, each listing its child directories and their
+  // worktrees.
+  readonly roots: readonly string[];
+
+  // zoxide's frecency list on the daemon's host, most visited first.
+  readonly collectZoxideDirs: () => Promise<string[]>;
+
+  // The daemon user's home directory, which a leading `~` stands for.
+  readonly homeDir: string;
+}
+
+/**
+ * The directories on the daemon's host a session can run in: the spawn
+ * history the requesting principal may read, most recent first, then the
+ * configured roots, then zoxide's list. A directory that no longer exists
+ * is left out, and a duplicate keeps its first place. Typed input is a
+ * directory when it is absolute or starts with `~`, which stands for the
+ * daemon user's home.
+ */
+export function buildDirsSource(services: DirsSourceServices): SourceProvider {
+  return {
+    id: 'dirs',
+    label: 'directory on the daemon host',
+    kind: 'path',
+    async list(_query, request) {
+      const seen = new Set<string>();
+
+      for (const dir of [
+        ...(await request.collectSpawnDirs()),
+        ...collectRootDirs(services.roots),
+        ...(await services.collectZoxideDirs()),
+      ]) {
+        if (!seen.has(dir) && existsSync(dir)) {
+          seen.add(dir);
+        }
+      }
+
+      return {
+        candidates: [...seen].map((dir) => ({
+          label: formatHomePath(dir, services.homeDir),
+          pick: { kind: 'path', dir },
+        })),
+        scope: null,
+      };
+    },
+    interpret(input) {
+      const text = input.trim();
+
+      const dir =
+        text === '~' || text.startsWith('~/') ? `${services.homeDir}${text.slice(1)}` : text;
+
+      const interpretation: SourceInterpretation = isAbsolute(dir)
+        ? { kind: 'path', dir }
+        : { kind: 'none' };
+
+      return Promise.resolve(interpretation);
+    },
+  };
+}
+
+function formatHomePath(dir: string, home: string): string {
+  return dir === home || dir.startsWith(`${home}/`) ? `~${dir.slice(home.length)}` : dir;
+}