@jinn-network/client 0.1.2 → 0.1.3-canary.24b69ea4

package/skills/jinn-operator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jinn-operator
-description: Set up and operate a Jinn Network agent. Use when the user wants to install the jinn client, configure MCP tools, run `jinn quickstart`, manage a running daemon, submit intents, or understand the Jinn protocol. Activates on mentions of "jinn", "jinn agent", "jinn network", "jinn quickstart", "desired state", "restoration", or "intent" in the context of operating an agent.
+description: Set up and operate a Jinn Network agent. Use when the user wants to install the jinn client, configure MCP tools, run `jinn run` or `jinn quickstart`, manage a running daemon, submit Tasks, or understand the Jinn protocol. Activates on mentions of "jinn", "jinn agent", "jinn network", "jinn run", "jinn quickstart", "Task", "SolverNet", "restoration", or "SolverPlugin" in the context of operating an agent.
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep
 ---
 
@@ -10,7 +10,7 @@ Guides you through installing, configuring, and operating a Jinn Network agent.
 
 ## What Is Jinn
 
-Jinn is a training protocol for agentic intents. It defines a loop:
+Jinn is a training protocol for agentic Tasks. It defines a loop:
 
 ```
 Creation  -->  Execution  -->  Evaluation  -->  Knowledge
@@ -18,8 +18,8 @@ Creation  -->  Execution  -->  Evaluation  -->  Knowledge
    +-----------------------------------------------+
 ```
 
-1. **Creation** — a creator publishes a *desired state* (an intent describing what should be true)
-2. **Execution** — a restorer claims the intent and attempts to make it true
+1. **Creation** — a creator publishes a Task describing work the network should perform
+2. **Execution** — a Solver claims the Task and attempts to solve it through the selected SolverNet
 3. **Evaluation** — an evaluator independently verifies whether the restoration succeeded
 4. **Knowledge** — artifacts (learnings, evidence) accumulate to improve future attempts
 
@@ -39,25 +39,57 @@ If not installed:
 npm install -g @jinn-network/client
 ```
 
-This gives you two binaries:
-- `jinn` — the operator CLI (17 verbs)
-- `jinn-mcp` — the MCP server for agent-to-agent operation
+This gives you the `jinn` operator CLI. The built-in MCP server is invoked via `jinn mcp` (see Phase 2).
 
 ### Prerequisites
 
 - **Node.js 22+** — `node --version` to check
 - **Claude Code CLI** — the daemon spawns Claude as a subprocess for restoration work. Must be installed and authenticated separately.
 
+### CLI verb reference
+
+<!-- skill:cli-table:start -->
+| Verb | What it does |
+|------|--------------|
+| `jinn version` | Print client version, protocol phase, and resolved token map |
+| `jinn doctor` | Preflight checks: answers "would jinn run work?" without running it |
+| `jinn init` | Generate the master wallet and write the encrypted keystore |
+| `jinn auth` | Check Claude authentication and persist how the operator runs the daemon |
+| `jinn bootstrap` | Advance the fleet state machine toward a running daemon |
+| `jinn fund-requirements` | List addresses that need funding before the next bootstrap step |
+| `jinn run` | Zero-to-running in one command: init, fund, bootstrap, then start the daemon in the foreground (stops on SIGINT/SIGTERM) |
+| `jinn stop` | Signal a running jinn daemon to shut down gracefully |
+| `jinn status` | Daemon liveness + roll-up (poll this for monitoring; pull detail separately) |
+| `jinn fleet` | Per-service fleet detail (wallets, staking, rewards, attention) |
+| `jinn balance` | Flat per-wallet balance map across master and service wallets |
+| `jinn history` | Recent protocol activity (Tasks, claims, deliveries, evaluations, rewards) |
+| `jinn rewards` | Earned vs claimed per service, per asset; next checkpoint time |
+| `jinn logs` | Structured event log (one JSON object per line) |
+| `jinn tasks` | Submit, list, and inspect Tasks |
+| `jinn solver-nets` | Enable SolverNets, select Harnesses, and attach SolverNet-scoped SolverPlugins |
+| `jinn harnesses` | List, inspect, add, and remove Harnesses |
+| `jinn solver-plugins` | Validate, inspect, and pack SolverPlugin packages |
+| `jinn integrations` | Configure host AI tools to use the Jinn MCP server and operator skill |
+| `jinn claim-rewards` | Pull pending protocol rewards to the fleet multisigs |
+| `jinn withdraw` | Sweep master / agents per withdraw flags |
+| `jinn keys` | Keystore management: backup, change-password |
+| `jinn update` | Update the client package and refresh integrations in all configured AI tools |
+| `jinn mcp` | Run the operator MCP server over stdio |
+| `jinn migrate-agent-id` | Backfill ERC-8004 agent_id on legacy complete services (jinn-mono-jgp) |
+| `jinn conformance` | Run the envelope + trajectory conformance suite against a signed envelope CID |
+<!-- skill:cli-table:end -->
+
 ## Phase 2: MCP Configuration
 
 If the user wants their agent (Claude Code, Cursor, etc.) to operate jinn programmatically, configure the MCP server:
 
-**For Claude Code** — add to project or user MCP settings:
+**For Claude Code** — run `jinn integrations install` (installs automatically) or add to project/user MCP settings manually:
 ```json
 {
   "mcpServers": {
     "jinn": {
-      "command": "jinn-mcp"
+      "command": "jinn",
+      "args": ["mcp"]
     }
   }
 }
