@zgeoff/atc 3.4.2 → 3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "3.4.2",
+  "version": "3.6.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/agents/gateway-adapter.ts

@@ -58,7 +58,7 @@ export class GatewayAdapter implements AgentAdapter {
 
   // A headless turn carries the same settings file the terminal spawn does,
   // so it reaches this backend rather than the default one. A gateway whose
-  // credential comes through impd's broker runs no headless turn.
+  // credential comes through impd's broker alone runs no headless turn.
   readonly headlessRunner: HeadlessRunner | null;
 
   // The CLI's hooks are authoritative; no screen heuristics needed.
@@ -132,7 +132,7 @@ export class GatewayAdapter implements AgentAdapter {
     );
 
     this.headlessRunner =
-      headlessRun === null || gateway.auth !== undefined
+      headlessRun === null || isBrokerOnlyGateway(gateway)
         ? null
         : makeClaudeHeadlessRunner(headlessRun, {
             claudeBin: gateway.bin,
@@ -169,15 +169,16 @@ export class GatewayAdapter implements AgentAdapter {
     return {
       gateway: { id: this.gateway.id, baseURL: this.gateway.baseURL, auth },
       profiles: this.config.authProfiles,
-      brokerRequired: true,
+      brokerRequired: isBrokerOnlyGateway(this.gateway),
     };
   }
 
-  // A gateway whose credential comes through impd's broker never starts on
-  // the daemon's machine: started without the broker, the CLI would send
-  // whatever credential it holds to the gateway's host.
+  // A gateway whose credential comes through impd's broker alone never
+  // starts on the daemon's machine: started without the broker, the CLI
+  // would send whatever credential it holds to the gateway's host. One
+  // with a credential helper as well starts there under that helper.
   planSpawn(opts: SpawnOptions): SpawnPlan {
-    if (this.gateway.auth !== undefined) {
+    if (isBrokerOnlyGateway(this.gateway)) {
       throw this.buildBrokerRefusal('which only an imp target can give it');
     }
 
@@ -186,7 +187,13 @@ export class GatewayAdapter implements AgentAdapter {
 
     return {
       bin: this.gateway.bin,
-      args: this.buildArgs(opts, modeArgs, this.writeSettings(), this.writeBridge()),
+      args: this.buildArgs(
+        this.gateway.args,
+        opts,
+        modeArgs,
+        this.writeSettings(),
+        this.writeBridge(),
+      ),
     };
   }
 
@@ -196,8 +203,9 @@ export class GatewayAdapter implements AgentAdapter {
   // and placeholders in place of the credential, which the broker swaps
   // for the real one on the host's side. A shell seeds the config folder
   // before it runs the CLI, since a transferred file would replace the
-  // state an earlier run left. Any other gateway's credential
-  // helper runs on the daemon's machine, so it never runs remotely.
+  // state an earlier run left. The launch takes the auth's own arguments
+  // when it sets them, and never the credential helper, which runs on the
+  // daemon's machine alone. A gateway without auth never runs remotely.
   planGuestSpawn(opts: SpawnOptions, guest: GuestPaths): GuestSpawnPlan | null {
     if (this.gateway.auth === undefined) {
       return null;
@@ -244,11 +252,14 @@ export class GatewayAdapter implements AgentAdapter {
       argv,
     );
 
+    const args = this.gateway.auth.args ?? this.gateway.args;
+
     const launch = buildClaudeGuestLaunch(guest.dir, [
       this.gateway.bin,
       ...this.buildArgs(
+        args,
         opts,
-        this.buildGuestModeArgs(),
+        this.buildGuestModeArgs(args),
         `${guest.dir}/${settingsPath}`,
         `${guest.dir}/atc-bridge`,
       ),
@@ -291,10 +302,10 @@ export class GatewayAdapter implements AgentAdapter {
   // explicit flag, so that mode overrides the one the CLI would restore, and
   // the generated settings file, because
   // without it the CLI would resume the session against the default backend.
-  // A gateway whose credential comes through impd's broker has none, since
-  // outside atc the broker never reaches it.
+  // A gateway whose credential comes through impd's broker alone has none,
+  // since outside atc the broker never reaches it.
   buildResumeCommand(cwd: string, agentSessionID: AgentSessionID | undefined): string | null {
-    if (this.gateway.auth !== undefined) {
+    if (isBrokerOnlyGateway(this.gateway)) {
       return null;
     }
 
@@ -312,13 +323,14 @@ export class GatewayAdapter implements AgentAdapter {
   }
 
   private buildArgs(
+    args: readonly string[],
     opts: SpawnOptions,
     modeArgs: readonly string[],
     settings: string,
     pluginDir: string,
   ): string[] {
     return [
-      ...buildClaudeOverrideArgs(this.gateway.args, opts),
+      ...buildClaudeOverrideArgs(args, opts),
       ...modeArgs,
       '--settings',
       settings,
@@ -332,11 +344,11 @@ export class GatewayAdapter implements AgentAdapter {
 
   // A brokered session's Claude config is fresh, so the CLI's own default
   // mode would apply rather than the one the owner's settings set. Every
-  // start therefore names its mode: the one the gateway's arguments or
-  // settings set, else the CLI's manual mode, which asks before each
-  // action.
-  private buildGuestModeArgs(): string[] {
-    if (findFlagValue(this.gateway.args, ['--permission-mode']) !== null) {
+  // start therefore names its mode: the one the launch's arguments or the
+  // gateway's settings set, else the CLI's manual mode, which asks before
+  // each action.
+  private buildGuestModeArgs(args: readonly string[]): string[] {
+    if (findFlagValue(args, ['--permission-mode']) !== null) {
       return [];
     }
 
@@ -464,6 +476,12 @@ export class GatewayAdapter implements AgentAdapter {
   }
 }
 
+// Whether a gateway takes its credential from impd's broker with no
+// credential helper to fall back on, so it starts only behind the broker.
+function isBrokerOnlyGateway(gateway: GatewayConfig): boolean {
+  return gateway.auth !== undefined && gateway.apiKeyHelper === undefined;
+}
+
 // The variable the Claude CLI sends as a bearer authorization header, and
 // the value impd's broker replaces with the credential on the host's side.
 const BEARER_VARIABLE = 'ANTHROPIC_AUTH_TOKEN';

package/src/build-migrated-config.ts

@@ -142,6 +142,7 @@ function renderAgentEntry(entry: AgentEntry): Record<string, unknown> {
       ...(Object.keys(entry.auth.placeholderEnv).length > 0
         ? { placeholderEnv: entry.auth.placeholderEnv }
         : {}),
+      ...(entry.auth.args === undefined ? {} : { args: entry.auth.args }),
       ...(entry.mcpServers === undefined
         ? {}
         : {

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;