@sangyaahub/pi-marg 1.0.0 → 1.0.3

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "PiMarg — a governed development path for Pi Agent and Oh My Pi.",
-    "version": "1.0.0"
+    "version": "1.0.3"
   },
   "plugins": [
     {
       "name": "pi-marg",
       "description": "Intent-led development workflow with live A/B/C/D routing, capability detection, verification, and approval gates.",
       "source": "./",
-      "version": "1.0.0",
+      "version": "1.0.3",
       "author": {
         "name": "Sangyaa",
         "email": "contact@sangyaa.co"

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.0.3 — 2026-09-14
+
+- Made model routing explicitly model-agnostic: live OMP/Pi authenticated catalogs are the only source of truth, with soft preferred-class ranking that never requires a maintainer's subscriptions.
+- Promotes provider/subscription setup when the live catalog is empty (`/login` + `omp models` on OMP; `pi --list-models` on Pi).
+- Shows required A/B/C/D stage options and catalog sections in ascending letter order.
+
+## 1.0.2 — 2026-09-12
+
+- Changed live catalog presentation to a provider-first numbered two-step: list every authenticated provider, then every model for the chosen provider.
+- Added optional `provider` filter on `auto_model_route` catalog so agents can request one provider's full model list without truncating giant catalogs.
+- Documented an OMP catalog advisory when both `cursor` and `openai-codex` are live: mid-session switches can hit a harness `call_id` max-length 64 rejection (tracked upstream in `@oh-my-pi/pi-coding-agent`); recover with a fresh session that does not replay the affected tool history.
+
+## 1.0.1 — 2026-09-10
+
+- Added the global `pi-marg start` and `pi-marg "<work prompt>"` OMP launch commands.
+- Canonicalized the npm executable mapping so npm installs the global `pi-marg` command.
+- Added native interactive OMP intake for work boundary, work type, workflow skill, and required A/B/C/D model choices.
+- Changed model pickers to show every authenticated and enabled runtime model while ranking stage-appropriate choices first.
+- Preserved independent-review enforcement: A cannot equal C, and B cannot equal D.
+
 ## 1.0.0 — 2026-09-08
 
 - First PiMarg release for Pi Agent and Oh My Pi.

package/MODEL-SETUP.md

@@ -1,6 +1,6 @@
 # Model setup
 
-PiMarg reads the active Pi or OMP model registry whenever `auto_model_route` runs. Exact selectors are deliberately absent from this document because providers rename and replace models.
+PiMarg reads the active Pi or OMP model registry whenever `auto_model_route` runs. It is model-agnostic: whatever subscriptions or providers someone has configured are what appear in the catalog. Exact selectors are deliberately absent from this document because providers rename and replace models.
 
 ```text
 LIVE AUTHENTICATED CATALOG
@@ -13,13 +13,15 @@ LIVE AUTHENTICATED CATALOG
      └─ different ─┘ within each pair
 ```
 
+If the live catalog is empty, PiMarg stops and promotes provider/subscription setup instead of guessing models.
+
 ## Roles
 
-| Stage | Purpose | Preferred class |
+| Stage | Purpose | Preferred class (optional ranking) |
 |---|---|---|
-| A | Discovery and difficult reasoning | Latest eligible Claude frontier, OpenAI frontier, or Grok frontier |
+| A | Discovery and difficult reasoning | Latest eligible Claude frontier, OpenAI frontier, or Grok frontier when present |
+| B | Execute the accepted plan | Claude/OpenAI mid-layer, Cursor Composer, eligible zero-metered route, or Devin SWE when present |
 | C | Independent plan review | A different frontier model/family from A |
-| B | Execute the accepted plan | Claude/OpenAI mid-layer, Cursor Composer, eligible zero-metered route, or Devin SWE |
 | D | Independent implementation review | A different execution model/family from B |
 
 “Zero-metered” means the runtime reports zero token price for that route. Subscription quotas and pool limits can still apply.
@@ -39,22 +41,57 @@ The Pi adapter reads `ctx.scopedModels` when the session has a model allowlist;
 Use OMP `/login`, then inspect `/model` or:
 
 ```bash
-omp models list
+omp models
 ```
 
-The OMP adapter reads `ctx.models.list()` and activates an exact catalog entry with `pi.setModel()`.
+The OMP adapter reads `ctx.models.list()`, which supplies authenticated and enabled models, and activates an exact catalog entry with `pi.setModel()`.
 
 ## Selection workflow
 
-1. Run `/auto-models choose`.
-2. Request `action: catalog` with the confirmed work type.
-3. Select A and C from frontier candidates.
-4. Select B and D when implementation is required.
-5. Resolve any A=C or B=D identity conflict before continuing.
-6. Activate the saved selector immediately before its stage.
+1. Run `/pi-marg` for the full native intake, or `/auto-models choose` to change saved models.
+2. Confirm the work type so PiMarg knows which stages are required.
+3. Required stage prompts and catalog sections are always shown in ascending order: **A, then B, then C, then D** (skipping stages that do not apply).
+4. For each required stage, choose a **provider** first (numbered `1. …`), then a **model** from that provider (numbered `1. …`). Exact `provider/id` selectors are the selection keys—not display numbers alone.
+5. Select A and C when discovery/review is required; recommended frontier choices appear first within their lists when recognizable, but every live model remains selectable.
+6. Select B and D when implementation is required; recommended execution choices appear first within their lists when recognizable, but every live model remains selectable.
+7. Resolve any A=C or B=D identity conflict before continuing.
+8. Activate the saved selector immediately before its stage.
+
+### Tool form (`auto_model_route`)
+
+```text
+# 1) Overview: every provider, no model dump
+auto_model_route action=catalog workType=<n>
+
+# 2) Full model list for one authenticated provider
+auto_model_route action=catalog workType=<n> provider=<provider-name>
+
+# 3) Persist and activate an exact selector
+auto_model_route action=select stage=<A|B|C|D> target=<provider>/<model-id> workType=<n>
+```
+
+Never present a hand-curated subset that omits a logged-in provider. Every authenticated and enabled runtime model remains selectable at every required stage. Soft preferred-class ranking controls order, not visibility.
 
 The normalized identity check treats the same underlying model reached through different providers as the same candidate when their identifiers normalize equally.
 
+### OMP cursor → openai-codex note
+
+On OMP with `@oh-my-pi/pi-coding-agent` 18.1.17, switching from a `cursor` stage to an `openai-codex` stage in the **same** session can fail if prior `cursor-agent` tool ids are replayed (`call_id` longer than 64). PiMarg surfaces this as a catalog advisory when both providers are live. Workaround: start a **fresh session** that does not replay the affected tool history. The durable fix belongs in the harness, not in PiMarg selectors.
+
+## Provider recommendation (optional ranking only)
+
+These names are soft ranking hints for common catalogs. They are never required. If your subscriptions expose different models, PiMarg still lists every authenticated entry and lets you choose.
+
+- Cursor Composer or a zero-metered Cursor route: economical B/D work when present in the live catalog.
+- Claude Fable/Opus: A/C product thinking, architecture, specification, and cross-family review.
+- Claude Sonnet: B/D mid-layer implementation or review.
+- OpenAI Astra/Sol: A/C complex discovery and plan review.
+- OpenAI Terra/Luna/Codex-class: B/D implementation and review, chosen by task risk and cost.
+- Latest matching Grok 4.6-or-newer model: A/C independent frontier analysis or current web/social context.
+- Native Devin SWE: B/D when exposed by the runtime. External Devin: bounded delegation with acceptance criteria and a quota limit.
+
+Use Pi or OMP's own authentication and model UI as the authority for what the account can actually access. When nothing is authenticated, set up any subscription first (`/login` on OMP, or Pi provider credentials), then re-run PiMarg.
+
 ## Devin
 
 Native Devin model entries are ordinary B/D candidates when the runtime catalog exposes them. A separate external Devin session appears only when a Devin tool is detected. Creating that session is a web mutation and requires one-use `post-web` approval.

package/PUBLISHING.md

@@ -5,7 +5,7 @@ This checklist is for maintainers. Public mutations remain subject to PiMarg's o
 ## Before a release
 
 1. Update `package.json`, `.omp-plugin/marketplace.json`, and `CHANGELOG.md` to the same version.
-2. Run `./scripts/validate.sh`, `bun test tests`, and `npm pack --dry-run`.
+2. Run `./scripts/validate.sh`, `bun test tests`, `node bin/pi-marg.js --version`, and `npm pack --dry-run`.
 3. Smoke-test the package root with the supported Pi and OMP versions.
 4. Inspect the packed file list for secrets, generated debris, and missing runtime files.
 

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/sangyaahub/pi-marg/releases"><img alt="Version 1.0.0" src="https://img.shields.io/badge/version-1.0.0-0451F7"></a>
+  <a href="https://github.com/sangyaahub/pi-marg/releases"><img alt="Version 1.0.3" src="https://img.shields.io/badge/version-1.0.3-0451F7"></a>
   <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-C27B1A"></a>
   <a href="https://pi.dev/packages?name=pi-marg"><img alt="Pi package" src="https://img.shields.io/badge/Pi-package-0338A8"></a>
   <a href="https://omp.sh"><img alt="Oh My Pi plugin" src="https://img.shields.io/badge/OMP-plugin-021E5C"></a>
@@ -11,7 +11,7 @@
 
 # PiMarg
 
-**Version 1.0.0 · MIT licensed · Pi Agent + Oh My Pi · by [Sangyaa](https://sangyaa.co)**
+**Version 1.0.3 · MIT licensed · Pi Agent + Oh My Pi · by [Sangyaa](https://sangyaa.co)**
 
 PiMarg turns an ordinary prompt into a governed development path. It identifies the work boundary, selects one engineering method, discovers the models and tools the active runtime really provides, separates thinking from execution, records evidence, and stops before protected actions.
 
@@ -42,7 +42,7 @@ The same model-selection and approval logic lives in `core/`. Runtime-specific c
 - Confirms job/client versus personal work; job/client mode suppresses Sangyaa branding by default.
 - Routes seven work types: idea, new feature, improvement, proactive bug fix, security, repository analysis, and business/sales analysis.
 - Uses one primary Compound Engineering, Superpowers, GSD Core, or automatically selected workflow spine.
-- Discovers current authenticated model selectors instead of pinning dated model names.
+- Shows every current authenticated and enabled model, ranking the best fit for each stage first instead of pinning dated model names.
 - Enforces that A and C use different underlying models, and B and D use different underlying models.
 - Uses CodeGraph for repository architecture and impact when available, with LSP/AST or repository-native tools for exact code questions.
 - Adds conditional testing, debugger, browser/desktop, security, Advisor, task, and memory routes only when detected.
@@ -62,7 +62,7 @@ The same model-selection and approval logic lives in `core/`. Runtime-specific c
 | Advisor, checkpoint, security scan, Hindsight | Extension/fallback when detected | Native capability when enabled |
 | Parallel agents | Only when a compatible task extension exists | Native `task`/workflow routes when available |
 
-Tested locally against Pi Agent `0.85.1` and OMP `18.1.14`. Optional features are always capability-detected, so their absence produces a recorded fallback rather than a false success claim.
+Tested locally against Pi Agent `0.85.1` and OMP `18.1.15`. Optional features are always capability-detected, so their absence produces a recorded fallback rather than a false success claim.
 
 ## Try the demo
 
@@ -98,6 +98,12 @@ Install PiMarg from the Pi package catalog/npm:
 pi install npm:@sangyaahub/pi-marg
 ```
 
+Install the global OMP launcher:
+
+```bash
+npm install --global @sangyaahub/pi-marg
+```
+
 Or install Pi and OMP directly from this GitHub repository:
 
 ```bash
@@ -106,6 +112,8 @@ omp plugin marketplace add sangyaahub/pi-marg
 omp plugin install --scope user pi-marg@pi-marg-marketplace
 ```
 
+The npm command launches OMP; the OMP plugin installation supplies PiMarg's extensions, skills, commands, and rules. Install both when you want to start the complete workflow with `pi-marg` from any repository.
+
 ## Configure models
 
 Authenticate providers using the active runtime's normal login flow, then run:
@@ -114,16 +122,27 @@ Authenticate providers using the active runtime's normal login flow, then run:
 /auto-models choose
 ```
 
-The router builds choices from the live authenticated registry. It does not promise that a subscription route is free or unlimited. See [MODEL-SETUP.md](MODEL-SETUP.md).
+The router shows every model in the live authenticated and enabled registry. Stage-appropriate choices appear first and all other enabled choices remain selectable. It does not promise that a subscription route is free or unlimited. See [MODEL-SETUP.md](MODEL-SETUP.md).
 
 ## Start a workflow
 
-Type a normal request or invoke:
+From a terminal in the repository you want to work on, run either:
+
+```bash
+pi-marg start
+pi-marg "add CSV export to this repository"
+```
+
+`pi-marg start` opens OMP and asks for the work prompt. Supplying a prompt starts the same guided flow immediately. Inside an existing OMP session, invoke:
 
 ```text
+/pi-marg
+/pi-marg add CSV export to this repository
 /auto add CSV export to this repository
 ```
 
+The native picker asks for work boundary, work type, workflow skill, and every model required by that work type. It shows only models reported as authenticated and enabled by OMP, with recommended stage fits first.
+
 Useful entry points:
 
 - `/auto-models choose` — refresh A/B/C/D choices.

package/adapters/omp/extensions/model-router.ts

@@ -1,21 +1,153 @@
 import {
   MODEL_STATE_TYPE,
   STAGES,
+  buildModelCatalog,
+  candidatesForProvider,
+  emptyCatalogSetupMessage,
   emptyModelRouteState,
   executeModelRoute,
+  matchNumberedOption,
+  numberedOptionLabel,
+  requiredStagesForWorkType,
   restoreModelRouteState,
+  uniqueProviders,
+  type AutoStage,
+  type ModelCandidate,
   type ModelLike,
   type ModelRouteParams,
+  type ModelRouteState,
 } from "../../../core/model-routing";
+import { normalizeCapabilityNames } from "../../../core/runtime-capabilities";
 
-function toolNames(pi: any): string[] {
-  return (pi.getAllTools?.() ?? [])
-    .map((tool: any) => typeof tool === "string" ? tool : String(tool?.name ?? ""))
-    .filter(Boolean);
-}
+const WORK_BOUNDARIES = ["1. Job/client", "2. Personal"] as const;
+
+const WORK_TYPES = [
+  "1. New idea or development from scratch",
+  "2. New feature for an existing repository",
+  "3. Improve an existing feature",
+  "4. Pro-active bug fix",
+  "5. Security review or fixes",
+  "6. Thoughts about an existing repository or features",
+  "7. Business, sales, or other non-technical analysis",
+] as const;
+
+const SKILL_MODES = [
+  "1. Compound Engineering",
+  "2. Superpowers",
+  "3. GSD Core",
+  "4. PiMarg chooses the best available skill",
+] as const;
+
+const STAGE_PURPOSE: Record<AutoStage, string> = {
+  A: "thinking/discovery",
+  B: "implementation/execution",
+  C: "plan second-eye review",
+  D: "implementation second-eye review",
+};
 
 function hasExternalDevin(pi: any): boolean {
-  return toolNames(pi).some((name) => /(?:^|[_-])devin(?:[_-]|$)/i.test(name));
+  return normalizeCapabilityNames(pi.getAllTools?.() ?? [])
+    .some((name) => /(?:^|[_-])devin(?:[_-]|$)/i.test(name));
+}
+
+function commandPrompt(args: string): string {
+  const trimmed = args.trim();
+  if (trimmed.toLowerCase() === "start") return "";
+  return trimmed;
+}
+
+function optionLabel(candidate: ModelCandidate): string {
+  return `${candidate.label} — ${candidate.selector}`;
+}
+
+function optionDescription(stage: AutoStage, candidate: ModelCandidate): string {
+  const preferredTier = stage === "A" || stage === "C" ? "frontier" : "execution";
+  const fit = candidate.tier === preferredTier ? "Recommended fit" : "Available";
+  return `${fit} for ${STAGE_PURPOSE[stage]}${candidate.billingNote ? ` · ${candidate.billingNote}` : ""}`;
+}
+
+async function chooseModel(
+  ctx: any,
+  stage: AutoStage,
+  candidates: ModelCandidate[],
+  selected: Partial<Record<AutoStage, ModelCandidate>>,
+): Promise<ModelCandidate | undefined> {
+  const opposite: Record<AutoStage, AutoStage> = { A: "C", C: "A", B: "D", D: "B" };
+  const other = selected[opposite[stage]];
+  const eligible = candidates.filter((candidate) => !other || candidate.identity !== other.identity);
+  if (eligible.length === 0) {
+    ctx.ui.notify(
+      "Paired stages require two distinct authenticated model identities. Configure another model, then run /pi-marg again.",
+      "error",
+    );
+    return undefined;
+  }
+
+  const providers = uniqueProviders(eligible);
+  const providerOptions = providers.map((name, index) => ({
+    label: numberedOptionLabel(index, `${name} (${candidatesForProvider(eligible, name).length})`),
+    description: `All authenticated ${name} models for ${STAGE_PURPOSE[stage]}`,
+  }));
+  const providerAnswer = await ctx.ui.select(`Stage ${stage} provider`, providerOptions, {
+    selectionMarker: "radio",
+    helpText: `${providers.length} providers · ${eligible.length} models · ${STAGE_PURPOSE[stage]}`,
+  });
+  const provider = matchNumberedOption(
+    providerAnswer,
+    providers,
+    (name) => `${name} (${candidatesForProvider(eligible, name).length})`,
+  );
+  if (!provider) return undefined;
+
+  const providerModels = candidatesForProvider(eligible, provider);
+  const modelOptions = providerModels.map((candidate, index) => ({
+    label: numberedOptionLabel(index, optionLabel(candidate)),
+    description: optionDescription(stage, candidate),
+  }));
+  const answer = await ctx.ui.select(`Stage ${stage} model`, modelOptions, {
+    selectionMarker: "radio",
+    helpText: `${providerModels.length} ${provider} choices · ${STAGE_PURPOSE[stage]}`,
+  });
+  return matchNumberedOption(answer, providerModels, optionLabel);
+}
+
+function selectedState(
+  workType: number,
+  selected: Partial<Record<AutoStage, ModelCandidate>>,
+): ModelRouteState {
+  const selectedAt = new Date().toISOString();
+  return {
+    version: 1,
+    workType,
+    selections: Object.fromEntries(
+      Object.entries(selected).map(([stage, candidate]) => [stage, { ...candidate, selectedAt }]),
+    ) as ModelRouteState["selections"],
+  };
+}
+
+function intakeMessage(
+  request: string,
+  boundary: string,
+  workType: string,
+  skillMode: string,
+  selected: Partial<Record<AutoStage, ModelCandidate>>,
+): string {
+  const models = STAGES
+    .filter((stage) => selected[stage])
+    .map((stage) => `- Stage ${stage} (${STAGE_PURPOSE[stage]}): ${selected[stage]!.selector}`)
+    .join("\n");
+  return [
+    "Start PiMarg for the following request:",
+    request,
+    "",
+    "Interactive intake is already confirmed; do not ask these questions again:",
+    `- Boundary: ${boundary}`,
+    `- Work type: ${workType}`,
+    `- Workflow skill: ${skillMode}`,
+    models,
+    "",
+    "Load auto-mode-router, record these choices in the session ledger, activate each saved model before its stage, and continue the workflow. Ask interactively only for information that is still missing.",
+  ].join("\n");
 }
 
 export default function modelRouter(pi: any) {
@@ -30,6 +162,61 @@ export default function modelRouter(pi: any) {
   pi.on("session_branch", restore);
   pi.on("session_tree", restore);
 
+  pi.registerCommand("pi-marg", {
+    description: "Start PiMarg with interactive intake, or pass a work prompt.",
+    async handler(args: string, ctx: any) {
+      if (typeof ctx.isIdle === "function" && ctx.isIdle() === false) {
+        ctx.ui.notify("PiMarg intake can start after the current turn finishes.", "warning");
+        return;
+      }
+
+      let request = commandPrompt(args);
+      if (!ctx.hasUI) {
+        if (!request) {
+          ctx.ui.notify("PiMarg interactive intake requires an OMP TUI session.", "error");
+          return;
+        }
+        pi.sendUserMessage(`Start PiMarg for this request:\n${request}`);
+        return;
+      }
+      if (!request) {
+        request = (await ctx.ui.input("PiMarg", "What would you like to work on?"))?.trim() ?? "";
+      }
+      if (!request) return;
+
+      const boundaryLabel = await ctx.ui.select("Work boundary", [...WORK_BOUNDARIES], {
+        selectionMarker: "radio",
+      });
+      const boundary = matchNumberedOption(boundaryLabel, ["Job/client", "Personal"], (item) => item);
+      if (!boundary) return;
+
+      const workTypeLabel = await ctx.ui.select("Work type", [...WORK_TYPES], { selectionMarker: "radio" });
+      const workType = Number.parseInt(workTypeLabel?.match(/^([1-7])\./)?.[1] ?? "", 10);
+      if (!Number.isInteger(workType)) return;
+
+      const skillMode = await ctx.ui.select("Workflow skill", [...SKILL_MODES], { selectionMarker: "radio" });
+      if (!skillMode) return;
+
+      const liveModels = ctx.models.list() as ModelLike[];
+      if (liveModels.length === 0) {
+        ctx.ui.notify(emptyCatalogSetupMessage("OMP"), "error");
+        return;
+      }
+      const catalog = buildModelCatalog(liveModels, hasExternalDevin(pi));
+      const selected: Partial<Record<AutoStage, ModelCandidate>> = {};
+      for (const stage of requiredStagesForWorkType(workType)) {
+        const choice = await chooseModel(ctx, stage, catalog[stage], selected);
+        if (!choice) return;
+        selected[stage] = choice;
+      }
+
+      const nextState = selectedState(workType, selected);
+      state = nextState;
+      pi.appendEntry(MODEL_STATE_TYPE, nextState);
+      pi.sendUserMessage(intakeMessage(request, boundary, workTypeLabel!, skillMode, selected));
+    },
+  });
+
   pi.registerTool({
     name: "auto_model_route",
     label: "PiMarg Model Router",
@@ -39,6 +226,7 @@ export default function modelRouter(pi: any) {
       stage: z.enum(STAGES).optional(),
       target: z.string().optional(),
       workType: z.number().optional(),
+      provider: z.string().optional(),
     }),
     async execute(_toolCallId: string, params: ModelRouteParams, _signal: unknown, _onUpdate: unknown, ctx: any) {
       const models = ctx.models.list() as ModelLike[];

package/adapters/pi/extensions/model-router.ts

@@ -44,6 +44,7 @@ export default function modelRouter(pi: any) {
       stage: Type.Optional(Type.Union([Type.Literal("A"), Type.Literal("B"), Type.Literal("C"), Type.Literal("D")])),
       target: Type.Optional(Type.String()),
       workType: Type.Optional(Type.Number()),
+      provider: Type.Optional(Type.String()),
     }),
     async execute(_toolCallId: string, params: ModelRouteParams, _signal: unknown, _onUpdate: unknown, ctx: any) {
       const models = availableModels(ctx);

package/bin/pi-marg.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { readFileSync, realpathSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+
+const HELP = `PiMarg ${VERSION}
+
+Usage:
+  pi-marg start
+  pi-marg "<work prompt>"
+  pi-marg start "<work prompt>"
+
+Starts Oh My Pi and invokes PiMarg's interactive workflow.`;
+
+export function parsePiMargArgs(args) {
+  if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
+    return { action: "help", prompt: "" };
+  }
+  if (args.length === 1 && (args[0] === "--version" || args[0] === "-v")) {
+    return { action: "version", prompt: "" };
+  }
+  const promptParts = args[0]?.toLowerCase() === "start" ? args.slice(1) : args;
+  return { action: "launch", prompt: promptParts.join(" ").trim() };
+}
+
+export function buildOmpInvocation(parsed) {
+  if (parsed.action !== "launch") return [];
+  return [parsed.prompt ? `/pi-marg ${parsed.prompt}` : "/pi-marg"];
+}
+
+export function runPiMarg(args = process.argv.slice(2)) {
+  const parsed = parsePiMargArgs(args);
+  if (parsed.action === "help") {
+    console.log(HELP);
+    return 0;
+  }
+  if (parsed.action === "version") {
+    console.log(VERSION);
+    return 0;
+  }
+
+  const executable = process.env.PIMARG_OMP_BIN || "omp";
+  const result = spawnSync(executable, buildOmpInvocation(parsed), {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+    shell: false,
+  });
+  if (result.error) {
+    if (result.error.code === "ENOENT") {
+      console.error("PiMarg could not find the `omp` command. Install Oh My Pi and make sure `omp` is on PATH.");
+      return 127;
+    }
+    console.error(`PiMarg could not start OMP: ${result.error.message}`);
+    return 1;
+  }
+  return result.status ?? (result.signal ? 1 : 0);
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  process.exitCode = runPiMarg();
+}

package/core/model-routing.ts

@@ -1,5 +1,5 @@
 export type AutoStage = "A" | "B" | "C" | "D";
-export type CandidateTier = "frontier" | "execution";
+export type CandidateTier = "frontier" | "execution" | "general";
 export type RuntimeName = "OMP" | "Pi";
 
 export interface ModelLike {
@@ -25,6 +25,7 @@ export interface ModelCandidate {
     | "included-cursor"
     | "devin-swe"
     | "included-devin"
+    | "runtime-available"
     | "devin-external";
   access: "runtime-model" | "external-agent";
   billingNote?: string;
@@ -45,6 +46,7 @@ export interface ModelRouteParams {
   stage?: AutoStage;
   target?: string;
   workType?: number;
+  provider?: string;
 }
 
 export interface ModelRoutePort {
@@ -88,7 +90,7 @@ export function requiredStagesForWorkType(workType: number): AutoStage[] {
   switch (workType) {
     case 2:
     case 3:
-      return ["A", "C", "B", "D"];
+      return ["A", "B", "C", "D"];
     case 4:
       return ["A", "B", "D"];
     case 1:
@@ -101,6 +103,25 @@ export function requiredStagesForWorkType(workType: number): AutoStage[] {
   }
 }
 
+export function ascendingStages(stages: readonly AutoStage[]): AutoStage[] {
+  return STAGES.filter((stage) => stages.includes(stage));
+}
+
+export function emptyCatalogSetupMessage(runtimeName: RuntimeName): string {
+  if (runtimeName === "OMP") {
+    return [
+      "No authenticated and enabled OMP models were found.",
+      "Set up any provider subscription with /login, verify with `omp models` or /model, then run /pi-marg again.",
+      "PiMarg picks up whatever models you configure in OMP; see MODEL-SETUP.md.",
+    ].join(" ");
+  }
+  return [
+    "No authenticated and available Pi models were found.",
+    "Configure any provider subscription or API credentials, verify with `pi --list-models`, then retry.",
+    "PiMarg picks up whatever models you configure in Pi; see MODEL-SETUP.md.",
+  ].join(" ");
+}
+
 export function normalizeModelIdentity(value: string): string {
   let normalized = value
     .toLowerCase()
@@ -130,7 +151,7 @@ export function normalizeModelIdentity(value: string): string {
   return normalized;
 }
 
-export function classifyModel(model: ModelLike): ModelCandidate | undefined {
+export function classifyModel(model: ModelLike): ModelCandidate {
   const selector = `${model.provider}/${model.id}`;
   const haystack = `${model.provider} ${model.id} ${model.name ?? ""}`;
 
@@ -156,17 +177,20 @@ export function classifyModel(model: ModelLike): ModelCandidate | undefined {
       billingNote: "The runtime reports zero metered token cost; Devin plan quotas or pool limits may still apply.",
     };
   }
-  return undefined;
+  return candidate(model, selector, "runtime-available", "general");
 }
 
 export function buildModelCatalog(models: ModelLike[], hasExternalDevin: boolean) {
-  const candidates = models
-    .map(classifyModel)
-    .filter((item): item is ModelCandidate => Boolean(item))
-    .sort(compareCandidates);
+  const candidates = [...new Map(models.map((model) => {
+    const item = classifyModel(model);
+    return [item.selector, item] as const;
+  })).values()];
+
+  const frontier = [...candidates].sort((left, right) => compareForStage(left, right, "frontier"));
+  const execution = [...candidates].sort((left, right) => compareForStage(left, right, "execution"));
 
   if (hasExternalDevin) {
-    candidates.push({
+    execution.push({
       selector: "devin/external-session",
       identity: "devin-external-session",
       label: "Devin external session",
@@ -176,11 +200,116 @@ export function buildModelCatalog(models: ModelLike[], hasExternalDevin: boolean
       access: "external-agent",
       billingNote: "Uses Devin quota rather than a runtime model slot; session creation requires post-web approval.",
     });
+    execution.sort((left, right) => compareForStage(left, right, "execution"));
   }
 
-  const frontier = candidates.filter((item) => item.tier === "frontier");
-  const execution = candidates.filter((item) => item.tier === "execution");
-  return { A: frontier, B: execution, C: frontier, D: execution } satisfies Record<AutoStage, ModelCandidate[]>;
+  return {
+    A: frontier,
+    B: execution,
+    C: frontier,
+    D: execution,
+  } satisfies Record<AutoStage, ModelCandidate[]>;
+}
+
+export function numberedOptionLabel(index: number, text: string): string {
+  return `${index + 1}. ${text}`;
+}
+
+export function matchNumberedOption<T>(
+  answer: string | undefined,
+  items: readonly T[],
+  labelOf: (item: T) => string,
+): T | undefined {
+  if (!answer) return undefined;
+  return items.find((item, index) => numberedOptionLabel(index, labelOf(item)) === answer);
+}
+
+export function uniqueProviders(candidates: readonly ModelCandidate[]): string[] {
+  return [...new Set(candidates.map((candidate) => candidate.provider))].sort((left, right) => left.localeCompare(right));
+}
+
+export function candidatesForProvider(
+  candidates: readonly ModelCandidate[],
+  provider: string,
+): ModelCandidate[] {
+  return candidates.filter((candidate) => candidate.provider === provider);
+}
+
+export function formatCatalogPresentation(
+  runtimeName: RuntimeName,
+  catalog: Record<AutoStage, ModelCandidate[]>,
+  requiredStages: AutoStage[],
+  providerFilter?: string,
+) {
+  const notes = catalogNotes(runtimeName, catalog);
+  const orderedStages = ascendingStages(requiredStages);
+  const stages: Record<string, {
+    providers: Array<{ index: number; name: string; count: number }>;
+    providerFilter: string | null;
+    count: number;
+    options: Array<{
+      index: number;
+      selector: string;
+      label: string;
+      provider: string;
+      tier: CandidateTier;
+      choice: ModelCandidate["choice"];
+    }>;
+  }> = {};
+  const lines: string[] = [
+    `${runtimeName} model catalog`,
+    `Required stages: ${orderedStages.join(", ")}`,
+    "",
+  ];
+
+  for (const stage of orderedStages) {
+    const all = catalog[stage];
+    const providers = uniqueProviders(all).map((name, index) => ({
+      index: index + 1,
+      name,
+      count: candidatesForProvider(all, name).length,
+    }));
+    const shown = providerFilter ? candidatesForProvider(all, providerFilter) : [];
+    const options = shown.map((candidate, index) => ({
+      index: index + 1,
+      selector: candidate.selector,
+      label: candidate.label,
+      provider: candidate.provider,
+      tier: candidate.tier,
+      choice: candidate.choice,
+    }));
+    stages[stage] = {
+      providers,
+      providerFilter: providerFilter ?? null,
+      count: providerFilter ? shown.length : all.length,
+      options,
+    };
+
+    lines.push(`## Stage ${stage} (${all.length} models across ${providers.length} providers)`);
+    lines.push("Providers:");
+    for (const provider of providers) {
+      const marker = providerFilter === provider.name ? " ← selected" : "";
+      lines.push(`  ${provider.index}. ${provider.name} (${provider.count})${marker}`);
+    }
+    if (!providerFilter) {
+      lines.push("Call catalog again with provider=<name> to list every model for that provider.");
+    } else {
+      lines.push(`Models for ${providerFilter} (${shown.length}):`);
+      for (const option of options) {
+        lines.push(`  ${option.index}. ${option.label} — ${option.selector} [${option.tier}]`);
+      }
+    }
+    lines.push("");
+  }
+
+  for (const note of notes) lines.push(`- ${note}`);
+  lines.push("- Present every provider as 1,2,… then every model for the chosen provider as 1,2,… Never omit a logged-in provider.");
+  lines.push("- Select with action=select using the exact selector string.");
+
+  return {
+    text: lines.join("\n"),
+    presentation: { runtime: runtimeName, requiredStages: orderedStages, stages, notes },
+  };
 }
 
 export function validateDistinctSelection(
@@ -215,14 +344,42 @@ export async function executeModelRoute(
   const catalog = buildModelCatalog(port.models, port.hasExternalDevin);
 
   if (params.action === "catalog") {
+    if (port.models.length === 0) {
+      return {
+        state: currentState,
+        response: toolResult(
+          emptyCatalogSetupMessage(port.runtimeName),
+          { runtime: port.runtimeName, catalog, state: currentState },
+          true,
+        ),
+      };
+    }
     const workType = Number(params.workType);
     const requiredStages = Number.isInteger(workType) ? requiredStagesForWorkType(workType) : STAGES;
+    const providerFilter = typeof params.provider === "string" && params.provider.trim() ? params.provider.trim() : undefined;
+    if (providerFilter) {
+      const known = STAGES.some((stage) => catalog[stage].some((candidate) => candidate.provider === providerFilter));
+      if (!known) {
+        return {
+          state: currentState,
+          response: toolResult(
+            `Provider ${providerFilter} is not in the live authenticated catalog. Refresh catalog without a provider filter.`,
+            { runtime: port.runtimeName, requiredStages, catalog, state: currentState },
+            true,
+          ),
+        };
+      }
+    }
+    const formatted = formatCatalogPresentation(port.runtimeName, catalog, requiredStages, providerFilter);
     return {
       state: currentState,
-      response: toolResult(
-        JSON.stringify({ runtime: port.runtimeName, requiredStages, catalog, notes: catalogNotes(port.runtimeName, catalog) }, null, 2),
-        { runtime: port.runtimeName, requiredStages, catalog, state: currentState },
-      ),
+      response: toolResult(formatted.text, {
+        runtime: port.runtimeName,
+        requiredStages: formatted.presentation.requiredStages,
+        catalog,
+        presentation: formatted.presentation,
+        state: currentState,
+      }),
     };
   }
 
@@ -328,6 +485,16 @@ function compareCandidates(left: ModelCandidate, right: ModelCandidate): number
   return left.selector.localeCompare(right.selector);
 }
 
+function compareForStage(
+  left: ModelCandidate,
+  right: ModelCandidate,
+  preferredTier: Exclude<CandidateTier, "general">,
+): number {
+  const leftRank = left.tier === preferredTier ? 0 : left.tier === "general" ? 1 : 2;
+  const rightRank = right.tier === preferredTier ? 0 : right.tier === "general" ? 1 : 2;
+  return leftRank - rightRank || compareCandidates(left, right);
+}
+
 function toolResult(text: string, details: unknown, isError = false) {
   return {
     content: [{ type: "text" as const, text }],
@@ -336,13 +503,30 @@ function toolResult(text: string, details: unknown, isError = false) {
   };
 }
 
+function catalogHasProvider(catalog: Record<AutoStage, ModelCandidate[]>, provider: string): boolean {
+  return STAGES.some((stage) => catalog[stage].some((candidate) => candidate.provider === provider));
+}
+
 function catalogNotes(runtimeName: RuntimeName, catalog: Record<AutoStage, ModelCandidate[]>): string[] {
   const notes = [
-    `The catalog is built from ${runtimeName}'s authenticated model registry at call time; selectors are never guessed or pinned.`,
-    "A and C use frontier candidates. B and D use execution candidates, including eligible Cursor or Devin routes when the runtime exposes them.",
+    `The catalog shows every model in ${runtimeName}'s authenticated, enabled registry at call time; selectors are never guessed, pinned, or limited to a maintainer's subscriptions.`,
+    "A and C rank recognizable frontier fits first when present. B and D rank recognizable execution fits first when present. Every live model remains selectable for every stage.",
     "Zero-metered describes the runtime's reported token price; it does not promise unlimited subscription usage.",
   ];
-  if (catalog.A.length === 0) notes.push("No frontier matches are authenticated. Connect a provider, then refresh.");
-  if (catalog.B.length === 0) notes.push("No execution matches are authenticated and no external Devin tool was detected.");
+  if (!catalog.A.some((candidate) => candidate.tier === "frontier")) {
+    notes.push("No preferred frontier matches are authenticated; choose another available model or connect a provider.");
+  }
+  if (!catalog.B.some((candidate) => candidate.tier === "execution")) {
+    notes.push("No preferred execution matches are authenticated and no external Devin tool was detected; choose another available model.");
+  }
+  if (
+    runtimeName === "OMP"
+    && catalogHasProvider(catalog, "cursor")
+    && catalogHasProvider(catalog, "openai-codex")
+  ) {
+    notes.push(
+      "OMP compatibility warning (@oh-my-pi/pi-coding-agent 18.1.17): mid-session switches from cursor to openai-codex can reject tool call_id values longer than 64 characters when prior cursor-agent history is replayed. Start a fresh session that does not replay the affected tool history; branching alone is insufficient if that history is retained. This is a harness limitation, not a PiMarg model-routing failure.",
+    );
+  }
   return notes;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sangyaahub/pi-marg",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "A governed, model-routed development path for Pi Agent and Oh My Pi.",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,9 @@
     "multi-agent",
     "sangyaa"
   ],
+  "bin": {
+    "pi-marg": "bin/pi-marg.js"
+  },
   "files": [
     ".mcp.json",
     ".omp-plugin",
@@ -40,6 +43,7 @@
     "adapters",
     "agents",
     "assets",
+    "bin",
     "commands",
     "core",
     "rules",

package/scripts/install.sh

@@ -71,4 +71,4 @@ if [[ "${runtime}" == "omp" || "${runtime}" == "both" ]]; then
   omp plugin install --scope user pi-marg@pi-marg-marketplace
 fi
 
-echo "PiMarg v1.0.0 installed for ${runtime}. Start a fresh runtime session, then run /auto-runtime status."
+echo "PiMarg v1.0.3 installed for ${runtime}. Start a fresh runtime session, then run /pi-marg."

package/scripts/validate.sh

@@ -17,10 +17,13 @@ bun -e '
   const packageJson = await Bun.file("package.json").json();
   const marketplace = await Bun.file(".omp-plugin/marketplace.json").json();
   if (packageJson.name !== "@sangyaahub/pi-marg") throw new Error("Unexpected package name");
-  if (packageJson.version !== "1.0.0") throw new Error("package.json must be v1.0.0");
+  if (packageJson.version !== "1.0.3") throw new Error("package.json must be v1.0.3");
   if (packageJson.license !== "MIT") throw new Error("package.json must declare MIT");
   if (packageJson.author !== "Sangyaa") throw new Error("Unexpected package author");
   if (!packageJson.keywords?.includes("pi-package")) throw new Error("Pi catalog keyword is missing");
+  if (packageJson.bin?.["pi-marg"] !== "bin/pi-marg.js") throw new Error("PiMarg CLI bin mapping is missing");
+  if (!packageJson.files?.includes("bin")) throw new Error("PiMarg CLI is excluded from npm files");
+  if (!existsSync("bin/pi-marg.js")) throw new Error("PiMarg CLI entry point is missing");
   if (marketplace.name !== "pi-marg-marketplace") throw new Error("Unexpected marketplace name");
   if (marketplace.metadata?.version !== packageJson.version) throw new Error("Marketplace version mismatch");
   if (marketplace.plugins?.[0]?.version !== packageJson.version) throw new Error("Plugin version mismatch");

package/skills/auto-mode-router/references/intake-and-state.md

@@ -18,11 +18,14 @@ Ask one intake stage at a time. A clear user prompt can support a proposed class
 
 ## Stage 1 — work context
 
-Ask first:
+Ask first with numbered options:
 
 > Is this for your job/client, or is it personal work?
+>
+> 1. Job/client
+> 2. Personal
 
-Record exactly one:
+Record exactly one canonical value (`job-client` or `personal`); numbering is presentation-only:
 
 - `job-client`: Do not add Sangyaa branding, name, logo, metadata, footer, or promotional language. Use the employer/client/project brand already in scope.
 - `personal`: Existing project branding wins. Sangyaa branding is opt-in, never automatic.
@@ -58,6 +61,14 @@ Ask:
 
 Call `auto_model_route` with `action: catalog` and the confirmed work type. Present only selectors returned by the tool; do not type a remembered model ID.
 
+Catalog presentation is provider-first:
+
+1. Show **every** authenticated provider as numbered options `1.`, `2.`, … (including Devin when present). Never omit a logged-in provider and never curate down to Claude/Codex/Cursor only.
+2. After the user picks a provider, call `auto_model_route` again with the same work type and `provider=<name>` so the tool lists **every** model for that provider as numbered `1.`, `2.`, …
+3. Ask the user with those numbered labels. If the option UI cannot fit the full list, paste the numbered list into the question text and accept the number or exact selector.
+
+Interactive `/pi-marg` uses the same provider → model two-step with numbered labels.
+
 The four roles are:
 
 - A — thinking/discovery using a current Claude Fable/Opus, OpenAI Astra/Sol, or Grok 4.6-or-newer frontier model.
@@ -67,7 +78,7 @@ The four roles are:
 
 Ask only for stages required by the current work type. Work types 2–3 normally use A → C → B → D. Type 4 uses A → B → D and adds C only for a non-trivial plan. Types 1, 6, and 7 use A → C. Type 5 uses A → C for review and adds B → D when fixes are authorized.
 
-Use `action: select` for each answer. The active adapter saves exact selectors in session state and immediately activates the selected runtime model. Native `devin/swe-*` selectors behave like other models. An external Devin session requires `post-web` approval before creation.
+Use `action: select` for each answer with the **exact selector** string (for example `devin/swe-2`), not the display number alone. The active adapter saves exact selectors in session state and immediately activates the selected runtime model. Native `devin/swe-*` selectors behave like other models. An external Devin session requires `post-web` approval before creation.
 
 ## Stage 5 — native runtime and supporting capabilities
 

package/skills/auto-mode-router/references/models-and-tools.md

@@ -4,6 +4,8 @@
 
 `auto_model_route` builds its catalog from the active runtime every time it is called: Pi uses scoped or authenticated available models, while OMP uses `ctx.models.list()`. Exact versions come from that live registry, not this document.
 
+Catalog text is compact and provider-grouped. Call `action: catalog` first to list every provider with counts, then call again with `provider=<name>` to list every model for that provider as numbered options. Both OMP and Pi adapters accept the optional `provider` parameter. Never present a hand-curated Claude/Codex/Cursor subset when other authenticated providers (including Devin) are in the catalog.
+
 | Stage | Purpose | Eligible live groups | Normal agent and tools |
 |---|---|---|---|
 | A | Thinking/discovery | Claude Fable/Opus; OpenAI Astra/Sol; current Grok 4.6-or-newer | strategy skill; detected CodeGraph/LSP/AST tools, web for current facts; no implementation writes |
@@ -61,7 +63,9 @@ Call `auto_runtime_status` during intake. Follow [native-omp-runtime.md](native-
 - Security: detected `security_scan` when available, otherwise repository-native dependency audit, secret scan, SAST rules, configuration review, and source-to-sink inspection. Validate findings before changing code.
 - Current business/market facts: web research with source links; keep external posting disabled until approved.
 
-## Provider recommendation for the user's accounts
+## Provider recommendation (optional ranking only)
+
+These names are soft ranking hints. They are never required. PiMarg always picks up the live authenticated catalog for whoever is using it.
 
 - Cursor Composer or a zero-metered Cursor route: economical B/D work when present in the live catalog.
 - Claude Fable/Opus: A/C product thinking, architecture, specification, and cross-family review.
@@ -71,4 +75,4 @@ Call `auto_runtime_status` during intake. Follow [native-omp-runtime.md](native-
 - Latest matching Grok 4.6-or-newer model: A/C independent frontier analysis or current web/social context.
 - Native Devin SWE: B/D when exposed by the runtime. External Devin: bounded delegation with acceptance criteria and a quota limit.
 
-Use Pi or OMP's own authentication and model UI as the authority for what the account can actually access.
+Use Pi or OMP's own authentication and model UI as the authority for what the account can actually access. If the catalog is empty, promote subscription/provider setup (`/login` on OMP, or Pi credentials) before continuing. Present required stages in ascending A/B/C/D order.