@zgeoff/atc 2.15.1 → 2.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.15.1",
+  "version": "2.16.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",
@@ -43,7 +43,7 @@
     "@better-auth/oauth-provider": "1.7.6",
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
-    "@zgeoff/imp-client": "0.24.0",
+    "@zgeoff/imp-client": "0.27.0",
     "better-auth": "1.7.6",
     "bun-pty": "0.4.10",
     "citty": "0.2.2",

package/src/agents/build-hook-settings.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { AgentID } from '../shared/agent-id';
+import { toShellArg } from '../shared/to-shell-arg';
 import { buildCLICommand } from './build-cli-command';
 
 /**
@@ -20,7 +21,9 @@ export interface HookSettingsProfile {
  * The settings object injected into wrangled sessions via
  * `claude --settings`. The user's own settings are untouched; these hooks
  * only exist in sessions atc spawns, and identify themselves via
- * ATC_SESSION_ID in the env.
+ * ATC_SESSION_ID in the env and the agent id on their command line. A
+ * nested harness inherits the env but not the command line, so the agent id
+ * keeps its reports from passing as the session's own.
  *
  * A settings-file env block outranks a shell export of the same variable, so
  * a session's backend is decided here rather than by whatever the terminal
@@ -37,7 +40,13 @@ export function buildHookSettings(
 ): Record<string, unknown> {
   const entry = [
     {
-      hooks: [{ type: 'command', command: buildCLICommand('hook-report', cliArgv), timeout: 5 }],
+      hooks: [
+        {
+          type: 'command',
+          command: buildCLICommand(`hook-report --agent ${toShellArg(profile.id)}`, cliArgv),
+          timeout: 5,
+        },
+      ],
     },
   ];
 
@@ -61,7 +70,7 @@ export function buildHookSettings(
     // padding.
     statusLine: {
       type: 'command',
-      command: buildCLICommand('statusline', cliArgv),
+      command: buildCLICommand(`statusline --agent ${toShellArg(profile.id)}`, cliArgv),
       padding: statuslinePadding,
     },
     ...(profile.env === undefined || Object.keys(profile.env).length === 0

package/src/agents/print-codex-hook-file.ts

@@ -17,7 +17,7 @@ export function printCodexHookFile(): void {
 }
 
 function buildCodexHookFile(): string {
-  const cmd = buildCLICommand('hook-report');
+  const cmd = buildCLICommand('hook-report --agent codex');
   const buildEntry = (timeout: number) => [{ hooks: [{ type: 'command', command: cmd, timeout }] }];
   const hooks = Object.fromEntries(CODEX_HOOK_EVENTS.map((event) => [event, buildEntry(5)]));
 

package/src/agents/print-grok-hook-file.ts

@@ -19,7 +19,7 @@ export function printGrokHookFile(): void {
 }
 
 function buildGrokHookFile(): string {
-  const cmd = buildCLICommand('hook-report');
+  const cmd = buildCLICommand('hook-report --agent grok');
   const entry = [{ hooks: [{ type: 'command', command: cmd, timeout: 5 }] }];
   const hooks = Object.fromEntries(GROK_HOOK_EVENTS.map((event) => [event, entry]));
 

package/src/cli.ts

@@ -291,10 +291,16 @@ const main = defineCommand({
           description: 'Forward a hook event from a wrangled session to the atc socket',
           hidden: true,
         },
-        async run() {
+
+        // No arg is required: a citty usage error exits nonzero, and
+        // reporters must always exit 0.
+        args: {
+          agent: { type: 'string', default: '' },
+        },
+        async run(ctx) {
           const reporter = await import('./hook-report');
 
-          await reporter.runHookReport();
+          await reporter.runHookReport(ctx.args.agent);
         },
       }),
     tap: () =>
@@ -352,10 +358,15 @@ const main = defineCommand({
           description: 'Render the chained statusline for a wrangled session',
           hidden: true,
         },
-        async run() {
+
+        // A statusline command must always exit 0 too, so no arg is required.
+        args: {
+          agent: { type: 'string', default: '' },
+        },
+        async run(ctx) {
           const statusline = await import('./statusline');
 
-          await statusline.runStatusline();
+          await statusline.runStatusline(ctx.args.agent);
         },
       }),
   },

package/src/daemon/broker-authority-error.ts

@@ -0,0 +1,41 @@
+/**
+ * Why impd's credential broker may not be used for a session, or why atc
+ * may not clean up after one:
+ *
+ * - `auth_impd_too_old`: impd lacks grantable tokens or secret rebinds.
+ * - `auth_token_scope`: the token's scope is below `manage`.
+ * - `auth_token_too_broad`: the token can reach imps outside atc's
+ *   namespace, through no imp patterns or a pattern whose literal text
+ *   before its first `*` does not start with the namespace prefix.
+ * - `auth_imp_out_of_scope`: an imp the call touches is outside the
+ *   token's patterns.
+ * - `auth_secret_not_grantable`: a bound secret is not on the token's
+ *   grantable list.
+ * - `auth_runtime_mismatch`: the imp under the recorded name has another
+ *   id than the one recorded.
+ */
+export type BrokerAuthorityCode =
+  | 'auth_impd_too_old'
+  | 'auth_token_scope'
+  | 'auth_token_too_broad'
+  | 'auth_imp_out_of_scope'
+  | 'auth_secret_not_grantable'
+  | 'auth_runtime_mismatch';
+
+/**
+ * A refusal to provision through impd's credential broker or to clean up
+ * after it, carrying its code and the detail the code defines.
+ */
+export class BrokerAuthorityError extends Error {
+  readonly code: BrokerAuthorityCode;
+
+  readonly data: Readonly<Record<string, unknown>>;
+
+  constructor(code: BrokerAuthorityCode, message: string, data: Readonly<Record<string, unknown>>) {
+    super(message);
+
+    this.code = code;
+    this.data = data;
+    this.name = 'BrokerAuthorityError';
+  }
+}

