agent-shim 8.18.0 → 8.20.0

package/README.md

@@ -57,7 +57,7 @@ That's it — with no further configuration, everything in `~/.claude` that isn'
 - **An identity** is a login: the thing that owns credentials and daemon state, selected with `agent-shim run @<name>` or, once `agent-shim shim enable` has run, `claude @<name>`.
 - **A configuration profile** is a reusable, named bundle of sharing rules, independent of any identity, resolved per working directory via directory rules or a committed `.agent-shim.json`.
 
-A third, optional thing sits on top of identities: **a pool** is a named list of them. Select `pool:<name>` where an identity name goes (`claude @pool:subs`) and agent-shim picks the member whose unused quota is closest to expiring, skipping any that are refused right now, using the usage it already records. See [docs/configuration-model.md](docs/configuration-model.md#pools-picking-an-account-at-launch).
+A third, optional thing sits on top of identities: **a pool** is a named list of them. Select `pool:<name>` where an identity name goes (`claude @pool:subs`) and agent-shim picks the member whose unused quota is closest to expiring, skipping any that are refused right now, using the usage it already records. A pool can instead declare `--preference listed`, which tries the members in the order the pool lists them, skipping only one that is refused right now. A member entry may itself name another pool (`pool:<name>`), which is ranked with its own policy and contributes its pick at that position, so "this identity first, then the fleet" nests the fleet rather than copying its member list; cycles are refused. See [docs/configuration-model.md](docs/configuration-model.md#pools-picking-an-account-at-launch).
 
 Every top-level entry in `~/.claude` is classified into one of five categories, shipped as a default map (`config/categories.default.json`):
 
@@ -103,8 +103,8 @@ agent-shim profile show <name> [--json]
 agent-shim profile remove <name> [--yes] [--json]
 agent-shim profile use <name>               # the global default configuration profile [--json]
 
-agent-shim pool add <name> --identity <identity>... [--json]
-agent-shim pool set <name> --identity <identity>... [--json]
+agent-shim pool add <name> --identity <member>... [--preference <score|listed>] [--json]
+agent-shim pool set <name> [--identity <member>...] [--preference <score|listed> | --no-preference] [--json]
 agent-shim pool list [--json]
 agent-shim pool show <name> [--json]
 agent-shim pool remove <name> [--yes] [--json]

package/dist/cli.cjs

@@ -55299,9 +55299,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 = external_exports.string().min(1).regex(new RegExp(`^${POOL_NAME_PATTERN}$`));
-var IdentitySelectorSchema = external_exports.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 = external_exports.string().min(1).regex(SELECTOR_RE);
+var PoolMemberSchema = external_exports.string().min(1).regex(SELECTOR_RE);
+var POOL_PREFERENCES = ["score", "listed"];
+var PoolPreferenceSchema = external_exports.enum(POOL_PREFERENCES);
 var PoolSchema = external_exports.strictObject({
-  identities: external_exports.array(external_exports.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: external_exports.array(PoolMemberSchema).min(1).refine((members2) => new Set(members2).size === members2.length, { message: "pool members must be unique" }),
+  preference: PoolPreferenceSchema.optional()
 });
 var DirectoryRuleSchema = ConfigProfileSchema.omit({ description: true }).extend({
   path: external_exports.string().min(1),
@@ -58305,7 +58310,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, path44) => {
+    for (const entry of pools[current]?.identities ?? []) {
+      const nested = poolNameOf(entry);
+      if (nested === void 0) {
+        continue;
+      }
+      if (nested === name) {
+        return [...path44, nested];
+      }
+      if (path44.includes(nested)) {
+        continue;
+      }
+      const found = walk(nested, [...path44, nested]);
+      if (found !== void 0) {
+        return found;
+      }
+    }
+    return void 0;
+  };
+  return walk(name, [name]);
+}
+function validateMembers(pools, name, members2) {
+  for (const entry of members2) {
+    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: [...members2] } }, 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);
   }
@@ -58313,13 +58352,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;
 }
