@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/azdo/src/azdo-wit.ts

@@ -0,0 +1,145 @@
+// Azure DevOps work item tool logic. Exported for direct, in-process use by
+// mcp-server.ts — there is no CLI entry point here (nothing else in the
+// repo invoked this file as a CLI).
+import { AdoClient, adoProjectUrl, resolveProject } from './lib/client.ts'
+
+// Work-item calls use the SAME org/project resolution as every other tool in
+// this package (`lib/client.ts`). They used to carry their own `config` object
+// that defaulted the project to a REPOSITORY name, so they addressed a
+// different URL than the PR and pipeline tools in the same process. That
+// divergence was described as deliberately preserved across an earlier
+// refactor; it was preserved, but it was never correct.
+let client: AdoClient | undefined
+
+async function getClient(): Promise<AdoClient> {
+  client ??= new AdoClient()
+  return client
+}
+
+/**
+ * Test seam: forget the cached client. `AdoClient` captures `AZURE_DEVOPS_BASE_URL`
+ * once, at construction — this module's singleton persists across bun:test
+ * files run in the same process, so a test file that points the client at its
+ * own local stub server must call this in `beforeAll`/`afterAll`, or a later
+ * file's calls silently keep hitting the FIRST file's (by then stopped) server.
+ */
+export function resetClientForTests(): void {
+  client = undefined
+}
+
+/** Canonical work-item contract: only these board levels are user-facing. */
+export const ALLOWED_TYPES = ['Feature', 'Product Backlog Item', 'Bug'] as const;
+type AllowedType = (typeof ALLOWED_TYPES)[number];
+export type WorkItemListOrGetArgs = { id?: number; ids?: number[]; type?: string; state?: string; assignedTo?: string; limit?: number; raw?: boolean };
+export type WorkItemWriteArgs = {
+  id?: number; type?: string; title?: string; description?: string; parentId?: number;
+  predecessors?: number[]; related?: number[]; fields?: Record<string, unknown>; state?: string; comment?: string;
+  assignedTo?: string; acceptanceCriteria?: string; priority?: number; startDate?: string; targetDate?: string;
+};
+
+const isAllowedType = (type: string | undefined): type is AllowedType => (ALLOWED_TYPES as readonly string[]).includes(type ?? '');
+function assertAllowedType(type: string | undefined): asserts type is AllowedType {
+  if (!isAllowedType(type)) throw new Error(`type must be one of ${ALLOWED_TYPES.join(', ')}; got ${type ?? 'undefined'}`);
+}
+function formatItem(wi: any, raw: boolean): Record<string, unknown> {
+  const fields = wi.fields ?? {};
+  const relationId = (url: string) => Number(/(\d+)\/?$/.exec(url)?.[1]);
+  const links = { parent: null as number | null, children: [] as number[], predecessors: [] as number[], successors: [] as number[], related: [] as number[] };
+  for (const relation of wi.relations ?? []) {
+    if (relation.rel === 'System.LinkTypes.Hierarchy-Reverse') links.parent = relationId(relation.url);
+    if (relation.rel === 'System.LinkTypes.Hierarchy-Forward') links.children.push(relationId(relation.url));
+    if (relation.rel === 'System.LinkTypes.Dependency-Reverse') links.predecessors.push(relationId(relation.url));
+    if (relation.rel === 'System.LinkTypes.Dependency-Forward') links.successors.push(relationId(relation.url));
+    if (relation.rel === 'System.LinkTypes.Related') links.related.push(relationId(relation.url));
+  }
+  const out: Record<string, unknown> = { id: wi.id, title: fields['System.Title'], type: fields['System.WorkItemType'], state: fields['System.State'], assignedTo: fields['System.AssignedTo']?.displayName, description: fields['System.Description'], url: wi._links?.html?.href, links, customFields: Object.fromEntries(Object.entries(fields).filter(([name]) => name.startsWith('Custom.'))) };
+  if (raw) { out.fields = fields; out.relations = wi.relations ?? []; }
+  return out;
+}
+function escapeWiql(value: string): string { return value.replace(/'/g, "''"); }
+async function batchFetch(c: AdoClient, ids: number[]): Promise<any[]> {
+  const result = await c.post<any>('/wit/workitemsbatch', { ids, $expand: 'all' }, { 'api-version': '7.1' });
+  return result.value ?? [];
+}
+function assertTracked(wi: any): void { if (!isAllowedType(wi.fields?.['System.WorkItemType'])) throw new Error(`work item ${wi.id} is a ${wi.fields?.['System.WorkItemType']}, which this server does not track`); }
+
+export async function workitemListOrGet(args: WorkItemListOrGetArgs = {}): Promise<string> {
+  if (args.id !== undefined && args.ids !== undefined) throw new Error('supply either id or ids, not both');
+  const filters = ['type', 'state', 'assignedTo', 'limit'].filter((key) => args[key as keyof WorkItemListOrGetArgs] !== undefined);
+  if ((args.id !== undefined || args.ids !== undefined) && filters.length) throw new Error('id and ids fetch exact work items; query filters must be omitted');
+  if (args.type !== undefined) assertAllowedType(args.type);
+  const c = await getClient();
+  if (args.id !== undefined) {
+    const item = await c.get<any>(`/wit/workitems/${args.id}`, { 'api-version': '7.1', $expand: 'all' }); assertTracked(item);
+    return JSON.stringify(formatItem(item, args.raw ?? false), null, 2);
+  }
+  if (args.ids !== undefined) {
+    const items = args.ids.length ? await batchFetch(c, args.ids) : []; items.forEach(assertTracked);
+    return JSON.stringify(items.map((item) => formatItem(item, args.raw ?? false)), null, 2);
+  }
+  const limit = args.limit ?? 25;
+  if (!Number.isInteger(limit) || limit < 1) throw new Error('limit must be a positive integer');
+  const clauses = [`[System.TeamProject] = '${escapeWiql(resolveProject())}'`, args.type ? `[System.WorkItemType] = '${escapeWiql(args.type)}'` : `[System.WorkItemType] IN (${ALLOWED_TYPES.map((type) => `'${type}'`).join(', ')})`];
+  if (args.state) clauses.push(`[System.State] = '${escapeWiql(args.state)}'`); else clauses.push("[System.State] <> 'Done'", "[System.State] <> 'Removed'", "[System.State] <> 'Closed'");
+  if (args.assignedTo) clauses.push(`[System.AssignedTo] = '${escapeWiql(args.assignedTo)}'`);
+  const result = await c.post<any>('/wit/wiql', { query: `SELECT [System.Id] FROM WorkItems WHERE ${clauses.join(' AND ')}` }, { 'api-version': '7.1', '$top': String(limit + 1) });
+  const ids = (result.workItems ?? []).map((item: any) => item.id) as number[];
+  const selected = ids.slice(0, limit); const items = selected.length ? await batchFetch(c, selected) : [];
+  return JSON.stringify({ items: items.map((item) => formatItem(item, args.raw ?? false)), count: selected.length, truncated: ids.length > limit, defaultsApplied: args.state === undefined }, null, 2);
+}
+
+function buildWriteOps(args: WorkItemWriteArgs): any[] {
+  const ops: any[] = [];
+  const add = (field: string, value: unknown) => { if (value !== undefined) ops.push({ op: 'add', path: `/fields/${field}`, value }); };
+  add('System.Title', args.title); add('System.Description', args.description); add('System.AssignedTo', args.assignedTo); add('Microsoft.VSTS.Common.AcceptanceCriteria', args.acceptanceCriteria); add('Microsoft.VSTS.Common.Priority', args.priority); add('Microsoft.VSTS.Scheduling.StartDate', args.startDate); add('Microsoft.VSTS.Scheduling.TargetDate', args.targetDate); add('System.State', args.state); add('System.History', args.comment);
+  for (const [field, value] of Object.entries(args.fields ?? {})) {
+    if (!field.startsWith('Custom.')) throw new Error(`fields may only set Custom.* fields; '${field}' is managed by this tool`);
+    add(field, value);
+  }
+  const base = process.env.AZURE_DEVOPS_BASE_URL || `${adoProjectUrl()}/_apis`;
+  const link = (rel: string, id: number) => ops.push({ op: 'add', path: '/relations/-', value: { rel, url: `${base}/wit/workItems/${id}` } });
+  if (args.parentId !== undefined) link('System.LinkTypes.Hierarchy-Reverse', args.parentId);
+  (args.predecessors ?? []).forEach((id) => link('System.LinkTypes.Dependency-Reverse', id));
+  (args.related ?? []).forEach((id) => link('System.LinkTypes.Related', id));
+  return ops;
+}
+
+export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<string> {
+  if (args.id === undefined) {
+    assertAllowedType(args.type); if (!args.title) throw new Error('title is required for create'); if (args.parentId === undefined) throw new Error(`${args.type} requires parentId`);
+    const ops = buildWriteOps(args);
+    const c = await getClient();
+    const parent = await c.get<any>(`/wit/workitems/${args.parentId}`, { 'api-version': '7.1' });
+    const expected = args.type === 'Feature' ? 'Epic' : 'Feature';
+    if (parent.fields?.['System.WorkItemType'] !== expected) throw new Error(`${args.type} must be parented to a ${expected}; work item ${args.parentId} is a ${parent.fields?.['System.WorkItemType']}`);
+    const created = await c.post<any>(`/wit/workitems/$${encodeURIComponent(args.type)}`, ops, { 'api-version': '7.1' }, 'application/json-patch+json');
+    return JSON.stringify(formatItem(created, false), null, 2);
+  }
+  if (args.type !== undefined) throw new Error('type cannot be changed on an existing work item');
+  let ops = buildWriteOps(args); if (!ops.length) throw new Error('nothing to write: no fields, state, comment, or relations were supplied');
+  const c = await getClient();
+  const current = await c.get<any>(`/wit/workitems/${args.id}`, { 'api-version': '7.1', $expand: 'all' });
+  assertTracked(current);
+  if (args.parentId !== undefined) {
+    // A parent is singular. Read the existing item so the write can remove all
+    // old parent links before adding the one validated replacement.
+    const type = current.fields?.['System.WorkItemType'];
+    const parent = await c.get<any>(`/wit/workitems/${args.parentId}`, { 'api-version': '7.1' });
+    const expected = type === 'Feature' ? 'Epic' : 'Feature';
+    if (parent.fields?.['System.WorkItemType'] !== expected) {
+      throw new Error(`${type} must be parented to a ${expected}; work item ${args.parentId} is a ${parent.fields?.['System.WorkItemType']}`);
+    }
+    const oldParentIndexes = (current.relations ?? [])
+      .map((relation: any, index: number) => relation.rel === 'System.LinkTypes.Hierarchy-Reverse' ? index : -1)
+      .filter((index: number) => index >= 0)
+      .sort((left: number, right: number) => right - left);
+    const parentAdd = ops.find((operation) => operation.path === '/relations/-' && operation.value?.rel === 'System.LinkTypes.Hierarchy-Reverse');
+    ops = [
+      ...ops.filter((operation) => operation !== parentAdd),
+      ...oldParentIndexes.map((index: number) => ({ op: 'remove', path: `/relations/${index}` })),
+      ...(parentAdd ? [parentAdd] : []),
+    ];
+  }
+  const updated = await c.patch<any>(`/wit/workitems/${args.id}`, ops, { 'api-version': '7.1' }, 'application/json-patch+json');
+  return JSON.stringify(formatItem(updated, false), null, 2);
+}

package/packages/azdo/src/cli.ts

@@ -0,0 +1,251 @@
+import { dispatchTool, type ToolArguments } from './tool-dispatch.ts';
+
+type Option = {
+  flag: string;
+  key: string;
+  type: 'string' | 'integer' | 'integer-list' | 'json-object' | 'date' | 'boolean';
+  values?: readonly string[];
+};
+
+type Command = {
+  name: string;
+  tool: string;
+  options: readonly Option[];
+  validate?: (args: ToolArguments) => void;
+};
+
+const WORK_ITEM_TYPES = ['Feature', 'Product Backlog Item', 'Bug'] as const;
+const PR_STATUSES = ['active', 'completed', 'abandoned', 'all'] as const;
+const PR_VOTES = ['approve', 'approve-with-suggestions', 'reset', 'wait-for-author', 'reject'] as const;
+
+const commands: readonly Command[] = [
+  {
+    name: 'pr-list-or-get',
+    tool: 'pr_list_or_get',
+    options: [
+      { flag: '--id', key: 'id', type: 'integer' },
+      { flag: '--status', key: 'status', type: 'string', values: PR_STATUSES },
+      { flag: '--repository', key: 'repository', type: 'string' },
+    ],
+    validate: (args) => {
+      if (args.id !== undefined && args.status !== undefined) {
+        throw new Error('pr-list accepts either --id or --status, not both');
+      }
+    },
+  },
+  {
+    name: 'pr-create-or-update',
+    tool: 'pr_create_or_update',
+    options: [
+      { flag: '--action', key: 'action', type: 'string', values: ['create', 'update'] },
+      { flag: '--pull-request-id', key: 'pullRequestId', type: 'integer' },
+      { flag: '--title', key: 'title', type: 'string' },
+      { flag: '--description', key: 'description', type: 'string' },
+      { flag: '--auto-complete', key: 'autoComplete', type: 'boolean' },
+      { flag: '--no-auto-complete', key: 'autoComplete', type: 'boolean' },
+      { flag: '--merge-strategy', key: 'mergeStrategy', type: 'string', values: ['Squash'] },
+      { flag: '--delete-source-branch', key: 'deleteSourceBranch', type: 'boolean' },
+      { flag: '--repository', key: 'repository', type: 'string' },
+    ],
+    validate: requirePullRequestWrite,
+  },
+  {
+    name: 'pr-review',
+    tool: 'pr_review',
+    options: [
+      { flag: '--pull-request-id', key: 'pullRequestId', type: 'integer' },
+      { flag: '--comment', key: 'comment', type: 'string' },
+      { flag: '--vote', key: 'vote', type: 'string', values: PR_VOTES },
+      { flag: '--target-branch', key: 'targetBranch', type: 'string' },
+      { flag: '--repository', key: 'repository', type: 'string' },
+    ],
+    validate: (args) => {
+      requireKeys(args, ['pullRequestId']);
+      if (args.comment === undefined && args.vote === undefined) {
+        throw new Error('pr-review requires --comment, --vote, or both');
+      }
+    },
+  },
+  {
+    name: 'build-list-or-get', tool: 'build_list_or_get',
+    options: [{ flag: '--build-id', key: 'buildId', type: 'integer' }, { flag: '--branch', key: 'branch', type: 'string' }, { flag: '--top', key: 'top', type: 'integer' }, { flag: '--tail', key: 'tail', type: 'integer' }],
+  },
+  {
+    name: 'build-run',
+    tool: 'build_run',
+    options: [
+      { flag: '--id', key: 'id', type: 'integer' },
+      { flag: '--branch', key: 'branch', type: 'string' },
+    ],
+    validate: (args) => requireKeys(args, ['id']),
+  },
+  {
+    name: 'workitem-list-or-get',
+    tool: 'workitem_list_or_get',
+    options: [{ flag: '--id', key: 'id', type: 'integer' }, { flag: '--ids', key: 'ids', type: 'string' }, { flag: '--type', key: 'type', type: 'string', values: WORK_ITEM_TYPES }, { flag: '--state', key: 'state', type: 'string' }, { flag: '--assigned-to', key: 'assignedTo', type: 'string' }, { flag: '--limit', key: 'limit', type: 'integer' }, { flag: '--raw', key: 'raw', type: 'boolean' }],
+  },
+  {
+    name: 'workitem-create-or-update',
+    tool: 'workitem_create_or_update',
+    options: [
+      { flag: '--id', key: 'id', type: 'integer' },
+      { flag: '--type', key: 'type', type: 'string', values: WORK_ITEM_TYPES },
+      { flag: '--title', key: 'title', type: 'string' },
+      { flag: '--description', key: 'description', type: 'string' },
+      { flag: '--parent-id', key: 'parentId', type: 'integer' },
+      { flag: '--predecessors', key: 'predecessors', type: 'integer-list' },
+      { flag: '--related', key: 'related', type: 'integer-list' },
+      { flag: '--fields', key: 'fields', type: 'json-object' },
+      { flag: '--state', key: 'state', type: 'string' },
+      { flag: '--comment', key: 'comment', type: 'string' },
+      { flag: '--assigned-to', key: 'assignedTo', type: 'string' },
+      { flag: '--acceptance-criteria', key: 'acceptanceCriteria', type: 'string' },
+      { flag: '--priority', key: 'priority', type: 'integer' },
+      { flag: '--start-date', key: 'startDate', type: 'date' },
+      { flag: '--target-date', key: 'targetDate', type: 'date' },
+    ],
+    validate: (args) => { if (args.id === undefined) requireKeys(args, ['type', 'title', 'parentId']); },
+  },
+];
+
+const help = `Usage: adl mcp cli <command> [options]
+
+Commands:
+  pr-list-or-get [--id ID] [--status active|completed|abandoned|all] [--repository REPOSITORY]
+  pr-create-or-update --action create|update [--pull-request-id ID] [--title TITLE] [--description DESCRIPTION] [--auto-complete|--no-auto-complete] [--merge-strategy Squash] [--delete-source-branch] [--repository REPOSITORY]
+  pr-review --pull-request-id ID [--comment TEXT] [--vote approve|approve-with-suggestions|reset|wait-for-author|reject] [--target-branch BRANCH] [--repository REPOSITORY]
+  build-list-or-get [--build-id ID] [--branch BRANCH] [--top N] [--tail N]
+  build-run --id ID [--branch BRANCH]
+  workitem-list-or-get [--id ID] [--ids IDS] [--type TYPE] [--state STATE] [--assigned-to IDENTITY] [--limit N] [--raw]
+  workitem-create-or-update [--id ID] [--type 'Feature'|'Product Backlog Item'|'Bug'] [--title TITLE] [--description DESCRIPTION] [--parent-id ID] [--predecessors ID[,ID...]] [--related ID[,ID...]] [--fields JSON_OBJECT] [--state STATE] [--comment TEXT] [--assigned-to IDENTITY] [--acceptance-criteria TEXT] [--priority N] [--start-date YYYY-MM-DD] [--target-date YYYY-MM-DD]
+`;
+
+function requireKeys(args: ToolArguments, keys: string[]): void {
+  const missing = keys.filter((key) => args[key] === undefined);
+  if (missing.length > 0) throw new Error(`Missing required option: --${missing[0]!.replace(/[A-Z]/g, (part) => `-${part.toLowerCase()}`)}`);
+}
+
+function requirePullRequestWrite(args: ToolArguments): void {
+  requireKeys(args, ['action']);
+  if (args.action === 'create') {
+    if (args.pullRequestId !== undefined) {
+      throw new Error('--pull-request-id is only valid for pr-create-or-update update');
+    }
+    if (args.mergeStrategy !== undefined) {
+      throw new Error('--merge-strategy is only valid for pr-create-or-update update');
+    }
+    if (args.deleteSourceBranch !== undefined) {
+      throw new Error('--delete-source-branch is only valid for pr-create-or-update update');
+    }
+    requireKeys(args, ['title', 'description']);
+    return;
+  }
+  if (args.sourceBranch !== undefined) {
+    throw new Error('--source-branch is not supported; PRs always use the current branch');
+  }
+  if (args.targetBranch !== undefined) {
+    throw new Error('--target-branch is not supported; PRs always target integration');
+  }
+  requireKeys(args, ['pullRequestId']);
+  if (
+    args.title === undefined &&
+    args.description === undefined &&
+    args.autoComplete !== true &&
+    args.mergeStrategy === undefined &&
+    args.deleteSourceBranch !== true
+  ) {
+    throw new Error('pr-create-or-update update requires metadata or completion options');
+  }
+}
+
+function parsePositiveIntegerList(flag: string, value: string): number[] {
+  const ids = value.split(',');
+  if (ids.length === 0 || ids.some((id) => !/^[1-9][0-9]*$/.test(id))) {
+    throw new Error(`${flag} must be a comma-separated list of positive integers`);
+  }
+  return ids.map(Number);
+}
+
+function parseJsonObject(flag: string, value: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error(`${flag} must be a JSON object`);
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed) || Object.keys(parsed).length === 0) {
+    throw new Error(`${flag} must be a non-empty JSON object`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function parseDate(flag: string, value: string): string {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) throw new Error(`${flag} must be an ISO date (YYYY-MM-DD)`);
+  const date = new Date(`${value}T00:00:00.000Z`);
+  if (Number.isNaN(date.valueOf()) || date.toISOString().slice(0, 10) !== value) {
+    throw new Error(`${flag} must be an ISO date (YYYY-MM-DD)`);
+  }
+  return value;
+}
+
+function parseOptions(command: Command, tokens: readonly string[]): ToolArguments {
+  const byFlag = new Map(command.options.map((option) => [option.flag, option]));
+  const args: ToolArguments = {};
+  const supplied = new Set<string>();
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index]!;
+    const option = byFlag.get(token);
+    if (!option) {
+      throw new Error(token.startsWith('--') ? `Unknown option for ${command.name}: ${token}` : `Unexpected argument for ${command.name}: ${token}`);
+    }
+    if (supplied.has(option.key)) throw new Error(`Option supplied more than once: ${token}`);
+    supplied.add(option.key);
+
+    if (option.type === 'boolean') {
+      args[option.key] = option.flag === '--no-auto-complete' ? false : true;
+      continue;
+    }
+
+    const value = tokens[index + 1];
+    if (value === undefined || value.startsWith('--')) throw new Error(`Option requires a value: ${token}`);
+    index += 1;
+    if (option.type === 'integer') {
+      if (!/^[1-9][0-9]*$/.test(value)) throw new Error(`Option requires a positive integer: ${token}`);
+      args[option.key] = Number(value);
+    } else if (option.type === 'integer-list') {
+      args[option.key] = parsePositiveIntegerList(token, value);
+    } else if (option.type === 'json-object') {
+      args[option.key] = parseJsonObject(token, value);
+    } else if (option.type === 'date') {
+      args[option.key] = parseDate(token, value);
+    } else {
+      if (value.trim() === '') throw new Error(`Option requires a non-empty value: ${token}`);
+      if (option.values && !option.values.includes(value)) {
+        throw new Error(`Invalid value for ${token}: ${value}; expected ${option.values.join(', ')}`);
+      }
+      if (option.key === 'ids') {
+        args[option.key] = parsePositiveIntegerList('--ids', value);
+      } else {
+        args[option.key] = value;
+      }
+    }
+  }
+
+  command.validate?.(args);
+  return args;
+}
+
+/** Execute direct CLI mode. This is explicit: invoking the binary without `cli` starts MCP. */
+export async function runCli(argv: readonly string[]): Promise<void> {
+  const [commandName, ...tokens] = argv;
+  if (commandName === undefined || commandName === 'help' || commandName === '--help') {
+    console.log(help);
+    return;
+  }
+
+  const command = commands.find((candidate) => candidate.name === commandName);
+  if (!command) throw new Error(`Unknown CLI command: ${commandName}\n\n${help}`);
+  const args = parseOptions(command, tokens);
+  console.log(await dispatchTool(command.tool, args));
+}