@@ -69,7 +101,7 @@ If the user wants their agent (Claude Code, Cursor, etc.) to operate jinn progra
   "mcpServers": {
     "jinn": {
       "command": "npx",
-      "args": ["-y", "-p", "@jinn-network/client", "jinn-mcp"]
+      "args": ["-y", "-p", "@jinn-network/client", "jinn", "mcp"]
     }
   }
 }
@@ -77,30 +109,47 @@ If the user wants their agent (Claude Code, Cursor, etc.) to operate jinn progra
 
 Once configured, these MCP tools become available:
 
+<!-- skill:mcp-table:start -->
 | Tool | What it does |
-|------|-------------|
-| `jinn_init` | Create master wallet (idempotent) |
-| `jinn_doctor` | Preflight checks |
-| `jinn_status` | Daemon health + fleet roll-up |
-| `jinn_fleet` | Per-service detail |
-| `jinn_balance` | Wallet balances |
-| `jinn_history` | Recent protocol activity |
-| `jinn_rewards` | Earned vs claimed rewards |
-| `jinn_bootstrap` | Advance fleet state machine |
-| `jinn_submit_intent` | Post a desired state on-chain |
-| `jinn_start_daemon` | Start daemon in background |
-| `jinn_stop_daemon` | Stop running daemon |
-
-## Phase 3: Quickstart (Zero to Running)
-
-The fastest path from nothing to a running agent:
+|------|--------------|
+| `jinn_auth` | Read-only: check Claude authentication status and the resolved runtime mode (bare/docker-compose/container). Does NOT attempt login — it only probes and reports. Use this as the first call to verify the agent path is ready. Returns authenticated:true + context + email on success; returns an error envelope if not authenticated. Fast (<1s). |
+| `jinn_doctor` | Preflight checks: node version, claude binary, keystore, deployment config. Read-only. Fast (<5s). |
+| `jinn_fund_requirements` | Read-only: list addresses and amounts that need funding before bootstrap can advance. Note: the underlying command may hydrate wallet state as a side effect of checking funding. Returns an array of funding gaps; empty array means all funded. |
+| `jinn_status` | Daemon liveness and fleet health roll-up. Read-only. Poll this to monitor progress. Fast (<2s). |
+| `jinn_fleet` | Per-service fleet detail: wallets, staking status, activity counts. Read-only. Fast (<5s). |
+| `jinn_balance` | Flat per-wallet balance map across master and service wallets. Read-only. Requires RPC. Fast (<5s). |
+| `jinn_history` | Recent protocol activity: Tasks, claims, deliveries, evaluations, rewards. Read-only from local DB. Fast (<2s). |
+| `jinn_logs` | Recent activity event log from the local SQLite store. Read-only. Fast (<2s). Returns events with ts, level, component, msg fields. Call with limit=100 for monitoring; increase for deeper history. |
+| `jinn_rewards` | Pending and claimed reward balances per staked service. Read-only. Requires RPC access. Fast (<5s). Returns per-service pending/claimed amounts and next checkpoint time. |
+| `jinn_solver_nets_list` | List configured SolverNets with their enabled state, solverType, selected Harness, and plugin set. Read-only. Fast (<2s). |
+| `jinn_solver_nets_show` | Detailed status for one SolverNet. Read-only. Fast (<2s). |
+| `jinn_solver_nets_enable` | MUTATING: Enable a SolverNet and optionally select a Harness. Idempotent. May call Harness onEnable with SolverNet context. |
+| `jinn_solver_nets_disable` | MUTATING: Disable a SolverNet. Writes config. Idempotent. Fast (<1s). |
+| `jinn_tasks_submit` | MUTATING. Post a Task to the protocol. Idempotent by id. Sends an on-chain transaction and pays gas when confirmed. Requires confirm: true; default is preview (uses CLI --dry-run, no on-chain action). |
+| `jinn_init` | MUTATING. Create the master wallet and write the encrypted keystore. Idempotent: re-runs return the existing master address. Requires confirm: true; default is preview (no filesystem write). |
+| `jinn_run` | MUTATING: Zero-to-running in one call: resolve/generate password, init wallet, bootstrap fleet, start daemon. Idempotent — safe to call repeatedly; resumes from last completed step. Long-running: can take up to 30 minutes if funding is required. Returns a progress stream via --json-progress; poll jinn_status to monitor after this returns. Use no_daemon=true to skip starting the daemon (useful for CI or when the daemon is managed separately). |
+| `jinn_bootstrap` | MUTATING. Advance the fleet state machine. Idempotent. May take several minutes; can post on-chain transactions and request testnet faucet funds. Returns funding_required if a wallet needs ETH. Requires confirm: true; default is preview (no chain or filesystem mutation). |
+| `jinn_claim_rewards` | MUTATING. Pull pending protocol rewards to the fleet multisigs. Idempotent: zero-delta exits 0. Requires confirm: true; default is preview (uses CLI --dry-run, no on-chain action). |
+| `jinn_update` | MUTATING: Update the client package and refresh installed integrations. Step 1: npm update -g @jinn-network/client Step 2: jinn integrations install (refreshes skills in all configured AI tools). May take 1-2 minutes. Use skip_npm=true to only refresh integrations with the current version. |
+| `jinn_start_daemon` | MUTATING. Start the jinn daemon as a detached background process. Spawns a long-lived child process and writes a pidfile. Requires confirm: true; default is preview (does not spawn a process). |
+| `jinn_stop_daemon` | MUTATING. Stop the running jinn daemon. Idempotent: returns success even if already stopped. Requires confirm: true; default is preview (does not signal any process). |
+<!-- skill:mcp-table:end -->
+
+## Phase 3: Zero to Running
+
+The canonical first-run path — run these two commands in order:
 
 ```bash
-jinn quickstart
+# Step 1 — one-time: pick runtime mode and authenticate Claude Code (interactive TTY required).
+jinn auth
+
+# Step 2 — zero-to-running: auto-generates a keystore password, then init → fund → bootstrap → run.
+jinn run
 ```
 
