@hegemonart/get-design-done 1.26.0 → 1.27.1

package/scripts/lib/bandit-router.cjs

@@ -1,6 +1,7 @@
 /**
  * bandit-router.cjs — contextual Thompson-sampling bandit over
- * (agent_type, touches_size_bin) → {haiku, sonnet, opus} (Plan 23.5-01).
+ * (agent_type, touches_size_bin[, delegate]) → {haiku, sonnet, opus}
+ * (Plan 23.5-01 + Plan 27-07 delegate dimension).
  *
  * Replaces Phase 10.1's static tier_overrides map when the user opts
  * into adaptive_mode = "full". The static map continues to apply when
@@ -10,12 +11,25 @@
  *   .design/telemetry/posterior.json
  *     { schema_version: '1.0.0',
  *       generated_at: ISO,
- *       arms: [{agent, bin, tier, alpha, beta, last_used, count}] }
+ *       arms: [{agent, bin, tier, delegate?, alpha, beta, last_used, count}] }
+ *
+ * The `delegate` field on an arm is OPTIONAL (Plan 27-07 / D-08). Existing
+ * callers that pass only `(agent, bin)` continue to read/write arms with
+ * `delegate === undefined`, which behaves identically to delegate='none'
+ * (i.e., the local-call slice). New callers can opt into the delegate
+ * dimension via `pullWithDelegate()` / `updateWithDelegate()` which
+ * persist `delegate ∈ {none, gemini, codex, cursor, copilot, qwen}`.
+ *
+ * Bootstrap discipline (D-08):
+ *   - delegate='none' arms inherit Phase 23.5's TIER_PRIOR (informed).
+ *   - delegate ∈ {gemini, codex, cursor, copilot, qwen} arms start
+ *     neutral — the same TIER_PRIOR shape, on the assumption that we
+ *     have no prior to favour any delegate over local; data drives.
  *
  * Atomic .tmp + rename. Discounted Thompson via per-arm time-decay
  * factor `rho^days_since_last_use` applied at sample time, not stored.
  *
- * Reward computation (D-06): two-stage lexicographic
+ * Reward computation (D-06): two-stage lexicographic — UNCHANGED.
  *   if !solidify_pass:           reward = 0
  *   elif user_undo_in_session:   reward = 0
  *   else:                        reward = 1 - lambda * normalize(cost + epsilon * wall_time)
@@ -45,11 +59,25 @@ const TIER_PRIOR = Object.freeze({
 const PRIOR_STRENGTH = 10;
 const DEFAULT_TIERS = Object.freeze(['haiku', 'sonnet', 'opus']);
 
+// Plan 27-07 / D-08. Delegate context dimension. 'none' = local Anthropic
+// call; the other 5 are peer-CLI delegations via ACP/ASP. Adding this as
+// a third context dimension expands the arm space 6× (78 → ~468 contexts).
+const DELEGATE_NONE = 'none';
+const DEFAULT_DELEGATES = Object.freeze([
+  DELEGATE_NONE,
+  'gemini',
+  'codex',
+  'cursor',
+  'copilot',
+  'qwen',
+]);
+
 const DEFAULT_PRIORS = Object.freeze({
   decay: DEFAULT_DECAY,
   strength: PRIOR_STRENGTH,
   tiers: DEFAULT_TIERS,
   perTier: TIER_PRIOR,
+  delegates: DEFAULT_DELEGATES,
 });
 
 const TOUCHES_BINS = Object.freeze([
@@ -141,12 +169,47 @@ function priorFor(tier, strength) {
   };
 }
 
-function findArm(arms, agent, bin, tier) {
-  return arms.find((a) => a.agent === agent && a.bin === bin && a.tier === tier);
+/**
+ * @param {object[]} arms
+ * @param {string} agent
+ * @param {string} bin
+ * @param {string} tier
+ * @param {string} [delegate] — when provided, match arms with that
+ *   delegate label. When omitted, match arms with no delegate field
+ *   (legacy Phase 23.5 slice — equivalent to delegate='none' for
+ *   bootstrap purposes but persisted distinctly to preserve
+ *   round-trippability of existing posterior files).
+ */
+function findArm(arms, agent, bin, tier, delegate) {
+  if (delegate === undefined) {
+    return arms.find(
+      (a) =>
+        a.agent === agent &&
+        a.bin === bin &&
+        a.tier === tier &&
+        a.delegate === undefined,
+    );
+  }
+  return arms.find(
+    (a) =>
+      a.agent === agent &&
+      a.bin === bin &&
+      a.tier === tier &&
+      a.delegate === delegate,
+  );
 }
 