package/packages/azdo/src/lib/agent-identity.ts

@@ -0,0 +1,198 @@
+// Azure DevOps identity RESOLUTION ONLY (P2, Tarun, 2026-09-27; standard
+// finalized 2026-09-28 in STATUS.md 12p "The
+// standard"; split from token minting 2026-09-28 -- see
+// ./agent-token.ts's header for why).
+//
+// This module is THE one identity resolver -- every other Azure DevOps
+// surface in this repo (packages/repo-controls, apps/cli, packages/fleet's
+// readers, packages/agent-hooks) resolves through `resolveAgentIdentity`
+// here rather than holding its own copy. Silently defaulting to the
+// machine's own agent is correct (that is what step 2 below is for);
+// running an agent action with NO resolvable identity at all is never
+// correct, so step 3 always refuses by name instead of falling through to a
+// human credential.
+//
+// This file holds NO spawn/Bun.which/token-minting code: `getAccessToken`,
+// `resolveAgentIdBinary`, the token cache and `resetAccessTokenCacheForTests`
+// live in ./agent-token.ts, which imports resolution from here -- never the
+// reverse. That split keeps `bun test`'s per-file instrumentation of THIS
+// module free of minting-only code paths agent-hooks' `check` gate cannot
+// exercise (its rule only ever calls `resolveAgentIdentity`).
+import { readFileSync } from 'node:fs';
+
+/**
+ * The three named coding-agent identities this estate authenticates Azure
+ * DevOps access as. A name outside this set is refused by name wherever it
+ * is found (env or the default-agent file), never silently skipped to try
+ * the next source.
+ */
+export const VALID_AGENTS = ['agent-tarun', 'agent-vivek', 'agent-reviewer'] as const;
+export type ValidAgent = (typeof VALID_AGENTS)[number];
+
+export function isValidAgent(name: string): name is ValidAgent {
+  return (VALID_AGENTS as readonly string[]).includes(name);
+}
+
+/** The one message every surface shows when no agent identity can be resolved at all. */
+export const NO_AGENT_IDENTITY_MESSAGE =
+  'no agent identity: prefix the command with ADL_AGENT_ID_AGENT=<agent-tarun|agent-vivek|agent-reviewer>, or start the session with `adl run <surface> --as <agent>`';
+
+/** Treat blank and whitespace-only values as unset. */
+function configured(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+/**
+ * The machine default-agent file's fixed per-OS path, written by fleet
+ * reconcile from `manifest.json`'s `default_agent`
+ * (packages/fleet/src/default-agent-file.ts owns the WRITE side).
+ */
+const DEFAULT_AGENT_FILE_PATH = {
+  darwin: '/Library/Application Support/adl/default-agent',
+  linux: '/etc/adl/default-agent',
+} as const;
+
+/**
+ * Test-only override -- every package that resolves identity through this
+ * module accepts this exact variable name, so tests never read or write
+ * the real system path (AGENTS.md: "tests hermetic ... no real
+ * HOME/passports/network/system paths"). Production never sets it.
+ */
+const OVERRIDE_ENV_VAR = 'ADL_DEFAULT_AGENT_FILE';
+
+/**
+ * Pure: the default-agent file's path for `platform`, or the
+ * `ADL_DEFAULT_AGENT_FILE` test override, or `undefined` on a platform with
+ * no default-agent path at all. No filesystem access -- exported so both
+ * platform branches (and the override) are testable without reading any
+ * real system path (`readDefaultAgentFile` below is the one caller that
+ * actually reads the file this resolves to).
+ */
+export function defaultAgentFilePath(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string | undefined {
+  const override = configured(env[OVERRIDE_ENV_VAR]);
+  if (override) return override;
+  if (platform === 'darwin') return DEFAULT_AGENT_FILE_PATH.darwin;
+  if (platform === 'linux') return DEFAULT_AGENT_FILE_PATH.linux;
+  return undefined;
+}
+
+/**
+ * The default-agent file's one line, trimmed -- with NO validation against
+ * VALID_AGENTS and NO ADL_AGENT_ID_AGENT env check of its own. Most callers
+ * want the full standard order instead (`resolveAgentIdentity`: env, then
+ * this file, else refuse); this narrower building block exists for `adl
+ * run`'s own `--as`/passport resolution (apps/cli/src/commands/run.ts),
+ * which validates the resolved name against the passports actually
+ * installed on THIS machine, not this fixed list, and has its own usage
+ * message and exit codes to preserve.
+ *
+ * undefined when the file does not exist yet (ENOENT -- the expected state
+ * on a freshly provisioned machine that has not run the fleet reconcile
+ * yet), is empty/whitespace-only, or this platform has no default-agent
+ * path at all.
+ *
+ * Any OTHER read failure (EACCES, EISDIR, a symlink loop, ...) is NOT the
+ * same thing as "no default agent configured" -- silently treating it that
+ * way would make a permissions mistake on the machine look exactly like a
+ * plain "pass --as"/"set ADL_AGENT_ID_AGENT" usage error, instead of the
+ * identity/auth problem it actually is. This throws in that case
+ * (AGENTS.md: "no silent fallback or degrade").
+ */
+export function readDefaultAgentFile(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string | undefined {
+  const path = defaultAgentFilePath(env, platform);
+  if (path === undefined) return undefined;
+  let content: string;
+  try {
+    content = readFileSync(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`cannot read the default-agent file at ${path}: ${detail}`);
+  }
+  return configured(content);
+}
+
+function invalidAgentError(source: string, name: string): Error {
+  return new Error(`invalid agent identity from ${source}: '${name}' is not one of ${VALID_AGENTS.join(', ')}`);
+}
+
+export interface AgentIdentityResolution {
+  agent: string;
+  source: 'env' | 'default-file';
+}
+
+/**
+ * The human Azure DevOps pass-through check (STATUS.md 12p decision 1: fail
+ * closed, the human opts in; 1b: TTY + env marker; 1c: the marker is
+ * `ADL_HUMAN_AZDO=1`). This is the ONE place the rule is expressed in
+ * TypeScript -- `adl id whoami` (apps/cli/src/commands/id.ts) calls this
+ * rather than re-implementing it. `bin/git-ado`'s own human-pass-through
+ * branch implements the IDENTICAL rule in bash (it cannot import this
+ * module), so a contract test
+ * (packages/fleet/tests/git-ado-vault-boundary.test.ts) runs the same
+ * env-value x TTY case table against both this function and the real
+ * script, to keep the two from drifting apart.
+ *
+ * Both halves are required:
+ *  - `stdinIsTTY`: the caller's stdin is a real terminal, not a pipe, a
+ *    closed fd, or a non-interactive automation shell (evidence 2026-09-29,
+ *    STATUS.md 12p: the desktop agent shell has no TTY and does not inherit
+ *    `.zshrc` exports either -- the TTY half alone already excludes it).
+ *  - `env.ADL_HUMAN_AZDO === '1'`: the EXACT string `"1"`, not `"true"`,
+ *    not `"yes"`, not trimmed whitespace -- Tarun exports it from his own
+ *    `.zshrc`. An agent must never set it (packages/agent-settings'
+ *    GLOBAL-AGENTS.md, "Agent identity"; the hook's denial of an agent
+ *    setting it is packages/agent-hooks work, not this module's).
+ *
+ * No fallback, no trimming, no case-insensitivity: a near-miss value is
+ * refused, exactly like `bin/git-ado`'s `[[ "$ADL_HUMAN_AZDO" == "1" ]]`.
+ */
+export function isMarkedHumanAzdoCaller(env: NodeJS.ProcessEnv, stdinIsTTY: boolean): boolean {
+  return stdinIsTTY === true && env.ADL_HUMAN_AZDO === '1';
+}
+
+/**
+ * The one agent-identity resolver every Azure DevOps surface in this repo
+ * shares (STATUS.md 12p, "The standard"). One
+ * function; first match wins; an invalid name is refused, never skipped:
+ *
+ *   1. `ADL_AGENT_ID_AGENT` from the environment (blank/whitespace-only
+ *      counts as unset) -- set by an `adl run --as <agent>` session, or by
+ *      a surface's managed default (e.g. Claude's managed-settings env).
+ *   2. Else the machine default-agent file, written by fleet reconcile.
+ *   3. Else refuse with `NO_AGENT_IDENTITY_MESSAGE` -- there is never a
+ *      human fallback for an agent.
+ *
+ * A name from EITHER source outside `VALID_AGENTS` is refused by name
+ * (never silently skipped to try the next source), and a default-agent
+ * file read failure other than "it does not exist" is refused by name too
+ * (see `readDefaultAgentFile`), never swallowed as "no identity
+ * configured".
+ */
+export function resolveAgentIdentity(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): AgentIdentityResolution {
+  const fromEnv = configured(env.ADL_AGENT_ID_AGENT);
+  if (fromEnv !== undefined) {
+    if (!isValidAgent(fromEnv)) throw invalidAgentError('ADL_AGENT_ID_AGENT', fromEnv);
+    return { agent: fromEnv, source: 'env' };
+  }
+
+  const fromFile = readDefaultAgentFile(env, platform);
+  if (fromFile !== undefined) {
+    if (!isValidAgent(fromFile)) {
+      throw invalidAgentError(`the default-agent file at ${defaultAgentFilePath(env, platform)}`, fromFile);
+    }
+    return { agent: fromFile, source: 'default-file' };
+  }
+
+  throw new Error(NO_AGENT_IDENTITY_MESSAGE);
+}