@aiwuk/team 0.0.0-stage → 5.0.8

package/package.json

@@ -1,6 +1,157 @@
 {
   "name": "@aiwuk/team",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "5.0.8",
+  "description": "AIWUK Team, a capability-routed multi-agent team preset for DeepSeek Harness (DSH) with per-role model routing, same-tier failover and conversational team configuration",
+  "license": "MIT",
+  "author": "walke2019",
+  "homepage": "https://github.com/walke2019/dsh-capability-team#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/walke2019/dsh-capability-team.git" },
+  "bugs": { "url": "https://github.com/walke2019/dsh-capability-team/issues" },
+  "keywords": ["aiwuk", "dsh", "dsh-plugin", "deepseek-harness", "cordis", "agent-team", "multi-agent", "model-routing", "failover", "ai-agent", "llm"],
+  "engines": { "node": ">=24.9", "dsh": ">=0.2.2-rc.1 <0.3.0" },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.1",
+    "@deepseek-ai/dsh-agent-preset": ">=0.2.2-rc.1",
+    "@deepseek-ai/dsh-persona": ">=0.2.2-rc.1",
+    "@deepseek-ai/dsh-experimental-agent-team": ">=0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": ">=0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": ">=0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-tool": ">=0.2.2-rc.1",
+    "@deepseek-ai/dsh-api-remotes": ">=0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": ">=0.2.2-rc.1",
+    "@deepseek-ai/schemastery": ">=3.18.4"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": { "optional": true },
+    "@deepseek-ai/dsh-agent-preset": { "optional": true },
+    "@deepseek-ai/dsh-persona": { "optional": true },
+    "@deepseek-ai/dsh-experimental-agent-team": { "optional": true },
+    "@deepseek-ai/dsh-client-locale": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-conversation": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-tool": { "optional": true },
+    "@deepseek-ai/dsh-api-remotes": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-sidebar-right": { "optional": true },
+    "@deepseek-ai/schemastery": { "optional": true }
+  },
+  "type": "module",
+  "scripts": {
+    "build:client": "node shared-ui/build.mjs && node scripts/build-client.mjs",
+    "pretest": "node shared-ui/build.mjs && node scripts/build-client.mjs && node packages/global-memory/scripts/build-shared.mjs && node packages/omni-search/scripts/build-shared.mjs && node packages/autocomplete/scripts/build-client.mjs",
+    "prepack": "node shared-ui/build.mjs && node scripts/build-client.mjs",
+    "test": "node --import ./tests/isolated-home.mjs --test tests/*.test.mjs && node --import ./tests/isolated-home.mjs --test tests/global-memory/*.test.mjs && node --import ./tests/isolated-home.mjs --test tests/omni-search/*.test.mjs && node --import ./tests/isolated-home.mjs --test tests/autocomplete/*.test.mjs",
+    "build:global-memory": "node packages/global-memory/scripts/build-shared.mjs",
+    "build:omni-search": "node packages/omni-search/scripts/build-shared.mjs",
+    "build:autocomplete": "node packages/autocomplete/scripts/build-client.mjs",
+    "lint": "node scripts/check.mjs syntax",
+    "build": "node scripts/check.mjs package"
+  },
+  "exports": {
+    ".": "./ui.js",
+    "./client": "./client.js",
+    "./roles": "./index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./i18n/*.json": "./i18n/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "brand.js",
+    "i18n.js",
+    "roles.js",
+    "member-models.js",
+    "lead-route.js",
+    "config.js",
+    "roster-defaults.js",
+    "single-model.js",
+    "onboarding.js",
+    "settings-schema.js",
+    "team.js",
+    "failover.js",
+    "defaults.js",
+    "index.js",
+    "free-worker.mjs",
+    "integrations.js",
+    "search.js",
+    "search-engines.js",
+    "transcribe.js",
+    "task-bridge.js",
+    "theme.js",
+    "allocation.js",
+    "theme-plugin.js",
+    "tool-schema.js",
+    "tool-names.js",
+    "workflow.js",
+    "opencode.js",
+    "ui.js",
+    "runtime-view.js",
+    "model-policy.js",
+    "access.js",
+    "teammate-wait.js",
+    "usage.js",
+    "long-context.js",
+    "plan-gate.js",
+    "template.js",
+    "config-projection.js",
+    "session-policy.js",
+    "request-evidence.js",
+    "activity-summary.js",
+    "observability-projection.js",
+    "runtime-observability.js",
+    "observability-api.js",
+    "member-task-control.js",
+    "task-control-audit.js",
+    "task-control-api.js",
+    "client.js",
+    "client/*.js",
+    "file-limits.js",
+    "dispatch-confirm.js",
+    "dispatch-routes-store.js",
+    "session-rotation.js",
+    "memory-embed.js",
+    "memory-store.js",
+    "memory-hub.js",
+    "memory-openviking.js",
+    "memory-backends.js",
+    "preset-guard.js",
+    "token-metrics.js",
+    "memory-sync-queue.js",
+    "memory-redact.js",
+    "integrations-config.js",
+    "integrations-messages.js",
+    "managed-resolve.js",
+    "managed-ref.js",
+    "managed-config-route.js",
+    "shared/managed-config.js",
+    "http-guard.js",
+    "model-prefs.js",
+    "board-dispatch.js",
+    "teammate-context.js",
+    "token-discipline.js",
+    "route-health.js",
+    "skills/project-role-theme/SKILL.md",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "scripts/memory-cli.mjs",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "i18n/*.json",
+    "icon.svg"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-tool",
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-ui-sidebar-right"
+      ]
+    }
+  }
+}