@@ -61749,7 +61790,7 @@ function registerIdentityCommand(program2, deps) {
 // package.json
 var package_default = {
   name: "agent-shim",
-  version: "8.18.0",
+  version: "8.20.0",
   description: "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   license: "MIT",
   author: "Joseph Mearman <joseph@mearman.co.uk>",
@@ -61828,7 +61869,7 @@ var package_default = {
     rollup: "4.64.0",
     "rollup-plugin-dts": "6.5.1",
     "semantic-release": "^25.0.9",
-    turbo: "^2.10.12",
+    turbo: "^2.11.5",
     typescript: "^6.0.3",
     "typescript-eslint": "^8.70.0",
     vitest: "^4.1.11"
@@ -62756,7 +62797,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 };
@@ -62823,7 +62887,7 @@ function rankPool(input2) {
     }
     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 = input2.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 = input2.sticky;
@@ -63108,6 +63172,12 @@ function createUsageStore(deps) {
 }
 
 // src/usage/poolPick.ts
+var PoolGraphError = class extends CliError {
+  constructor(message) {
+    super(message);
+    this.name = "PoolGraphError";
+  }
+};
 var SCHEMA_VERSION = 1;
 var PickEntrySchema = external_exports.strictObject({ identity: external_exports.string().min(1), at: external_exports.iso.datetime() });
 var PicksFileSchema = external_exports.strictObject({
@@ -63134,13 +63204,63 @@ function loadPoolMembers(fs19, 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(input2) {
+  return rankNamedPool(input2, input2.poolName, [], input2.sticky);
+}
+function rankNamedPool(input2, poolName, stack, sticky) {
+  const pool = input2.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) => !input2.identityExists(entry)).map((identity) => ({ pool: poolName, identity }));
+  const loaded = new Map(loadPoolMembers(input2.fs, input2.paths, direct.filter(input2.identityExists), input2.nowMs).map((member) => [member.identity, member]));
+  const members2 = [];
+  for (const entry of pool.identities) {
+    const nestedName = poolNameOf(entry);
+    if (nestedName === void 0) {
+      const member = loaded.get(entry);
+      if (member !== void 0) {
+        members2.push(member);
+      }
+      continue;
+    }
+    if (input2.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(input2, nestedName, childStack, sticky);
+    members2.push(nested.member);
+    missing.push(...nested.missing);
+  }
+  const ranking = rankPool({
+    members: members2,
+    nowMs: input2.nowMs,
+    resuming: input2.resuming,
+    ...sticky === void 0 ? {} : { sticky },
+    ...pool.preference === void 0 ? {} : { preference: pool.preference }
   });
+  return { ranking, missing };
+}
+function nestedMember(input2, nestedName, childStack, sticky) {
+  const nested = rankNamedPool(input2, nestedName, childStack, sticky);
+  const pick2 = nested.ranking.pick;
+  if (pick2 !== void 0) {
+    const [member] = loadPoolMembers(input2.fs, input2.paths, [pick2.identity], input2.nowMs);
+    return { member: { ...member ?? { identity: pick2.identity, records: [] }, nested: { kind: "pick", pool: nestedName, reasons: pick2.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(fs19, file2) {
   const empty = { schemaVersion: SCHEMA_VERSION, picks: {} };
@@ -63171,59 +63291,6 @@ function recordStickyPick(fs19, 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, fs19) {
-  const exists = (name) => loadIdentity(paths.identitiesDir, name, fs19) !== 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: pick2, earliestReturn } = ranking;
-    if (pick2 !== void 0) {
-      recordStickyPick(params.usageFs, params.paths.usagePicksFile, params.cwd, pick2.identity, nowMs);
-      return { ok: true, identity: pick2.identity, explanation: `pool ${poolName}: ${pick2.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 {
@@ -63237,14 +63304,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 {
@@ -63252,7 +63320,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 }
   };
@@ -64047,11 +64115,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);
@@ -67940,13 +68008,34 @@ 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);
     return poolName === void 0 ? validIdentityNames.has(selector) : poolName in pools;
@@ -69238,7 +69327,7 @@ var PoolPickReportSchema = external_exports.strictObject({
   /** The member a launch would run as, absent when every member is refused. */
   pick: external_exports.string().optional(),
   candidates: external_exports.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: external_exports.array(external_exports.string()),
   /** When nothing can be picked, the soonest any member returns. */
   earliestReturn: external_exports.strictObject({ identity: external_exports.string(), at: external_exports.iso.datetime() }).optional(),
@@ -75782,7 +75871,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) {
@@ -75824,7 +75913,7 @@ function parseLauncherArgv(argv) {
     if (token === void 0) {
       continue;
     }
-    if (token === TERMINATOR2) {
+    if (token === TERMINATOR) {
       rest.push(...remaining.slice(index));
       break;
     }
@@ -75851,7 +75940,7 @@ function parseLauncherArgv(argv) {
       value2 = matched.inlineValue;
     } else {
       const next = remaining[index + 1];
-      if (next === void 0 || next === TERMINATOR2) {
+      if (next === void 0 || next === TERMINATOR) {
         rest.push(token);
         continue;
       }
@@ -76708,7 +76797,7 @@ function formatPoolPick(report, nowMs) {
 function requireIdentities(paths, names) {
   const existing = new Set(listIdentities(paths).map((entry) => entry.name));
   for (const name of names) {
-    if (!existing.has(name)) {
+    if (poolNameOf(name) === void 0 && !existing.has(name)) {
       throw new IdentityNotFoundError(name);
     }
   }
@@ -76719,40 +76808,48 @@ function membersOf(options) {
   }
   return options.identity;
 }
+var PREFERENCE_DESCRIPTION = "How a launch picks a member: score (the default) picks the member whose remaining quota expires soonest; listed tries the members in the order the pool lists them, skipping any that is refused right now.";
 function registerPoolCommand(program2, deps) {
   const { paths } = deps;
   const pool = withExamples(
-    program2.command("pool").description("Manage pools: named sets of identities that a launch picks one member of, by remaining quota, with `claude @pool:<name>`."),
+    program2.command("pool").description("Manage pools: named sets of identities that a launch picks one member of, by remaining quota or the pool's listed order, with `claude @pool:<name>`."),
     ["agent-shim pool add subs --identity work --identity personal", "agent-shim pool pick subs"]
   );
   withExamples(
-    pool.command("add <name>").description("Define a pool. Fails if one with this name already exists.").option("--identity <name>", "A member identity (repeatable).", collectRepeated).option("--json", "Print the result as JSON.").action((name, options) => {
+    pool.command("add <name>").description("Define a pool. Fails if one with this name already exists.").option("--identity <name>", "A member: an identity name, or pool:<name> to nest another pool with its own policy (repeatable).", collectRepeated).addOption(new Option("--preference <mode>", PREFERENCE_DESCRIPTION).choices(POOL_PREFERENCES)).option("--json", "Print the result as JSON.").action((name, options) => {
       const members2 = membersOf(options);
       requireIdentities(paths, members2);
-      const created = addPool(paths, name, members2);
+      const created = addPool(paths, name, members2, options.preference);
       reportMutation(options.json, { action: "created", kind: "pool", name, value: created }, () => {
         console.log(`Created pool "${name}" with ${members2.join(", ")}.`);
       });
     }),
-    ["agent-shim pool add subs --identity work --identity personal"]
+    ["agent-shim pool add subs --identity work --identity personal", "agent-shim pool add client --identity client-main --identity spare --preference listed"]
   );
   withExamples(
-    pool.command("set <name>").description("Replace a pool's members.").option("--identity <name>", "A member identity (repeatable); the full new list.", collectRepeated).option("--json", "Print the result as JSON.").action((name, options) => {
-      const members2 = membersOf(options);
-      requireIdentities(paths, members2);
-      const updated = setPool(paths, name, members2);
+    pool.command("set <name>").description("Replace a pool's members, its preference, or both.").option("--identity <name>", "A member: an identity name, or pool:<name> to nest another pool with its own policy (repeatable); the full new list. Kept as-is when this option is absent.", collectRepeated).addOption(new Option("--preference <mode>", PREFERENCE_DESCRIPTION).choices(POOL_PREFERENCES)).option("--no-preference", "Clear the preference back to the default, score.").option("--json", "Print the result as JSON.").action((name, options) => {
+      const existing = requirePool(paths, name);
+      if (options.identity === void 0 && options.preference === void 0) {
+        throw new UsageError("Nothing to change: pass --identity, --preference or --no-preference.");
+      }
+      const members2 = options.identity === void 0 ? existing.identities : membersOf(options);
+      if (options.identity !== void 0) {
+        requireIdentities(paths, members2);
+      }
+      const preference = options.preference === void 0 ? existing.preference : options.preference === false ? void 0 : options.preference;
+      const updated = setPool(paths, name, members2, preference);
       reportMutation(options.json, { action: "updated", kind: "pool", name, value: updated }, () => {
         console.log(`Pool "${name}" now has ${members2.join(", ")}.`);
       });
     }),
-    ["agent-shim pool set subs --identity work --identity personal --identity spare"]
+    ["agent-shim pool set subs --identity work --identity personal --identity spare", "agent-shim pool set subs --preference listed"]
   );
   withExamples(
     pool.command("list").description("List every pool and its members, marking the active selection with *.").option("--json", "Print the pools as JSON.").action((options) => {
       const pools = readPools(paths);
       const active = readActiveIdentity(paths);
       if (options.json === true) {
-        printJson(Object.entries(pools).map(([name, entry]) => ({ name, identities: entry.identities, active: active === `${POOL_SELECTOR_PREFIX}${name}` })));
+        printJson(Object.entries(pools).map(([name, entry]) => ({ name, identities: entry.identities, ...entry.preference === void 0 ? {} : { preference: entry.preference }, active: active === `${POOL_SELECTOR_PREFIX}${name}` })));
         return;
       }
       const names = Object.keys(pools).sort();
@@ -76761,7 +76858,8 @@ function registerPoolCommand(program2, deps) {
         return;
       }
       for (const name of names) {
-        console.log(`${active === `${POOL_SELECTOR_PREFIX}${name}` ? "*" : " "} ${name}: ${(pools[name]?.identities ?? []).join(", ")}`);
+        const entry = pools[name];
+        console.log(`${active === `${POOL_SELECTOR_PREFIX}${name}` ? "*" : " "} ${name}: ${(entry?.identities ?? []).join(", ")}${entry?.preference === void 0 ? "" : " (preference: listed)"}`);
       }
     }),
     ["agent-shim pool list", "agent-shim pool list --json"]
@@ -76770,11 +76868,14 @@ function registerPoolCommand(program2, deps) {
     pool.command("show <name>").description("Show one pool's members.").option("--json", "Print the pool as JSON.").action((name, options) => {
       const entry = requirePool(paths, name);
       if (options.json === true) {
-        printJson({ name, identities: entry.identities });
+        printJson({ name, identities: entry.identities, ...entry.preference === void 0 ? {} : { preference: entry.preference } });
         return;
       }
       console.log(`Pool: ${name}`);
       console.log(`Members: ${entry.identities.join(", ")}`);
+      if (entry.preference !== void 0) {
+        console.log(`Preference: ${entry.preference}`);
+      }
     }),
     ["agent-shim pool show subs"]
   );
@@ -76801,7 +76902,7 @@ function registerPoolCommand(program2, deps) {
   withExamples(
     pool.command("pick <name>").description("Show how a launch from this directory would rank the pool's members right now, and which it would run as. Read-only: it records nothing.").option("--json", "Print the ranking as JSON.").action((name, options) => {
       const nowMs = Date.now();
-      const report = collectPoolPick({ paths, fs: realFsPort, usageFs: realFarmFs, poolName: name, pool: requirePool(paths, name), directory: process.cwd(), nowMs });
+      const report = collectPoolPick({ paths, fs: realFsPort, usageFs: realFarmFs, poolName: name, pools: readPools(paths), directory: process.cwd(), nowMs });
       if (options.json === true) {
         printJson(report);
         return;
@@ -77568,6 +77669,76 @@ function splitExtraFlags(value2) {
   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 (error62) {
+      if (error62 instanceof PoolGraphError) {
+        return { ok: false, message: `agent-shim: ${error62.message}` };
+      }
+      throw error62;
+    }
+    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: pick2, earliestReturn } = graph.ranking;
+    if (pick2 !== void 0) {
+      recordStickyPick(params.usageFs, params.paths.usagePicksFile, params.cwd, pick2.identity, nowMs);
+      return { ok: true, identity: pick2.identity, explanation: `pool ${poolName}: ${pick2.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_os7 = __toESM(require("node:os"), 1);
 var SIGNAL_EXIT_CODE_OFFSET = 128;