@zgeoff/atc 3.4.2 → 3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/agents/agent-adapter.ts

@@ -169,6 +169,10 @@ export interface HeadlessRunRequest {
   // Environment variable names the run's process goes without, such as the
   // credential a session's workspace was cloned with.
   readonly withheldEnv?: readonly string[];
+
+  // Where the session's published record lies, which the run's process
+  // reads from ATC_SESSION_RECORD.
+  readonly recordPath?: string;
 }
 
 export interface HeadlessRunEvents {

package/src/agents/build-claude-query-options.ts

@@ -55,6 +55,7 @@ export function buildClaudeQueryOptions(
       ...(opts.pluginDir === undefined ? {} : { pluginDir: opts.pluginDir }),
       ...(opts.sessionID === undefined ? {} : { sessionID: opts.sessionID }),
       ...(opts.withheldEnv === undefined ? {} : { withheldEnv: opts.withheldEnv }),
+      ...(opts.recordPath === undefined ? {} : { recordPath: opts.recordPath }),
     }),
     ...(opts.resume === undefined ? {} : { resume: opts.resume }),
     ...(mode === undefined ? {} : { permissionMode: mode }),

package/src/agents/build-headless-env.ts

@@ -8,6 +8,9 @@ interface HeadlessEnvParams {
 
   // Variables the run goes without, such as a workspace credential.
   readonly withheldEnv?: readonly string[];
+
+  // Where the session's published record lies.
+  readonly recordPath?: string;
 }
 
 /**
@@ -23,6 +26,7 @@ export function buildHeadlessEnv(params: HeadlessEnvParams): Record<string, stri
       ...(params.sessionID === undefined
         ? {}
         : { ATC_SESSION_ID: params.sessionID, ATC_SOCKET: params.socketPath }),
+      ...(params.recordPath === undefined ? {} : { ATC_SESSION_RECORD: params.recordPath }),
     },
     params.withheldEnv,
   );

package/src/client/daemon-client.ts

@@ -68,11 +68,16 @@ export class DaemonClient implements DaemonChannel {
   }
 
   // A handshake with a token presents it as a bearer token, which a TCP
-  // listener requires.
+  // listener requires. A client started inside an atc session gives that
+  // session, so the daemon never takes a change to the session's own record
+  // from it.
   sendHello(build: string, token?: string): Promise<Readonly<Record<string, unknown>>> {
+    const session = process.env['ATC_SESSION_ID'];
+
     return this.sendRequest('daemon.hello', {
       client: build,
       auth: token === undefined ? { scheme: 'none' } : { scheme: 'bearer', token },
+      ...(session === undefined || session === '' ? {} : { session }),
     });
   }
 

package/src/collect-restart-env.ts

@@ -1,6 +1,9 @@
+// The variables atc sets for the harness of a session it hosts.
+const SESSION_VARIABLES = new Set(['ATC_SESSION_ID', 'ATC_SOCKET', 'ATC_SESSION_RECORD']);
+
 /**
- * Copies an environment without the variables that name the session or
- * socket of whoever runs the restart, so the daemon it starts never mistakes
+ * Copies an environment without the variables that name the session, its
+ * record, or the socket of whoever runs the restart, so the daemon it starts never mistakes
  * itself for a hosted session. Entries with no value drop out.
  */
 export function collectRestartEnv(
@@ -9,7 +12,7 @@ export function collectRestartEnv(
   const copy: Record<string, string> = {};
 
   for (const [key, value] of Object.entries(env)) {
-    if (value !== undefined && key !== 'ATC_SESSION_ID' && key !== 'ATC_SOCKET') {
+    if (value !== undefined && !SESSION_VARIABLES.has(key)) {
       copy[key] = value;
     }
   }

package/src/daemon/build-scoped-context.ts

@@ -144,6 +144,8 @@ export function buildScopedContext(
     revokeSessionAuth: (id) => (canSee(id) ? ctx.revokeSessionAuth(id) : Promise.resolve(false)),
     updateSessionAuth: (id) => (canSee(id) ? ctx.updateSessionAuth(id) : Promise.resolve(null)),
     updateSession: (id, name, pinned) => canSee(id) && ctx.updateSession(id, name, pinned),
+    updateSessionScope: (id, scope) =>
+      canSee(id) ? ctx.updateSessionScope(id, scope) : Promise.resolve('missing' as const),
     ackSession: (id) => canSee(id) && ctx.ackSession(id),
     buildResumeCommand: (id) => (canSee(id) ? ctx.buildResumeCommand(id) : null),
     readSessionScreen: (id) =>

package/src/daemon/check-session-scope.ts

@@ -0,0 +1,235 @@
+import { z } from 'zod';
+import { DaemonError } from '../protocol/daemon-error';
+import type { DeclaredScope } from '../protocol/parse-declared-scope';
+import type {
+  RecordedBranch,
+  RecordedPullRequest,
+  RecordedWorktree,
+} from '../protocol/published-record';
+import { runGH } from '../sources/github/run-gh';
+import type { ExecutionProvider } from './execution-provider';
+import { findHostBranch } from './find-host-branch';
+import { runHostGit } from './run-host-git';
+
+/**
+ * Where a declared scope is checked: the session's host and directory,
+ * and the repository URL of its materialized workspace, null for a
+ * directory that runs as it stands.
+ */
+export interface ScopeCheckRequest {
+  readonly provider: ExecutionProvider;
+  readonly host: string;
+  readonly dir: string;
+  readonly repoURL: string | null;
+  readonly declared: DeclaredScope;
+}
+
+export interface CheckedScope {
+  readonly worktrees: readonly RecordedWorktree[];
+  readonly branches: readonly RecordedBranch[];
+  readonly pullRequests: readonly RecordedPullRequest[];
+}
+
+// How long one gh call may take before the entry it checks is refused.
+const GH_TIMEOUT_MS = 20_000;
+
+/**
+ * Checks each declared entry against the session's host and returns what
+ * the record holds for it: a worktree's branch as git reads it there, a
+ * branch with the repository it exists in, and a pull request as GitHub
+ * holds it. The first entry that fails refuses the whole scope with
+ * `scope_invalid`, the entry in its message and `data.entry`.
+ */
+export async function checkSessionScope(
+  request: ScopeCheckRequest,
+  ghBin: string,
+): Promise<CheckedScope> {
+  const declared = request.declared;
+  const needsHost = declared.worktrees.length > 0 || declared.branches.length > 0;
+
+  if (needsHost && request.provider.remote && !request.provider.capabilities.run) {
+    const first = declared.worktrees.length > 0 ? 'scope.worktrees[0]' : 'scope.branches[0]';
+
+    throw buildScopeRefusal(first, 'cannot be checked: the target runs no commands');
+  }
+
+  const worktrees: RecordedWorktree[] = [];
+
+  for (const [index, worktree] of declared.worktrees.entries()) {
+    const checked = await checkWorktree(request, `scope.worktrees[${index}]`, worktree.path);
+
+    worktrees.push(checked);
+  }
+
+  const branches: RecordedBranch[] = [];
+
+  for (const [index, branch] of declared.branches.entries()) {
+    const repo = branch.repo ?? request.dir;
+
+    const checked = await checkBranch(request, `scope.branches[${index}]`, branch.name, repo);
+
+    branches.push(checked);
+  }
+
+  const pullRequests: RecordedPullRequest[] = [];
+
+  for (const [index, pr] of declared.pullRequests.entries()) {
+    const entry = `scope.pullRequests[${index}]`;
+    let repo = pr.repo;
+
+    repo ??= await findGitHubRepo(request, entry);
+
+    const checked = await checkPullRequest(entry, repo, pr.number, ghBin);
+
+    pullRequests.push(checked);
+  }
+
+  return { worktrees, branches, pullRequests };
+}
+
+async function checkWorktree(
+  request: ScopeCheckRequest,
+  entry: string,
+  path: string,
+): Promise<RecordedWorktree> {
+  const top = await runHostGit(request.provider, request.host, path, [
+    'rev-parse',
+    '--show-toplevel',
+  ]);
+
+  if (top.exitCode !== 0) {
+    throw buildScopeRefusal(entry, `${path} is not a git worktree on the session's host`);
+  }
+
+  if (top.stdout.trim() !== path.replace(/\/+$/u, '')) {
+    throw buildScopeRefusal(
+      entry,
+      `${path} is inside the worktree ${top.stdout.trim()}, not its top level`,
+    );
+  }
+
+  return { path, branch: await findHostBranch(request.provider, request.host, path) };
+}
+
+async function checkBranch(
+  request: ScopeCheckRequest,
+  entry: string,
+  name: string,
+  repo: string,
+): Promise<RecordedBranch> {
+  const format = await runHostGit(request.provider, request.host, repo, [
+    'check-ref-format',
+    '--branch',
+    name,
+  ]);
+
+  if (format.exitCode !== 0) {
+    throw buildScopeRefusal(entry, `${name} is not a valid branch name`);
+  }
+
+  for (const ref of [`refs/heads/${name}`, `refs/remotes/origin/${name}`]) {
+    const found = await runHostGit(request.provider, request.host, repo, [
+      'rev-parse',
+      '--verify',
+      '--quiet',
+      '--end-of-options',
+      `${ref}^{commit}`,
+    ]);
+
+    if (found.exitCode === 0) {
+      return { name, repo };
+    }
+  }
+
+  throw buildScopeRefusal(entry, `${repo} has no branch ${name}`);
+}
+
+// The GitHub repository a pull request defaults to: that of the workspace's
+// origin.
+async function findGitHubRepo(request: ScopeCheckRequest, entry: string): Promise<string> {
+  let url = request.repoURL;
+
+  if (url === null && (!request.provider.remote || request.provider.capabilities.run)) {
+    const origin = await runHostGit(request.provider, request.host, request.dir, [
+      'remote',
+      'get-url',
+      'origin',
+    ]);
+
+    url = origin.exitCode === 0 ? origin.stdout.trim() : null;
+  }
+
+  const repo = url === null ? null : findGitHubRepoInURL(url);
+
+  if (repo === null) {
+    throw buildScopeRefusal(entry, "needs a repo: the workspace's origin is not on GitHub");
+  }
+
+  return repo;
+}
+
+const GITHUB_URL =
+  /^(?:https:\/\/github\.com\/|ssh:\/\/git@github\.com\/|git@github\.com:)(?<repo>[\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/u;
+
+function findGitHubRepoInURL(url: string): string | null {
+  return GITHUB_URL.exec(url)?.groups?.['repo'] ?? null;
+}
+
+const BASE_REPO_SCHEMA = z.object({ full_name: z.string() });
+
+const PULL_REQUEST_SCHEMA = z.object({
+  number: z.number(),
+  html_url: z.string(),
+  head: z.object({ ref: z.string() }),
+  base: z.object({ repo: BASE_REPO_SCHEMA }),
+});
+
+async function checkPullRequest(
+  entry: string,
+  repo: string,
+  number: number,
+  ghBin: string,
+): Promise<RecordedPullRequest> {
+  let run: Awaited<ReturnType<typeof runGH>>;
+
+  try {
+    run = await runGH(ghBin, AbortSignal.timeout(GH_TIMEOUT_MS), [
+      'api',
+      `repos/${repo}/pulls/${number}`,
+    ]);
+  } catch {
+    throw buildScopeRefusal(entry, 'cannot be checked: gh is not installed on the daemon host');
+  }
+
+  if (run.timedOut) {
+    throw buildScopeRefusal(entry, 'cannot be checked: gh took too long');
+  }
+
+  const parsed =
+    run.exitCode === 0 ? PULL_REQUEST_SCHEMA.safeParse(tryParseJSON(run.stdout)) : null;
+
+  if (parsed === null || !parsed.success) {
+    throw buildScopeRefusal(entry, `${repo} has no pull request #${number}`);
+  }
+
+  if (parsed.data.base.repo.full_name.toLowerCase() !== repo.toLowerCase()) {
+    throw buildScopeRefusal(
+      entry,
+      `pull request #${number} belongs to ${parsed.data.base.repo.full_name}, not ${repo}`,
+    );
+  }
+
+  return { repo, number, url: parsed.data.html_url, branch: parsed.data.head.ref };
+}
+
+function tryParseJSON(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function buildScopeRefusal(entry: string, reason: string): DaemonError {
+  return new DaemonError('scope_invalid', `${entry} ${reason}`, { entry });
+}

package/src/daemon/daemon-connection.ts

@@ -6,6 +6,8 @@ import { encodeCursor } from '../protocol/encode-cursor';
 import { LineDecoder } from '../protocol/line-decoder';
 import { OutboundQueue } from '../protocol/outbound-queue';
 import type { SocketWriter } from '../protocol/outbound-queue';
+import { parseDeclaredScope } from '../protocol/parse-declared-scope';
+import type { DeclaredScope } from '../protocol/parse-declared-scope';
 import { parseRequestParams } from '../protocol/parse-request-params';
 import type { RequestMethod } from '../protocol/parse-request-params';
 import {
@@ -103,6 +105,11 @@ export class DaemonConnection {
 
   private access: TargetAccess | null = null;
 
+  // The atc session the client runs inside, from its handshake; null for a
+  // client that gave none. A session never changes its own record or that
+  // of a session it is a sub-session of through it.
+  private callerSession: SessionID | null = null;
+
   // The sessions in this limited connection's view, the sessions the daemon
   // holds that the view leaves out, and the permission requests the
   // connection was shown, so the events that end them reach it after the
@@ -629,6 +636,11 @@ export class DaemonConnection {
 
         return;
       }
+      case 'session.scope.add': {
+        await this.applyScopeAdd(req, ctx);
+
+        return;
+      }
       case 'session.kill': {
         await this.applySessionVerb(req, 'session.kill', ctx.killSession);
 
@@ -919,6 +931,48 @@ export class DaemonConnection {
     }
   }
 
+  // A client inside a session never adds to the record of that session or
+  // of a session it is a sub-session of: only a caller outside the tree
+  // vouches for what the session may touch.
+  private async applyScopeAdd(req: RequestMsg, ctx: DaemonContext): Promise<void> {
+    const parsed = parseRequestParams('session.scope.add', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    const sessionID = parsed.data.session;
+    const declared = parseDeclaredScope(parsed.data.scope);
+
+    if (!declared.ok) {
+      this.sendErr(req.id, 'scope_invalid', declared.message, { entry: declared.entry });
+
+      return;
+    }
+
+    if (this.callerSession !== null && ctx.isCallerTree(sessionID, this.callerSession)) {
+      this.sendErr(
+        req.id,
+        'unauthorized',
+        `session '${this.callerSession}' cannot add to the scope of session '${sessionID}': a session never widens its own scope or that of a session above it`,
+      );
+
+      return;
+    }
+
+    const record = await ctx.updateSessionScope(sessionID, declared.scope);
+
+    if (record === 'missing') {
+      this.sendErr(req.id, 'no_such_session', `no session '${sessionID}'`);
+
+      return;
+    }
+
+    this.sendOk(req.id, { record });
+  }
+
   private async applySpawn(req: RequestMsg, ctx: DaemonContext): Promise<void> {
     const parsed = parseRequestParams('session.spawn', req.p);
 
@@ -1041,6 +1095,7 @@ export class DaemonConnection {
         target,
         workspace: data.workspace ?? null,
         autoDir: cwd === undefined,
+        scope: requireDeclaredScope(data.scope),
       };
     };
 
@@ -1668,6 +1723,8 @@ export class DaemonConnection {
       this.setPrincipal(principal);
     }
 
+    this.callerSession = parsedHello.ok ? (parsedHello.data.session ?? null) : null;
+
     if (req.v !== PROTOCOL_V) {
       this.sendErr(
         req.id,
@@ -1745,6 +1802,7 @@ export class DaemonConnection {
         this.setPrincipal(principal);
       }
 
+      this.callerSession = parsedHello.data.session ?? null;
       this.fingerprint = fingerprint;
 
       await this.sendHelloOk(req.id);
@@ -1851,3 +1909,19 @@ function isPlainWorkspaceDir(dir: string): boolean {
     !CONTROL_CHARACTER.test(dir) && !dir.split('/').some((part) => part === '.' || part === '..')
   );
 }
+
+// A spawn without a scope declares none; one whose scope does not read
+// refuses before anything starts, with the entry at fault.
+function requireDeclaredScope(raw: unknown): DeclaredScope | null {
+  if (raw === undefined) {
+    return null;
+  }
+
+  const parsed = parseDeclaredScope(raw);
+
+  if (!parsed.ok) {
+    throw new DaemonError('scope_invalid', parsed.message, { entry: parsed.entry });
+  }
+
+  return parsed.scope;
+}

package/src/daemon/daemon-context.ts

@@ -1,5 +1,7 @@
 import type { AgentAdapter, SpawnOptions, SpawnOverrides } from '../agents/agent-adapter';
+import type { DeclaredScope } from '../protocol/parse-declared-scope';
 import type { EventMsg } from '../protocol/protocol';
+import type { PublishedRecord } from '../protocol/published-record';
 import type { SpawnWorkspaceSource } from '../protocol/request-param-schemas';
 import type { AgentID } from '../shared/agent-id';
 import type { TargetConfigError } from '../shared/collect-targets';
@@ -40,6 +42,10 @@ export interface SpawnParams {
   // session in cwd as it stands.
   readonly workspace: SpawnWorkspaceSource | null;
 
+  // The scope beyond its workspace the session's record holds once each
+  // entry is checked on its host; null declares none.
+  readonly scope: DeclaredScope | null;
+
   // Whether the daemon picked cwd for a git workspace the spawn gave no
   // directory for, so a held directory moves the spawn to a numbered one
   // beside it.
@@ -52,6 +58,10 @@ interface SessionRecord {
   readonly lastActivityAt: number;
   readonly pending: { readonly message: string } | null;
   readonly result: string | null;
+
+  // The record atc publishes for the session; null for a session that has
+  // none yet.
+  readonly sessionRecord: PublishedRecord | null;
 }
 
 /**
@@ -248,6 +258,17 @@ export interface DaemonContext {
   // answers the new revision, or null for no such session.
   readonly updateSessionAuth: (id: SessionID) => Promise<number | null>;
   readonly updateSession: (id: SessionID, name?: string, pinned?: boolean) => boolean | 'child_pin';
+
+  // Adds a checked scope to a session's published record and returns the
+  // record as it stands after; 'missing' for no such session.
+  readonly updateSessionScope: (
+    id: SessionID,
+    scope: DeclaredScope,
+  ) => Promise<PublishedRecord | 'missing'>;
+
+  // Whether the session is the caller itself or a session the caller is a
+  // sub-session of, at any depth.
+  readonly isCallerTree: (id: SessionID, caller: SessionID) => boolean;
   readonly quitDaemon: () => void;
   readonly ackSession: (id: SessionID) => boolean;
   readonly buildResumeCommand: (id: SessionID) => string | null;

package/src/daemon/daemon.ts

@@ -82,6 +82,7 @@ import { mintMessageID } from './mint-message-id';
 import { mintSessionID } from './mint-session-id';
 import { parseReport } from './parse-report';
 import { PermissionRegistry } from './permission-registry';
+import { PublishedRecords } from './published-records';
 import { requireGitTransports } from './require-git-transports';
 import { restoreFleet } from './restore-fleet';
 import type { RestoreSettled } from './restore-fleet';
@@ -228,6 +229,10 @@ export interface DaemonOptions {
   // services it uses; none when unset.
   readonly sources?: readonly SourceProvider[];
 
+  // The gh executable that checks a pull request a session's scope
+  // declares; `gh` on PATH when unset.
+  readonly ghBin?: string;
+
   // The transports a git workspace source may use and git may fetch over,
   // or the invalid list the config holds, which refuses every git
   // operation; https and ssh when unset.
@@ -422,6 +427,16 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     mgr.log = opts.log;
   }
 
+  const records = new PublishedRecords({
+    store,
+    daemonID: store.daemonID,
+    localDir: join(stateDir, 'records'),
+    ghBin: opts.ghBin ?? 'gh',
+    now: () => Date.now(),
+  });
+
+  mgr.records = records;
+
   const authBinder = new RuntimeAuthBinder(store);
 
   mgr.authBinder = authBinder;
@@ -1159,6 +1174,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
           targetIdentity: string,
         ) => Promise<Readonly<{
           workspace: SessionWorkspace;
+          branch: string | null;
           withheldEnv: readonly string[];
         }> | null>)
       | null,
@@ -1180,6 +1196,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       materialize,
       requireInReach,
       p.autoDir,
+      p.scope,
     );
 
     const runtime = runtimes.get(s.id);
@@ -1623,6 +1640,8 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       });
     },
     updateSession: (id, name, pinned) => mgr.updateSession(id, name, pinned),
+    updateSessionScope: (id, scope) => mgr.updateScope(id, scope),
+    isCallerTree: (id, caller) => mgr.isCallerTree(id, caller),
     quitDaemon: () => {
       // The ok response for the quit request must flush before the sockets
       // close under it.
@@ -1960,6 +1979,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       const linked = access !== null || shared ? undefined : s.agentSessionID;
 
       const lastEventAt = await store.loadLastActivityAt(s.id, linked);
+      const sessionRecord = await records.findRecord(s.id);
 
       return {
         session,
@@ -1967,6 +1987,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         lastActivityAt: lastEventAt ?? createdAt,
         pending,
         result,
+        sessionRecord,
       };
     },
     loadSessionTranscript: async (id, from, limit) => {

package/src/daemon/find-host-branch.ts

@@ -0,0 +1,28 @@
+import type { ExecutionProvider } from './execution-provider';
+import { runHostGit } from './run-host-git';
+
+/**
+ * The branch a directory on a session's host has checked out; null for a
+ * detached checkout, a directory outside git, or a remote host that runs
+ * no commands.
+ */
+export async function findHostBranch(
+  provider: ExecutionProvider,
+  host: string,
+  dir: string,
+): Promise<string | null> {
+  if (provider.remote && !provider.capabilities.run) {
+    return null;
+  }
+
+  const head = await runHostGit(provider, host, dir, [
+    'symbolic-ref',
+    '--quiet',
+    '--short',
+    'HEAD',
+  ]);
+
+  const branch = head.stdout.trim();
+
+  return head.exitCode === 0 && branch !== '' ? branch : null;
+}

package/src/daemon/materialize-workspace.ts

@@ -76,6 +76,9 @@ type MaterializedWorkspace = { readonly kind: 'in_place' } | ReadyWorkspace;
 interface ReadyWorkspace {
   readonly kind: 'ready';
   readonly workspace: SessionWorkspace;
+
+  // The branch the checkout is on, null for a detached checkout.
+  readonly branch: string | null;
   readonly warnings: readonly string[];
 
   // The variables every harness the session starts goes without.
@@ -298,6 +301,7 @@ async function runMaterialization(
       ...(ref === null ? {} : { ref }),
       materializedAt,
     },
+    branch: clone.branch,
     warnings: pinned.warnings,
   };
 }
@@ -532,6 +536,7 @@ async function recordPhase(
 
 interface CleanClone {
   readonly sha: string;
+  readonly branch: string | null;
   readonly archive: Uint8Array;
 }
 
@@ -580,7 +585,7 @@ async function createCleanClone(
     throw new DaemonError(outcome.code, outcome.message, { phase: 'cloning' });
   }
 
-  return { sha: clone.sha, archive };
+  return { sha: clone.sha, branch: clone.branch, archive };
 }
 
 function toDaemonError(error: unknown, code: ErrorCode, phase: MaterializationPhase): DaemonError {