@ludi-uni/ludi-agent-kit 0.1.0 → 0.1.1

package/README.md

@@ -77,7 +77,8 @@ Requirements for local validation: Windows, PowerShell 7, Git and Node.js with `
 ## Executable path (Phase 2)
 
 ```powershell
-Copy-Item adapters/pi/models.local.example.json adapters/pi/models.local.json   # then edit with `pi --list-models` ids
+New-Item -ItemType Directory -Force "$HOME/.pi/agent/ludi-agent-kit" | Out-Null
+Copy-Item adapters/pi/models.local.example.json "$HOME/.pi/agent/ludi-agent-kit/models.local.json"  # edit with `pi --list-models` ids; use $env:PI_CODING_AGENT_DIR/ludi-agent-kit if set
 node scripts/resolve-capabilities.mjs                                            # chains + out/settings.proposal.json
 node scripts/run-pipeline.mjs --repo <fixture-copy> --task "Fix the failing test" --dry-run
 node scripts/run-pipeline.mjs --repo <fixture-copy> --task "Fix the failing test"           # real: scout -> pack -> coder -> tests
@@ -90,7 +91,7 @@ never the same modelId twice, failures appended to `previous_attempts`. See `doc
 
 ## Orchestration and safety
 
-`node scripts/orchestrate.mjs --dry-run "<request>"` previews a rules-based plan without launching agents. A live invocation can call external models and consume quota; review the plan, model availability and `docs/orchestrator.md` before using it. `sync-pi.ps1` is dry-run by default; `-Apply` writes to the chosen pi agent directory. The optional real E2E scripts are not part of routine validation.
+`node scripts/orchestrate.mjs --dry-run "<request>"` previews a rules-based plan without launching agents. A live invocation can call external models and consume quota; review the plan, model availability and `docs/orchestrator.md` before using it. Before creating a run, the orchestrator checks that each planned capability has at least one concrete model binding (and checks `orchestration` before model planning); a missing binding reports the user-level file to edit. This is a binding check, not an authentication/quota probe. `sync-pi.ps1` is dry-run by default; `-Apply` writes to the chosen pi agent directory. The optional real E2E scripts are not part of routine validation.
 
 ## Distribution checklist
 

package/adapters/pi/README.md

@@ -6,7 +6,8 @@ Binds the neutral kit to a native-Windows pi installation (`~/.pi/agent`, or
 | File | Role |
 | --- | --- |
 | `models.json` | shared TEMPLATE: logical backend -> pi `provider`/`model`/`thinking`. Ships with `TODO-*` placeholders that the resolver skips. |
-| `models.local.json` | **gitignored** machine-local bindings; overrides `models.json` per backend and may add backends. Copy `models.local.example.json` and fill from `pi --list-models`. Allowed keys: `provider, model, thinking, vision, note`. Credentials are rejected by the validator. |
+| `~/.pi/agent/ludi-agent-kit/models.local.json` | **Recommended durable user-level bindings**, outside the npm install (use `$env:PI_CODING_AGENT_DIR/ludi-agent-kit/models.local.json` when set). Copy `models.local.example.json` and fill from `pi --list-models`. Overrides package-local bindings per field and may add backends. Allowed keys: `provider, model, thinking, vision, note`; credentials are rejected. The kit reads this file but never writes it. |
+| `models.local.json` | **gitignored package-local migration fallback**; still overrides `models.json` when present, but is overridden by the user-level file. Existing machine-local files continue to work without migration; a package upgrade may remove this file. |
 | `lib/invoke.mjs` | one-shot model call through the installed pi CLI (`node <pi cli.js> -p --model provider/id:thinking --no-tools --no-session --no-approve --system-prompt ...`). Uses pi's own auth store. Verified against `qoder/Qwen3.8-Flash` and `devin/swe-2-high` — no provider-specific runner is needed; any provider registered in pi's model store works. |
 | `lib/subagent.mjs` | tool-capable child (`pi --mode json -p`). **Do not pass `--no-extensions`**: providers registered by pi extensions (qoder, devin) are absent from the static model store and only resolve once their extension has loaded; with `--no-extensions` `--model` fails `Model ... not found`. Kit extensions the child needs are passed explicitly (`-e shell-gate`). |
 | `lib/settings-proposal.mjs` | renders resolved agents into `subagents.agentOverrides.<agent>.{model,thinking}` — the shape verified in pi-subagents 0.68.0 (`docs/models.md`, `src/agents/agents.ts parseBuiltinOverrideEntry`). pi-subagents removed `fallbackModels`, so fallback chains are *not* expressible there; the kit runner owns escalation. |
@@ -25,14 +26,15 @@ Binds the neutral kit to a native-Windows pi installation (`~/.pi/agent`, or
 ```
 agents/<name>.md  capability
    -> routing/routing.json   primary + fallback backends
