@zgeoff/atc 3.4.1 → 3.5.0

package/src/protocol/parse-declared-scope.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+
+/**
+ * The scope a caller declares for a session, before atc checks any entry
+ * against the session's host.
+ */
+export interface DeclaredScope {
+  readonly worktrees: readonly { readonly path: string }[];
+  readonly branches: readonly { readonly name: string; readonly repo?: string }[];
+  readonly pullRequests: readonly { readonly number: number; readonly repo?: string }[];
+}
+
+export type ParsedDeclaredScope =
+  | { readonly ok: true; readonly scope: DeclaredScope }
+  | { readonly ok: false; readonly entry: string; readonly message: string };
+
+// An absolute path without `.` or `..` segments or control characters, so
+// the host resolves it to the directory it holds as written.
+const ABSOLUTE_PATH = z
+  .string({ error: 'a path must be a string' })
+  .startsWith('/', 'a path must be absolute')
+  .max(4096, 'a path must be at most 4096 characters')
+  .refine(
+    (path) => !path.split('/').some((segment) => segment === '.' || segment === '..'),
+    'a path must not hold . or .. segments',
+  )
+  .refine((path) => !hasControlCharacter(path), 'a path must not hold control characters');
+
+const BRANCH_NAME = z
+  .string({ error: 'a branch name must be a string' })
+  .min(1, 'a branch name must not be empty')
+  .max(255, 'a branch name must be at most 255 characters')
+  .refine((name) => !name.startsWith('-'), 'a branch name must not start with -')
+  .refine((name) => !hasControlCharacter(name), 'a branch name must not hold control characters');
+
+// A GitHub repository as `owner/name`.
+const GITHUB_REPO = z
+  .string({ error: 'a pull request repo must be a string' })
+  .regex(/^[\w.-]+\/[\w.-]+$/u, 'a pull request repo is a GitHub repository as owner/name');
+
+// How many entries one list of a declared scope holds at most.
+const MAX_ENTRIES = 64;
+
+const WORKTREE_ENTRY = z.strictObject(
+  { path: ABSOLUTE_PATH },
+  { error: buildEntryError('a worktree holds only path') },
+);
+
+const BRANCH_ENTRY = z.strictObject(
+  { name: BRANCH_NAME, repo: ABSOLUTE_PATH.optional() },
+  { error: buildEntryError('a branch holds only name and repo') },
+);
+
+const PULL_REQUEST_NUMBER = z
+  .number({ error: 'a pull request number must be a number' })
+  .int('a pull request number must be a whole number')
+  .positive('a pull request number must be positive');
+
+const PULL_REQUEST_ENTRY = z.strictObject(
+  { number: PULL_REQUEST_NUMBER, repo: GITHUB_REPO.optional() },
+  { error: buildEntryError('a pull request holds only number and repo') },
+);
+
+const SCOPE = z.strictObject(
+  {
+    worktrees: z
+      .array(WORKTREE_ENTRY, { error: 'worktrees must be a list' })
+      .max(MAX_ENTRIES, `worktrees holds at most ${MAX_ENTRIES} entries`)
+      .optional(),
+    branches: z
+      .array(BRANCH_ENTRY, { error: 'branches must be a list' })
+      .max(MAX_ENTRIES, `branches holds at most ${MAX_ENTRIES} entries`)
+      .optional(),
+    pullRequests: z
+      .array(PULL_REQUEST_ENTRY, { error: 'pullRequests must be a list' })
+      .max(MAX_ENTRIES, `pullRequests holds at most ${MAX_ENTRIES} entries`)
+      .optional(),
+  },
+  {
+    error: (issue) =>
+      issue.code === 'unrecognized_keys'
+        ? 'a scope holds only worktrees, branches, and pullRequests'
+        : 'scope must be an object',
+  },
+);
+
+/**
+ * Reads a declared scope off the wire. Every object is closed, so a key the
+ * format does not define refuses the scope, and a refusal holds the entry
+ * at fault, such as `scope.branches[1]`.
+ */
+export function parseDeclaredScope(raw: unknown): ParsedDeclaredScope {
+  const result = SCOPE.safeParse(raw);
+
+  if (result.success) {
+    return {
+      ok: true,
+      scope: {
+        worktrees: result.data.worktrees ?? [],
+        branches: (result.data.branches ?? []).map((branch) =>
+          branch.repo === undefined
+            ? { name: branch.name }
+            : { name: branch.name, repo: branch.repo },
+        ),
+        pullRequests: (result.data.pullRequests ?? []).map((pr) =>
+          pr.repo === undefined ? { number: pr.number } : { number: pr.number, repo: pr.repo },
+        ),
+      },
+    };
+  }
+
+  const [issue] = result.error.issues;
+
+  if (issue === undefined) {
+    return { ok: false, entry: 'scope', message: 'scope is invalid' };
+  }
+
+  const entry = formatEntry({
+    path: issue.path,
+    unrecognized: issue.code === 'unrecognized_keys' ? (issue.keys[0] ?? '') : undefined,
+  });
+
+  return { ok: false, entry, message: `${entry} is invalid: ${issue.message}` };
+}
+
+function hasControlCharacter(text: string): boolean {
+  return /\p{Cc}/u.test(text);
+}
+
+// Where an issue lies: its path, and the first key a closed object refused
+// when it refused one.
+interface IssueLocation {
+  readonly path: readonly PropertyKey[];
+  readonly unrecognized?: string | undefined;
+}
+
+// The entry an issue lies in: the list and index it sits under, or the key
+// a closed object refused.
+function formatEntry(issue: IssueLocation): string {
+  const [list, index] = issue.path;
+
+  if (issue.unrecognized !== undefined && list === undefined) {
+    return `scope.${issue.unrecognized}`;
+  }
+
+  if (typeof list !== 'string') {
+    return 'scope';
+  }
+
+  return typeof index === 'number' ? `scope.${list}[${index}]` : `scope.${list}`;
+}
+
+// The message for an entry that is not an object, or that holds a key its
+// kind does not define.
+function buildEntryError(unrecognized: string): (issue: Readonly<{ code?: string }>) => string {
+  return (issue) =>
+    issue.code === 'unrecognized_keys' ? unrecognized : 'an entry must be an object';
+}