package/plan-gate.js

@@ -0,0 +1,92 @@
+import { m as modelText } from './i18n.js';
+// Plan-first teammates: a capability with `planFirst` submits a plan to the Lead and waits for approval before it may
+// run execution tools. A new dispatch plan that assigns the role asks for a fresh plan, so one approval covers one task.
+import { params } from './tool-schema.js';
+import { ownsCapabilityTeam } from './preset-guard.js';
+import { resolveRole } from './config.js';
+import { toolClass } from './workflow.js';
+export const SUBMIT_TOOL = 'capability_submit_plan';
+export const REVIEW_TOOL = 'capability_review_plan';
+const output = { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] };
+const STATUS = { pending: modelText('plan-gate.324'), approved: modelText('plan-gate.325'), rejected: modelText('plan-gate.326') };
+function text(value, max, label) {
+  if (typeof value !== 'string' || !value.trim() || value.length > max) throw new Error(modelText('plan-gate.327', { 0: label, 1: max }));
+  return value.trim();
+}
+/** Pure decision for one teammate call under plan-first; returns a denial reason or undefined. */
+export function planDenial(exec, role, plan, workflow) {
+  if (!role.planFirst || exec.name === SUBMIT_TOOL || plan?.status === 'approved') return undefined;
+  const kind = toolClass(exec.name, workflow);
+  if (kind === 'analysis' || kind === 'coordination') return undefined;
+  const state = plan ? modelText('plan-gate.328', { 0: STATUS[plan.status], 1: plan.feedback ? modelText('plan-gate.329', { 0: plan.feedback }) : '' }) : modelText('plan-gate.330');
+  return modelText('plan-gate.331', { 0: role.displayName, 1: role.capability, 2: SUBMIT_TOOL, 3: exec.name, 4: state });
+}
+export function createPlanGate(ctx, team) {
+  const plans = new Map(); // `${teamId}:${role}` → { status, plan, feedback?, at }
+  const keyOf = (membership, role = membership.name) => `${membership.id}:${role}`;
+  const roleOf = (agent, membership) => {
+    const project = team.pinned(agent);
+    const effective = project ? team.loadSync(project, agent).effective : team.base;
+    return { role: resolveRole(membership, effective), effective };
+  };
+  return {
+    plans,
+    /** Model-facing plan state for a teammate's own context, or undefined when its capability is not plan-first. */
+    status(agent, membership, role) {
+      if (!role?.planFirst || membership?.role !== 'teammate') return undefined;
+      const plan = plans.get(keyOf(membership));
+      return plan ? `${STATUS[plan.status]}${plan.feedback ? modelText('plan-gate.332', { 0: plan.feedback }) : ''}` : modelText('plan-gate.333', { 0: SUBMIT_TOOL });
+    },
+    /** The Lead assigned these roles in a new dispatch plan: earlier approvals do not cover the new task. */
+    reset(leadMembership, roles) {
+      for (const role of roles) plans.delete(keyOf(leadMembership, role));
+    },
+    guard(exec) {
+      const membership = ctx.agentTeams.tryMembership(exec.agent);
+      if (!ownsCapabilityTeam(ctx, exec.agent) || membership?.role !== 'teammate') return undefined;
+      let resolved;
+      try { resolved = roleOf(exec.agent, membership); } catch { return undefined; } // Routing and the access guard report config errors.
+      return planDenial(exec, resolved.role, plans.get(keyOf(membership)), resolved.effective.workflow);
+    },
+    register() {
+      ctx.effect(() => ctx.tools.guard(exec => this.guard(exec)));
+      ctx.effect(() => ctx.tools.register({ name: SUBMIT_TOOL, output,
+        description: modelText('plan-gate.334'),
+        parameters: params({ plan: { type: 'string', description: modelText('plan-gate.335') } }, ['plan']),
+        async execute(args, exec) {
+          const membership = ctx.agentTeams.membership(exec.agent);
+          if (membership.role !== 'teammate') throw new Error(modelText('plan-gate.336'));
+          const { role } = roleOf(exec.agent, membership);
+          if (!role.planFirst) throw new Error(modelText('plan-gate.337', { 0: role.displayName }));
+          const plan = text(args.plan, 8000, modelText('plan-gate.338'));
+          plans.set(keyOf(membership), { status: 'pending', plan, at: Date.now() });
+          await ctx.agentTeams.sendMessage(exec.agent, { target: 'lead', signal: exec.signal, content: [{ type: 'text',
+            text: modelText('plan-gate.339', { 0: role.displayName, 1: membership.name, 2: REVIEW_TOOL, 3: membership.name, 4: plan }) }] });
+          return modelText('plan-gate.340', { 0: STATUS.pending });
+        },
+      }));
+      ctx.effect(() => ctx.tools.register({ name: REVIEW_TOOL, output,
+        description: modelText('plan-gate.341'),
+        parameters: params({
+          role: { type: 'string', description: modelText('plan-gate.342') },
+          approve: { type: 'boolean', description: modelText('plan-gate.343') },
+          feedback: { type: 'string', description: modelText('plan-gate.344') },
+        }, ['role', 'approve']),
+        async execute(args, exec) {
+          const membership = ctx.agentTeams.membership(exec.agent);
+          if (membership.role !== 'lead') throw new Error(modelText('plan-gate.345'));
+          const role = text(args.role, 64, modelText('plan-gate.346'));
+          const plan = plans.get(keyOf(membership, role));
+          if (!plan || plan.status !== 'pending') throw new Error(modelText('plan-gate.347', { 0: role }));
+          if (args.approve !== true && args.approve !== false) throw new Error(modelText('plan-gate.348'));
+          const feedback = args.feedback === undefined || args.feedback === '' ? undefined : text(args.feedback, 2000, modelText('plan-gate.349'));
+          if (!args.approve && !feedback) throw new Error(modelText('plan-gate.350'));
+          plans.set(keyOf(membership, role), { ...plan, status: args.approve ? 'approved' : 'rejected', feedback, at: Date.now() });
+          await ctx.agentTeams.sendMessage(exec.agent, { target: role, signal: exec.signal, content: [{ type: 'text',
+            text: args.approve ? modelText('plan-gate.351', { 0: feedback ? modelText('plan-gate.352', { 0: feedback }) : '' }) : modelText('plan-gate.353', { 0: SUBMIT_TOOL, 1: feedback }) }] });
+          return modelText('plan-gate.354', { 0: args.approve ? modelText('plan-gate.355') : modelText('plan-gate.356'), 1: role });
+        },
+      }));
+    },
+  };
+}