package/src/daemon/build-fleet-events.ts

@@ -18,18 +18,24 @@ export interface FleetEvent {
   readonly label?: string;
 }
 
+/**
+ * Builds the events from the sessions that may name them. Rows written
+ * before atc session ids stayed stable across restores carry an earlier atc
+ * id, so a session of `aliases` that holds a row's agent session id names
+ * it when no session holds the atc id; every session that may name a row
+ * may alias it unless the caller gives fewer.
+ */
 export function buildFleetEvents(
   rows: readonly StoredEvent[],
   sessions: readonly SessionDescriptor[],
+  aliases: readonly SessionDescriptor[] = sessions,
 ): FleetEvent[] {
   return rows.map((row) => {
-    // Rows written before atc session ids stayed stable across restores
-    // carry an earlier atc id, so the agent session id links them.
     const live =
+      sessions.find((s) => s.id === row.atcID) ??
       (row.agentSessionID === null
         ? undefined
-        : sessions.find((s) => s.agentSessionID === row.agentSessionID)) ??
-      sessions.find((s) => s.id === row.atcID);
+        : aliases.find((s) => s.agentSessionID === row.agentSessionID));
 
     return {
       cursor: encodeCursor({ kind: 'events', id: row.id }),

package/src/daemon/build-grant-from-fleet-entry.ts

@@ -0,0 +1,14 @@
+import type { FleetEntry } from '../store/fleet-entry';
+import { buildTargetIdentity } from './build-target-identity';
+import type { TargetGrant } from './target-access';
+
+/**
+ * The target a fleet row's session is bound to. A row that stores no
+ * target ran on the implicit `local` target, under its identity.
+ */
+export function buildGrantFromFleetEntry(entry: FleetEntry): TargetGrant {
+  return {
+    target: entry.target ?? 'local',
+    targetIdentity: entry.targetIdentity ?? buildTargetIdentity('local-pty', {}),
+  };
+}

package/src/daemon/build-report-view.ts

@@ -17,17 +17,23 @@ export interface ReportView {
   readonly complete: boolean;
 }
 
+/**
+ * Builds the view from the sessions that may name it. A row written before
+ * atc session ids stayed stable across restores carries an earlier atc id,
+ * so a session of `aliases` that holds its agent session id names it when
+ * no session holds the atc id. The alias only names the report: whoever
+ * checks who may read it checks the row's own atc id.
+ */
 export function buildReportView(
   stored: StoredReport,
   sessions: readonly SessionDescriptor[],
+  aliases: readonly SessionDescriptor[],
 ): ReportView {
-  // A row written before atc session ids stayed stable across restores
-  // carries an earlier atc id, so the agent session id links it.
   const live =
+    sessions.find((s) => s.id === stored.atcID) ??
     (stored.agentSessionID === null
       ? undefined
-      : sessions.find((s) => s.agentSessionID === stored.agentSessionID)) ??
-    sessions.find((s) => s.id === stored.atcID);
+      : aliases.find((s) => s.agentSessionID === stored.agentSessionID));
 
   return {
     report: encodeCursor({ kind: 'events', id: stored.id }),

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

@@ -1,8 +1,8 @@
 import { DaemonError } from '../protocol/daemon-error';
 import type { SessionID } from '../shared/session-id';
 import { toSessionID } from '../shared/to-session-id';
+import { buildGrantFromFleetEntry } from './build-grant-from-fleet-entry';
 import { buildTargetForbiddenError } from './build-target-forbidden-error';
-import { buildTargetIdentity } from './build-target-identity';
 import type { DaemonContext } from './daemon-context';
 import type { KeyedRequest } from './idempotency-ledger';
 import type { TargetAccess, TargetGrant } from './target-access';
@@ -10,14 +10,16 @@ import type { TargetAccess, TargetGrant } from './target-access';
 /**
  * The daemon as a principal with the given access sees it. Its keyed
  * spawns and messages hold their keys in the given namespace, apart from
- * every other namespace's. A session on a target outside the access does
- * not exist here: every lookup of it answers as a lookup of an unknown
- * session does, so the request's own handling refuses it with the words
- * and data it gives a session that never existed. Lists leave such
- * sessions out, and a spawn may use only a target the access holds, a
- * spawn's replayed answer included. A kill, or a pin, of a session whose
- * sub-sessions reach past the access is refused whole, before anything
- * changes.
+ * every other namespace's. A session exists here only when the access
+ * reaches every session in its tree: its top-level session and each
+ * sub-session of that one. Every lookup of any other session answers as a
+ * lookup of an unknown session does, so the request's own handling refuses
+ * it with the words and data it gives a session that never existed. Lists
+ * leave such sessions out, the directory list leaves out directories
+ * spawned only on targets outside the access, and a spawn may use only a
+ * target the access holds, a spawn's replayed answer included. A kill, a
+ * forget, or a change checks the tree in the same synchronous step that
+ * starts it, so a sub-session added after the check is never part of it.
  */
 export function buildScopedContext(
   ctx: DaemonContext,
@@ -28,11 +30,11 @@ export function buildScopedContext(
   const buildPrincipalKey = (keyed: KeyedRequest | null): KeyedRequest | null =>
     keyed === null ? null : { ...keyed, principal: keyNamespace };
 
-  const canSee = (id: SessionID): boolean => {
-    const grant = ctx.findSessionGrant(id);
+  const canSee = (id: SessionID): boolean => ctx.canSeeSession(id, access);
 
-    return grant !== null && access.canUse(grant);
-  };
+  // A request's own access narrowed to this one.
+  const mergeAccess = (outer: TargetAccess | null): TargetAccess =>
+    outer === null ? access : outer.merge(access);
 
   const canUseTarget = (target: string): boolean => {
     const targetIdentity = ctx.findTargetIdentity(target);
@@ -57,10 +59,7 @@ export function buildScopedContext(
       return null;
     }
 
-    return {
-      target: entry.target ?? 'local',
-      targetIdentity: entry.targetIdentity ?? buildTargetIdentity('local-pty', {}),
-    };
+    return buildGrantFromFleetEntry(entry);
   };
 
   // Throws the refusal a fresh spawn to the session's target gets when a
@@ -73,24 +72,9 @@ export function buildScopedContext(
     }
   };
 
-  // Throws the refusal of a change to a session whose sub-sessions the
-  // change would reach too when any of them is out of reach. The refusal
-  // holds only the session the caller sent, never a sub-session's id or
-  // how many there are.
-  const requireTreeInReach = (id: SessionID, action: string): void => {
-    if (ctx.collectChildIDs(id).every((child) => canSee(child))) {
-      return;
-    }
-
-    throw new DaemonError(
-      'target_forbidden',
-      `this client may not ${action} session '${id}': it has a sub-session on a target this client may not use`,
-      { session: id },
-    );
-  };
-
   return {
     ...ctx,
+    isSessionVisible: canSee,
     collectSessions: () => ctx.collectSessions().filter((session) => canSee(session.id)),
     collectAgents: () => {
       const list = ctx.collectAgents();
@@ -115,11 +99,12 @@ export function buildScopedContext(
         }),
       };
     },
-    collectFleet: async () => {
-      const fleet = await ctx.collectFleet();
+    collectSpawnDirs: (outer) => {
+      const merged = outer === null ? access : outer.merge(access);
 
-      return fleet.filter((entry) => canSee(entry.sessionID));
+      return ctx.collectSpawnDirs(merged);
     },
+    resolveSpawnParent: (id) => (canSee(id) ? ctx.resolveSpawnParent(id) : 'missing'),
     resolveSpawnTarget: (requested) => {
       if (requested !== undefined) {
         requireTarget(canUseTarget, requested);
@@ -132,12 +117,10 @@ export function buildScopedContext(
       return target;
     },
     spawnSession: async (plan, keyed) => {
-      let answer: Readonly<Record<string, unknown>>;
-
       // A held key's replay is checked against the target its session was
       // bound to, inside the spawn, before its answer leaves the daemon.
       try {
-        answer = await ctx.spawnSession(plan, buildPrincipalKey(keyed), access);
+        return await ctx.spawnSession(plan, buildPrincipalKey(keyed), access);
       } catch (error) {
         // A held key's refusal may carry the session its spawn made.
         if (error instanceof DaemonError && typeof error.data?.['effectRef'] === 'string') {
@@ -146,29 +129,17 @@ export function buildScopedContext(
 
         throw error;
       }
-
-      return answer;
     },
-    killSession: (id) => {
-      if (!canSee(id)) {
-        return Promise.resolve(false);
-      }
 
-      requireTreeInReach(id, 'kill');
-
-      return ctx.killSession(id);
-    },
-    updateSession: (id, name, pinned) => {
-      if (!canSee(id)) {
-        return false;
-      }
+    // The daemon's kill takes the session's sub-sessions before its first
+    // await, so the set it kills is the set this check saw.
+    killSession: (id) => (canSee(id) ? ctx.killSession(id) : Promise.resolve(false)),
 
-      if (pinned !== undefined) {
-        requireTreeInReach(id, 'pin');
-      }
-
-      return ctx.updateSession(id, name, pinned);
-    },
+    // A session out of reach answers before any confirm token is handed
+    // out or taken, so its host is never touched.
+    forgetSession: (id, confirmToken) =>
+      canSee(id) ? ctx.forgetSession(id, confirmToken) : Promise.resolve('missing' as const),
+    updateSession: (id, name, pinned) => canSee(id) && ctx.updateSession(id, name, pinned),
     ackSession: (id) => canSee(id) && ctx.ackSession(id),
     buildResumeCommand: (id) => (canSee(id) ? ctx.buildResumeCommand(id) : null),
     readSessionScreen: (id) =>
@@ -190,12 +161,16 @@ export function buildScopedContext(
     writeSessionLine: (sessionID, text) =>
       canSee(sessionID) ? ctx.writeSessionLine(sessionID, text) : 'missing',
     ejectSession: (id, prompt) => (canSee(id) ? ctx.ejectSession(id, prompt) : 'missing'),
-    adoptSession: (id, cols, rows) =>
-      canSee(id) ? ctx.adoptSession(id, cols, rows) : Promise.resolve('missing' as const),
+    adoptSession: (id, cols, rows, outer) =>
+      canSee(id)
+        ? ctx.adoptSession(id, cols, rows, mergeAccess(outer))
+        : Promise.resolve('missing' as const),
     resizeSession: (client, sessionID, dims) =>
       canSee(sessionID) && ctx.resizeSession(client, sessionID, dims),
-    readSessionRecord: (id) =>
-      canSee(id) ? ctx.readSessionRecord(id) : Promise.resolve('missing' as const),
+    readSessionRecord: (id, outer) =>
+      canSee(id)
+        ? ctx.readSessionRecord(id, mergeAccess(outer))
+        : Promise.resolve('missing' as const),
     loadSessionTranscript: (id, from, limit) =>
       canSee(id) ? ctx.loadSessionTranscript(id, from, limit) : Promise.resolve('missing' as const),
     readEvents: (afterID, limit, waitMs, sessionID, outer) => {
@@ -203,31 +178,43 @@ export function buildScopedContext(
 
       return ctx.readEvents(afterID, limit, waitMs, sessionID, merged);
     },
-    readReport: (id, outer) => {
-      const merged = outer === null ? access : outer.merge(access);
-
-      return ctx.readReport(id, merged);
-    },
-    writeSessionMessage: (sessionID, from, text, keyed) =>
+    readReport: (id, outer) => ctx.readReport(id, mergeAccess(outer)),
+    writeSessionMessage: (sessionID, from, text, keyed, outer) =>
       canSee(sessionID)
-        ? ctx.writeSessionMessage(sessionID, from, text, buildPrincipalKey(keyed))
+        ? ctx.writeSessionMessage(
+            sessionID,
+            from,
+            text,
+            buildPrincipalKey(keyed),
+            mergeAccess(outer),
+          )
         : Promise.resolve('missing' as const),
     readMessage: async (messageID, waitMs) => {
       // The owner is checked before any wait, so a message outside the
       // access answers at once, as an unknown message does.
       const view = await ctx.readMessage(messageID, 0);
 
-      if (view === null || !canSee(view.session)) {
+      // Only the session the message was sent to owns it here, never one
+      // that shares its agent session id.
+      if (view === null || view.session !== view.record.atcID || !canSee(view.session)) {
         return null;
       }
 
-      return waitMs === 0 ? view : ctx.readMessage(messageID, waitMs);
+      if (waitMs === 0) {
+        return view;
+      }
+
+      // The message may move to another session that holds its agent
+      // session id while the read waits.
+      const waited = await ctx.readMessage(messageID, waitMs);
+
+      return waited !== null && waited.session === waited.record.atcID ? waited : null;
     },
-    attachTap: (client, sessionID) =>
-      canSee(sessionID) ? ctx.attachTap(client, sessionID) : 'missing',
-    ackMessage: (client, sessionID, messageID) =>
+    attachTap: (client, sessionID, outer) =>
+      canSee(sessionID) ? ctx.attachTap(client, sessionID, mergeAccess(outer)) : 'missing',
+    ackMessage: (client, sessionID, messageID, outer) =>
       canSee(sessionID)
-        ? ctx.ackMessage(client, sessionID, messageID)
+        ? ctx.ackMessage(client, sessionID, messageID, mergeAccess(outer))
         : Promise.resolve('unknown' as const),
   };
 }

package/src/daemon/collect-secret-rule-mismatches.ts

@@ -0,0 +1,83 @@
+import type { ImpSecret, ImpSecretRule } from './imp-port';
+
+/**
+ * One secret as a resolved binding expects impd to hold it: its kind and
+ * the complete set of rules, one per host.
+ */
+export interface ExpectedSecret {
+  readonly secret: string;
+  readonly kind: ImpSecret['kind'];
+  readonly rules: readonly ImpSecretRule[];
+}
+
+export type SecretRuleMismatch =
+  | { readonly secret: string; readonly reason: 'missing' }
+  | {
+      readonly secret: string;
+      readonly reason: 'kind';
+      readonly expected: ImpSecret['kind'];
+      readonly actual: ImpSecret['kind'];
+    }
+  | {
+      readonly secret: string;
+      readonly reason: 'rules';
+      readonly expected: readonly ImpSecretRule[];
+      readonly actual: readonly ImpSecretRule[];
+    };
+
+/**
+ * Compares the secrets a resolved binding expects with the secrets impd
+ * lists, secret by secret. Each expected secret must exist with the same
+ * kind and exactly the same set of rules, in any order: a rule impd holds
+ * that the binding lacks is a mismatch as much as a missing one, since it
+ * sends the credential to a host the binding never approved. An empty
+ * result means every expected secret matches; secrets the binding does not
+ * expect are ignored.
+ */
+export function collectSecretRuleMismatches(
+  expected: readonly ExpectedSecret[],
+  secrets: readonly ImpSecret[],
+): SecretRuleMismatch[] {
+  const held = new Map(secrets.map((secret) => [secret.name, secret]));
+
+  const mismatches: SecretRuleMismatch[] = [];
+
+  for (const want of expected) {
+    const actual = held.get(want.secret);
+
+    if (actual === undefined) {
+      mismatches.push({ secret: want.secret, reason: 'missing' });
+    } else if (actual.kind !== want.kind) {
+      mismatches.push({
+        secret: want.secret,
+        reason: 'kind',
+        expected: want.kind,
+        actual: actual.kind,
+      });
+    } else if (!hasSameRules(want.rules, actual.rules)) {
+      mismatches.push({
+        secret: want.secret,
+        reason: 'rules',
+        expected: want.rules,
+        actual: actual.rules,
+      });
+    }
+  }
+
+  return mismatches;
+}
+
+function hasSameRules(left: readonly ImpSecretRule[], right: readonly ImpSecretRule[]): boolean {
+  const leftKeys = left.map((rule) => toRuleKey(rule)).toSorted();
+  const rightKeys = right.map((rule) => toRuleKey(rule)).toSorted();
+
+  return (
+    leftKeys.length === rightKeys.length && leftKeys.every((key, index) => key === rightKeys[index])
+  );
+}
+
+// A rule as one comparable string; JSON keeps a missing user apart from
+// any user a basic rule can hold.
+function toRuleKey(rule: ImpSecretRule): string {
+  return JSON.stringify([rule.host, rule.header, rule.scheme, rule.user ?? null]);
+}