package/src/protocol/protocol.ts

@@ -46,6 +46,7 @@ const ERROR_CODES = [
   'workspace_overlap',
   'transfer_failed',
   'workspace_mismatch',
+  'scope_invalid',
   'github_unavailable',
   'host_unavailable',
   'auth_not_configured',

package/src/protocol/published-record.ts

@@ -0,0 +1,62 @@
+/**
+ * The record atc publishes for one session: what atc vouches for about it,
+ * in the format the session record doc defines as atc's contract. A reader
+ * ignores the keys it does not know, so a field added within a version
+ * breaks none.
+ */
+export interface PublishedRecord {
+  readonly format: 'atc.session-record';
+  readonly version: 1;
+  readonly session: string;
+  readonly daemonID: string;
+  readonly target: string;
+
+  // Starts at 1 and grows by one with each change to the record.
+  readonly revision: number;
+
+  // When atc last changed the record, as an ISO 8601 UTC time.
+  readonly updatedAt: string;
+  readonly scope: RecordedScope;
+}
+
+export interface RecordedScope {
+  readonly workspace: RecordedWorkspace;
+  readonly worktrees: readonly RecordedWorktree[];
+  readonly branches: readonly RecordedBranch[];
+  readonly pullRequests: readonly RecordedPullRequest[];
+}
+
+/**
+ * The directory the session runs in and its branch, null for a detached
+ * checkout or a directory outside git. The repository URL and the commit
+ * are those of a materialized workspace, null for a directory that runs as
+ * it stands.
+ */
+interface RecordedWorkspace {
+  readonly path: string;
+  readonly branch: string | null;
+  readonly repoURL: string | null;
+  readonly sha: string | null;
+}
+
+export interface RecordedWorktree {
+  readonly path: string;
+  readonly branch: string | null;
+}
+
+export interface RecordedBranch {
+  readonly name: string;
+
+  // The repository directory on the session's host the branch exists in.
+  readonly repo: string;
+}
+
+export interface RecordedPullRequest {
+  // The GitHub repository the pull request belongs to, as `owner/name`.
+  readonly repo: string;
+  readonly number: number;
+  readonly url: string;
+
+  // The pull request's head branch.
+  readonly branch: string;
+}

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

@@ -112,6 +112,13 @@ export const REQUEST_PARAM_SCHEMAS = {
       .string({ error: 'daemon.hello principal must be a non-empty string' })
       .min(1, 'daemon.hello principal must be a non-empty string')
       .optional(),
+
+    // The atc session the client runs inside, which a client started in a
+    // session's environment sends; absent for a client outside any session.
+    session: z.preprocess(
+      (v) => (typeof v === 'string' && v !== '' ? v : undefined),
+      z.string().transform(toSessionID).optional(),
+    ),
   }),
   'daemon.ping': z.object({}),
   'daemon.quit': z.object({}),