package/preset-guard.js

@@ -0,0 +1,47 @@
+// Fail closed: native team membership alone does not identify this preset.
+export const CAPABILITY_PRESET = 'capability-team';
+// A service missing from the caller's `inject` throws on direct property access in cordis; ctx.get() does not.
+const service = (ctx, name) => { try { const direct = ctx[name]; if (direct) return direct; } catch { /* not injected */ } try { return ctx.get?.(name); } catch { return undefined; } };
+export function ownsCapabilityTeam(ctx, agent) {
+  if (!agent) return false;
+  try {
+    const membership = service(ctx, 'agentTeams')?.tryMembership(agent);
+    const owner = membership?.root ?? agent;
+    const presets = service(ctx, 'agentPresets');
+    return presets?.composedPreset(owner.ctx) === CAPABILITY_PRESET;
+  } catch { return false; }
+}
+export function capabilitySession(ctx, session) {
+  try { return ownsCapabilityTeam(ctx, ctx.agents?.get(session?.id)); }
+  catch { return false; }
+}
+export function isolatedProjection(ctx, definition) {
+  const owns = header => {
+    // DSH's own SessionHeader.agentPreset decides first. The live Agent is only a fallback for headers without it:
+    // a projection can initialise before the Agent's preset is composed, and that early "not ours" used to stick
+    // for the whole session, leaving usage, activity and report empty for real capability-team sessions.
+    const recorded = header?.agentPreset ?? header?.preset;
+    if (recorded !== undefined) return recorded === CAPABILITY_PRESET;
+    try {
+      const agent = ctx.agents?.get(header?.id ?? header?.sessionId);
+      return agent ? ownsCapabilityTeam(ctx, agent) : false;
+    } catch { return false; }
+  };
+  // +2: checkpoints written by the earlier decision are discarded and refolded from the session log.
+  return { ...definition, stateVersion: definition.stateVersion + 2,
+    init(header, inherited) {
+      const state = definition.init(header, inherited);
+      return { ...state, capabilityPreset: owns(header) };
+    },
+    apply(state, event) {
+      // A blank session may switch preset before its first turn: re-decide from the committed selection.
+      if (event?.type === 'agent-preset/selected') {
+        const owned = event.data?.agentPreset === CAPABILITY_PRESET;
+        if (owned !== state.capabilityPreset) return { ...state, capabilityPreset: owned };
+      }
+      if (!state.capabilityPreset) return state;
+      return { ...definition.apply(state, event), capabilityPreset: true };
+    },
+    wire: { ...definition.wire, view: state => definition.wire.view(state.capabilityPreset ? state : definition.init()) },
+  };
+}

