@zgeoff/atc 3.4.1 → 3.5.0

package/src/daemon/sessions.ts

@@ -12,7 +12,9 @@ import type { AdapterEvent } from '../protocol/adapter-event';
 import { countSessionStates } from '../protocol/count-session-states';
 import { DaemonError } from '../protocol/daemon-error';
 import type { HookEvent } from '../protocol/hook-event';
+import type { DeclaredScope } from '../protocol/parse-declared-scope';
 import type { ErrorCode } from '../protocol/protocol';
+import type { PublishedRecord } from '../protocol/published-record';
 import type { SessionState } from '../protocol/session-state';
 import { sortSessionViews } from '../protocol/sort-session-views';
 import type { AgentID } from '../shared/agent-id';
@@ -50,6 +52,7 @@ import { loadOAuthStates } from './load-oauth-states';
 import { LocalPTYProvider } from './local-pty-provider';
 import { mintSessionID } from './mint-session-id';
 import { pickSessionState } from './pick-session-state';
+import type { PublishedRecords } from './published-records';
 import type { RuntimeAuthBinder } from './runtime-auth-binder';
 
 export type SessionEventKind = 'added' | 'state' | 'renamed' | 'removed';
@@ -191,6 +194,9 @@ export interface Session {
 // A session's ready workspace and the variables its harnesses go without.
 interface MaterializedSpawn {
   readonly workspace: SessionWorkspace;
+
+  // The branch the checkout is on, null for a detached checkout.
+  readonly branch: string | null;
   readonly withheldEnv: readonly string[];
 }
 
@@ -354,6 +360,10 @@ export class SessionManager {
   // from impd's broker; with none, every such start is refused.
   authBinder: RuntimeAuthBinder | null = null;
 
+  // Publishes each session's record before its harness starts; with none,
+  // sessions start without a record.
+  records: PublishedRecords | null = null;
+
   // Whether any registered adapter has a screen detector, decided once at
   // construction since the registry never changes afterward. Lets a hot path
   // that only cares about this answer skip walking live sessions to find it.
@@ -709,25 +719,48 @@ export class SessionManager {
     this.adopting.add(id);
 
     let plan: HarnessPlan;
+    let recordPath: string | null;
+    const resume = s.agentSessionID;
 
+    // The record is placed again while the host still counts as readying,
+    // so a host that lost its copy, such as one that booted cold, has it
+    // back before the harness starts.
     try {
-      const setup = await this.setupHarness(
-        adapter,
-        provider,
-        s.id,
-        s.hostKey,
-        s.target,
-        {
-          prompt: '',
-          resume: s.agentSessionID,
-          ...(s.model === undefined ? {} : { model: s.model }),
-          ...(s.effort === undefined ? {} : { effort: s.effort }),
-        },
-        authSetup,
-        s.cwd,
-      );
+      const setup = await this.withHostReadying(s.hostKey, async () => {
+        const planned = await this.setupHarnessOnHost(
+          adapter,
+          provider,
+          s.id,
+          s.hostKey,
+          s.target,
+          {
+            prompt: '',
+            resume,
+            ...(s.model === undefined ? {} : { model: s.model }),
+            ...(s.effort === undefined ? {} : { effort: s.effort }),
+          },
+          authSetup,
+          s.cwd,
+          false,
+        );
+
+        const path =
+          this.records === null
+            ? null
+            : await this.records.restoreCopy({
+                session: s.id,
+                target: s.target,
+                provider,
+                host: s.hostKey,
+                dir: s.cwd,
+                workspace: s.workspace ?? null,
+              });
+
+        return { plan: planned.plan, recordPath: path };
+      });
 
       plan = setup.plan;
+      recordPath = setup.recordPath;
     } finally {
       this.adopting.delete(id);
     }
@@ -753,7 +786,12 @@ export class SessionManager {
       bin: plan.bin,
       args: plan.args,
       cwd: s.cwd,
-      env: { ...plan.env, ATC_SESSION_ID: s.id, ATC_SOCKET: socketPath },
+      env: {
+        ...plan.env,
+        ATC_SESSION_ID: s.id,
+        ATC_SOCKET: socketPath,
+        ...(recordPath === null ? {} : { ATC_SESSION_RECORD: recordPath }),
+      },
       withheldEnv: s.withheldEnv,
       cols,
       rows,
@@ -842,6 +880,67 @@ export class SessionManager {
     });
   }
 
+  // Adds a checked scope to a session's published record and returns the
+  // record as it stands after. The checks run on the session's host, so a
+  // remote host that is not awake refuses the change until a revive wakes
+  // it.
+  async updateScope(id: SessionID, scope: DeclaredScope): Promise<PublishedRecord | 'missing'> {
+    const s = this.sessions.find((x) => x.id === id);
+
+    if (s === undefined) {
+      return 'missing';
+    }
+
+    if (this.records === null) {
+      throw new DaemonError('unsupported', 'this daemon publishes no session records');
+    }
+
+    const provider = this.requireExecution(s, 'spawn').provider;
+
+    if (provider.remote && s.vm !== 'awake') {
+      throw new DaemonError(
+        'host_unavailable',
+        `the host of session ${id} is not awake; revive the session before adding to its scope`,
+        { provider: provider.kind, problem: 'host_asleep', host: s.hostKey },
+      );
+    }
+
+    const subject = {
+      session: s.id,
+      target: s.target,
+      provider,
+      host: s.hostKey,
+      dir: s.cwd,
+      workspace: s.workspace ?? null,
+    };
+
+    const record = await this.records.updateScope(subject, scope);
+
+    return record;
+  }
+
+  // Whether the session is the caller or a session the caller sits under,
+  // following each parent link the fleet holds.
+  isCallerTree(id: SessionID, caller: SessionID): boolean {
+    let current: SessionID | null = caller;
+
+    const seen = new Set<SessionID>();
+
+    while (current !== null && !seen.has(current)) {
+      if (current === id) {
+        return true;
+      }
+
+      seen.add(current);
+
+      const at: SessionID = current;
+
+      current = this.sessions.find((x) => x.id === at)?.parent ?? null;
+    }
+
+    return false;
+  }
+
   /**
    * Renames and/or pins a session on a caller's behalf. A rename lands at
    * user strength, so auto-summaries stop overwriting it while an
@@ -957,6 +1056,7 @@ export class SessionManager {
     materialize: SpawnMaterializer | null = null,
     requireInReach: () => void = () => {},
     autoDir = false,
+    scope: DeclaredScope | null = null,
   ): Promise<Session> {
     const adapter = this.findAdapter(agent);
 
@@ -1091,23 +1191,51 @@ export class SessionManager {
 
     // The host stays readying until its workspace is in place, so nothing
     // gives its lease back or puts it to sleep in between.
+    // The record is published while the host still counts as readying, so
+    // nothing sleeps it between the record and the harness start.
+    const published: { path: string | null; failure: { readonly error: unknown } | null } = {
+      path: null,
+      failure: null,
+    };
+
     const prepared = await this.withHostReadying(hostKey, async () => {
-      if (materialize === null) {
-        return { setup: await setupHost(), materialized: null, root: null };
+      const ready =
+        materialize === null
+          ? { setup: await setupHost(), materialized: null, root: null }
+          : await this.materializeOnSpawnHost(
+              provider,
+              id,
+              hostKey,
+              target,
+              cwd,
+              execution.identity,
+              materialize,
+              setupHost,
+              checkWorkspace,
+              trustWorkspace,
+            );
+
+      try {
+        published.path =
+          this.records === null
+            ? null
+            : await this.records.createRecord(
+                {
+                  session: id,
+                  target,
+                  provider,
+                  host: hostKey,
+                  dir: autoDir && ready.root !== null ? ready.root : cwd,
+                  workspace: ready.materialized?.workspace ?? null,
+                  ...(ready.materialized === null ? {} : { branch: ready.materialized.branch }),
+                },
+                scope,
+              );
+      } catch (error) {
+        published.failure = { error };
       }
 
-      return this.materializeOnSpawnHost(
-        provider,
-        id,
-        hostKey,
-        target,
-        cwd,
-        execution.identity,
-        materialize,
-        setupHost,
-        checkWorkspace,
-        trustWorkspace,
-      );
+      return ready;
     });
 
     // A spawn whose directory the daemon picked runs in the one it claimed,
@@ -1116,6 +1244,17 @@ export class SessionManager {
     const setup = prepared.setup;
     const materialized = prepared.materialized;
     const readied: SpawnReadied = { attemptID: setup.attemptID, root: prepared.root };
+
+    // A scope that fails its check, or a record that cannot be placed,
+    // takes back what the spawn readied before any harness starts.
+    if (published.failure !== null) {
+      await this.removeLocalTrust(localTrust.remove, id);
+      await this.records?.remove(id);
+      await this.removeFailedSpawnEffects(provider, id, hostKey, target, readied);
+
+      throw published.failure.error;
+    }
+
     const plan = setup.plan;
     const binding = this.mintBridgeBinding(id, target, execution.identity, hostKey);
     let pty: HarnessHandle;
@@ -1132,7 +1271,12 @@ export class SessionManager {
         bin: plan.bin,
         args: plan.args,
         cwd: dir,
-        env: { ...plan.env, ATC_SESSION_ID: id, ATC_SOCKET: socketPath },
+        env: {
+          ...plan.env,
+          ATC_SESSION_ID: id,
+          ATC_SOCKET: socketPath,
+          ...(published.path === null ? {} : { ATC_SESSION_RECORD: published.path }),
+        },
         withheldEnv: materialized?.withheldEnv ?? [],
         cols,
         rows,
@@ -1143,6 +1287,7 @@ export class SessionManager {
       });
     } catch (error) {
       await this.removeLocalTrust(localTrust.remove, id);
+      await this.records?.remove(id);
       await this.removeFailedSpawnEffects(provider, id, hostKey, target, readied);
 
       throw error;
@@ -1937,28 +2082,6 @@ export class SessionManager {
   }
 
   // Readies the host a harness is about to start on and plans the harness.
-  // On a remote host the agent plans a guest spawn, whose files unpack into
-  // the session's own guest folder, and the agent's sign-in check runs
-  // there first. Every refusal comes before the harness starts. A harness
-  // behind the broker has its binding created or verified before the host
-  // is readied, and a binding this call created is taken back when a later
-  // step fails; the attempt that created it comes back with the plan. A
-  // spawn's new host of its own without a binding is destroyed instead.
-  private setupHarness(
-    adapter: AgentAdapter,
-    provider: ExecutionProvider,
-    id: SessionID,
-    hostKey: SessionID,
-    target: string,
-    options: SpawnOptions,
-    auth: HarnessAuthSetup | null,
-    dir: string,
-  ): Promise<{ readonly plan: HarnessPlan; readonly attemptID: string | null }> {
-    return this.withHostReadying(hostKey, () =>
-      this.setupHarnessOnHost(adapter, provider, id, hostKey, target, options, auth, dir, false),
-    );
-  }
-
   // Counts a host as readying while run runs, so it is not idle then.
   private async withHostReadying<T>(hostKey: SessionID, run: () => Promise<T>): Promise<T> {
     this.readying.set(hostKey, (this.readying.get(hostKey) ?? 0) + 1);
@@ -1976,6 +2099,13 @@ export class SessionManager {
     }
   }
 
+  // On a remote host the agent plans a guest spawn, whose files unpack into
+  // the session's own guest folder, and the agent's sign-in check runs
+  // there first. Every refusal comes before the harness starts. A harness
+  // behind the broker has its binding created or verified before the host
+  // is readied, and a binding this call created is taken back when a later
+  // step fails; the attempt that created it comes back with the plan. A
+  // spawn's new host of its own without a binding is destroyed instead.
   private async setupHarnessOnHost(
     adapter: AgentAdapter,
     provider: ExecutionProvider,
@@ -3075,6 +3205,8 @@ export class SessionManager {
 
     for (const id of removed) {
       this.removedIDs.delete(id);
+
+      await this.records?.remove(id);
     }
   }
 

package/src/daemon/start-headless-turn.ts

@@ -48,6 +48,9 @@ export function startHeadlessTurn(
       ...(s.model === undefined ? {} : { model: s.model }),
       ...(s.effort === undefined ? {} : { effort: s.effort }),
       ...(s.withheldEnv.length === 0 ? {} : { withheldEnv: s.withheldEnv }),
+      ...(mgr.records === null || mgr.findProvider(s)?.remote !== false
+        ? {}
+        : { recordPath: mgr.records.getLocalPath(sessionID) }),
     },
     {
       onOutput: (text) => {

package/src/federation/id-rules.ts

@@ -6,7 +6,8 @@
  * `keep` passes a value that looks like an id but is none of atc's, such as
  * an agent's own session id, while still rewriting ruled fields below it.
  * `opaque` passes a whole value unread: text an agent or a terminal wrote,
- * or a cursor only the same daemon reads back.
+ * a cursor only the same daemon reads back, or the daemon id a session
+ * record holds as written.
  */
 export type IDRule = 'id' | 'locator' | 'cursor' | 'keep' | 'opaque';
 
@@ -41,7 +42,15 @@ export const ID_RULES: Readonly<Record<string, ReadonlyMap<string, IDRule>>> = {
   'session.forget': new Map([['confirmToken', 'opaque']]),
   'session.list': buildPrefixedRules('sessions[].', DESCRIPTOR_RULES),
   'session.spawn': buildPrefixedRules('session.', DESCRIPTOR_RULES),
-  'session.get': buildPrefixedRules('session.', DESCRIPTOR_RULES),
+  'session.get': new Map([
+    ...buildPrefixedRules('session.', DESCRIPTOR_RULES),
+    ['sessionRecord.session', 'id'],
+    ['sessionRecord.daemonID', 'opaque'],
+  ]),
+  'session.scope.add': new Map([
+    ['record.session', 'id'],
+    ['record.daemonID', 'opaque'],
+  ]),
   'session.message': new Map([['message', 'id']]),
   'message.get': new Map([
     ['message', 'id'],

package/src/mcp/mcp-tools.ts

@@ -41,6 +41,40 @@ const DIRS_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   { io: 'input' },
 );
 
+// The scope a session may touch beyond its own workspace, which atc checks
+// entry by entry on the session's host.
+const SCOPE_WORKTREE = z.strictObject({ path: z.string() });
+const SCOPE_BRANCH = z.strictObject({ name: z.string(), repo: z.string().optional() });
+const SCOPE_PULL_REQUEST_NUMBER = z.number().int();
+
+const SCOPE_PULL_REQUEST = z.strictObject({
+  number: SCOPE_PULL_REQUEST_NUMBER,
+  repo: z.string().optional(),
+});
+
+const SCOPE_FIELD = z
+  .strictObject({
+    worktrees: z
+      .array(SCOPE_WORKTREE)
+      .optional()
+      .describe('Absolute paths of git worktrees on the session host, each its worktree top level'),
+    branches: z
+      .array(SCOPE_BRANCH)
+      .optional()
+      .describe(
+        "Branches that exist in repo, an absolute repository path on the session host; repo defaults to the session's directory",
+      ),
+    pullRequests: z
+      .array(SCOPE_PULL_REQUEST)
+      .optional()
+      .describe(
+        "GitHub pull requests of repo, as owner/name; repo defaults to the GitHub repository of the workspace's origin",
+      ),
+  })
+  .describe(
+    "Worktrees, branches, and pull requests the session may touch beyond its own workspace. atc checks each entry on the session's host, refuses an invalid or unknown entry with scope_invalid naming it, and records the rest in the session's record, which the session reads at $ATC_SESSION_RECORD.",
+  );
+
 const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   z.strictObject({
     daemon: DAEMON_FIELD,
@@ -65,6 +99,7 @@ const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
     trustClonedWorkspace: SPAWN_SCHEMA.shape.trustClonedWorkspace.describe(
       "Trust the exact verified clone for this launch. An explicit true or false overrides the configured target trustClonedWorkspace default; omitting both keeps trust off. Requires a workspace source and either stock Claude on the local target, which adds trust for the clone root alone to the user's Claude config, or, on an imp target, a brokered Claude gateway or stock Claude signed in through the broker, each with isolated guest config; other launches are refused. Accepts repository configuration and helpers without changing tool permission mode. Existing guest config is preserved.",
     ),
+    scope: SCOPE_FIELD.optional(),
     detached: z
       .boolean()
       .optional()
@@ -76,6 +111,11 @@ const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   { io: 'input' },
 );
 
+const SCOPE_ADD_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
+  SESSION_ID_BASE.extend({ scope: SCOPE_FIELD }).strict(),
+  { io: 'input' },
+);
+
 const SESSION_READ_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   SESSION_ID_BASE.extend({
     cursor: z
@@ -420,6 +460,7 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
         target: 'spawn.target',
         workspace: 'spawn.workspace',
         trustClonedWorkspace: 'spawn.workspace.trust',
+        scope: 'session.record',
       },
     },
   },
@@ -428,7 +469,7 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     annotations: AGENT_FACING_DESTRUCTIVE,
     scope: 'spawn',
     description:
-      "Type a line of text into a running session and submit it, as if the operator typed it and pressed enter. atc submits the line the way the session's agent accepts one. Use it to answer a session that is waiting on input. A result of sent means atc wrote the line and its submit key to the session; it does not confirm that the agent took the line or answered it. Read the session's screen or events for that. The tool sends no raw keystrokes.",
+      "Type a line of text into a running session and submit it, as if the operator typed it and pressed enter. atc submits the line the way the session's agent accepts one. Use it to answer a session that is waiting on input. atc pastes the line, so its newlines stay in it, and Claude takes a line of about 800 characters or more as pasted text, not as typed words. On a Claude session, a line that starts with a slash command and an argument, such as /goal finish the release, has the command name typed and only the argument pasted, so the command runs at any length. A result of sent means atc wrote the line and its submit key to the session; it does not confirm that the agent took the line or answered it. Read the session's screen or events for that. The tool sends no raw keystrokes.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -450,6 +491,15 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
       'Read the current terminal screen of a session as plain text, without attaching to it. Use it to see what a session printed or what it is waiting on before answering it with atc_session_input. A killed session keeps its last screen.',
     inputSchema: SESSION_INPUT,
   },
+  {
+    name: 'atc_session_scope_add',
+    annotations: ADDITIVE,
+    scope: 'spawn',
+    description:
+      "Add worktrees, branches, or pull requests to the scope a session's record holds, as checked by atc on the session's host. Entries the record already holds change nothing, and atc never removes an entry. A session can never add to its own scope or to that of a session it is a sub-session of; ask whoever started it. Returns the record as it stands after.",
+    inputSchema: SCOPE_ADD_INPUT,
+    requires: { tool: 'session.record' },
+  },
   {
     name: 'atc_session_update',
     annotations: ADDITIVE,

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

@@ -27,6 +27,7 @@ const FEATURE_USES: Readonly<Record<DaemonFeature, string>> = {
   'transport.tcp': 'a TCP connection to the daemon',
   'idempotency.replayOnly': 'a resend that only replays a held idempotency key',
   'session.auth': 'session.auth.revoke and session.auth.rebind',
+  'session.record': "atc_session_scope_add and atc_session_spawn's scope",
 };
 
 /**

package/src/mcp/run-tool.ts

@@ -58,6 +58,7 @@ export function runTool(
         ...(args['trustClonedWorkspace'] === undefined
           ? {}
           : { trustClonedWorkspace: args['trustClonedWorkspace'] }),
+        ...(args['scope'] === undefined ? {} : { scope: args['scope'] }),
         cols: 100,
         rows: 30,
       };
@@ -85,6 +86,9 @@ export function runTool(
           ? ['spawn.workspace.autoDir']
           : [];
 
+      const scopeFeatures: readonly DaemonFeature[] =
+        args['scope'] === undefined ? [] : ['session.record'];
+
       const required = [
         ...optionFeatures,
         ...keyFeatures,
@@ -92,6 +96,7 @@ export function runTool(
         ...workspaceFeatures,
         ...trustFeatures,
         ...autoDirFeatures,
+        ...scopeFeatures,
       ];
 
       const ok =
@@ -141,6 +146,15 @@ export function runTool(
 
       return { text: 'updated', structured: null };
     })
+    .with('atc_session_scope_add', async () => {
+      const ok = await caller.sendRequest(
+        'session.scope.add',
+        { session: args['session'], scope: args['scope'] },
+        ['session.record'],
+      );
+
+      return { text: JSON.stringify(ok), structured: ok };
+    })
     .with('atc_session_kill', async () => {
       await caller.sendRequest('session.kill', { session: args['session'] });
 

package/src/protocol/daemon-features.ts

@@ -90,6 +90,11 @@ export const DAEMON_FEATURES = [
   // `session.auth.revoke` and `session.auth.rebind` exist, open to the
   // daemon's owner only.
   'session.auth',
+
+  // Every session has a published record: `session.spawn` takes `scope`,
+  // `session.scope.add` exists, `session.get` returns `sessionRecord`, and
+  // `daemon.hello` takes `session`, the session the client runs inside.
+  'session.record',
 ] as const;
 
 export type DaemonFeature = (typeof DAEMON_FEATURES)[number];