@@ -196,6 +203,11 @@ export const REQUEST_PARAM_SCHEMAS = {
       .boolean({ error: 'session.spawn trustClonedWorkspace must be a boolean' })
       .optional(),
 
+    // The worktrees, branches, and pull requests the session may touch
+    // beyond its own workspace, which the daemon checks entry by entry and
+    // refuses as scope_invalid.
+    scope: z.unknown().optional(),
+
     // The session the new one is a sub-session of; absent or empty spawns a
     // top-level session.
     parent: z.preprocess(
@@ -225,6 +237,10 @@ export const REQUEST_PARAM_SCHEMAS = {
   // session's host, or bind that host to its agent's current selection.
   'session.auth.revoke': SESSION_DEFAULTED,
   'session.auth.rebind': SESSION_DEFAULTED,
+
+  // Adds checked entries to a session's published record, refused for the
+  // session itself and for any session it is a sub-session of.
+  'session.scope.add': SESSION_DEFAULTED.extend({ scope: z.unknown() }),
   'session.update': SESSION_DEFAULTED.extend({
     name: buildOptionalString(),
     pinned: buildOptionalBoolean(),

package/src/store/parse-published-record.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import type { PublishedRecord } from '../protocol/published-record';
+
+const NULLABLE_STRING = z.string().nullable();
+
+const WORKSPACE_SCHEMA = z.object({
+  path: z.string(),
+  branch: NULLABLE_STRING,
+  repoURL: NULLABLE_STRING,
+  sha: NULLABLE_STRING,
+});
+
+const WORKTREE_SCHEMA = z.object({ path: z.string(), branch: NULLABLE_STRING });
+const BRANCH_SCHEMA = z.object({ name: z.string(), repo: z.string() });
+
+const PULL_REQUEST_SCHEMA = z.object({
+  repo: z.string(),
+  number: z.number(),
+  url: z.string(),
+  branch: z.string(),
+});
+
+const SCOPE_SCHEMA = z.object({
+  workspace: WORKSPACE_SCHEMA,
+  worktrees: z.array(WORKTREE_SCHEMA),
+  branches: z.array(BRANCH_SCHEMA),
+  pullRequests: z.array(PULL_REQUEST_SCHEMA),
+});
+
+const REVISION = z.number().int().positive();
+
+const PUBLISHED_RECORD_SCHEMA = z.object({
+  format: z.literal('atc.session-record'),
+  version: z.literal(1),
+  session: z.string(),
+  daemonID: z.string(),
+  target: z.string(),
+  revision: REVISION,
+  updatedAt: z.string(),
+  scope: SCOPE_SCHEMA,
+});
+
+/**
+ * Reads a published record back from the JSON the state store holds; null
+ * for text that is not a version 1 record.
+ */
+export function parsePublishedRecord(text: string): PublishedRecord | null {
+  let raw: unknown;
+
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return null;
+  }
+
+  const parsed = PUBLISHED_RECORD_SCHEMA.safeParse(raw);
+
+  return parsed.success ? parsed.data : null;
+}

package/src/store/run-migrations.ts

@@ -154,6 +154,16 @@ interface RuntimeAuthGrantTable {
   updated_at: number;
 }
 
+// One session's published record, keyed by the session.
+interface PublishedRecordTable {
+  session_id: string;
+
+  // The record as JSON, in the format its version defines.
+  record: string;
+  revision: number;
+  updated_at: number;
+}
+
 interface MessagesTable {
   id: string;
   atc_id: string;
@@ -186,6 +196,7 @@ export interface StateStoreSchema {
   workspace_materialization: WorkspaceMaterializationTable;
   runtime_auth_binding: RuntimeAuthBindingTable;
   runtime_auth_grant: RuntimeAuthGrantTable;
+  published_record: PublishedRecordTable;
 }
 
 // Every shape the fleet table has shipped with: the oldest carries only
@@ -557,6 +568,18 @@ const MIGRATIONS: Record<string, Migration> = {
         .execute();
     },
   },
+  '027_create_published_record': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema
+        .createTable('published_record')
+        .ifNotExists()
+        .addColumn('session_id', 'text', (c) => c.primaryKey())
+        .addColumn('record', 'text', (c) => c.notNull())
+        .addColumn('revision', 'integer', (c) => c.notNull())
+        .addColumn('updated_at', 'integer', (c) => c.notNull())
+        .execute();
+    },
+  },
 };
 
 const PROVIDER: MigrationProvider = {

package/src/store/state-store.ts

@@ -13,6 +13,7 @@ import type {
 import type { AdapterEvent } from '../protocol/adapter-event';
 import { DaemonError } from '../protocol/daemon-error';
 import type { HookEvent } from '../protocol/hook-event';
+import type { PublishedRecord } from '../protocol/published-record';
 import type { AgentID } from '../shared/agent-id';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import { BunSqliteDriver } from '../shared/bun-sqlite-driver';
@@ -29,6 +30,7 @@ import type { FleetEntry, FleetEntryUpdate, LegacyFleetEntry } from './fleet-ent
 import type { EffectTarget, IdempotencyClaim, IdempotencyRecord } from './idempotency-record';
 import type { MessageOwner } from './message-owner';
 import type { MessageRecord } from './message-record';
+import { parsePublishedRecord } from './parse-published-record';
 import { runMigrations } from './run-migrations';
 import type { StateStoreSchema } from './run-migrations';
 import type {
@@ -1003,6 +1005,36 @@ export class StateStore {
       .execute();
   }
 
+  // A row whose JSON no longer reads as a record counts as no record, so
+  // the next delivery records the session afresh.
+  async findPublishedRecord(sessionID: SessionID): Promise<PublishedRecord | null> {
+    const row = await this.db
+      .selectFrom('published_record')
+      .select('record')
+      .where('session_id', '=', sessionID)
+      .executeTakeFirst();
+
+    return row === undefined ? null : parsePublishedRecord(row.record);
+  }
+
+  async writePublishedRecord(record: PublishedRecord): Promise<void> {
+    const values = {
+      record: JSON.stringify(record),
+      revision: record.revision,
+      updated_at: Date.parse(record.updatedAt),
+    };
+
+    await this.db
+      .insertInto('published_record')
+      .values({ session_id: record.session, ...values })
+      .onConflict((oc) => oc.column('session_id').doUpdateSet(values))
+      .execute();
+  }
+
+  async removePublishedRecord(sessionID: SessionID): Promise<void> {
+    await this.db.deleteFrom('published_record').where('session_id', '=', sessionID).execute();
+  }
+
   // Records a host's binding as its first attempt starts provisioning it,
   // at the first revision, before the imp exists.
   async createAuthBinding(

package/src/test-utils/build-mock-published-record.ts

@@ -0,0 +1,39 @@
+import { faker } from '@faker-js/faker';
+import type { PublishedRecord } from '../protocol/published-record';
+import { mergeDeep } from './merge-deep';
+import type { MockOverrides } from './mock-overrides';
+
+type DefaultedKey = keyof PublishedRecord;
+
+/**
+ * A first-revision version 1 record of a fresh session on the local target,
+ * whose workspace is an arbitrary directory on a branch, with no declared
+ * scope. Overrides merge into fresh defaults at every depth.
+ */
+export function buildMockPublishedRecord(
+  overrides: MockOverrides<PublishedRecord, DefaultedKey> = {},
+): PublishedRecord {
+  return mergeDeep<PublishedRecord, DefaultedKey>(
+    {
+      format: 'atc.session-record',
+      version: 1,
+      session: faker.string.uuid(),
+      daemonID: faker.string.uuid(),
+      target: 'local',
+      revision: 1,
+      updatedAt: faker.date.recent().toISOString(),
+      scope: {
+        workspace: {
+          path: faker.system.directoryPath(),
+          branch: faker.git.branch(),
+          repoURL: null,
+          sha: null,
+        },
+        worktrees: [],
+        branches: [],
+        pullRequests: [],
+      },
+    },
+    overrides,
+  );
+}

package/src/test-utils/build-stub-brokered-agent-adapter.ts

@@ -23,7 +23,9 @@ interface StubBrokeredAgentAdapterConfig {
  * prints `revision <n>` for the binding's revision and then sleeps, with
  * the binding's variables and `CLAUDE_CONFIG_DIR` set to `claude-config`
  * in the guest folder; a guest spawn without one, and a local spawn, sleep.
- * Every other member is the plain agent adapter's.
+ * Its profile is a `GLM` agent of the claude kind run through `sh`, which
+ * offers no model or effort choice. Every other member is the plain agent
+ * adapter's.
  */
 export function buildStubBrokeredAgentAdapter(
   config: StubBrokeredAgentAdapterConfig,

package/src/test-utils/build-stub-daemon-context.ts

@@ -45,6 +45,8 @@ export function buildStubDaemonContext(overrides: Partial<DaemonContext> = {}):
     revokeSessionAuth: makeUnreached('revokeSessionAuth'),
     updateSessionAuth: makeUnreached('updateSessionAuth'),
     updateSession: makeUnreached('updateSession'),
+    updateSessionScope: makeUnreached('updateSessionScope'),
+    isCallerTree: makeUnreached('isCallerTree'),
     quitDaemon: makeUnreached('quitDaemon'),
     ackSession: makeUnreached('ackSession'),
     buildResumeCommand: makeUnreached('buildResumeCommand'),

package/src/test-utils/build-stub-daemon-requests.ts

@@ -51,7 +51,7 @@ export function buildStubDaemonRequests(options: StubDaemonRequestsOptions) {
 
   const countAll = () => sent.length + options.countReactions();
 
-  const resolveAndWait = async (request: Readonly<StubRequest>, value: DaemonAnswer) => {
+  const answerRequest = async (request: Readonly<StubRequest>, value: DaemonAnswer) => {
     const before = countAll();
 
     answered.add(request);
@@ -81,7 +81,7 @@ export function buildStubDaemonRequests(options: StubDaemonRequestsOptions) {
         return latest;
       }, waitOptions);
 
-      await resolveAndWait(request, value);
+      await answerRequest(request, value);
     },
     async answerOldest(m: string, value: DaemonAnswer): Promise<void> {
       const request = await waitFor(() => {
@@ -94,7 +94,7 @@ export function buildStubDaemonRequests(options: StubDaemonRequestsOptions) {
         return oldest;
       }, waitOptions);
 
-      await resolveAndWait(request, value);
+      await answerRequest(request, value);
     },
     collectSent(m: string): DaemonAnswer[] {
       return sent.filter((request) => request.m === m).map((request) => request.p);

package/src/test-utils/build-stub-harness-relay.ts

@@ -5,7 +5,7 @@ import type { HarnessRelay } from '../daemon/execution-provider';
  * a guest's connection. `sendLine` delivers a value as one JSON line from
  * the guest to every line listener, `written` holds every line written back
  * to the guest, parsed, in order, and `isClosed` turns true once the relay
- * is closed. A write settles at once, as a relay with room does. `hangUp`
+ * is closed. A write settles at once, as a relay with room does. `emitClose`
  * runs every close listener, as a guest that hangs up does; closing the
  * relay from the daemon's end runs none.
  */
@@ -41,7 +41,7 @@ export function buildStubHarnessRelay() {
         listener(JSON.stringify(value));
       }
     },
-    hangUp: () => {
+    emitClose: () => {
       for (const listener of closeListeners) {
         listener();
       }

package/src/test-utils/build-stub-held-gh.ts

@@ -1,18 +1,16 @@
 /**
  * The script of a stand-in `gh` whose repository listing waits for the
- * test. `gh config …` prints `https`. Any other command touches
- * `$HOME/gh-held` and waits while `$HOME/gh-hold` exists, then prints one
- * repository, `me/dots`, in the JSON shape `gh repo list` prints.
+ * test. `gh config …` prints `https`. Any other command waits while
+ * `$HOME/gh-hold` exists, touching `$HOME/gh-held` on each pass of the
+ * wait, so the marker appears only once the stand-in is held, then prints
+ * one repository, `me/dots`, in the JSON shape `gh repo list` prints.
  */
 export function buildStubHeldGH(): string {
   return `#!/bin/sh
 case "$1" in
   config) echo https ;;
   *)
-    if [ -f "$HOME/gh-hold" ]; then
-      touch "$HOME/gh-held"
-      while [ -f "$HOME/gh-hold" ]; do sleep 0.05; done
-    fi
+    while [ -f "$HOME/gh-hold" ]; do touch "$HOME/gh-held"; sleep 0.05; done
     echo '[{"nameWithOwner":"me/dots","description":"dotfiles","isPrivate":false,"url":"https://github.com/me/dots","sshUrl":"git@github.com:me/dots.git"}]' ;;
 esac
 `;

package/src/test-utils/build-stub-held-inbox-source.ts

@@ -9,7 +9,7 @@ import type { MessageRecord } from '../store/message-record';
  * An inbox source over a real, empty tap registry, standing in for the
  * daemon's store. It holds every session under the given agent session id,
  * and its pending-message read waits until the test answers it: `reading`
- * settles once a read starts, `read` answers the read with the given
+ * settles once a read starts, `answer` answers the read with the given
  * messages whatever owner it asked for.
  */
 export function buildStubHeldInboxSource(agentSessionID: AgentSessionID) {
@@ -29,7 +29,7 @@ export function buildStubHeldInboxSource(agentSessionID: AgentSessionID) {
   return {
     source,
     reading: reading.promise,
-    read: (records: readonly MessageRecord[]) => {
+    answer: (records: readonly MessageRecord[]) => {
       pending.resolve([...records]);
     },
   };

package/src/test-utils/build-stub-held-zoxide.ts

@@ -1,13 +1,11 @@
 /**
  * The script of a stand-in `zoxide` that lists no directories, and waits
- * for the test first: while `$HOME/zoxide-hold` exists, it touches
- * `$HOME/zoxide-held` and waits for the file to go.
+ * for the test first: while `$HOME/zoxide-hold` exists, it waits for the
+ * file to go, touching `$HOME/zoxide-held` on each pass of the wait, so the
+ * marker appears only once the stand-in is held.
  */
 export function buildStubHeldZoxide(): string {
   return `#!/bin/sh
-if [ -f "$HOME/zoxide-hold" ]; then
-  touch "$HOME/zoxide-held"
-  while [ -f "$HOME/zoxide-hold" ]; do sleep 0.05; done
-fi
+while [ -f "$HOME/zoxide-hold" ]; do touch "$HOME/zoxide-held"; sleep 0.05; done
 `;
 }

package/src/test-utils/build-stub-host-hold.ts

@@ -1,9 +1,10 @@
 /**
  * A host operation a test can hold open, for a host preparation or sleep
- * that must stay in flight while the test changes something. Unarmed, the
- * operation resolves at once, so the arrange steps before the hold pass
- * through. Once armed, the next call resolves `entered` and every call
- * waits until `release`; after the release, calls resolve at once again.
+ * that must stay in flight while the test changes something: a test passes
+ * `waitForRelease` as the operation. Before `startHold`, the operation
+ * resolves at once, so the arrange steps before the hold pass through.
+ * After it, the next call resolves `entered` and every call waits until
+ * `release`; after the release, calls resolve at once again.
  */
 export function buildStubHostHold() {
   const entered = Promise.withResolvers<void>();
@@ -11,7 +12,7 @@ export function buildStubHostHold() {
   let armed = false;
 
   return {
-    hold: (): Promise<void> => {
+    waitForRelease: (): Promise<void> => {
       if (!armed) {
         return Promise.resolve();
       }
@@ -20,7 +21,7 @@ export function buildStubHostHold() {
 
       return released.promise;
     },
-    arm: () => {
+    startHold: () => {
       armed = true;
     },
     entered: entered.promise,

package/src/test-utils/build-stub-launch-admission.ts

@@ -0,0 +1,20 @@
+import type { LaunchTicket } from '../daemon/execution-provider';
+import type { DaemonError } from '../protocol/daemon-error';
+
+/**
+ * A runtime auth binder's launch admission for a harness behind the
+ * broker. `admit` admits every start and attach: it hands `send` a ticket
+ * at once, before the admission settles, as the binder does under its host
+ * lock, and then resolves. The ticket's check runs the given check, which
+ * returns the refusal that stops the request unsent or null to let it go,
+ * and may throw as a broken binder would. Its release does nothing.
+ */
+export function buildStubLaunchAdmission(check: () => DaemonError | null) {
+  return {
+    admit: (_kind: 'start' | 'attach', send: (ticket: LaunchTicket) => void): Promise<void> => {
+      send({ check, release: () => {} });
+
+      return Promise.resolve();
+    },
+  };
+}

package/src/test-utils/build-stub-pregranted-broker-host.ts

@@ -0,0 +1,22 @@
+import type { BrokerAuthHost } from '../daemon/broker-auth-host';
+
+/**
+ * A broker host whose new imps already hold a grant of `secret` when its
+ * create returns, as on an impd where another principal grants every imp
+ * the moment it appears. Every other member is the given host's own.
+ */
+export function buildStubPregrantedBrokerHost(
+  host: BrokerAuthHost,
+  secret: string,
+): BrokerAuthHost {
+  return {
+    ...host,
+    createImp: async (hostKey) => {
+      const imp = await host.createImp(hostKey);
+
+      await host.port.createGrant(imp.name, secret);
+
+      return imp;
+    },
+  };
+}