package/request-evidence.js

@@ -0,0 +1,41 @@
+import { m as modelText } from './i18n.js';
+// Extract only recorded model identities, never prompt/content/replayState.
+// Request headers prove configuration admission, not successful provider completion.
+import { foldUsage } from './usage.js';
+export function requestEvidence(snapshot, limit = 30) {
+  const inherited = snapshot.inheritedEventCount ?? 0;
+  const result = [];
+  for (let i = snapshot.events.length - 1; i >= inherited && result.length < limit; i--) {
+    const event = snapshot.events[i];
+    let source, evidence;
+    if (event.type === 'request/header') { source = event.data?.header?.config; evidence = 'request-header'; }
+    else if (event.type === 'assistant/message') { source = event.data?.message?.source; evidence = 'assistant-message'; }
+    if (typeof source?.provider !== 'string' || typeof source?.model !== 'string') continue;
+    result.push({ seq: event.seq, time: event.time, provider: source.provider, model: source.model, evidence,
+      ...(event.data?.interrupted ? { interrupted: true } : {}) });
+  }
+  return result;
+}
+export async function readTeamEvidence(query, teams, agent) {
+  let members;
+  try { members = teams ? teams.listMembers(agent) : [{ id: agent.id, name: 'lead' }]; }
+  catch (error) {
+    return [{ sessionId: agent.id, name: 'lead', ...await readRequestEvidence(query, agent.id),
+      unavailable: modelText('request-evidence.357', { 0: error.message ?? error }) }];
+  }
+  const result = [];
+  // Deliberately sequential: bound peak log memory to one member at a time.
+  for (const member of members) {
+    result.push({ sessionId: member.id, name: member.name, inheritedModel: member.model ?? null,
+      ...await readRequestEvidence(query, member.id) });
+  }
+  return result;
+}
+export async function readRequestEvidence(query, sessionId) {
+  if (!query) return { records: [], unavailable: modelText('request-evidence.358') };
+  try {
+    const snapshot = await query.readSession(sessionId);
+    return { records: requestEvidence(snapshot), usage: foldUsage(snapshot) };
+  }
+  catch (error) { return { records: [], unavailable: String(error.message ?? error) }; }
+}

package/roles.js