-   -> models.json + models.local.json   provider/model/thinking per backend
+   -> models.json < package-local models.local.json < user-level models.local.json
+      provider/model/thinking per backend (later source overrides fields)
    -> "provider/model:thinking"  (pi --model syntax / pi-subagents model syntax)
 ```
 
 Logical backends include `qoder` (cheap-first, bound to `qoder/Qwen3.8-Flash` on this
 machine) and `devin` (strong-first, bound to `devin/swe-2-high`). Both are ordinary
 pi providers — the kit never forks a runner per provider; bindings live only in
-`models.local.json` and facts in `model-catalog.json`. If Codex quota is exhausted,
+the user-level `models.local.json` (or legacy package-local file) and facts in `model-catalog.json`. If Codex quota is exhausted,
 cheap-code still resolves `qoder -> cheap -> local -> sol` and strong-code
 `devin -> qoder -> sol -> codex -> local`, so the orchestrator keeps running on
 Qoder/Devin/FreeToken without any code change.

package/adapters/pi/lib/model-registry.mjs

@@ -0,0 +1,12 @@
+// Pi's durable model bindings live in the user agent directory, outside the npm package.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { loadRegistry } from '../../../lib/registry.mjs';
+
+export function piUserModelsPath(env = process.env, home = homedir()) {
+  return join(env.PI_CODING_AGENT_DIR || join(home, '.pi', 'agent'), 'ludi-agent-kit', 'models.local.json');
+}
+
+export function loadPiRegistry(kit, routing, { env = process.env, home = homedir() } = {}) {
+  return loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing, piUserModelsPath(env, home));
+}

package/docs/model-maintenance.md

@@ -12,7 +12,7 @@ automatically.
 | --- | --- | --- |
 | routing | `routing/routing.json` | capabilities, backend tiers, `requires.vision` |
 | agents | `agents/*.md` | capability → agent names (for `affected.agents`) |
-| model bindings | `adapters/<x>/models.json` + `models.local.json` | current provider/model per backend |
+| model bindings | `adapters/pi/models.json` < legacy `adapters/pi/models.local.json` < `~/.pi/agent/ludi-agent-kit/models.local.json` (`PI_CODING_AGENT_DIR` respected) | current provider/model per backend; user-level overrides survive npm upgrades |
 | catalog | `adapters/<x>/model-catalog.json` | model facts: status, cost, contextK, vision, toolUse, quality scores, `location`/`local` power metadata |
 | exec policy | `adapters/<x>/maintenance-policy.json` | Phase 2: requiredQuality per tier, capabilityRequirements (coding/reasoning floors), cost weights, electricity price, escalation thresholds |
 | events | `--events <file>` | what changed (see event types below) |
@@ -86,7 +86,7 @@ binding embedded plus the manual steps to restore it.
 ## Applying and rolling back
 
 The task writes only `adapters/<x>/out/model-maintenance.proposal.json`. To apply:
-edit `adapters/<x>/models.local.json` per `proposedModel`, re-run
+edit the user-level `ludi-agent-kit/models.local.json` per `proposedModel`, re-run
 `scripts/resolve-capabilities.mjs`, then merge `out/settings.proposal.json` into
 `~/.pi/agent/settings.json` yourself. Rollback is the same flow using
 `rollback.previousBinding`. It never writes `settings.json`, `models.json`,

package/docs/orchestrator.md

@@ -11,6 +11,8 @@ node scripts/orchestrate.mjs --repo <dir> --apply "..."                # coder t
   [--planner rules|model] [--policy <file>] [--out <dir>] [--json] [--trace]
 ```
 
+Before starting a persistent run, the planner's capability (for `--planner model`) and every capability in the validated task plan must have at least one non-placeholder binding. Otherwise the call fails without creating a run and reports the user-level `models.local.json` path. Existing runs can still be listed/shown; resuming pending tasks checks their bindings. The check does not guarantee provider authentication, quota, or model availability. Configure `~/.pi/agent/ludi-agent-kit/models.local.json` (or `$env:PI_CODING_AGENT_DIR/ludi-agent-kit/models.local.json`) and see `adapters/pi/README.md` for migration precedence.
+
 ## Response language
 
 All agents default to **Japanese** for user-facing output (summaries, reports, decisions,

package/lib/orchestrator/api.mjs

@@ -2,7 +2,7 @@
 // the caller supplies `invoke` / `runner`. Natural-language UI can call these functions later.
 import { join } from 'node:path';
 import { loadRouting } from '../routing.mjs';
-import { loadRegistry } from '../registry.mjs';
+import { loadPiRegistry, piUserModelsPath } from '../../adapters/pi/lib/model-registry.mjs';
 import { loadAgents } from '../agents.mjs';
 import { loadPolicy } from './policy.mjs';
 import { openStore } from './store.mjs';
@@ -15,15 +15,15 @@ export function defaultStorePath(kit, env = process.env) {
   return env.LUDI_ORCHESTRATION_STORE || join(kit, '.orchestration', 'state.db');
 }
 
-export function loadOrchestrationContext({ kit, storePath, policyPath = null, localPolicyPath = null, clientContext = null }) {
+export function loadOrchestrationContext({ kit, storePath, policyPath = null, localPolicyPath = null, clientContext = null, modelOptions = {} }) {
   const routing = loadRouting(join(kit, 'routing/routing.json'));
-  const { registry } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+  const { registry } = loadPiRegistry(kit, routing, modelOptions);
   const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
   const base = join(kit, 'orchestration/decision-policy.json');
   const { policy } = loadPolicy(base, policyPath ?? localPolicyPath);
   const session = openStore(storePath);
   const activity = createActivityTracker({ kit, clientContext });
-  return { kit, routing, registry, agents, errors, policy, session, storePath, clientContext, activity };
+  return { kit, routing, registry, agents, errors, policy, session, storePath, clientContext, activity, bindingPath: piUserModelsPath(modelOptions.env, modelOptions.home) };
 }
 
 /** Public live activity for one run (in-memory projection; null when unknown). */