-This single command:
-1. Generates a random keystore password (saved to `~/.jinn-client/keystore-password`)
+`jinn auth` persists the runtime-mode choice so all subsequent commands agree on how to spawn Claude.
+`jinn run` then:
+1. Generates a random keystore password (saved to `~/.jinn-client/keystore-password`, mode 0600)
 2. Creates the master wallet
 3. Funds via Coinbase CDP faucet (automatic on testnet)
 4. Bootstraps the fleet (Safe wallet, service registration, staking, mech deployment)
@@ -108,104 +157,69 @@ This single command:
 
 When it finishes: **open `http://localhost:7331`** for the operator dashboard.
 
-### If the user already has JINN_PASSWORD set:
+### Advanced / CI: explicit password
+
+If you want to manage the password yourself (recommended for production or CI pipelines), set `JINN_PASSWORD` before calling `jinn run`. No file will be written to disk:
 
 ```bash
-JINN_PASSWORD=their-password jinn quickstart
+JINN_PASSWORD=their-password jinn run
 ```
 
-The command respects an existing password and won't generate a new one.
+For CI, prefer reading the password from a file descriptor: `--password-fd N`.
 
-### If quickstart stops at "funding required":
+### If `jinn run` stops at "funding required":
 
 The automatic faucet may have rate-limited (1 claim per 24 hours per address). Options:
-- Wait 24 hours and re-run `jinn quickstart`
+- Wait 24 hours and re-run `jinn run`
 - Fund manually: go to https://portal.cdp.coinbase.com/products/faucet, send testnet ETH to the printed master address, then re-run
 
-## Phase 3.5: Opting In to Intent Kinds
+## Phase 3.5: Opting In to SolverNets
 
-After quickstart, the daemon participates in `legacy` (health-check) and `prediction.v0` intents by default. Other intent kinds are **off by default** because they require operator-specific credentials (exchange authorizations, API keys, etc.).
+After `jinn run` brings the fleet up, the Prediction SolverNet is enabled by default. Other
+SolverNets are off by default because they may require operator-specific
+credentials, APIs, or Harness choices.
 
-### Generic flow (applies to every intent kind with external deps)
+### Generic flow
 
-**Always start with `list`.** It tells you what's enabled, what's ready, and for disabled kinds, what running `enable` would need.
+Start with `list`. It tells you which SolverNets are enabled, which SolverType
+each one serves, and which Harness each one uses.
 
 ```bash
-jinn intents list --human
+jinn solver-nets list
 ```
 
 Example output for a fresh operator:
 ```
-kind           enabled   ready   notes
-portfolio.v0   no        no      HL api-wallet not provisioned
-prediction.v0  yes       yes
+name          solverType       enabled   harness
+prediction    prediction.v0    yes       claude-code-learner
 ```
 
-### Enabling a kind (idempotent state machine)
+### Enabling a SolverNet
 
 ```bash
-jinn intents enable <kind> [--key=value ...]
+jinn solver-nets enable <name> [--harness <name>]
 ```
 
-The command is idempotent. Rerun the same command until the response has `"status": "ready"`. Intermediate states tell you exactly what to do:
-
-- `"status": "missing_args"` — the envelope lists `required` args. Re-run with them. Shape:
-  ```json
-  {
-    "status": "missing_args",
-    "required": [{"name": "hl-master", "description": "...", "required": true}],
-    "example": {"cli": "jinn intents enable portfolio.v0 --hl-master 0x..."}
-  }
-  ```
-
-- `"status": "waiting_for_external_action"` — the operator needs to do something out-of-band (e.g., approve an api-wallet on an exchange). Show the `action.description` and `action.url` to the operator. When they confirm done, run the command in `nextInvocation.cli`. Shape:
-  ```json
-  {
-    "status": "waiting_for_external_action",
-    "action": {"description": "...", "url": "https://..."},
-    "details": {"apiWalletAddress": "0x..."},
-    "nextInvocation": {"cli": "jinn intents enable <kind> --confirm-approved", "purpose": "..."}
-  }
-  ```
-
-- `"status": "ready"` — the kind is enabled. The daemon will now claim intents of this kind. No further action.
+SolverPlugins are scoped to SolverNets, not injected globally into Harnesses:
 