@@ -0,0 +1,105 @@
+import { m as modelText, roleText } from './i18n.js';
+import { allocatedRequest } from './allocation.js';
+import { followUserChoice, leadRequest } from './lead-route.js';
+import { budgetDenial, sessionUsage } from './usage.js';
+import { createLongContext, promptTokens } from './long-context.js';
+import { ensurePreset } from './access.js';
+import { bindRuntime } from './runtime-observability.js';
+import { FILE_LIMITS, fileLimitRules } from './file-limits.js';
+import { TOKEN_RULES, tokenRuleText } from './token-discipline.js';
+// `allowed` is the free list resolved from OpenCode's catalog (opencode.js); nothing is fixed here.
+export function freeArgs(prompt, model, allowed = []) {
+  if (typeof model !== 'string' || !allowed.includes(model)) throw new Error(modelText('roles.359'));
+  if (typeof prompt !== 'string' || !prompt.trim() || prompt.length > 16000) throw new Error(modelText('roles.360'));
+  return ['run', '--format', 'json', '--model', model, '--', prompt];
+}
+// Static rules hold no role names, models or tiers: those come from the per-Agent team context.
+export const policy = roleText('roles.361', { 0: fileLimitRules(FILE_LIMITS), 1: tokenRuleText(TOKEN_RULES) });
+/**
+ * Route every model request by the native Team identity.
+ * The loop re-runs agent/request for each retry, so the failover state picks the attempt's route.
+ */
+export function apply(ctx, team, failover, observability, taskControl) {
+  const installed = new WeakSet();
+  const installPolicy = agent => {
+    if (!team.owns(agent) || installed.has(agent)) return;
+    installed.add(agent);
+    agent.ctx.systemPrompt.context({ name: 'capability-team:policy', order: 95, text: () => team.owns(agent) ? policy : '' });
+  };
+  ctx.on('agent/created', async ({ agent }) => { installPolicy(agent); await preselect(ctx, team, failover, agent); });
+  for (const agent of ctx.agents?.list?.() ?? []) installPolicy(agent);
+  const longContext = createLongContext();
+  const hadOverride = new WeakSet();
+  ctx.on('agent/request', async ({ agent, turn, step }, next) => {
+    const previous = await next();
+    if (!team.owns(agent)) return previous;
+    const resolved = await team.resolve(agent);
+    const lead = ctx.agentTeams?.tryMembership?.(agent)?.role === 'lead';
+    const { leadContext, ...configuredRole } = resolved;
+    // The Lead uses the model the user picked in the conversation; teammates are routed strictly by role.
+    const role = lead ? followUserChoice(configuredRole, previous, leadContext) : configuredRole;
+    if (role.userChoiceRejected) ctx.logger?.warn?.(modelText('roles.362', { 0: role.userChoiceRejected }));
+    // Fail closed: silently inheriting the Lead model defeats capability tiers and hides misconfiguration.
+    if (role.unassigned) throw new Error(modelText('roles.363', { 0: role.displayName ?? role.id, 1: role.capability }));
+    // DSH's own sandbox preset for read-only roles; re-checked every request so config edits take effect.
+    ensurePreset(ctx.get?.('permissionPresets'), agent.session, role.access, message => ctx.logger?.warn?.(`capability-team: ${message}`));
+    const projections = ctx.get?.('sessionProjections');
+    const overBudget = budgetDenial(role, sessionUsage(projections, agent.session));
+    if (overBudget) throw new Error(overBudget);
+    const controlled = taskControl ? await taskControl.route(agent, role) : role;
+    if (hadOverride.has(agent) && !controlled.taskLeaseSignature) { longContext.reset(agent.session); hadOverride.delete(agent); }
+    if (controlled.taskLeaseSignature) hadOverride.add(agent);
+    const routed = controlled.taskLeaseSignature ? controlled : longContext.apply(agent.session, controlled, promptTokens(projections, agent.session));
+    // Always explicit: the loop pins the last logged header, so the primary must be restored by name.
+    const selected = failover.route(agent, turn, step, routed);
+    if (observability) {
+      try {
+        bindRuntime(agent, observability, ctx.agentTeams);
+        observability.request(agent, { turn, step, role, routed, selected });
+      } catch { /* telemetry must never change model selection */ }
+    }
+    // DSH fixes provider/model before step preparation; a different route can only take effect from the next step.
+    if (agent.model?.select && !sameRoute(previous, selected)) {
+      agent.model.select({ provider: selected.provider, model: selected.model });
+      ctx.logger?.info?.(`capability-team: ${previous.provider}/${previous.model} -> ${selected.provider}/${selected.model} from the next step`);
+      return previous;
+    }
+    if (agent.model?.select) return (lead && leadRequest(previous, selected)) || keepEffort(previous, allocatedRequest(previous, selected));
+    return (lead && leadRequest(previous, selected)) || allocatedRequest(previous, selected);
+  });
+  ctx.on('agent/request-error', async ({ agent, failure, signal }, next) => {
+    const downstream = await next(); // DSH provider retry policy keeps priority.
+    if (team.owns(agent)) { try { observability?.failure(agent, failure); } catch { /* read-only telemetry */ } }
+    if (downstream?.kind === 'retry' || !team.owns(agent)) return downstream;
+    const before = failover.status(agent)?.active;
+    if (!(await failover.recover(agent, failure, signal))) return undefined;
+    const after = failover.status(agent)?.active;
+    // A retry reuses the step's fixed route, so a switch is recorded for the next step instead of retried here.
+    if (agent.model?.select && after && after !== before) {
+      const slash = after.indexOf('/');
+      agent.model.select({ provider: after.slice(0, slash), model: after.slice(slash + 1) });
+      return undefined;
+    }
+    return { kind: 'retry' };
+  });
+}
+const sameRoute = (a, b) => a?.provider === b?.provider && a?.model === b?.model;
+/** Same route as the step's selection: its reasoning effort is part of the fixed selection and must be kept. */
+function keepEffort(previous, request) {
+  return previous.reasoningEffort === undefined ? request : { ...request, reasoningEffort: previous.reasoningEffort };
+}
+/**
+ * Select a teammate's role route when it is created, before its first step fixes a model. Without this the
+ * teammate starts on the inherited Lead model and DSH rejects the per-role route in agent/request.
+ */
+export async function preselect(ctx, team, failover, agent) {
+  try {
+    if (!agent?.model?.select || !team.owns(agent) || ctx.agentTeams?.tryMembership?.(agent)?.role !== 'teammate') return;
+    const role = await team.resolve(agent);
+    if (role.unassigned || !role.provider) return; // agent/request fails closed with guidance
+    const route = failover.route(agent, 0, 0, role);
+    if (!sameRoute(agent.model.current?.(), route)) agent.model.select({ provider: route.provider, model: route.model });
+  } catch (error) {
+    ctx.logger?.warn?.(`capability-team: route preselection failed: ${String(error?.message ?? error)}`);
+  }
+}

package/roster-defaults.js

