agent-shim 8.18.0 → 8.20.0

package/dist/index.cjs

@@ -571,9 +571,14 @@ var POOL_SELECTOR_PREFIX = "pool:";
 var POOL_NAME_PATTERN = "[A-Za-z0-9][A-Za-z0-9._-]*";
 var IDENTITY_NAME_PATTERN = "[A-Za-z0-9][A-Za-z0-9._@-]*";
 var PoolNameSchema = import_zod.z.string().min(1).regex(new RegExp(`^${POOL_NAME_PATTERN}$`));
-var IdentitySelectorSchema = import_zod.z.string().min(1).regex(new RegExp(`^(${POOL_SELECTOR_PREFIX}${POOL_NAME_PATTERN}|${IDENTITY_NAME_PATTERN})$`));
+var SELECTOR_RE = new RegExp(`^(${POOL_SELECTOR_PREFIX}${POOL_NAME_PATTERN}|${IDENTITY_NAME_PATTERN})$`);
+var IdentitySelectorSchema = import_zod.z.string().min(1).regex(SELECTOR_RE);
+var PoolMemberSchema = import_zod.z.string().min(1).regex(SELECTOR_RE);
+var POOL_PREFERENCES = ["score", "listed"];
+var PoolPreferenceSchema = import_zod.z.enum(POOL_PREFERENCES);
 var PoolSchema = import_zod.z.strictObject({
-  identities: import_zod.z.array(import_zod.z.string().min(1).regex(new RegExp(`^${IDENTITY_NAME_PATTERN}$`))).min(1).refine((names) => new Set(names).size === names.length, { message: "pool members must be unique" })
+  identities: import_zod.z.array(PoolMemberSchema).min(1).refine((members) => new Set(members).size === members.length, { message: "pool members must be unique" }),
+  preference: PoolPreferenceSchema.optional()
 });
 var DirectoryRuleSchema = ConfigProfileSchema.omit({ description: true }).extend({
   path: import_zod.z.string().min(1),
@@ -5616,54 +5621,6 @@ function resolveLayoutPaths() {
   return buildLayoutPaths(resolveAgentShimHome());
 }
 
-// src/usage/preflight.ts
-var MS_PER_SECOND2 = 1e3;
-var SECONDS_PER_MINUTE = 60;
-var MINUTES_PER_HOUR = 60;
-var HOURS_PER_DAY = 24;
-var WARNING_STATUSES = /* @__PURE__ */ new Set(["allowed_warning", "rejected"]);
-function formatAge(ms) {
-  const minutes = Math.floor(ms / (MS_PER_SECOND2 * SECONDS_PER_MINUTE));
-  if (minutes < MINUTES_PER_HOUR) {
-    return `${String(Math.max(minutes, 0))}m`;
-  }
-  const hours = Math.floor(minutes / MINUTES_PER_HOUR);
-  return hours < HOURS_PER_DAY ? `${String(hours)}h` : `${String(Math.floor(hours / HOURS_PER_DAY))}d`;
-}
-function effectiveWindow(window, nowMs) {
-  const resetsAtMs = window.resetsAt === void 0 ? void 0 : Date.parse(window.resetsAt);
-  if (resetsAtMs !== void 0 && resetsAtMs <= nowMs) {
-    return { reset: true, utilization: 0 };
-  }
-  return {
-    reset: false,
-    ...window.utilization === void 0 ? {} : { utilization: window.utilization },
-    ...resetsAtMs === void 0 ? {} : { resetsAtMs },
-    ...window.status === void 0 ? {} : { status: window.status }
-  };
-}
-function quotaWarnings(snapshot, provider, nowMs) {
-  const rateLimit = snapshot?.providers[provider]?.rateLimit;
-  const unified = rateLimit?.unified;
-  if (snapshot === void 0 || rateLimit === void 0 || unified === void 0) {
-    return [];
-  }
-  const age = formatAge(nowMs - Date.parse(rateLimit.observedAt));
-  const windows = [
-    { name: "five-hour", window: unified.fiveHour },
-    { name: "seven-day", window: unified.sevenDay }
-  ];
-  return windows.flatMap(({ name, window }) => {
-    const effective = window === void 0 ? void 0 : effectiveWindow(window, nowMs);
-    if (window === void 0 || effective?.status === void 0 || !WARNING_STATUSES.has(effective.status)) {
-      return [];
-    }
-    const reset = window.resetsAt === void 0 ? "" : `, resets ${window.resetsAt}`;
-    const verdict = effective.status === "rejected" ? "exhausted" : "nearly used";
-    return [`agent-shim: identity ${snapshot.identity}: the ${name} quota is ${verdict}${reset} (last seen ${age} ago)`];
-  });
-}
-
 // src/usage/poolPick.ts
 var import_node_path17 = __toESM(require("node:path"), 1);
 var import_zod9 = require("zod");
@@ -5910,13 +5867,13 @@ function planOf(account) {
 }
 
 // src/usage/rateLimit.ts
-var MS_PER_SECOND3 = 1e3;
+var MS_PER_SECOND2 = 1e3;
 function epochSecondsToIso(value) {
   if (value === void 0) {
     return void 0;
   }
   const seconds = Number(value);
-  return Number.isFinite(seconds) && seconds > 0 ? new Date(seconds * MS_PER_SECOND3).toISOString() : void 0;
+  return Number.isFinite(seconds) && seconds > 0 ? new Date(seconds * MS_PER_SECOND2).toISOString() : void 0;
 }
 function nonNegativeNumber(value) {
   if (value === void 0 || value.trim() === "") {
@@ -5972,6 +5929,54 @@ var ErrorObjectSchema = import_zod8.z.looseObject({
 // src/usage/middleware.ts
 var ANTHROPIC_PROVIDER = "anthropic";
 
+// src/usage/preflight.ts
+var MS_PER_SECOND3 = 1e3;
+var SECONDS_PER_MINUTE = 60;
+var MINUTES_PER_HOUR = 60;
+var HOURS_PER_DAY = 24;
+var WARNING_STATUSES = /* @__PURE__ */ new Set(["allowed_warning", "rejected"]);
+function formatAge(ms) {
+  const minutes = Math.floor(ms / (MS_PER_SECOND3 * SECONDS_PER_MINUTE));
+  if (minutes < MINUTES_PER_HOUR) {
+    return `${String(Math.max(minutes, 0))}m`;
+  }
+  const hours = Math.floor(minutes / MINUTES_PER_HOUR);
+  return hours < HOURS_PER_DAY ? `${String(hours)}h` : `${String(Math.floor(hours / HOURS_PER_DAY))}d`;
+}
+function effectiveWindow(window, nowMs) {
+  const resetsAtMs = window.resetsAt === void 0 ? void 0 : Date.parse(window.resetsAt);
+  if (resetsAtMs !== void 0 && resetsAtMs <= nowMs) {
+    return { reset: true, utilization: 0 };
+  }
+  return {
+    reset: false,
+    ...window.utilization === void 0 ? {} : { utilization: window.utilization },
+    ...resetsAtMs === void 0 ? {} : { resetsAtMs },
+    ...window.status === void 0 ? {} : { status: window.status }
+  };
+}
+function quotaWarnings(snapshot, provider, nowMs) {
+  const rateLimit = snapshot?.providers[provider]?.rateLimit;
+  const unified = rateLimit?.unified;
+  if (snapshot === void 0 || rateLimit === void 0 || unified === void 0) {
+    return [];
+  }
+  const age = formatAge(nowMs - Date.parse(rateLimit.observedAt));
+  const windows = [
+    { name: "five-hour", window: unified.fiveHour },
+    { name: "seven-day", window: unified.sevenDay }
+  ];
+  return windows.flatMap(({ name, window }) => {
+    const effective = window === void 0 ? void 0 : effectiveWindow(window, nowMs);
+    if (window === void 0 || effective?.status === void 0 || !WARNING_STATUSES.has(effective.status)) {
+      return [];
+    }
+    const reset = window.resetsAt === void 0 ? "" : `, resets ${window.resetsAt}`;
+    const verdict = effective.status === "rejected" ? "exhausted" : "nearly used";
+    return [`agent-shim: identity ${snapshot.identity}: the ${name} quota is ${verdict}${reset} (last seen ${age} ago)`];
+  });
+}
+
 // src/usage/pick.ts
 var MS_PER_SECOND4 = 1e3;
 var MS_PER_HOUR = 36e5;
@@ -6033,7 +6038,30 @@ function describeWindow(label, window, effective, nowMs) {
 function capacityOf(plan) {
   return plan.kind === "subscription" ? plan.capacity : 1;
 }
+function assessRefusedNested(member, nested, nowMs) {
+  const refusal = nested.earliestReturn === void 0 ? { reason: `no member of pool "${nested.pool}" can be picked` } : { reason: `every member of pool "${nested.pool}" is refused; ${nested.earliestReturn.identity} returns at ${new Date(nested.earliestReturn.atMs).toISOString()} (in ${formatAge(nested.earliestReturn.atMs - nowMs)})`, blockedUntilMs: nested.earliestReturn.atMs };
+  return {
+    candidate: {
+      identity: member.identity,
+      class: "ineligible",
+      ...refusal.blockedUntilMs === void 0 ? {} : { blockedUntilMs: refusal.blockedUntilMs },
+      plan: planOf(member.account),
+      reasons: [refusal.reason]
+    }
+  };
+}
 function assess(member, nowMs) {
+  const nested = member.nested;
+  if (nested === void 0) {
+    return assessIdentity(member, nowMs);
+  }
+  if (nested.kind === "refused") {
+    return assessRefusedNested(member, nested, nowMs);
+  }
+  const assessment = assessIdentity(member, nowMs);
+  return { ...assessment, candidate: { ...assessment.candidate, reasons: [`picked by pool "${nested.pool}": ${nested.reasons.join("; ")}`, ...assessment.candidate.reasons] } };
+}
+function assessIdentity(member, nowMs) {
   const plan = planOf(member.account);
   const planReasons = plan.kind === "pay-per-use" ? ["billed by use (no plan allowance)"] : plan.recognised ? [`${String(plan.capacity)}x plan`] : [`plan tier ${plan.tier === void 0 ? "not known" : `"${plan.tier}" not recognised`}, counted as 1x`];
   const base = { identity: member.identity, plan };
@@ -6100,7 +6128,7 @@ function rankPool(input) {
     }
     return { ...candidate, feasible: false, reasons: [`5h window would run dry in ${formatAge(runsDryInMs)}, before it resets in ${formatAge(fiveHour.untilResetMs)}`, ...candidate.reasons] };
   });
-  const ordered = [...candidates].sort(
+  const ordered = input.preference === "listed" ? [...candidates] : [...candidates].sort(
     (left, right) => CLASS_ORDER[left.class] - CLASS_ORDER[right.class] || Number(right.feasible) - Number(left.feasible) || (right.score ?? 0) - (left.score ?? 0) || left.identity.localeCompare(right.identity)
   );
   const sticky = input.sticky;
@@ -6228,6 +6256,12 @@ var DAYS_IN_WEEK = 7;
 var USAGE_RETENTION_MS = DAYS_IN_WEEK * DAY_MS2;
 
 // src/usage/poolPick.ts
+var PoolGraphError = class extends CliError {
+  constructor(message) {
+    super(message);
+    this.name = "PoolGraphError";
+  }
+};
 var SCHEMA_VERSION = 1;
 var PickEntrySchema = import_zod9.z.strictObject({ identity: import_zod9.z.string().min(1), at: import_zod9.z.iso.datetime() });
 var PicksFileSchema = import_zod9.z.strictObject({
@@ -6254,13 +6288,63 @@ function loadPoolMembers(fs12, paths, identities, nowMs) {
     }
   });
 }
-function rankPoolFromStore(params) {
-  return rankPool({
-    members: loadPoolMembers(params.fs, params.paths, params.identities, params.nowMs),
-    nowMs: params.nowMs,
-    resuming: params.resuming,
-    ...params.sticky === void 0 ? {} : { sticky: params.sticky }
+function rankPoolGraph(input) {
+  return rankNamedPool(input, input.poolName, [], input.sticky);
+}
+function rankNamedPool(input, poolName, stack, sticky) {
+  const pool = input.pools[poolName];
+  if (pool === void 0) {
+    throw new PoolGraphError(`No pool named "${poolName}". Run \`agent-shim pool add ${poolName} --identity <name>...\` first.`);
+  }
+  const childStack = [...stack, poolName];
+  const direct = pool.identities.filter((entry) => poolNameOf(entry) === void 0);
+  const missing = direct.filter((entry) => !input.identityExists(entry)).map((identity) => ({ pool: poolName, identity }));
+  const loaded = new Map(loadPoolMembers(input.fs, input.paths, direct.filter(input.identityExists), input.nowMs).map((member) => [member.identity, member]));
+  const members = [];
+  for (const entry of pool.identities) {
+    const nestedName = poolNameOf(entry);
+    if (nestedName === void 0) {
+      const member = loaded.get(entry);
+      if (member !== void 0) {
+        members.push(member);
+      }
+      continue;
+    }
+    if (input.pools[nestedName] === void 0) {
+      throw new PoolGraphError(`Pool "${poolName}" member "${entry}" names a pool that is not defined.`);
+    }
+    if (childStack.includes(nestedName)) {
+      throw new PoolGraphError(`Pool "${poolName}" member "${entry}" closes a cycle: ${[...childStack.slice(childStack.indexOf(nestedName)), nestedName].join(" -> ")}. A pool cannot nest itself, directly or through another pool.`);
+    }
+    const nested = nestedMember(input, nestedName, childStack, sticky);
+    members.push(nested.member);
+    missing.push(...nested.missing);
+  }
+  const ranking = rankPool({
+    members,
+    nowMs: input.nowMs,
+    resuming: input.resuming,
+    ...sticky === void 0 ? {} : { sticky },
+    ...pool.preference === void 0 ? {} : { preference: pool.preference }
   });
+  return { ranking, missing };
+}
+function nestedMember(input, nestedName, childStack, sticky) {
+  const nested = rankNamedPool(input, nestedName, childStack, sticky);
+  const pick = nested.ranking.pick;
+  if (pick !== void 0) {
+    const [member] = loadPoolMembers(input.fs, input.paths, [pick.identity], input.nowMs);
+    return { member: { ...member ?? { identity: pick.identity, records: [] }, nested: { kind: "pick", pool: nestedName, reasons: pick.reasons } }, missing: nested.missing };
+  }
+  const earliestReturn = nested.ranking.earliestReturn;
+  return {
+    member: {
+      identity: earliestReturn?.identity ?? `pool:${nestedName}`,
+      records: [],
+      nested: { kind: "refused", pool: nestedName, ...earliestReturn === void 0 ? {} : { earliestReturn } }
+    },
+    missing: nested.missing
+  };
 }
 function readPicksFile(fs12, file) {
   const empty = { schemaVersion: SCHEMA_VERSION, picks: {} };
@@ -6291,59 +6375,6 @@ function recordStickyPick(fs12, picksFile, directory, identity, nowMs) {
 `);
 }
 
-// src/launcher/pool.ts
-var RESUME_FLAGS = /* @__PURE__ */ new Set(["--continue", "-c", "--resume", "-r"]);
-var TERMINATOR = "--";
-var REASONS_LOGGED = 3;
-function splitMembers(pool, paths, fs12) {
-  const exists = (name) => loadIdentity(paths.identitiesDir, name, fs12) !== void 0;
-  return { present: pool.identities.filter(exists), missing: pool.identities.filter((name) => !exists(name)) };
-}
-function isResuming(passthrough) {
-  const end = passthrough.indexOf(TERMINATOR);
-  return (end === -1 ? passthrough : passthrough.slice(0, end)).some((token) => RESUME_FLAGS.has(token));
-}
-function resolvePoolLaunch(params) {
-  const { poolName, log } = params;
-  const pool = params.pools?.[poolName];
-  if (pool === void 0) {
-    return { ok: false, message: `agent-shim: no pool named "${poolName}" (selected via ${params.selectedVia}). Run \`agent-shim pool add ${poolName} --identity <name>...\` first.` };
-  }
-  const { present: identities, missing } = splitMembers(pool, params.paths, params.fs);
-  for (const name of missing) {
-    log.warn(`agent-shim: pool "${poolName}" names identity "${name}", which does not exist; skipping it`);
-  }
-  if (identities.length === 0) {
-    return { ok: false, message: `agent-shim: no member of pool "${poolName}" is an existing identity.` };
-  }
-  const resuming = isResuming(params.passthrough);
-  const stickyRead = readStickyPick(params.usageFs, params.paths.usagePicksFile, params.cwd);
-  if (stickyRead.problem !== void 0) {
-    log.warn(`agent-shim: ${stickyRead.problem}; ignoring the last-pick record`);
-  }
-  for (; ; ) {
-    const nowMs = params.now();
-    const ranking = rankPoolFromStore({ fs: params.usageFs, paths: params.paths, identities, nowMs, resuming, ...stickyRead.sticky === void 0 ? {} : { sticky: stickyRead.sticky } });
-    const { pick, earliestReturn } = ranking;
-    if (pick !== void 0) {
-      recordStickyPick(params.usageFs, params.paths.usagePicksFile, params.cwd, pick.identity, nowMs);
-      return { ok: true, identity: pick.identity, explanation: `pool ${poolName}: ${pick.reasons.slice(0, REASONS_LOGGED).join("; ")}` };
-    }
-    if (earliestReturn === void 0) {
-      return { ok: false, message: `agent-shim: no member of pool "${poolName}" can be picked.` };
-    }
-    const until = new Date(earliestReturn.atMs).toISOString();
-    if (!params.wait) {
-      return {
-        ok: false,
-        message: `agent-shim: every member of pool "${poolName}" is refused right now; the earliest, ${earliestReturn.identity}, returns at ${until} (in ${formatAge(earliestReturn.atMs - nowMs)}). Pass --wait to sleep until then.`
-      };
-    }
-    log.info(`agent-shim: every member of pool "${poolName}" is refused; waiting until ${until} for ${earliestReturn.identity}`);
-    params.sleep(Math.max(earliestReturn.atMs - nowMs, 0));
-  }
-}
-
 // src/poolPickReport.ts
 function candidateView(candidate) {
   return {
@@ -6357,14 +6388,15 @@ function candidateView(candidate) {
   };
 }
 function collectPoolPick(params) {
-  const { present, missing } = splitMembers(params.pool, params.paths, params.fs);
   const sticky = readStickyPick(params.usageFs, params.paths.usagePicksFile, params.directory);
-  const ranking = rankPoolFromStore({
+  const { ranking, missing } = rankPoolGraph({
     fs: params.usageFs,
     paths: params.paths,
-    identities: present,
+    pools: params.pools,
+    poolName: params.poolName,
     nowMs: params.nowMs,
     resuming: false,
+    identityExists: (name) => loadIdentity(params.paths.identitiesDir, name, params.fs) !== void 0,
     ...sticky.sticky === void 0 ? {} : { sticky: sticky.sticky }
   });
   return {
@@ -6372,7 +6404,7 @@ function collectPoolPick(params) {
     directory: params.directory,
     ...ranking.pick === void 0 ? {} : { pick: ranking.pick.identity },
     candidates: ranking.candidates.map(candidateView),
-    missing: [...missing],
+    missing: missing.map(({ identity }) => identity),
     ...ranking.earliestReturn === void 0 ? {} : { earliestReturn: { identity: ranking.earliestReturn.identity, at: new Date(ranking.earliestReturn.atMs).toISOString() } },
     ...sticky.problem === void 0 ? {} : { stickyProblem: sticky.problem }
   };
@@ -6542,7 +6574,41 @@ function requirePool(paths, name) {
 function writePools(paths, pools) {
   applyPatch(paths.globalConfigFile, GlobalConfigSchema, { pools }, { defaults: {} });
 }
-function addPool(paths, name, identities) {
+function poolCycleOf(pools, name) {
+  const walk = (current, path32) => {
+    for (const entry of pools[current]?.identities ?? []) {
+      const nested = poolNameOf(entry);
+      if (nested === void 0) {
+        continue;
+      }
+      if (nested === name) {
+        return [...path32, nested];
+      }
+      if (path32.includes(nested)) {
+        continue;
+      }
+      const found = walk(nested, [...path32, nested]);
+      if (found !== void 0) {
+        return found;
+      }
+    }
+    return void 0;
+  };
+  return walk(name, [name]);
+}
+function validateMembers(pools, name, members) {
+  for (const entry of members) {
+    const nested = poolNameOf(entry);
+    if (nested !== void 0 && nested !== name && pools[nested] === void 0) {
+      throw new UsageError(`Member "${entry}" of pool "${name}" names a pool that is not defined. Run \`agent-shim pool add ${nested} --identity <name>...\` first.`);
+    }
+  }
+  const cycle = poolCycleOf({ ...pools, [name]: { identities: [...members] } }, name);
+  if (cycle !== void 0) {
+    throw new UsageError(`Member "pool:${cycle[1] ?? name}" would make pool "${name}" reach itself: ${cycle.join(" -> ")}. A pool cannot nest itself, directly or through another pool.`);
+  }
+}
+function addPool(paths, name, identities, preference) {
   if (!PoolNameSchema.safeParse(name).success) {
     throw new InvalidPoolNameError(name);
   }
@@ -6550,13 +6616,15 @@ function addPool(paths, name, identities) {
   if (pools[name] !== void 0) {
     throw new PoolAlreadyExistsError(name);
   }
-  const pool = { identities: [...identities] };
+  validateMembers(pools, name, identities);
+  const pool = { identities: [...identities], ...preference === void 0 ? {} : { preference } };
   writePools(paths, { ...pools, [name]: pool });
   return pool;
 }
-function setPool(paths, name, identities) {
+function setPool(paths, name, identities, preference) {
   requirePool(paths, name);
-  const pool = { identities: [...identities] };
+  validateMembers(readPools(paths), name, identities);
+  const pool = { identities: [...identities], ...preference === void 0 ? {} : { preference } };
   writePools(paths, { ...readPools(paths), [name]: pool });
   return pool;
 }
@@ -8467,11 +8535,11 @@ function collectCheckReport(params) {
   });
   let poolPick;
   if (decidedIdentity.pool !== void 0) {
-    const pool = loaded.globalConfig?.pools?.[decidedIdentity.pool];
-    if (pool === void 0) {
+    const pools = loaded.globalConfig?.pools ?? {};
+    if (pools[decidedIdentity.pool] === void 0) {
       throw new PoolNotFoundError(decidedIdentity.pool);
     }
-    poolPick = collectPoolPick({ paths, fs: realFsPort, usageFs: realFarmFs, poolName: decidedIdentity.pool, pool, directory: cwd, nowMs: Date.now() });
+    poolPick = collectPoolPick({ paths, fs: realFsPort, usageFs: realFarmFs, poolName: decidedIdentity.pool, pools, directory: cwd, nowMs: Date.now() });
   }
   const identityDecision = poolPick?.pick === void 0 ? decidedIdentity : { ...decidedIdentity, name: poolPick.pick };
   const loadedIdentity = identityDecision.name === void 0 ? void 0 : loadIdentity(paths.identitiesDir, identityDecision.name, realFsPort);
@@ -8605,7 +8673,7 @@ var PoolPickReportSchema = import_zod13.z.strictObject({
   /** The member a launch would run as, absent when every member is refused. */
   pick: import_zod13.z.string().optional(),
   candidates: import_zod13.z.array(PoolPickCandidateViewSchema),
-  /** Members that name an identity that does not exist; a launch skips them. */
+  /** Identity members anywhere in the pool's graph that do not exist; a launch skips them. */
   missing: import_zod13.z.array(import_zod13.z.string()),
   /** When nothing can be picked, the soonest any member returns. */
   earliestReturn: import_zod13.z.strictObject({ identity: import_zod13.z.string(), at: import_zod13.z.iso.datetime() }).optional(),
@@ -9235,12 +9303,33 @@ function runDoctor(params) {
   const validatedGlobalConfig = params.globalConfig.raw === void 0 ? void 0 : validateJson(GlobalConfigSchema, params.globalConfig);
   const pools = validatedGlobalConfig?.ok === true ? validatedGlobalConfig.data.pools ?? {} : {};
   for (const [poolName, pool] of Object.entries(pools)) {
-    const missing = pool.identities.filter((member) => !validIdentityNames.has(member));
-    if (missing.length === 0) {
+    const missing = pool.identities.filter((member) => poolNameOf(member) === void 0 && !validIdentityNames.has(member));
+    const undefinedPools = pool.identities.flatMap((member) => {
+      const nested = poolNameOf(member);
+      return nested === void 0 || nested in pools ? [] : [nested];
+    });
+    if (missing.length === 0 && undefinedPools.length === 0) {
       push("pool", "pass", `${poolName} is valid (${pool.identities.join(", ")}).`, poolName);
     } else {
-      push("pool", "fail", `Pool "${poolName}" names ${missing.map((member) => `identity "${member}"`).join(" and ")}, which ${missing.length === 1 ? "does" : "do"} not exist.`, poolName);
+      const problems = [
+        ...missing.map((member) => `identity "${member}", which does not exist`),
+        ...undefinedPools.map((nested) => `pool "${nested}", which is not defined`)
+      ];
+      push("pool", "fail", `Pool "${poolName}" names ${problems.join(" and ")}.`, poolName);
+    }
+  }
+  const reportedCycles = /* @__PURE__ */ new Set();
+  for (const poolName of Object.keys(pools).sort()) {
+    const chain = poolCycleOf(pools, poolName);
+    if (chain === void 0) {
+      continue;
+    }
+    const key = [...chain].slice(0, -1).sort().join(">");
+    if (reportedCycles.has(key)) {
+      continue;
     }
+    reportedCycles.add(key);
+    push("pool", "fail", `Pool cycle: ${chain.join(" -> ")}. A pool cannot nest itself, directly or through another pool.`, chain[0]);
   }
   const selectionExists = (selector) => {
     const poolName = poolNameOf(selector);
@@ -11043,7 +11132,7 @@ var LAUNCHER_FLAG_NAMES = [
   ...BOOLEAN_FLAGS.flatMap(({ flag }) => [flag, `--no-${flag.slice(2)}`])
 ];
 var NATIVE_FLAG = "--native";
-var TERMINATOR2 = "--";
+var TERMINATOR = "--";
 function matchValuedFlag(token) {
   for (const flag of VALUED_FLAGS) {
     if (token === flag) {
@@ -11085,7 +11174,7 @@ function parseLauncherArgv(argv) {
     if (token === void 0) {
       continue;
     }
-    if (token === TERMINATOR2) {
+    if (token === TERMINATOR) {
       rest.push(...remaining.slice(index));
       break;
     }
@@ -11112,7 +11201,7 @@ function parseLauncherArgv(argv) {
       value = matched.inlineValue;
     } else {
       const next = remaining[index + 1];
-      if (next === void 0 || next === TERMINATOR2) {
+      if (next === void 0 || next === TERMINATOR) {
         rest.push(token);
         continue;
       }
@@ -11396,6 +11485,76 @@ function splitExtraFlags(value) {
   return trimmed.split(/\s+/);
 }
 
+// src/launcher/pool.ts
+var RESUME_FLAGS = /* @__PURE__ */ new Set(["--continue", "-c", "--resume", "-r"]);
+var TERMINATOR2 = "--";
+var REASONS_LOGGED = 3;
+function isResuming(passthrough) {
+  const end = passthrough.indexOf(TERMINATOR2);
+  return (end === -1 ? passthrough : passthrough.slice(0, end)).some((token) => RESUME_FLAGS.has(token));
+}
+function resolvePoolLaunch(params) {
+  const { poolName, log } = params;
+  const pool = params.pools?.[poolName];
+  if (pool === void 0) {
+    return { ok: false, message: `agent-shim: no pool named "${poolName}" (selected via ${params.selectedVia}). Run \`agent-shim pool add ${poolName} --identity <name>...\` first.` };
+  }
+  const resuming = isResuming(params.passthrough);
+  const stickyRead = readStickyPick(params.usageFs, params.paths.usagePicksFile, params.cwd);
+  if (stickyRead.problem !== void 0) {
+    log.warn(`agent-shim: ${stickyRead.problem}; ignoring the last-pick record`);
+  }
+  const warned = /* @__PURE__ */ new Set();
+  for (; ; ) {
+    const nowMs = params.now();
+    let graph;
+    try {
+      graph = rankPoolGraph({
+        fs: params.usageFs,
+        paths: params.paths,
+        pools: params.pools ?? {},
+        poolName,
+        nowMs,
+        resuming,
+        identityExists: (name) => loadIdentity(params.paths.identitiesDir, name, params.fs) !== void 0,
+        ...stickyRead.sticky === void 0 ? {} : { sticky: stickyRead.sticky }
+      });
+    } catch (error) {
+      if (error instanceof PoolGraphError) {
+        return { ok: false, message: `agent-shim: ${error.message}` };
+      }
+      throw error;
+    }
+    for (const gone of graph.missing) {
+      const key = `${gone.pool}:${gone.identity}`;
+      if (!warned.has(key)) {
+        warned.add(key);
+        log.warn(`agent-shim: pool "${gone.pool}" names identity "${gone.identity}", which does not exist; skipping it`);
+      }
+    }
+    if (graph.ranking.candidates.length === 0) {
+      return { ok: false, message: `agent-shim: no member of pool "${poolName}" is an existing identity.` };
+    }
+    const { pick, earliestReturn } = graph.ranking;
+    if (pick !== void 0) {
+      recordStickyPick(params.usageFs, params.paths.usagePicksFile, params.cwd, pick.identity, nowMs);
+      return { ok: true, identity: pick.identity, explanation: `pool ${poolName}: ${pick.reasons.slice(0, REASONS_LOGGED).join("; ")}` };
+    }
+    if (earliestReturn === void 0) {
+      return { ok: false, message: `agent-shim: no member of pool "${poolName}" can be picked.` };
+    }
+    const until = new Date(earliestReturn.atMs).toISOString();
+    if (!params.wait) {
+      return {
+        ok: false,
+        message: `agent-shim: every member of pool "${poolName}" is refused right now; the earliest, ${earliestReturn.identity}, returns at ${until} (in ${formatAge(earliestReturn.atMs - nowMs)}). Pass --wait to sleep until then.`
+      };
+    }
+    log.info(`agent-shim: every member of pool "${poolName}" is refused; waiting until ${until} for ${earliestReturn.identity}`);
+    params.sleep(Math.max(earliestReturn.atMs - nowMs, 0));
+  }
+}
+
 // src/launcher/spawn.ts
 var import_node_os5 = __toESM(require("node:os"), 1);
 var SIGNAL_EXIT_CODE_OFFSET = 128;