-function ensureArm(posterior, agent, bin, tier, strength) {
-  let arm = findArm(posterior.arms, agent, bin, tier);
+/**
+ * Ensure an arm exists, creating it with the informed prior when missing.
+ *
+ * For Plan 27-07: when `delegate` is provided, the arm is persisted with
+ * that label. Bootstrap is identical for delegate='none' (inherits Phase
+ * 23.5 prior — no migration needed because the legacy slice and the
+ * 'none' slice are independent contexts) and for the 5 peer delegates
+ * (each starts neutral with the same TIER_PRIOR shape; data drives).
+ */
+function ensureArm(posterior, agent, bin, tier, strength, delegate) {
+  let arm = findArm(posterior.arms, agent, bin, tier, delegate);
   if (arm) return arm;
   const { alpha, beta } = priorFor(tier, strength);
   arm = {
@@ -158,6 +221,9 @@ function ensureArm(posterior, agent, bin, tier, strength) {
     last_used: null,
     count: 0,
   };
+  if (delegate !== undefined) {
+    arm.delegate = delegate;
+  }
   posterior.arms.push(arm);
   return arm;
 }
@@ -310,6 +376,143 @@ function update(input) {
   return { alpha: arm.alpha, beta: arm.beta, posteriorPath: p };
 }
 
+/**
+ * Pull an arm with the delegate context dimension (Plan 27-07 / D-08).
+ *
+ * Joint sample over `tiers × delegates` — i.e., 3 × 6 = 18 arms in the
+ * default case. Returns the (tier, delegate) pair with the highest
+ * sampled posterior. Bumps the chosen arm's last_used + count.
+ *
+ * Caller-restricted delegate set:
+ *   - For `delegate_to: none` agents (Plan 27-06 frontmatter), the caller
+ *     should pass `delegates: ['none']` to constrain sampling to the
+ *     local-call slice — the bandit will not explore peer delegations.
+ *   - For agents without `delegate_to` (default), the caller may either
+ *     omit delegates (legacy `pull()` behaviour) or pass DEFAULT_DELEGATES
+ *     to enable adaptive routing across the full 18-arm space.
+ *
+ * @param {{
+ *   agent: string,
+ *   bin: string,
+ *   tiers?: string[],
+ *   delegates?: string[],
+ *   baseDir?: string,
+ *   posteriorPath?: string,
+ *   decay?: number,
+ *   strength?: number,
+ *   now?: Date,
+ * }} input
+ * @returns {{
+ *   tier: string,
+ *   delegate: string,
+ *   samples: Record<string, Record<string, number>>,
+ *   posteriorPath: string,
+ * }}
+ */
+function pullWithDelegate(input) {
+  if (!input || typeof input.agent !== 'string' || input.agent.length === 0) {
+    throw new TypeError('bandit-router.pullWithDelegate: agent (string) required');
+  }
+  if (typeof input.bin !== 'string' || input.bin.length === 0) {
+    throw new TypeError('bandit-router.pullWithDelegate: bin (string) required');
+  }
+  const tiers = input.tiers ?? DEFAULT_TIERS;
+  const delegates = input.delegates ?? DEFAULT_DELEGATES;
+  if (!Array.isArray(delegates) || delegates.length === 0) {
+    throw new TypeError(
+      'bandit-router.pullWithDelegate: delegates must be a non-empty array',
+    );
+  }
+  const strength = input.strength ?? PRIOR_STRENGTH;
+  const now = input.now ?? new Date();
+
+  const posterior = loadPosterior(input);
+  /** @type {Record<string, Record<string, number>>} */
+  const samples = {};
+  let bestTier = tiers[0];
+  let bestDelegate = delegates[0];
+  let bestSample = -1;
+  for (const delegate of delegates) {
+    samples[delegate] = {};
+    for (const tier of tiers) {
+      const arm = ensureArm(posterior, input.agent, input.bin, tier, strength, delegate);
+      const decayed = decayArm(arm, { decay: input.decay, now, strength });
+      const s = sampleBeta(decayed.alpha, decayed.beta);
+      samples[delegate][tier] = s;
+      if (s > bestSample) {
+        bestSample = s;
+        bestTier = tier;
+        bestDelegate = delegate;
+      }
+    }
+  }
+  const chosen = ensureArm(
+    posterior,
+    input.agent,
+    input.bin,
+    bestTier,
+    strength,
+    bestDelegate,
+  );
+  chosen.last_used = now.toISOString();
+  chosen.count += 1;
+  const written = savePosterior(posterior, input);
+  return {
+    tier: bestTier,
+    delegate: bestDelegate,
+    samples,
+    posteriorPath: written,
+  };
+}
+
+/**
+ * Update the posterior with a reward signal — delegate-aware variant.
+ *
+ * Reward signal is UNCHANGED from Phase 23.5 (D-08): two-stage
+ * lexicographic via `computeReward()` — correctness first, cost as
+ * tiebreaker. The delegate dimension is applied at the arm-locator
+ * level, not the reward computation.
+ *
+ * @param {{
+ *   agent: string,
+ *   bin: string,
+ *   tier: string,
+ *   delegate: string,
+ *   reward: number,
+ *   baseDir?: string,
+ *   posteriorPath?: string,
+ *   strength?: number,
+ * }} input
+ * @returns {{alpha: number, beta: number, posteriorPath: string}}
+ */
+function updateWithDelegate(input) {
+  if (!input) throw new TypeError('bandit-router.updateWithDelegate: input required');
+  for (const k of ['agent', 'bin', 'tier', 'delegate']) {
+    if (typeof input[k] !== 'string' || input[k].length === 0) {
+      throw new TypeError(
+        `bandit-router.updateWithDelegate: ${k} (string) required`,
+      );
+    }
+  }
+  if (typeof input.reward !== 'number' || Number.isNaN(input.reward)) {
+    throw new TypeError('bandit-router.updateWithDelegate: reward (number) required');
+  }
+  const r = Math.min(1, Math.max(0, input.reward));
+  const posterior = loadPosterior(input);
+  const arm = ensureArm(
+    posterior,
+    input.agent,
+    input.bin,
+    input.tier,
+    input.strength ?? PRIOR_STRENGTH,
+    input.delegate,
+  );
+  arm.alpha += r;
+  arm.beta += 1 - r;
+  const p = savePosterior(posterior, input);
+  return { alpha: arm.alpha, beta: arm.beta, posteriorPath: p };
+}
+
 /**
  * Two-stage lexicographic reward (D-06).
  *
@@ -350,6 +553,8 @@ function computeReward(input) {
 module.exports = {
   pull,
   update,
+  pullWithDelegate,
+  updateWithDelegate,
   reset,
   loadPosterior,
   savePosterior,
@@ -360,6 +565,8 @@ module.exports = {
   priorFor,
   DEFAULT_PRIORS,
   DEFAULT_TIERS,
+  DEFAULT_DELEGATES,
+  DELEGATE_NONE,
   TIER_PRIOR,
   PRIOR_STRENGTH,
   TOUCHES_BINS,

package/scripts/lib/budget-enforcer.cjs

@@ -384,6 +384,15 @@ function computeCost(args, opts) {
  * event-stream import); .cjs callers (non-CC mirrors) compose this with
  * the JSONL line shape used in tier-resolver.cjs's `emitEvent()`.
  *
+ * Phase 27 / Plan 27-08 (D-09) extension — additive: cost rows now
+ * optionally carry `runtime_role` ("host" | "peer", default "host" when
+ * absent for back-compat) and `peer_id` (set only when
+ * `runtime_role === "peer"`). Pre-Phase-27 callers that don't pass these
+ * fields get the legacy shape with `runtime_role: "host"` stamped — so
+ * the cost-aggregator + reflector cross-runtime arbitrage
+ * (`scripts/lib/cost-arbitrage.cjs`) never sees an absent role tag and
+ * mixed-role cycle history rolls up correctly without crashing.
+ *
  * @param {object} args
  * @param {string} args.runtime
  * @param {string} args.agent
@@ -392,10 +401,18 @@ function computeCost(args, opts) {
  * @param {number} args.tokens_in
  * @param {number} args.tokens_out
  * @param {number|null} args.cost_usd
+ * @param {('host'|'peer')} [args.runtime_role]
+ *   Phase 27. Defaults to `"host"` when absent.
+ * @param {string|null} [args.peer_id]
+ *   Phase 27. The peer-CLI ID when `runtime_role === "peer"` (e.g.
+ *   `"gemini"`, `"codex"`). Omitted from output when absent or when
+ *   `runtime_role === "host"`.
  * @returns {object}
  */
 function buildCostEventPayload(args) {
-  return {
+  const role = args && args.runtime_role === 'peer' ? 'peer' : 'host';
+  /** @type {Record<string, unknown>} */
+  const out = {
     runtime: args.runtime,
     agent: args.agent,
     model_id: args.model_id,
@@ -405,7 +422,54 @@ function buildCostEventPayload(args) {
     cost_usd: typeof args.cost_usd === 'number' && Number.isFinite(args.cost_usd)
       ? args.cost_usd
       : null,
+    runtime_role: role,
   };
+  // peer_id is only meaningful when role === "peer"; we omit it for
+  // host rows to keep the legacy on-disk shape stable for cost-aggregator
+  // tests that snapshot the line content.
+  if (role === 'peer') {
+    const pid = args && typeof args.peer_id === 'string' && args.peer_id.length > 0
+      ? args.peer_id
+      : null;
+    out.peer_id = pid;
+  }
+  return out;
+}
+
+/**
+ * Phase 27 / Plan 27-08 helper — derive `(runtime_role, peer_id)` from a
+ * router decision shape, mirroring `modelFromResolved`'s contract:
+ *
+ *   - When the router decision carries `runtime_role: "peer"` AND
+ *     `peer_id: "<non-empty-string>"`, return `{ role: 'peer', peer_id }`.
+ *   - When the decision is absent, malformed, or not flagged as peer-mode,
+ *     return `{ role: 'host', peer_id: null }`.
+ *
+ * Plan 27-06's session-runner sets `runtime_role` + `peer_id` on its
+ * router-decision payload before invoking the budget-enforcer hook; this
+ * helper is the pure backend lookup that the hook (and any non-CC
+ * cost-recorder mirror) calls to thread those values into the cost row.
+ *
+ * Defensive on every shape — never throws on null / wrong type. Returning
+ * `host` on every error path keeps the legacy back-compat default
+ * everywhere.
+ *
+ * @param {unknown} routerDecision
+ * @returns {{ role: 'host' | 'peer', peer_id: string | null }}
+ */
+function roleFromRouterDecision(routerDecision) {
+  if (!routerDecision || typeof routerDecision !== 'object') {
+    return { role: 'host', peer_id: null };
+  }
+  const role = routerDecision.runtime_role;
+  if (role !== 'peer') return { role: 'host', peer_id: null };
+  const pid = routerDecision.peer_id;
+  if (typeof pid !== 'string' || pid.length === 0) {
+    // peer-flagged but no peer_id is malformed — degrade to host to
+    // avoid emitting a half-tagged cost row.
+    return { role: 'host', peer_id: null };
+  }
+  return { role: 'peer', peer_id: pid };
 }
 
 /**
@@ -435,6 +499,10 @@ module.exports = {
   computeCost,
   buildCostEventPayload,
   modelFromResolved,
+  // Plan 27-08 (D-09): runtime-role + peer-id derivation from router
+  // decision. Used by the .ts hook and any non-CC cost-recorder mirror to
+  // thread peer-delegation tags into cost.jsonl rows.
+  roleFromRouterDecision,
   parsePriceTable,
   loadPriceTable,
   priceTablePath,

package/scripts/lib/event-stream/index.ts

@@ -50,8 +50,21 @@ export type {
   ToolCallCompletedEvent,
   AgentSpawnEvent,
   AgentOutcomeEvent,
+  // Phase 27 / Plan 27-08 — peer-CLI delegation events (D-09).
+  RuntimeRole,
+  PeerCallStartedEvent,
+  PeerCallCompleteEvent,
+  PeerCallFailedEvent,
+} from './types.ts';
+export {
+  KNOWN_EVENT_TYPES,
+  // Phase 27 / Plan 27-08 — symbolic constants for peer-CLI event names.
+  PEER_CALL_STARTED,
+  PEER_CALL_COMPLETE,
+  PEER_CALL_FAILED,
+  PEER_CALL_EVENT_TYPES,
+  DEFAULT_RUNTIME_ROLE,
 } from './types.ts';
-export { KNOWN_EVENT_TYPES } from './types.ts';
 export { EventBus } from './emitter.ts';
 export type { EventHandler, Unsubscribe } from './emitter.ts';
 export { EventWriter, DEFAULT_EVENTS_PATH, DEFAULT_MAX_LINE_BYTES } from './writer.ts';

package/scripts/lib/event-stream/types.ts

@@ -218,6 +218,87 @@ export type AgentOutcomeEvent = BaseEvent & {
   };
 };
 
+// ---------------------------------------------------------------------------
+// Phase 27 — peer-CLI delegation lifecycle (Plan 27-08, D-09)
+// ---------------------------------------------------------------------------
+//
+// Additive extension. Every event keeps existing fields. Peer-call events
+// gain two payload tags:
+//
+//   * `runtime_role: "host" | "peer"` — defaults to `"host"` if absent at
+//     read time (so all pre-Phase-27 events continue to read as host-mode).
+//     Only the three `peer_call_*` events below MUST carry it as `"peer"`.
+//   * `peer_id` — the peer-CLI ID (`"gemini"`, `"codex"`, `"cursor"`,
+//     `"copilot"`, `"qwen"`, …) — set when `runtime_role === "peer"`.
+//
+// `costs.jsonl` cost rows (`cost_recorded` / `cost.update`) gain the same
+// two tags so Phase 26's reflector cross-runtime arbitrage continues to
+// roll up correctly with mixed-role data. See
+// `scripts/lib/budget-enforcer.cjs#buildCostEventPayload` for the cost-row
+// extension.
+//
+// Plan 27-06 owns the actual emission call sites in session-runner; this
+// file provides the shape + symbolic constants so 27-06 can import the
+// type names without redefining them.
+
+/**
+ * Narrow union for the runtime-role tag. Pre-Phase-27 events do not carry
+ * this field; readers MUST default to `"host"` when absent.
+ */
+export type RuntimeRole = 'host' | 'peer';
+
+/**
+ * Emitted by session-runner (Plan 27-06) when a peer-CLI delegation is
+ * about to start. `latency_ms` is captured on the corresponding
+ * `peer_call_complete` / `peer_call_failed` event; this event marks the
+ * boundary so chain-walkers can pair started/complete via shared
+ * sessionId + peer_id + role.
+ */
+export type PeerCallStartedEvent = BaseEvent & {
+  type: 'peer_call_started';
+  payload: {
+    runtime_role: 'peer';
+    peer_id: string;
+    role: string;
+  };
+};
+
+/**
+ * Emitted by session-runner on successful peer-CLI delegation.
+ * `cost_usd` is computed via the shared cost backend (Plan 26-05)
+ * extended with `runtime_role` + `peer_id` tags so the cost-aggregator
+ * rolls up peer spend correctly.
+ */
+export type PeerCallCompleteEvent = BaseEvent & {
+  type: 'peer_call_complete';
+  payload: {
+    runtime_role: 'peer';
+    peer_id: string;
+    role: string;
+    latency_ms: number;
+    tokens_in: number;
+    tokens_out: number;
+    cost_usd: number | null;
+  };
+};
+
+/**
+ * Emitted by session-runner when peer-CLI delegation fails (peer-absent,
+ * peer-error, timeout). D-07: failure is transparent — session-runner
+ * falls back to the local Anthropic call — so this event is purely a
+ * measurement signal for the reflector. `error_class` mirrors
+ * Plan 20-04's `classify(err).kind`.
+ */
+export type PeerCallFailedEvent = BaseEvent & {
+  type: 'peer_call_failed';
+  payload: {
+    runtime_role: 'peer';
+    peer_id: string;
+    role: string;
+    error_class: string;
+  };
+};
+
 /**
  * Union of all pre-registered event types. Not a closed enum at the
  * envelope level — callers can emit unknown types — but downstream
@@ -247,7 +328,10 @@ export type KnownEvent =
   | ToolCallStartedEvent
   | ToolCallCompletedEvent
   | AgentSpawnEvent
-  | AgentOutcomeEvent;
+  | AgentOutcomeEvent
+  | PeerCallStartedEvent
+  | PeerCallCompleteEvent
+  | PeerCallFailedEvent;
 
 /**
  * Runtime list of all pre-registered event `type` strings. Used by the
@@ -278,4 +362,44 @@ export const KNOWN_EVENT_TYPES: readonly string[] = [
   'tool_call.completed',
   'agent.spawn',
   'agent.outcome',
+  // Phase 27 / Plan 27-08 — peer-CLI delegation lifecycle (D-09).
+  'peer_call_started',
+  'peer_call_complete',
+  'peer_call_failed',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Phase 27 / Plan 27-08 — symbolic constants for peer-CLI event names.
+// ---------------------------------------------------------------------------
+//
+// Plan 27-06 (session-runner) imports these by name rather than copying
+// string literals so a downstream rename is a single-source-of-truth edit.
+// All three are also present in `KNOWN_EVENT_TYPES` above for the registry
+// test in `tests/event-types-registry.test.ts`.
+
+/** Event type emitted when a peer-CLI delegation starts. See `PeerCallStartedEvent`. */
+export const PEER_CALL_STARTED = 'peer_call_started' as const;
+/** Event type emitted when a peer-CLI delegation succeeds. See `PeerCallCompleteEvent`. */
+export const PEER_CALL_COMPLETE = 'peer_call_complete' as const;
+/** Event type emitted when a peer-CLI delegation fails (D-07: transparent fallback). See `PeerCallFailedEvent`. */
+export const PEER_CALL_FAILED = 'peer_call_failed' as const;
+
+/**
+ * Frozen set of all three peer-call event names. Convenient for
+ * downstream code that wants to gate "is this a peer-call event?" checks
+ * (e.g. the cost-aggregator's mixed-role roll-up).
+ */
+export const PEER_CALL_EVENT_TYPES: readonly string[] = [
+  PEER_CALL_STARTED,
+  PEER_CALL_COMPLETE,
+  PEER_CALL_FAILED,
 ] as const;
+
+/**
+ * Default runtime-role tag for events that pre-date Phase 27. Readers
+ * SHOULD substitute this when `payload.runtime_role` is absent so legacy
+ * event-stream consumers continue to read uniformly. Stamping at write
+ * time on every emission would be a much larger surface change — see
+ * Plan 27-08 deviation notes for rationale.
+ */
+export const DEFAULT_RUNTIME_ROLE: RuntimeRole = 'host';

package/scripts/lib/install/runtimes.cjs

@@ -50,6 +50,8 @@ const RUNTIMES = Object.freeze([
     configDirFallback: '.gemini',
     kind: 'agents-md',
     files: ['GEMINI.md'],
+    // Phase 27 (Plan 27-11): peer-CLI delegation binary, ACP protocol.
+    peerBinary: process.platform === 'win32' ? 'gemini.cmd' : 'gemini',
   },
   {
     id: 'kilo',
@@ -66,6 +68,8 @@ const RUNTIMES = Object.freeze([
     configDirFallback: '.codex',
     kind: 'agents-md',
     files: ['AGENTS.md'],
+    // Phase 27 (Plan 27-11): peer-CLI delegation binary, ASP protocol.
+    peerBinary: process.platform === 'win32' ? 'codex.cmd' : 'codex',
   },
   {
     id: 'copilot',
@@ -74,6 +78,8 @@ const RUNTIMES = Object.freeze([
     configDirFallback: '.copilot',
     kind: 'agents-md',
     files: ['AGENTS.md'],
+    // Phase 27 (Plan 27-11): peer-CLI delegation binary, ACP protocol.
+    peerBinary: process.platform === 'win32' ? 'copilot.cmd' : 'copilot',
   },
   {
     id: 'cursor',
@@ -82,6 +88,8 @@ const RUNTIMES = Object.freeze([
     configDirFallback: '.cursor',
     kind: 'agents-md',
     files: ['AGENTS.md'],
+    // Phase 27 (Plan 27-11): peer-CLI delegation binary, ACP protocol.
+    peerBinary: process.platform === 'win32' ? 'cursor-agent.cmd' : 'cursor-agent',
   },
   {
     id: 'windsurf',
@@ -122,6 +130,8 @@ const RUNTIMES = Object.freeze([
     configDirFallback: '.qwen',
     kind: 'agents-md',
     files: ['AGENTS.md'],
+    // Phase 27 (Plan 27-11): peer-CLI delegation binary, ACP protocol.
+    peerBinary: process.platform === 'win32' ? 'qwen.cmd' : 'qwen',
   },
   {
     id: 'codebuddy',
@@ -202,6 +212,52 @@ function _resetRuntimeModelsCache() {
   _modelsCache.clear();
 }
 
+// Phase 27 (Plan 27-11) — peer-CLI detection helpers.
+//
+// `listPeerCapableRuntimes()` returns the entries that carry a `peerBinary`
+// field — the 5 runtimes that gdd can DELEGATE to (codex, gemini, cursor,
+// copilot, qwen). The other 9 runtimes (claude, opencode, kilo, windsurf,
+// antigravity, augment, trae, codebuddy, cline) are install targets only.
+//
+// `detectInstalledPeers({ which? })` checks each peer-capable runtime's
+// `peerBinary` against the system PATH and returns the IDs of the peers
+// that are installed locally. The `which` parameter is injectable for
+// tests — the production caller passes a real `which`/`where` shim.
+
+function listPeerCapableRuntimes() {
+  return RUNTIMES.filter((r) => typeof r.peerBinary === 'string');
+}
+
+function detectInstalledPeers(opts) {
+  const opts2 = opts || {};
+  const whichFn = opts2.which || _defaultWhich;
+  const detected = [];
+  for (const r of listPeerCapableRuntimes()) {
+    try {
+      if (whichFn(r.peerBinary)) {
+        detected.push(r.id);
+      }
+    } catch (_e) {
+      // ENOENT / non-zero exit = not installed; never throw.
+    }
+  }
+  return detected;
+}
+
+function _defaultWhich(binary) {
+  const { execSync } = require('node:child_process');
+  const cmd = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const out = execSync(`${cmd} ${binary}`, {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+    }).trim();
+    return out.length > 0 ? out.split(/\r?\n/)[0] : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
 module.exports = {
   RUNTIMES,
   REPO,
@@ -211,5 +267,7 @@ module.exports = {
   listRuntimes,
   listRuntimeIds,
   getRuntimeModels,
+  listPeerCapableRuntimes,
+  detectInstalledPeers,
   _resetRuntimeModelsCache,
 };