@@ -0,0 +1,70 @@
+import { roleText, m as modelText } from './i18n.js';
+// Built-in role rosters. The neutral roster is the default; "three-kingdoms" is an optional skin applied
+// per project through capability_team_import { theme }. Projects saved before 4.0 keep their hero roster.
+const isMap = v => !!v && typeof v === 'object' && !Array.isArray(v);
+const frozen = roles => Object.freeze(Object.fromEntries(Object.entries(roles).map(([id, r]) => [id, Object.freeze(r)])));
+/** Neutral default roster (English display names; the Web client localizes untouched defaults). */
+export const DEFAULT_ROLES = frozen({
+  lead: { displayName: 'Lead', capability: 'orchestrator' },
+  architect: { displayName: 'Architect', capability: 'technical-director' },
+  backend: { displayName: 'Backend', capability: 'backend' },
+  frontend: { displayName: 'Frontend', capability: 'frontend' },
+  researcher: { displayName: 'Researcher', capability: 'research' },
+  writer: { displayName: 'Writer', capability: 'writer' },
+  qa: { displayName: 'QA', capability: 'qa' },
+});
+/** The pre-4.0 default roster, kept as the optional "three-kingdoms" theme. */
+export const THREE_KINGDOMS_ROLES = frozen({
+  lead: { displayName: roleText('roster-defaults.364'), capability: 'orchestrator' },
+  'zhuge-liang': { displayName: roleText('roster-defaults.365'), capability: 'technical-director' },
+  'lv-bu': { displayName: roleText('roster-defaults.366'), capability: 'backend' },
+  'diao-chan': { displayName: roleText('roster-defaults.367'), capability: 'frontend' },
+  'zhao-yun': { displayName: roleText('roster-defaults.368'), capability: 'research' },
+  'chen-lin': { displayName: roleText('roster-defaults.369'), capability: 'writer' },
+  'zhou-yu': { displayName: roleText('roster-defaults.370'), capability: 'qa' },
+});
+export const ROLE_THEMES = Object.freeze({ default: DEFAULT_ROLES, 'three-kingdoms': THREE_KINGDOMS_ROLES });
+/** Hero id → neutral id with the same capability; lets members spawned under the old roster keep routing. */
+export const LEGACY_ROLE_ALIASES = Object.freeze({ 'zhuge-liang': 'architect', 'lv-bu': 'backend', 'diao-chan': 'frontend', 'zhao-yun': 'researcher', 'chen-lin': 'writer', 'zhou-yu': 'qa' });
+const sameRole = (a, b) => isMap(a) && isMap(b) && a.displayName === b.displayName && a.capability === b.capability && a.description === b.description;
+/** Stored-override marker written by 4.0+: such files are never read against the old hero default. */
+export const ROSTER_MARK = 2;
+/**
+ * True for overrides saved before 4.0 against the hero default: no marker (every 4.0+ save writes one), and a hero id
+ * the base lacks is stored, whether as a partial rename, a deletion (null) or a complete role from a 3.x template.
+ * Such a file was written on top of the hero roster, so mixing it into the neutral default would duplicate roles.
+ */
+export function isLegacyRoster(baseRoles = {}, overrides = {}) {
+  if (overrides.roster === ROSTER_MARK) return false;
+  return Object.keys(overrides.roles ?? {}).some(id => Object.hasOwn(LEGACY_ROLE_ALIASES, id) && !Object.hasOwn(baseRoles, id));
+}
+/** Base roles for one project's stored overrides: a pre-4.0 save keeps the hero roster (neutral defaults it never saw are dropped). */
+export function rosterBase(baseRoles = {}, overrides = {}) {
+  if (!isLegacyRoster(baseRoles, overrides)) return baseRoles;
+  const kept = Object.entries(baseRoles).filter(([id, r]) => !(Object.hasOwn(DEFAULT_ROLES, id) && sameRole(r, DEFAULT_ROLES[id])));
+  return { ...Object.fromEntries(kept), ...THREE_KINGDOMS_ROLES };
+}
+/**
+ * Overrides to store after a save: marked as 4.0+. A legacy project's roster is written out explicitly on its first
+ * save (base-only roles stored as null), so later loads no longer depend on guessing.
+ */
+export function pinRoster(next, previous, baseRoles = {}) {
+  if (!isLegacyRoster(baseRoles, previous)) return { ...next, roster: ROSTER_MARK };
+  const roles = Object.fromEntries(Object.keys(baseRoles).map(id => [id, null]));
+  for (const [id, r] of Object.entries(rosterBase(baseRoles, previous))) roles[id] = { ...r };
+  for (const [id, r] of Object.entries(next.roles ?? {})) roles[id] = r === null ? null : isMap(r) && isMap(roles[id]) ? { ...roles[id], ...r } : r;
+  return { ...next, roles, roster: ROSTER_MARK };
+}
+/** Role id a member name resolves to when the roster lacks it: a legacy hero name maps to its neutral role. */
+export function legacyRoleId(name, roles) {
+  const alias = LEGACY_ROLE_ALIASES[name];
+  return alias && !Object.hasOwn(roles, name) && Object.hasOwn(roles, alias) ? alias : undefined;
+}
+/** Save patch that replaces the project's roster with a built-in theme; other roles are removed, per-role descriptions kept. */
+export function themePatch(theme, current) {
+  const roles = Object.hasOwn(ROLE_THEMES, theme) ? ROLE_THEMES[theme] : undefined;
+  if (!roles) throw new Error(modelText('roster-defaults.371', { 0: theme, 1: Object.keys(ROLE_THEMES).join(' / ') }));
+  const patch = Object.fromEntries(Object.entries(roles).map(([id, r]) => [id, { ...r }]));
+  for (const id of Object.keys(current.roles ?? {})) if (!Object.hasOwn(patch, id)) patch[id] = false;
+  return { roles: patch };
+}