-- `"status": "error"` — surface `message` to the operator.
+- `jinn solver-nets set-harness prediction <harness>` changes the Harness used for restoration Tasks.
+- `jinn solver-nets add-plugin prediction <source>` attaches an extra SolverPlugin to only that SolverNet.
+- `jinn solver-nets doctor prediction` validates the canonical plugin, extra plugins, schemas, and Harness wiring.
 
 ### Disabling
 
 ```bash
-jinn intents disable <kind>
+jinn solver-nets disable <name>
 ```
 
-Removes the kind from the operator's claim rotation. Preserves any generated key material so a later `enable` doesn't re-initialize exchange approvals.
-
-### Example: enabling portfolio.v0
-
-portfolio.v0 requires a Hyperliquid master account (holds USDC) and an approved HL api-wallet (agent key). The enable flow walks the operator through it:
-
-1. Run list to see what's needed:
-   ```bash
-   jinn intents list --human
-   jinn intents status portfolio.v0 --human
-   ```
-
-2. First invocation generates the api-wallet keypair and returns `waiting_for_external_action` with the wallet address and the HL URL:
-   ```bash
-   jinn intents enable portfolio.v0 --hl-master 0xYOUR_HL_MASTER
-   ```
-
-3. Surface the wallet address and URL to the operator. They approve the address on HL (Settings → API Wallets → Add).
-
-4. Once they confirm, re-run with `--confirm-approved`:
-   ```bash
-   jinn intents enable portfolio.v0 --confirm-approved
-   ```
-   Envelope returns `"status": "ready"`. Config is updated. Daemon will claim future portfolio.v0 requests.
+Removes the SolverNet from the operator's claim rotation. It does not uninstall
+the Harness or delete SolverPlugin packages.
 
 ### Runtime guardrail
 
-The daemon checks each impl's readiness before spending gas on a claim transaction. If a portfolio.v0 request arrives and the api-wallet is missing/unapproved, the intent is marked FAILED locally with a reason pointing back to `jinn intents enable portfolio.v0 ...`. No gas wasted.
+The daemon checks SolverNet and Harness readiness before spending gas on a claim
+transaction. If a Task arrives for an unknown or disabled SolverNet, the daemon
+does not claim it.
 
 ## Phase 4: Ongoing Operation
 
@@ -216,15 +230,19 @@ The daemon checks each impl's readiness before spending gas on a claim transacti
 - **Fleet detail:** `jinn fleet` shows each service's step, Safe, mech, staking status
 - **Balances:** `jinn balance` shows master and service wallet balances
 
-### Submitting Intents
+### Submitting Tasks
 
-To post a desired state for the network to work on:
+To post a Task for the network to work on:
 
 ```bash
-jinn submit-intent --id my-intent --description "The service publishes a daily summary" --yes
+jinn tasks submit --id my-task --description "The service publishes a daily summary" --solver-net prediction --yes
 ```
 
-Or via MCP: call `jinn_submit_intent` with `id` and `description` parameters.
+Or via MCP: call `jinn_tasks_submit` with `id`, `description`, and either
+`solver_net` or `solver_type`. Mutating MCP tools default to a preview envelope;
+pass `confirm: true` to actually post on-chain. Other mutating tools
+(`jinn_init`, `jinn_bootstrap`, `jinn_start_daemon`, `jinn_stop_daemon`) follow
+the same `confirm: true` rule.
 
 ### Checking Rewards
 
@@ -236,7 +254,7 @@ Shows pending vs claimed rewards per service.
 
 ### Changing the Auto-Generated Password
 