@@ -137,14 +137,14 @@ export function createRunRunner(ctx, { invoke, runSubagent = null, repoRoot, out
 export async function startOrchestration(ctx, { request, repoRoot = null, planner = 'rules', plan = null, runner, invoke = null, health = null, projectStore }) {
   return orchestrate({
     request, planner, plan, agents: ctx.agents, routing: ctx.routing, registry: ctx.registry, policy: ctx.policy,
-    runner, invoke, repoRoot, session: ctx.session, health, projectStore, activity: ctx.activity,
+    runner, invoke, repoRoot, session: ctx.session, health, projectStore, activity: ctx.activity, bindingPath: ctx.bindingPath,
   });
 }
 
 export async function resumeOrchestration(ctx, { runId, answers = [], repoRoot = null, runner, invoke = null, health = null, projectStore }) {
   return orchestrate({
     request: '', resumeRunId: runId, answers, agents: ctx.agents, routing: ctx.routing, registry: ctx.registry,
-    policy: ctx.policy, runner, invoke, repoRoot, session: ctx.session, health, projectStore, activity: ctx.activity,
+    policy: ctx.policy, runner, invoke, repoRoot, session: ctx.session, health, projectStore, activity: ctx.activity, bindingPath: ctx.bindingPath,
   });
 }
 

package/lib/orchestrator/orchestrator.mjs

@@ -8,6 +8,7 @@ import { evaluateResult } from './evaluator.mjs';
 import { evaluateDecision, decisionKey } from './escalation.mjs';
 import { classifyRun, REASSIGN_CLASSES, isProtocolFailure, shouldMarkTaskGlobalFailure } from './failures.mjs';
 import { declaredMode, accessOf, piToolsForAccess, workspaceOf } from './permissions.mjs';
+import { resolveCapability } from '../resolve.mjs';
 
 const STOP = new Set(['failed', 'blocked', 'waiting_for_user']);
 
@@ -87,7 +88,7 @@ export async function orchestrate(options) {
   }
 }
 
-async function orchestrateImpl({ request: requestArg, planner = 'rules', plan = null, agents, routing, registry, policy, runner, invoke = null, repoRoot = null, projectStore = createNullProjectStore(), now = () => new Date().toISOString(), session = null, resumeRunId = null, answers = [], health = null, activity = null, onRunCreated = () => {} }) {
+async function orchestrateImpl({ request: requestArg, planner = 'rules', plan = null, agents, routing, registry, policy, runner, invoke = null, repoRoot = null, projectStore = createNullProjectStore(), now = () => new Date().toISOString(), session = null, resumeRunId = null, answers = [], health = null, activity = null, bindingPath = null, onRunCreated = () => {} }) {
   let request = requestArg;
   let activePolicy = policy;
   let dp = activePolicy.decision_policy, limits = activePolicy.limits;
@@ -95,6 +96,13 @@ async function orchestrateImpl({ request: requestArg, planner = 'rules', plan =
   const trace = [], autoDecisions = [], escalations = [], unresolved = [], decisionLog = [];
   const limitsHit = new Set();
   let store = null, planning = true, recovered = [];
+  const requireModels = capabilities => {
+    for (const capability of new Set(capabilities)) {
+      if (!resolveCapability(routing, registry, capability).candidates.length) {
+        throw new Error(`No bound model for required capability "${capability}". Set a provider/model binding in ${bindingPath ?? 'your adapter models.local.json'} (see adapters/pi/models.local.example.json).`);
+      }
+    }
+  };
   const scopeKeyOf = () => repoRoot ?? (runId ? session?.getRun(runId)?.scopeKey : null) ?? 'default';
   // Live-activity bridge: the tracker decides whether an event type is significant
   // (persist to the run trace) or high-frequency (live snapshot only, e.g. turns).
@@ -141,6 +149,7 @@ async function orchestrateImpl({ request: requestArg, planner = 'rules', plan =
       if (res.idempotent && !res.same) unresolved.push(`decision ${a.decisionId} already answered; kept the first answer`);
     }
     store = session.openTaskStore(runId);
+    requireModels(store.list().filter(t => !['completed', 'failed', 'cancelled'].includes(t.status)).map(t => t.capability));
     releaseRecoverable(store);
     planning = store.size() === 0;
     for (const d of session.listDecisions(runId, 'pending')) escalations.push(toEscalation(d));
@@ -149,17 +158,18 @@ async function orchestrateImpl({ request: requestArg, planner = 'rules', plan =
 
   try {
   if (planning) {
+    if (!plan && planner === 'model') requireModels(['orchestration']);
+    p = await makePlan(request, { planner, plan, agents, routing, registry, policy: activePolicy, invoke, cwd: repoRoot ?? process.cwd(), trace, health });
+    const v = validatePlan(p.tasks, { agents, routing, policy: activePolicy });
+    if (!v.errors.length) requireModels(v.tasks.map(t => t.capability));
     if (session && !runId) {
       runId = session.createRun({ request, policy, repoRoot, planner, scopeKey: repoRoot ?? 'default' });
       onRunCreated(runId);
-      // Bind the owning client immediately so its public snapshot exists from the start.
       activity?.bindRun?.({ runId, repoRoot });
     }
     health?.bindRun?.(runId);
     store = store ?? (session ? session.openTaskStore(runId) : createTaskStore());
-    p = await makePlan(request, { planner, plan, agents, routing, registry, policy: activePolicy, invoke, cwd: repoRoot ?? process.cwd(), trace, health });
     if (p.fallbackReason) decide({ subject: 'planner', choice: 'rules planner', reason: `model plan unusable (${p.fallbackReason}); reversible`, step: 'reversible' });
-    const v = validatePlan(p.tasks, { agents, routing, policy: activePolicy });
     event('plan', { planner: p.planner, tasks: v.tasks.map(t => ({ id: t.id, agent: t.assignedAgent, capability: t.capability, dependencies: t.dependencies })), errors: v.errors });
     if (v.errors.length) return finish('plan-invalid', v.errors);
     for (const t of v.tasks) {

package/lib/registry.mjs

@@ -1,4 +1,4 @@
-// Adapter model registry: models.json (shared template) overlaid by models.local.json (gitignored).
+// Adapter model registry: shared template, package-local migration file, then durable user bindings.
 // Validates against routing backends. Contains no provider/model names.
 import { readFileSync, existsSync } from 'node:fs';
 
@@ -46,10 +46,10 @@ export function isPlaceholder(binding) {
 }
 
 /**
- * Load <adapterDir>/models.json overlaid with <adapterDir>/models.local.json (if present).
- * Throws on validation errors of either file or of the merged result.
+ * Load the template, then optional package-local and user-level bindings (highest priority).
+ * Throws on validation errors in any present file.
  */
-export function loadRegistry(modelsPath, localPath, routing) {
+export function loadRegistry(modelsPath, localPath, routing, userPath = null) {
   const base = JSON.parse(readFileSync(modelsPath, 'utf8'));
   const errors = validateRegistry(base, routing, 'models.json');
   let local = null;
@@ -57,7 +57,12 @@ export function loadRegistry(modelsPath, localPath, routing) {
     local = JSON.parse(readFileSync(localPath, 'utf8'));
     errors.push(...validateRegistry(local, routing, 'models.local.json'));
   }
+  let user = null;
+  if (userPath && existsSync(userPath)) {
+    user = JSON.parse(readFileSync(userPath, 'utf8'));
+    errors.push(...validateRegistry(user, routing, userPath));
+  }
   if (errors.length) throw new Error(errors.join('\n'));
-  const merged = mergeRegistries(base, local);
-  return { registry: merged, sources: { models: modelsPath, local: local ? localPath : null } };
+  const merged = mergeRegistries(mergeRegistries(base, local), user);
+  return { registry: merged, sources: { models: modelsPath, local: local ? localPath : null, user: user ? userPath : null } };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludi-uni/ludi-agent-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Windows-first, backend-neutral agent kit with Pi skills and extensions",
   "license": "MIT",
   "type": "module",

package/scripts/e2e-investigate-repro.mjs

@@ -10,7 +10,7 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import assert from 'node:assert/strict';
 import { loadRouting } from '../lib/routing.mjs';
-import { loadRegistry } from '../lib/registry.mjs';
+import { loadPiRegistry } from '../adapters/pi/lib/model-registry.mjs';
 import { loadAgents } from '../lib/agents.mjs';
 import { loadPolicy, mergePolicy } from '../lib/orchestrator/policy.mjs';
 import { openStore } from '../lib/orchestrator/store.mjs';
@@ -35,7 +35,7 @@ const plan = [
 ];
 
 const routing = loadRouting(join(kit, 'routing/routing.json'));
-const { registry } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+const { registry } = loadPiRegistry(kit, routing);
 const { agents } = loadAgents(join(kit, 'agents'), routing);
 const { policy } = loadPolicy(join(kit, 'orchestration/decision-policy.json'));
 const active = mergePolicy(policy, { limits: { max_retries: 1 }, agent_runtime: { max_runtime_ms: 300000, max_tool_calls: 25, max_turns: 8 } });

package/scripts/model-maintenance-job.mjs

@@ -18,6 +18,7 @@ import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadRouting } from '../lib/routing.mjs';
 import { loadRegistry } from '../lib/registry.mjs';
+import { piUserModelsPath } from '../adapters/pi/lib/model-registry.mjs';
 import { loadAgents } from '../lib/agents.mjs';
 import { loadCatalog } from '../lib/maintenance.mjs';
 import { loadExecPolicy } from '../lib/maintenance-exec.mjs';
@@ -32,7 +33,7 @@ const adapterDir = join(kit, 'adapters', adapter);
 const outDir = join(adapterDir, 'out');
 
 const routing = loadRouting(join(kit, 'routing/routing.json'));
-const { registry } = loadRegistry(join(adapterDir, 'models.json'), join(adapterDir, 'models.local.json'), routing);
+const { registry } = loadRegistry(join(adapterDir, 'models.json'), join(adapterDir, 'models.local.json'), routing, adapter === 'pi' ? piUserModelsPath() : null);
 const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
 if (errors.length) { console.error(errors.join('\n')); process.exit(1); }
 const catalog = loadCatalog(join(adapterDir, 'model-catalog.json'));

package/scripts/observe-models.mjs

@@ -17,6 +17,7 @@ import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadRouting } from '../lib/routing.mjs';
 import { loadRegistry } from '../lib/registry.mjs';
+import { piUserModelsPath } from '../adapters/pi/lib/model-registry.mjs';
 import { loadAgents } from '../lib/agents.mjs';
 import { loadCatalog } from '../lib/maintenance.mjs';
 import { ingestObservations, loadObservationStore, productionObservations } from '../lib/observe/observation.mjs';
@@ -80,7 +81,7 @@ let previewFile = null;
 if (has('preview-maintenance')) {
   const hypothetical = applyProposalToCatalog(catalog, proposal);
   const routing = loadRouting(join(kit, 'routing/routing.json'));
-  const { registry } = loadRegistry(join(adapterDir, 'models.json'), join(adapterDir, 'models.local.json'), routing);
+  const { registry } = loadRegistry(join(adapterDir, 'models.json'), join(adapterDir, 'models.local.json'), routing, adapter === 'pi' ? piUserModelsPath() : null);
   const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
   if (errors.length) { console.error(errors.join('\n')); process.exit(1); }
   const policy = loadExecPolicy(join(adapterDir, 'maintenance-policy.json'));

package/scripts/orchestrate.mjs

@@ -18,7 +18,8 @@ import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { loadRouting } from '../lib/routing.mjs';
-import { loadRegistry } from '../lib/registry.mjs';
+import { loadPiRegistry, piUserModelsPath } from '../adapters/pi/lib/model-registry.mjs';
+import { resolveCapability } from '../lib/resolve.mjs';
 import { loadAgents } from '../lib/agents.mjs';
 import { loadPolicy } from '../lib/orchestrator/policy.mjs';
 import { dryRun, formatPlan } from '../lib/orchestrator/orchestrator.mjs';
@@ -63,7 +64,7 @@ const planner = opts.planner ?? 'rules';
 if (!['rules', 'model'].includes(planner)) { console.error(`unknown planner "${planner}"`); process.exit(2); }
 
 const routing = loadRouting(join(kit, 'routing/routing.json'));
-const { registry } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+const { registry } = loadPiRegistry(kit, routing);
 const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
 if (errors.length) { console.error(errors.join('\n')); process.exit(1); }
 const { policy } = opts.policy
@@ -74,6 +75,7 @@ const outDir = resolve(opts.out ?? join(kit, 'adapters/pi/out/orchestrate'));
 
 if (opts['dry-run'] && !cleanupMode) {
   const invoke = planner === 'model' ? createPiInvoker() : null;
+  if (planner === 'model' && !resolveCapability(routing, registry, 'orchestration').candidates.length) throw new Error(`No bound model for orchestration; edit ${piUserModelsPath()}`);
   const dry = await dryRun(request, { planner, agents, routing, registry, policy, invoke, cwd: repoRoot ?? process.cwd() });
   console.log(opts.json ? JSON.stringify(dry, null, 2) : formatPlan(dry));
   process.exitCode = dry.errors.length ? 1 : 0;

package/scripts/reevaluate-models.mjs

@@ -25,6 +25,7 @@ import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadRouting } from '../lib/routing.mjs';
 import { loadRegistry } from '../lib/registry.mjs';
+import { piUserModelsPath } from '../adapters/pi/lib/model-registry.mjs';
 import { loadAgents } from '../lib/agents.mjs';
 import { loadCatalog, loadEvents, loadAvailabilityFile } from '../lib/maintenance.mjs';
 import { runMaintenancePlan, loadExecPolicy } from '../lib/maintenance-exec.mjs';
@@ -37,7 +38,7 @@ const adapter = opt('adapter', 'pi');
 const adapterDir = join(kit, 'adapters', adapter);
 
 const routing = loadRouting(join(kit, 'routing/routing.json'));
-const { registry, sources } = loadRegistry(join(adapterDir, 'models.json'), join(adapterDir, 'models.local.json'), routing);
+const { registry, sources } = loadRegistry(join(adapterDir, 'models.json'), join(adapterDir, 'models.local.json'), routing, adapter === 'pi' ? piUserModelsPath() : null);
 const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
 if (errors.length) { console.error(errors.join('\n')); process.exit(1); }
 const catalog = loadCatalog(join(adapterDir, 'model-catalog.json'));

package/scripts/resolve-capabilities.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { loadRouting } from '../lib/routing.mjs';
 import { loadRegistry } from '../lib/registry.mjs';
+import { piUserModelsPath } from '../adapters/pi/lib/model-registry.mjs';
 import { loadAgents } from '../lib/agents.mjs';
 import { resolveAgents, resolveCapability } from '../lib/resolve.mjs';
 
@@ -17,7 +18,7 @@ const opt = (name, def) => { const i = args.indexOf(`--${name}`); return i >= 0
 const adapter = opt('adapter', 'pi');
 const adapterDir = join(kit, 'adapters', adapter);
 const routing = loadRouting(join(kit, 'routing/routing.json'));
-const { registry, sources } = loadRegistry(join(adapterDir, 'models.json'), join(adapterDir, 'models.local.json'), routing);
+const { registry, sources } = loadRegistry(join(adapterDir, 'models.json'), join(adapterDir, 'models.local.json'), routing, adapter === 'pi' ? piUserModelsPath() : null);
 const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
 if (errors.length) { console.error(errors.join('\n')); process.exit(1); }
 

package/scripts/run-pipeline.mjs

@@ -8,7 +8,7 @@ import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeFileSync, mkdirSync, readFileSync } from 'node:fs';
 import { loadRouting } from '../lib/routing.mjs';
-import { loadRegistry } from '../lib/registry.mjs';
+import { loadPiRegistry } from '../adapters/pi/lib/model-registry.mjs';
 import { loadAgents } from '../lib/agents.mjs';
 import { resolveAgents, resolveCapability } from '../lib/resolve.mjs';
 import { runPipeline, surveyRepo, scoutPrompt, detectTestCommand, runTests, coderPrompt } from '../lib/pipeline.mjs';
@@ -25,7 +25,7 @@ const outDir = resolve(opt('out', join(kit, 'adapters/pi/out/pipeline')));
 const maxAttempts = Number(opt('max-attempts', 2));
 
 const routing = loadRouting(join(kit, 'routing/routing.json'));
-const { registry, sources } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+const { registry, sources } = loadPiRegistry(kit, routing);
 const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
 if (errors.length) { console.error(errors.join('\n')); process.exit(1); }
 const resolved = resolveAgents(agents, routing, registry);

package/tests/e2e-real-orchestrator-resume.mjs

@@ -9,7 +9,7 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import assert from 'node:assert/strict';
 import { loadRouting } from '../lib/routing.mjs';
-import { loadRegistry } from '../lib/registry.mjs';
+import { loadPiRegistry } from '../adapters/pi/lib/model-registry.mjs';
 import { loadAgents } from '../lib/agents.mjs';
 import { loadPolicy, mergePolicy } from '../lib/orchestrator/policy.mjs';
 import { openStore } from '../lib/orchestrator/store.mjs';
@@ -38,7 +38,7 @@ const plan = [
 
 function context(repo) {
   const routing = loadRouting(join(kit, 'routing/routing.json'));
-  const { registry } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+  const { registry } = loadPiRegistry(kit, routing);
   const { agents } = loadAgents(join(kit, 'agents'), routing);
   const { policy } = loadPolicy(join(kit, 'orchestration/decision-policy.json'));
   // Stay on cheap-code so a hosted usage limit falls through to the local candidate instead of the hosted-only ladder.

package/tests/e2e-real-orchestrator.mjs

@@ -8,7 +8,7 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import assert from 'node:assert/strict';
 import { loadRouting } from '../lib/routing.mjs';
-import { loadRegistry } from '../lib/registry.mjs';
+import { loadPiRegistry } from '../adapters/pi/lib/model-registry.mjs';
 import { loadAgents } from '../lib/agents.mjs';
 import { loadPolicy } from '../lib/orchestrator/policy.mjs';
 import { createAgentRunner } from '../lib/orchestrator/runner.mjs';
@@ -17,7 +17,7 @@ import { createPiInvoker } from '../adapters/pi/lib/invoke.mjs';
 
 const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const routing = loadRouting(join(kit, 'routing/routing.json'));
-const { registry } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+const { registry } = loadPiRegistry(kit, routing);
 const { agents } = loadAgents(join(kit, 'agents'), routing);
 const { policy } = loadPolicy(join(kit, 'orchestration/decision-policy.json'));
 const repo = mkdtempSync(join(tmpdir(), 'ludi-real-orch-'));

package/tests/e2e-real-pi.mjs

@@ -1,21 +1,21 @@
 // Opt-in real E2E through the installed pi CLI and the machine-local model registry.
 // Not part of `node --test`; it spends real model quota. Run:
 //   node tests/e2e-real-pi.mjs
-// Requires adapters/pi/models.local.json with ready providers (`pi auth check --provider <p>`).
+// Requires user-level (or legacy package-local) models.local.json with ready providers (`pi auth check --provider <p>`).
 import { mkdtempSync, cpSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import assert from 'node:assert/strict';
 import { loadRouting } from '../lib/routing.mjs';
-import { loadRegistry } from '../lib/registry.mjs';
+import { loadPiRegistry } from '../adapters/pi/lib/model-registry.mjs';
 import { loadAgents } from '../lib/agents.mjs';
 import { runPipeline, runTests } from '../lib/pipeline.mjs';
 import { createPiInvoker } from '../adapters/pi/lib/invoke.mjs';
 
 const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const routing = loadRouting(join(kit, 'routing/routing.json'));
-const { registry } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+const { registry } = loadPiRegistry(kit, routing);
 const { agents } = loadAgents(join(kit, 'agents'), routing);
 const repo = mkdtempSync(join(tmpdir(), 'ludi-real-e2e-'));
 cpSync(join(kit, 'tests/fixtures/math-repo'), repo, { recursive: true });

package/tests/e2e-real-tool-orchestrator.mjs

@@ -9,7 +9,7 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import assert from 'node:assert/strict';
 import { loadRouting } from '../lib/routing.mjs';
-import { loadRegistry } from '../lib/registry.mjs';
+import { loadPiRegistry } from '../adapters/pi/lib/model-registry.mjs';
 import { loadAgents } from '../lib/agents.mjs';
 import { loadPolicy, mergePolicy } from '../lib/orchestrator/policy.mjs';
 import { openStore } from '../lib/orchestrator/store.mjs';
@@ -37,7 +37,7 @@ const plan = [
 ];
 
 const routing = loadRouting(join(kit, 'routing/routing.json'));
-const { registry } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+const { registry } = loadPiRegistry(kit, routing);
 const { agents } = loadAgents(join(kit, 'agents'), routing);
 const { policy } = loadPolicy(join(kit, 'orchestration/decision-policy.json'));
 const active = mergePolicy(policy, { decision_policy: { reassign_on_failure: false }, limits: { max_retries: 1 }, agent_runtime: { max_runtime_ms: 180000, max_tool_calls: 25, max_turns: 8 } });

package/tests/orchestrator-persist.test.mjs

@@ -2,7 +2,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { mkdtempSync } from 'node:fs';
+import { mkdtempSync, cpSync, mkdirSync, copyFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -15,6 +15,7 @@ import { newTask } from '../lib/orchestrator/task-store.mjs';
 import { classifyBackendFailure, createHealthMonitor } from '../lib/orchestrator/health.mjs';
 import { evaluateDecision } from '../lib/orchestrator/escalation.mjs';
 import { orchestrate } from '../lib/orchestrator/orchestrator.mjs';
+import { loadOrchestrationContext, startOrchestration } from '../lib/orchestrator/api.mjs';
 
 const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const routing = loadRouting(join(kit, 'routing/routing.json'));
@@ -34,6 +35,42 @@ const completed = (task, extra = {}) => ({ ok: true, structured: true, modelId:
 const blocked = decisions => ({ ok: true, structured: true, result: { status: 'blocked', summary: 'need a choice', artifacts: [], verification: [], acceptance: [], remainingIssues: [], decisions, newTasks: [] } });
 const dbPath = () => join(mkdtempSync(join(tmpdir(), 'ludi-orch-')), 'state.db');
 
+test('unbound task capability fails before a run is created with the user binding path', async () => {
+  const path = dbPath();
+  const session = openStore(path);
+  const userPath = join(dirname(path), 'agent', 'ludi-agent-kit', 'models.local.json');
+  try {
+    await assert.rejects(orchestrate({ request: 'implement', plan: [spec('a', 'coder')], agents, routing,
+      registry: { version: 1, backends: { devin: { provider: 'TODO-provider', model: 'TODO-model' } } },
+      bindingPath: userPath, policy: DEFAULT_POLICY, session, runner: { async run() { throw new Error('should not run'); } },
+    }), error => error.message.includes('strong-code') && error.message.includes(userPath));
+    assert.deepEqual(session.listRuns(), []);
+    await assert.rejects(orchestrate({ request: 'plan', planner: 'model', agents, routing,
+      registry: { version: 1, backends: {} }, bindingPath: userPath, policy: DEFAULT_POLICY, session,
+      invoke: async () => { throw new Error('should not plan'); },
+    }), /required capability "orchestration"/);
+    assert.deepEqual(session.listRuns(), []);
+  } finally { session.close(); }
+});
+
+test('API start uses the user-level binding path without touching the real agent directory', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'ludi-model-home-'));
+  const isolatedKit = mkdtempSync(join(tmpdir(), 'ludi-model-kit-'));
+  cpSync(join(kit, 'routing'), join(isolatedKit, 'routing'), { recursive: true, filter: path => !path.endsWith('.local.json') });
+  cpSync(join(kit, 'agents'), join(isolatedKit, 'agents'), { recursive: true });
+  mkdirSync(join(isolatedKit, 'adapters', 'pi'), { recursive: true });
+  mkdirSync(join(isolatedKit, 'orchestration'), { recursive: true });
+  copyFileSync(join(kit, 'adapters/pi/models.json'), join(isolatedKit, 'adapters/pi/models.json'));
+  copyFileSync(join(kit, 'orchestration/decision-policy.json'), join(isolatedKit, 'orchestration/decision-policy.json'));
+  const ctx = loadOrchestrationContext({ kit: isolatedKit, storePath: dbPath(), modelOptions: { env: {}, home } });
+  try {
+    await assert.rejects(startOrchestration(ctx, { request: 'implement', plan: [spec('a', 'coder')],
+      runner: { async run() { throw new Error('should not run'); } } }),
+    error => error.message.includes(join(home, '.pi', 'agent', 'ludi-agent-kit', 'models.local.json')));
+    assert.deepEqual(ctx.session.listRuns(), []);
+  } finally { ctx.session.close(); }
+});
+
 test('persistent run creation stores the run, tasks and trace', async () => {
   const session = openStore(dbPath());
   const r = await orchestrate({

package/tests/pipeline.test.mjs

@@ -2,7 +2,7 @@
 // and a fixture-repo E2E with a scripted invoker (no model calls).
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, cpSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, cpSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -14,6 +14,7 @@ import { normalizeContextPack, classifyPath, relativizeText } from '../lib/norma
 import { withEscalation, runPipeline, parseFileBlocks, runTests } from '../lib/pipeline.mjs';
 import { buildSettingsProposal } from '../adapters/pi/lib/settings-proposal.mjs';
 import { createScriptedInvoker } from '../adapters/pi/lib/invoke.mjs';
+import { loadPiRegistry, piUserModelsPath } from '../adapters/pi/lib/model-registry.mjs';
 
 const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const routing = loadRouting(join(kit, 'routing/routing.json'));
@@ -60,6 +61,31 @@ test('registry: loadRegistry merges files and rejects invalid local file', () =>
   assert.equal(shipped.sources.local, null);
 });
 
+test('pi user bindings override package-local bindings without writing to the agent directory', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ludi-pi-reg-'));
+  const adapter = join(dir, 'adapters', 'pi');
+  const home = join(dir, 'home');
+  mkdirSync(adapter, { recursive: true });
+  const userPath = piUserModelsPath({}, home);
+  mkdirSync(dirname(userPath), { recursive: true });
+  const file = (path, backends) => writeFileSync(path, JSON.stringify({ version: 1, backends }));
+  file(join(adapter, 'models.json'), { devin: { provider: 'TODO-provider', model: 'TODO-model', thinking: 'low' } });
+  file(join(adapter, 'models.local.json'), { devin: { provider: 'package', model: 'old' }, sol: { provider: 'package', model: 'fallback' } });
+  file(userPath, { devin: { provider: 'user', model: 'new' } });
+  const merged = loadPiRegistry(dir, routing, { env: {}, home });
+  assert.equal(merged.registry.backends.devin.model, 'new');
+  assert.equal(merged.registry.backends.devin.thinking, 'low');
+  assert.equal(merged.registry.backends.sol.model, 'fallback');
+  assert.equal(merged.sources.user, userPath);
+  rmSync(join(adapter, 'models.local.json'));
+  assert.equal(loadPiRegistry(dir, routing, { env: {}, home }).registry.backends.devin.model, 'new');
+  file(join(adapter, 'models.local.json'), { devin: { provider: 'package', model: 'old' } });
+  assert.equal(loadPiRegistry(dir, routing, { env: { PI_CODING_AGENT_DIR: join(dir, 'empty') }, home }).sources.user, null);
+  assert.equal(piUserModelsPath({ PI_CODING_AGENT_DIR: join(dir, 'custom') }, home), join(dir, 'custom', 'ludi-agent-kit', 'models.local.json'));
+  file(userPath, { devin: { apiKey: 'bad' } });
+  assert.throws(() => loadPiRegistry(dir, routing, { env: {}, home }), /must not store credentials/);
+});
+
 // ---------- resolution ----------
 test('resolve: agent -> capability -> backend chain -> concrete model; placeholders skipped', () => {
   const r = resolveAgents(agents, routing, REG);