package/route-health.js

@@ -0,0 +1,39 @@
+// Route failures that outlive a DSH restart. The failover layer keeps cooldowns in memory, so after a restart
+// a route with a dead key looked healthy again and could even be preselected as a habit. Failures are kept
+// here: credential errors (the key is wrong until someone fixes it) for a day, other failures for an hour.
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+export const CREDENTIAL_CODES = new Set(['AUTH', 'INVALID_CREDENTIAL', 'MISSING_CREDENTIAL']);
+export const KEEP_MS = { credential: 24 * 3600_000, other: 3600_000 };
+/** Whether a failure means the route's key is wrong or missing (it stays bad until someone fixes it). */
+export const isCredential = (code, status) => CREDENTIAL_CODES.has(code) || status === 401 || status === 403;
+export function createRouteHealth(root, { now = Date.now } = {}) {
+  const path = join(root, 'route-health.json');
+  let data;
+  const load = () => {
+    if (data) return data;
+    try { data = JSON.parse(readFileSync(path, 'utf8')); } catch { data = {}; }
+    return data;
+  };
+  const save = () => {
+    try { mkdirSync(root, { recursive: true }); const temp = `${path}.${process.pid}.tmp`; writeFileSync(temp, JSON.stringify(data)); renameSync(temp, path); } catch { /* best effort */ }
+  };
+  const alive = (entry, at) => at - entry.lastFailureAt < (entry.credential ? KEEP_MS.credential : KEEP_MS.other);
+  return {
+    /** Failover telemetry: remember each cooldown with its error class. */
+    record(event) {
+      if (event?.kind !== 'cooldown' || !event.route) return;
+      const key = `${event.route.provider}/${event.route.model}`;
+      load()[key] = { strikes: event.strikes ?? 1, lastFailureAt: now(), code: event.code ?? null, credential: isCredential(event.code, event.status) };
+      for (const [k, v] of Object.entries(data)) if (!alive(v, now())) delete data[k];
+      save();
+    },
+    /** Recent failures, in the same shape as failover.health(). */
+    recent() {
+      const at = now();
+      return Object.fromEntries(Object.entries(load()).filter(([, v]) => alive(v, at)).map(([k, v]) => [k, { strikes: v.strikes, lastFailureAt: v.lastFailureAt, cooling: false, credential: v.credential }]));
+    },
+  };
+}
+/** Persisted failures merged with the live failover state (live state wins). */
+export const mergeHealth = (persisted, live) => ({ ...persisted, ...live });

package/runtime-observability.js