-If the user started with `jinn quickstart` and wants to set their own password:
+If the user started with `jinn run` and wants to set their own password:
 
 ```bash
 JINN_NEW_PASSWORD=their-new-password jinn keys change-password
@@ -280,13 +298,14 @@ Bootstrap may need multiple runs if it hit a funding gate partway through. Re-ru
 
 When operating jinn tools, keep this mental model:
 
-- **`jinn quickstart`** is the one-shot setup. After this, the daemon is running.
+- **`jinn run`** is the one-shot setup. After this, the daemon is running.
 - **`jinn status`** is your health check. Poll it to know if things are working.
-- **`jinn submit-intent`** is the main action verb. This is how you create work on the network.
+- **`jinn tasks submit`** is the main action verb. This is how you create work on the network.
+- **`jinn solver-nets`** is how you choose which SolverNets this operator participates in and which Harness each SolverNet uses.
 - **`jinn fleet`** tells you about your staked services and their state.
 - **`jinn bootstrap`** is idempotent. If anything is stuck, re-running it is always safe.
 - **`funding_required`** means "the wallet needs ETH." On testnet, this should auto-resolve via faucet. If not, the user needs to fund manually.
-- The daemon runs three loops: creator (posts intents), restorer (claims and fulfills intents), delivery-watcher (evaluates results). All three run automatically once the daemon starts.
+- The daemon runs three loops: creator (posts Tasks), Solver (claims and solves Tasks), delivery-watcher (evaluates results). All three run automatically once the daemon starts.
 
 ## Network Details
 

package/templates/harnesses/alternative-harness/README.md.tmpl

@@ -0,0 +1,44 @@
+# {{packageName}}
+
+Jinn external harness for `{{solverTypeString}}` running the **seven-phase
+learning pipeline** (Orient -> Strategize -> Plan -> Execute -> Debrief
+-> Improve -> Memory) against a non-Claude-Code harness.
+
+This package owns the phase orchestration; the harness is a swappable
+runtime. Tests use a deterministic in-process mock harness; production
+builders swap `createMockHarness` for a real harness (Pi.dev, Codex,
+Gemini CLI, custom).
+
+## Quickstart
+
+```bash
+yarn install
+yarn test
+```
+
+## Plugging in your real harness
+
+Implement the `HarnessAdapter` interface (see `src/harness.ts`):
+
+```ts
+import type { HarnessAdapter } from '{{packageName}}';
+
+export const myHarness: HarnessAdapter = {
+  name: 'my-harness',
+  async promptForJson({ systemPrompt, userPrompt, budgetMs, abort }) {
+    // Spawn / call your harness; parse its JSON response; return.
+  },
+};
+```
+
+Then construct the harness with your factory:
+
+```ts
+import createHarness from '{{packageName}}';
+const impl = createHarness(env, { harnessFactory: () => myHarness });
+```
+
+## Spec
+
+- `spec/2026-04-30-plug-in-surface.md` §3.3.3 (alternative-harness pattern).
+- `docs/superpowers/specs/2026-04-23-default-learning-harness-design.md` §2 (phase pipeline definition).

package/templates/harnesses/alternative-harness/gitignore.tmpl

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+.DS_Store

package/templates/harnesses/alternative-harness/jinn.manifest.json.tmpl

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "1.0.0",
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Alternative-harness harness for {{solverTypeString}}.",
+  "supportedSolverTypes": ["{{solverTypeString}}>=1.0.0"],
+  "entry": "./dist/index.js",
+  "package": {
+    "cid": "bafy-PLACEHOLDER",
+    "hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "capabilities": {
+    "rpc": [
+      { "chainId": {{networkChainId}}, "methods": ["eth_call", "eth_blockNumber"] }
+    ]
+  },
+  "signature": {
+    "alg": "ed25519",
+    "publicKey": "PLACEHOLDER",
+    "sig": "PLACEHOLDER"
+  }
+}

package/templates/harnesses/alternative-harness/package.json.tmpl

@@ -0,0 +1,26 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn external harness running the seven-phase learning pipeline against a non-Claude-Code harness. {{solverTypeString}} only.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist/", "jinn.manifest.json", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@jinn-network/sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

package/templates/harnesses/alternative-harness/src/coordinator.ts.tmpl

@@ -0,0 +1,50 @@
+import type {
+  HarnessContext,
+  Solution,
+} from '@jinn-network/sdk/harness';
+import type { HarnessAdapter } from './harness.js';
+import { runOrient } from './phases/orient.js';
+import { runStrategize } from './phases/strategize.js';
+import { runPlan } from './phases/plan.js';
+import { runExecute } from './phases/execute.js';
+import { runDebrief } from './phases/debrief.js';
+import { runImprove } from './phases/improve.js';
+import { runMemory } from './phases/memory.js';
+
+export interface CoordinatorArgs {
+  ctx: HarnessContext;
+  harness: HarnessAdapter;
+}
+
+/**
+ * Sequence the seven phases (orient, strategize, plan, execute,
+ * debrief, improve, memory). Mirrors `spec/2026-04-30-plug-in-surface.md`
+ * §3.3.3 and `docs/superpowers/specs/2026-04-23-default-learning-harness-design.md` §2.
+ */
+export async function runCoordinator({
+  ctx,
+  harness,
+}: CoordinatorArgs): Promise<Solution> {
+  const orient = await runOrient({ ctx, harness });
+  const strategy = await runStrategize({ ctx, harness, orient });
+  const plan = await runPlan({ ctx, harness, strategy, orient });
+  const execute = await runExecute({ ctx, harness, plan, strategy });
+  const debrief = await runDebrief({ ctx, harness, execute, strategy });
+  await runImprove({ ctx, harness, debrief });
+  await runMemory({ ctx, harness, debrief });
+
+  return {
+    venueRef: { name: harness.name },
+    gating: {
+      timingPosture: strategy.timingPosture,
+      executeReturnReason: execute.returnReason,
+      debriefVerdict: debrief.successCriteriaMet,
+    },
+    informational: {
+      strategyApproach: strategy.approach,
+      planSteps: plan.steps.length,
+      stepsCompleted: execute.stepsCompleted.length,
+      stepsFailed: execute.stepsFailed.length,
+    },
+  };
+}

package/templates/harnesses/alternative-harness/src/harness.ts.tmpl

@@ -0,0 +1,31 @@
+// HarnessAdapter contract — the impl talks to the harness through this
+// interface. The package owns this type; it does NOT depend on
+// `claude-code-learner/types.ts` (which is internal to that package).
+//
+// Production builders implement this around their own runtime
+// (Pi.dev, Codex CLI, Gemini CLI, custom subprocess, etc.).
+
+export interface HarnessPromptArgs {
+  promptId: string;
+  systemPrompt: string;
+  userPrompt: string;
+  /** Per-phase budget in ms. Caller honours abort. */
+  budgetMs: number;
+  abort: AbortSignal;
+}
+
+export interface HarnessAdapter {
+  readonly name: string;
+
+  /**
+   * Send a prompt to the harness's underlying agent runtime; receive a
+   * structured JSON result. Used by every phase.
+   */
+  promptForJson<T>(args: HarnessPromptArgs): Promise<T>;
+
+  /**
+   * Optional: signal that a phase has finished, for harnesses that
+   * persist conversation state across calls (e.g. Pi.dev's session model).
+   */
+  closePhase?(phaseId: string): Promise<void>;
+}

package/templates/harnesses/alternative-harness/src/index.ts.tmpl

@@ -0,0 +1,44 @@
+import type {
+  Harness,
+  ExternalHarnessEnv,
+  HarnessContext,
+  Solution,
+} from '@jinn-network/sdk/harness';
+import type { HarnessAdapter } from './harness.js';
+import { runCoordinator } from './coordinator.js';
+import { createMockHarness } from './mock-harness.js';
+
+export interface AlternativeHarnessConfig {
+  /** The harness to drive. Defaults to the deterministic mock for tests. */
+  harnessFactory?: (env: ExternalHarnessEnv) => HarnessAdapter;
+}
+
+export default function createHarness(
+  env: ExternalHarnessEnv,
+  config: AlternativeHarnessConfig = {},
+): Harness {
+  const factory = config.harnessFactory ?? createMockHarness;
+  const harness = factory(env);
+  return {
+    name: env.implName,
+    version: env.implVersion,
+    supports({ solverType, role }) {
+      return solverType === '{{solverTypeString}}' && role !== 'evaluation';
+    },
+    async isReady() {
+      return env.stub
+        ? { ready: false, reason: 'stub mode' }
+        : { ready: true };
+    },
+    async run(ctx: HarnessContext): Promise<Solution> {
+      env.log({
+        level: 'info',
+        msg: 'alternative-harness.start',
+        data: { taskId: ctx.task.id },
+      });
+      return runCoordinator({ ctx, harness });
+    },
+  };
+}
+
+export type { HarnessAdapter, HarnessPromptArgs } from './harness.js';

package/templates/harnesses/alternative-harness/src/mock-harness.ts.tmpl

@@ -0,0 +1,41 @@
+import type { ExternalHarnessEnv } from '@jinn-network/sdk/harness';
+import type { HarnessAdapter, HarnessPromptArgs } from './harness.js';
+
+/**
+ * Deterministic in-process mock harness. Returns canned per-phase
+ * shapes so tests run offline. Real builders replace this with a
+ * subprocess wrapper around their actual harness (Pi.dev, Codex, etc.).
+ */
+export function createMockHarness(_env: ExternalHarnessEnv): HarnessAdapter {
+  return {
+    name: 'mock-harness',
+    async promptForJson<T>({ promptId }: HarnessPromptArgs): Promise<T> {
+      switch (promptId) {
+        case 'orient':
+          return { topics: [{ name: 'task-parse', summary: 'parsed' }] } as T;
+        case 'strategize':
+          return {
+            approach: 'mock approach',
+            successCriteria: 'always succeed',
+            timingPosture: 'early-return',
+          } as T;
+        case 'plan':
+          return { steps: [{ id: 's1', description: 'do the thing' }] } as T;
+        case 'execute':
+          return {
+            stepsCompleted: ['s1'],
+            stepsFailed: [],
+            returnReason: 'all-steps-completed',
+          } as T;
+        case 'debrief':
+          return { successCriteriaMet: 'yes', rationale: 'mock rationale' } as T;
+        case 'improve':
+          return { mutations: [] } as T;
+        case 'memory':
+          return { kept: 0, pruned: 0 } as T;
+        default:
+          throw new Error(`mock-harness: unknown promptId ${promptId}`);
+      }
+    },
+  };
+}

package/templates/harnesses/alternative-harness/src/phases/debrief.ts.tmpl

@@ -0,0 +1,28 @@
+import type { HarnessContext } from '@jinn-network/sdk/harness';
+import type { HarnessAdapter } from '../harness.js';
+import type { ExecuteResult } from './execute.js';
+import type { StrategyResult } from './strategize.js';
+
+export type DebriefVerdict = 'yes' | 'no' | 'partial';
+
+export interface DebriefResult {
+  successCriteriaMet: DebriefVerdict;
+  rationale: string;
+}
+
+export async function runDebrief(args: {
+  ctx: HarnessContext;
+  harness: HarnessAdapter;
+  execute: ExecuteResult;
+  strategy: StrategyResult;
+}): Promise<DebriefResult> {
+  const { ctx, harness, execute, strategy } = args;
+  return harness.promptForJson<DebriefResult>({
+    promptId: 'debrief',
+    systemPrompt:
+      'Decide whether the frozen success criteria were met. Be honest.',
+    userPrompt: JSON.stringify({ task: ctx.task, strategy, execute }),
+    budgetMs: Math.min(ctx.msUntilEndTs(), 15_000),
+    abort: ctx.abort,
+  });
+}