@@ -0,0 +1,78 @@
+// Ephemeral routing telemetry: no prompt/error text and no persisted session events.
+import { randomUUID } from 'node:crypto';
+import { safeId, safeTime } from './activity-summary.js';
+import { taskControlSnapshot } from './member-task-control.js';
+const routeOf = r => r && typeof r.provider === 'string' && r.provider.length <= 128 && typeof r.model === 'string' && r.model.length <= 512 ? { provider: r.provider, model: r.model } : null;
+const same = (a, b) => a && b && a.provider === b.provider && a.model === b.model;
+const codeOf = c => safeId(c, 80);
+const statusOf = s => Number.isInteger(s) && s >= 100 && s <= 599 ? s : null;
+export function createRuntimeObservability({ now = Date.now, epoch = randomUUID() } = {}) {
+  const since = safeTime(now()) ?? 0;
+  const members = new Map(), listeners = new Set(), sharedCooling = new Map(); let revision = 0;
+  const changed = () => { revision += 1; for (const listener of listeners) { try { listener(); } catch { /* observation must not affect routing */ } } };
+  const get = agent => {
+    const id = safeId(agent?.id); if (!id) return null;
+    if (!members.has(id)) {
+      if (members.size >= 256) members.delete(members.keys().next().value);
+      members.set(id, { sessionId: id, candidates: [], cooling: [], switches: [], counters: { requestFailures: 0, pluginRetries: 0, failoverSwitches: 0, longContextSwitches: 0 }, attempt: 0, turn: null, step: null, active: null, lc: false, truncated: false });
+    }
+    return members.get(id);
+  };
+  const record = (m, from, to, reason, detail = {}) => {
+    if (!from || !to || same(from, to)) return;
+    const at = safeTime(now()) ?? 0;
+    m.switches.unshift({ id: `${epoch}:${revision + 1}:${m.sessionId}`, at, turn: m.turn, step: m.step, attempt: m.attempt, from, to, reason, code: codeOf(detail.code), status: statusOf(detail.status) });
+    if (m.switches.length > 16) { m.switches.length = 16; m.truncated = true; }
+    if (reason === 'failover' || reason === 'long-context') m.counters[reason === 'failover' ? 'failoverSwitches' : 'longContextSwitches'] += 1;
+  };
+  return {
+    epoch,
+    notifyTaskControl() { changed(); },
+    onChanged(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    request(agent, { turn, step, role, routed, selected }) {
+      const m = get(agent); if (!m) return;
+      const newStep = m.turn !== turn || m.step !== step;
+      m.attempt = !newStep ? m.attempt + 1 : 1;
+      m.turn = Number.isSafeInteger(turn) ? turn : null; m.step = Number.isSafeInteger(step) ? step : null;
+      m.candidates = [role, ...(role?.fallbacks ?? []), ...(role?.longContext ? [role.longContext] : [])].map(routeOf).filter(Boolean).slice(0, 32);
+      const active = routeOf(selected), lc = !!routed.longContextActive;
+      if (m.active && m.override !== (routed.taskLeaseSignature ?? null)) record(m, m.active, active, routed.taskLeaseSignature ? 'override' : 'override-expired');
+      m.override = routed.taskLeaseSignature ?? null;
+      if (m.active && !routed.taskLeaseSignature && lc !== m.lc) record(m, m.active, routeOf(routed), 'long-context');
+      const primary = routeOf(routed);
+      if (primary && active && !same(primary, active)) {
+        // recover already recorded a switch in this attempt; a new step skipping a cooled route has not.
+        if (m.active && newStep && (!m.pendingSwitch || !same(m.pendingSwitch, active))) record(m, primary, active, 'failover', [...sharedCooling.values()].find(c => same(c.route, primary)));
+      }
+      m.pendingSwitch = null; m.active = active; m.lc = lc; changed();
+    },
+    failure(agent, failure) { const m = get(agent); if (!m) return; m.counters.requestFailures += 1; changed(); },
+    telemetry(event) {
+      const m = get(event.agent); if (!m) return;
+      if (event.kind === 'retry') m.counters.pluginRetries += 1;
+      if (event.kind === 'cooldown') {
+        const route = routeOf(event.route); if (!route) return;
+        const cooldown = { route, code: codeOf(event.code), status: statusOf(event.status), until: safeTime(event.until), attempt: m.attempt };
+        // Shared cooldown is filtered by each member's confirmed candidates at snapshot time.
+        sharedCooling.set(JSON.stringify(route), cooldown);
+        if (sharedCooling.size > 256) sharedCooling.delete(sharedCooling.keys().next().value);
+      }
+      if (event.kind === 'switch') { const to = routeOf(event.to); record(m, routeOf(event.from), to, 'failover', event); m.pendingSwitch = to; }
+      changed();
+    },
+    snapshot(leadSessionId, roster) {
+      const result = [];
+      for (const member of roster.slice(0, 64)) {
+        const m = members.get(member.id);
+        const candidates = m?.candidates ?? [];
+        const cooling = [...sharedCooling.values()].filter(c => c.until > now() && candidates.some(r => same(c.route, r)));
+        result.push({ sessionId: member.id, cooling: cooling.slice(0, 16).map(c => ({ ...c, route: { ...c.route } })), switches: (m?.switches ?? []).map(s => ({ ...s, from: { ...s.from }, to: { ...s.to } })), counters: { ...(m?.counters ?? { requestFailures: 0, pluginRetries: 0, failoverSwitches: 0, longContextSwitches: 0 }) }, truncated: !!m?.truncated || cooling.length > 16 });
+      }
+      return { schemaVersion: 1, leadSessionId, epoch, revision, generatedAt: safeTime(now()) ?? 0, coverage: { mode: 'runtime', since }, members: result, taskControl: taskControlSnapshot(leadSessionId) };
+    },
+  };
+}
+// Kept outside session checkpoints. Bound to the exact live Agent identity.
+const runtimeBindings = new WeakMap();
+export function bindRuntime(agent, runtime, teams) { runtimeBindings.set(agent, { runtime, teams }); }
+export function runtimeBinding(agent) { return runtimeBindings.get(agent); }