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

package/dist/x402/handler.js

@@ -1,40 +1,205 @@
 /**
  * x402 payment-gated artifact serving.
- * Adds payment middleware to Hono app for artifact content access.
- * Ported from protocol/src/x402/handler.ts.
+ *
+ * Single route, dynamic per-row price (spec/2026-04-30-phase-a-umbrella.md §5.4):
+ *   priceUsdc='0'  → respond 200 immediately, no payment dance.
+ *   priceUsdc>'0'  → emit 402 with payment requirements built from the row's
+ *                    price; on valid X-PAYMENT, verify + settle via local
+ *                    facilitator, then 200.
+ *
+ * The route is keyed by sha256, matching the artifact identifier in the signed
+ * envelope (post jinn-mono-vy37.1.2 — artifacts no longer have IPFS CIDs).
  */
-import { paymentMiddleware } from '@x402/hono';
-import { x402ResourceServer } from '@x402/core/server';
-import { registerExactEvmScheme } from '@x402/evm/exact/server';
 import { createLocalFacilitatorClient } from './facilitator.js';
+function dollarStringFromUsdc(usdc) {
+    // X402 'exact' scheme expects a string like '$0.001' for USDC amounts.
+    return `$${usdc}`;
+}
+function mimeForArtifactType(artifactType) {
+    if (!artifactType)
+        return 'application/octet-stream';
+    const t = artifactType.toLowerCase();
+    if (t.includes('markdown') || t.includes('.md'))
+        return 'text/markdown';
+    if (t.includes('tar') || t.includes('gz'))
+        return 'application/gzip';
+    return 'application/octet-stream';
+}
+function requestMeta(c) {
+    return {
+        remoteAddr: c.req.header('x-forwarded-for')?.split(',')[0]?.trim()
+            ?? c.req.header('cf-connecting-ip')
+            ?? null,
+        userAgent: c.req.header('user-agent') ?? null,
+    };
+}
+function stringFromRecord(value, keys) {
+    let current = value;
+    for (const key of keys) {
+        if (typeof current !== 'object' || current === null)
+            return null;
+        current = current[key];
+    }
+    return typeof current === 'string' && current.length > 0 ? current : null;
+}
+function payerFromPayload(payload) {
+    return (stringFromRecord(payload, ['payload', 'authorization', 'from'])
+        ?? stringFromRecord(payload, ['payload', 'permit2Authorization', 'owner'])
+        ?? stringFromRecord(payload, ['payer']));
+}
+function stringField(value, key) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const raw = value[key];
+    return typeof raw === 'string' && raw.length > 0 ? raw : null;
+}
+function safeRecordAccess(store, input) {
+    try {
+        store.recordArtifactAccessEvent(input);
+    }
+    catch (err) {
+        console.warn(`[x402] Failed to record artifact access event for ${input.sha256}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 export function addX402Routes(app, store, config) {
-    const facilitatorClient = createLocalFacilitatorClient({
+    const facilitator = createLocalFacilitatorClient({
         privateKey: config.privateKey,
         network: config.network,
         rpcUrl: config.rpcUrl,
     });
     const network = (config.network ?? 'eip155:8453');
-    const price = config.pricePerArtifact ?? '$0.001';
-    const resourceServer = new x402ResourceServer(facilitatorClient);
-    registerExactEvmScheme(resourceServer);
-    const routes = {
-        'GET /x402/artifacts/:id/content': {
-            accepts: {
+    app.get('/v1/artifacts/:sha256/content', async (c) => {
+        const sha256 = c.req.param('sha256');
+        if (!sha256)
+            return c.json({ error: 'Missing sha256' }, 400);
+        const row = store.getServedArtifact(sha256);
+        if (!row) {
+            safeRecordAccess(store, {
+                sha256,
+                artifactType: null,
+                priceUsdc: null,
+                outcome: 'not_found',
+                httpStatus: 404,
+                createdAt: new Date().toISOString(),
+                ...requestMeta(c),
+            });
+            return c.json({ error: 'Not found' }, 404);
+        }
+        if (row.priceUsdc === '0') {
+            safeRecordAccess(store, {
+                sha256,
+                artifactType: row.artifactType,
+                priceUsdc: row.priceUsdc,
+                outcome: 'free_served',
+                httpStatus: 200,
+                createdAt: new Date().toISOString(),
+                ...requestMeta(c),
+            });
+            c.header('Content-Type', mimeForArtifactType(row.artifactType));
+            c.header('X-Artifact-Type', row.artifactType ?? '');
+            return c.body(new Uint8Array(row.content));
+        }
+        // Paid path
+        const accepts = [{
                 scheme: 'exact',
                 payTo: config.recipientAddress,
-                price,
+                price: dollarStringFromUsdc(row.priceUsdc),
                 network,
-            },
-            description: 'Access artifact content',
-        },
-    };
-    app.use(paymentMiddleware(routes, resourceServer));
-    app.get('/x402/artifacts/:id/content', async (c) => {
-        const id = c.req.param('id');
-        const content = store.getArtifactContent(id);
-        if (content === null)
-            return c.json({ error: 'Not found' }, 404);
-        return c.json({ content });
+                description: `artifact ${sha256.slice(0, 12)}…`,
+            }];
+        const xPayment = c.req.header('X-Payment');
+        if (!xPayment) {
+            safeRecordAccess(store, {
+                sha256,
+                artifactType: row.artifactType,
+                priceUsdc: row.priceUsdc,
+                outcome: 'payment_required',
+                httpStatus: 402,
+                createdAt: new Date().toISOString(),
+                ...requestMeta(c),
+            });
+            return c.json({ accepts }, 402);
+        }
+        let decoded;
+        try {
+            decoded = JSON.parse(Buffer.from(xPayment, 'base64').toString('utf-8'));
+            const requirement = accepts.find((a) => a.scheme === decoded.scheme);
+            if (!requirement) {
+                safeRecordAccess(store, {
+                    sha256,
+                    artifactType: row.artifactType,
+                    priceUsdc: row.priceUsdc,
+                    outcome: 'payment_malformed',
+                    httpStatus: 402,
+                    payer: payerFromPayload(decoded.payload),
+                    errorReason: 'unsupported_payment_scheme',
+                    createdAt: new Date().toISOString(),
+                    ...requestMeta(c),
+                });
+                return c.json({ error: 'Unsupported payment scheme', accepts }, 402);
+            }
+            const verification = await facilitator.verify(decoded.payload, requirement);
+            if (!verification.isValid) {
+                const reason = verification.invalidReason ?? 'Payment verification failed';
+                safeRecordAccess(store, {
+                    sha256,
+                    artifactType: row.artifactType,
+                    priceUsdc: row.priceUsdc,
+                    outcome: 'verification_failed',
+                    httpStatus: 402,
+                    payer: stringField(verification, 'payer') ?? payerFromPayload(decoded.payload),
+                    errorReason: reason,
+                    createdAt: new Date().toISOString(),
+                    ...requestMeta(c),
+                });
+                return c.json({ error: reason, accepts }, 402);
+            }
+            const settlement = await facilitator.settle(decoded.payload, requirement);
+            if (!settlement.success) {
+                const reason = settlement.errorReason ?? 'Settlement failed';
+                safeRecordAccess(store, {
+                    sha256,
+                    artifactType: row.artifactType,
+                    priceUsdc: row.priceUsdc,
+                    outcome: 'settlement_failed',
+                    httpStatus: 402,
+                    payer: stringField(settlement, 'payer') ?? stringField(verification, 'payer') ?? payerFromPayload(decoded.payload),
+                    settlementTx: stringField(settlement, 'transaction'),
+                    errorReason: reason,
+                    createdAt: new Date().toISOString(),
+                    ...requestMeta(c),
+                });
+                return c.json({ error: reason, accepts }, 402);
+            }
+            safeRecordAccess(store, {
+                sha256,
+                artifactType: row.artifactType,
+                priceUsdc: row.priceUsdc,
+                outcome: 'paid_served',
+                httpStatus: 200,
+                payer: stringField(settlement, 'payer') ?? stringField(verification, 'payer') ?? payerFromPayload(decoded.payload),
+                settlementTx: stringField(settlement, 'transaction'),
+                createdAt: new Date().toISOString(),
+                ...requestMeta(c),
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            safeRecordAccess(store, {
+                sha256,
+                artifactType: row.artifactType,
+                priceUsdc: row.priceUsdc,
+                outcome: 'payment_malformed',
+                httpStatus: 402,
+                errorReason: msg,
+                createdAt: new Date().toISOString(),
+                ...requestMeta(c),
+            });
+            return c.json({ error: `Payment validation error: ${msg}`, accepts }, 402);
+        }
+        c.header('Content-Type', mimeForArtifactType(row.artifactType));
+        c.header('X-Artifact-Type', row.artifactType ?? '');
+        return c.body(new Uint8Array(row.content));
     });
 }
 //# sourceMappingURL=handler.js.map

package/dist/x402/handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../src/x402/handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAUhE,MAAM,UAAU,aAAa,CAAC,GAAS,EAAE,KAAY,EAAE,MAAkB;IACvE,MAAM,iBAAiB,GAAG,4BAA4B,CAAC;QACrD,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,aAAa,CAAY,CAAC;IAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,gBAAgB,IAAI,QAAQ,CAAC;IAElD,MAAM,cAAc,GAAG,IAAI,kBAAkB,CAAC,iBAAiB,CAAC,CAAC;IACjE,sBAAsB,CAAC,cAAc,CAAC,CAAC;IAEvC,MAAM,MAAM,GAAG;QACb,iCAAiC,EAAE;YACjC,OAAO,EAAE;gBACP,MAAM,EAAE,OAAO;gBACf,KAAK,EAAE,MAAM,CAAC,gBAAgB;gBAC9B,KAAK;gBACL,OAAO;aACR;YACD,WAAW,EAAE,yBAAyB;SACvC;KACF,CAAC;IAEF,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAEnD,GAAG,CAAC,GAAG,CAAC,6BAA6B,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QACjD,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,MAAM,OAAO,GAAG,KAAK,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC;QAC7C,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC;QACjE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../src/x402/handler.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@jinn-network/client",
-  "version": "0.1.2",
+  "version": "0.1.3-canary.24b69ea4",
   "description": "Jinn protocol client — headless daemon for the restoration training loop",
   "type": "module",
   "packageManager": "yarn@4.13.0",
+  "workspaces": [
+    "src/dashboard/spa"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,14 +19,16 @@
   "bin": {
     "client": "./dist/bin/jinn.js",
     "jinn": "./dist/bin/jinn.js",
-    "jinn-mcp": "./dist/bin/jinn-mcp.js"
+    "jinn-stop-hook": "./dist/bin/jinn-stop-hook.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
     "dist/",
     "deployments/",
+    "plugins/",
     "skills/",
+    "templates/",
     "docker-compose.yml",
     "CONTRIBUTING.md",
     "CHANGELOG.md",
@@ -34,17 +39,24 @@
     "access": "public"
   },
   "scripts": {
+    "postinstall": "node dist/scripts/fix-node-pty.mjs 2>/dev/null || node scripts/fix-node-pty.mjs 2>/dev/null || true",
+    "e2e:full-cycle": "tsx test/e2e/claude-code-learner-full-cycle.ts",
     "jinn": "tsx src/bin/jinn.ts",
     "dev": "yarn build && node dist/bin/jinn.js",
-    "build": "tsc && chmod +x dist/bin/jinn.js dist/bin/jinn-mcp.js && mkdir -p dist/dashboard && cp src/dashboard/index.html dist/dashboard/index.html && node scripts/write-dist-build-meta.mjs",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "build:sdk": "yarn --cwd ../packages/sdk install --immutable && yarn --cwd ../packages/sdk build",
+    "build": "yarn build:sdk && yarn build:spa && tsc && chmod +x dist/bin/jinn.js && rm -rf dist/dashboard && mkdir -p dist/dashboard && cp -R src/dashboard/spa/dist/. dist/dashboard/ && rm -rf dist/templates && cp -R templates dist/templates && mkdir -p dist/scripts && cp scripts/fix-node-pty.mjs dist/scripts/ && node scripts/vendor-sdk.mjs && node scripts/write-dist-build-meta.mjs",
+    "typecheck": "yarn build:sdk && tsc --noEmit",
+    "test": "yarn build:sdk && vitest run",
     "test:watch": "vitest",
-    "test:claude-prediction": "yarn build && JINN_TEST_CLAUDE_PREDICTION=1 vitest run test/restorer/impls/claude-mcp-prediction/isolation.test.ts",
-    "test:claude-prediction-apy": "yarn build && JINN_TEST_CLAUDE_PREDICTION_APY=1 vitest run test/restorer/impls/claude-mcp-prediction-apy/isolation.test.ts",
+    "test:claude-prediction": "yarn build && JINN_TEST_CLAUDE_PREDICTION=1 vitest run test/harnesses/impls/claude-mcp-prediction/isolation.test.ts",
+    "test:claude-prediction-apy": "yarn build && JINN_TEST_CLAUDE_PREDICTION_APY=1 vitest run test/harnesses/impls/claude-mcp-prediction-apy/isolation.test.ts",
+    "skill:generate": "tsx scripts/skill-generate.ts",
+    "skill:check": "tsx scripts/skill-check.ts",
     "prepublishOnly": "yarn build && yarn test",
-    "pack:smoke": "yarn pack -o jinn-client.tgz && node scripts/smoke-test-pack.mjs",
+    "pack:smoke": "node scripts/smoke-test-pack.mjs",
+    "release:client": "node scripts/release-client.mjs",
     "release:operator-gate": "yarn staking && yarn e2e",
+    "release:donation-consumption": "node dist/scripts/donation-consumption-acceptance.js",
     "setup:testnet-acceptance-operator": "node scripts/setup-testnet-acceptance-operator-docker.mjs",
     "setup:testnet-acceptance-operator:docker": "node scripts/setup-testnet-acceptance-operator-docker.mjs",
     "setup:testnet-acceptance-operator:host": "node scripts/setup-testnet-acceptance-operator.mjs",
@@ -52,19 +64,39 @@
     "release:testnet-acceptance:docker": "node scripts/testnet-acceptance-docker.mjs",
     "release:testnet-acceptance:host": "node scripts/testnet-acceptance.mjs",
     "status": "tsx scripts/status.ts",
-    "e2e": "tsx scripts/e2e-validate.ts",
-    "e2e-portfolio-v0": "tsx scripts/e2e-portfolio-v0.ts",
-    "e2e-prediction-apy-v0": "tsx scripts/e2e-prediction-apy-v0.ts",
-    "e2e:prediction": "cd ../contracts && yarn compile && cd ../client && tsx scripts/e2e-prediction-v0.ts",
-    "staking": "tsx scripts/staking-validate.ts",
-    "stolas": "tsx scripts/stolas-validate.ts",
-    "withdraw": "tsx scripts/withdraw.ts"
+    "e2e": "tsx test/e2e/validate.ts",
+    "e2e:task-first-local": "tsx test/e2e/task-first-local.ts",
+    "e2e:claude-code-learner": "tsx test/e2e/claude-code-learner-portfolio-v0.ts",
+    "e2e:prediction": "tsx test/e2e/prediction-v1.ts",
+    "e2e:freeze-mode": "tsx test/e2e/freeze-mode.test.ts",
+    "e2e:checkpoint-flow": "tsx test/e2e/checkpoint-flow.test.ts",
+    "e2e:swe-rebench-v2": "tsx test/e2e/swe-rebench-v2.test.ts",
+    "e2e:capture": "tsx scripts/e2e-capture-validate.ts",
+    "staking": "tsx test/e2e/staking.ts",
+    "stolas": "tsx test/e2e/stolas.ts",
+    "withdraw": "tsx scripts/withdraw.ts",
+    "corpus:e2e": "tsx scripts/corpus-e2e-validate.ts",
+    "build:spa": "yarn workspace @jinn-network/operator-spa build",
+    "dev:spa": "yarn workspace @jinn-network/operator-spa dev",
+    "e2e:spa": "yarn build && playwright test --config=playwright.config.ts test/dashboard/spa.e2e.test.ts",
+    "e2e:solvernet-flow": "yarn build && playwright test --config=playwright.config.ts test/dashboard/solvernet-flow.e2e.test.ts",
+    "e2e:donation": "vitest run test/smoke/donation-mode-smoke.test.ts test/smoke/donation-ipfs-http-smoke.test.ts"
   },
   "dependencies": {
     "@ethereumjs/wallet": "^10.0.0",
+    "@grpc/grpc-js": "^1.14.3",
     "@hono/node-server": "^1.19.12",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@msgpack/msgpack": "^3.0.0",
+    "@noble/ed25519": "^3.1.0",
+    "@noble/hashes": "^2.2.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/core": "^2.7.1",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.217.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.217.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-node": "^0.217.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@safe-global/protocol-kit": "^6.1.2",
     "@safe-global/types-kit": "^3.0.0",
     "@scure/bip32": "^1.7.0",
@@ -74,18 +106,31 @@
     "@x402/evm": "^2.9.0",
     "@x402/fetch": "^2.9.0",
     "@x402/hono": "^2.9.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "better-sqlite3": "^11.0.0",
+    "bs58": "^6.0.0",
+    "canonicalize": "^2.0.0",
+    "chokidar": "^5.0.0",
     "dotenv": "^17.4.1",
     "hono": "^4.12.10",
+    "node-pty": "^1.1.0",
+    "protobufjs": "^8.0.3",
+    "semver": "^7.7.4",
     "viem": "^2.0.0",
+    "ws": "^8.20.0",
     "zod": "^3.22.0"
   },
   "optionalDependencies": {
     "@coinbase/cdp-sdk": "^1.48.2"
   },
   "devDependencies": {
+    "@jinn-network/sdk": "portal:../packages/sdk",
+    "@playwright/test": "^1.59.1",
     "@types/better-sqlite3": "^7.6.0",
     "@types/node": "^20.0.0",
+    "@types/semver": "^7.7.1",
+    "@types/ws": "^8.18.1",
     "tsx": "^4.0.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"

package/plugins/claude-code-learner/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "claude-code-learner",
+  "description": "Generic learning agent plugin — runs a goal through a seven-phase pipeline (Orient → Strategize → Plan → Execute → Debrief → Improve → Memory consolidation) and self-improves between runs by mutating its own state directory.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Jinn Network",
+    "url": "https://github.com/Jinn-Network/mono"
+  }
+}

package/plugins/claude-code-learner/.codex-plugin/plugin.json

@@ -0,0 +1,39 @@
+{
+  "name": "claude-code-learner",
+  "version": "0.1.0",
+  "description": "Generic learning agent plugin - runs a goal through a seven-phase pipeline and self-improves between runs by mutating its own state directory.",
+  "author": {
+    "name": "Jinn Network",
+    "url": "https://github.com/Jinn-Network/mono"
+  },
+  "homepage": "https://github.com/Jinn-Network/mono",
+  "repository": "https://github.com/Jinn-Network/mono",
+  "license": "MIT",
+  "keywords": [
+    "jinn",
+    "learner",
+    "codex",
+    "skills"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Claude Code Learner",
+    "shortDescription": "Seven-phase learning loop for harness-driven goals",
+    "longDescription": "Runs a generic goal through orient, strategize, plan, execute, debrief, improve, and memory consolidation phases.",
+    "developerName": "Jinn Network",
+    "category": "Coding",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/Jinn-Network/mono",
+    "privacyPolicyURL": "https://github.com/Jinn-Network/mono",
+    "termsOfServiceURL": "https://github.com/Jinn-Network/mono",
+    "defaultPrompt": [
+      "Run the learning loop for this goal."
+    ],
+    "brandColor": "#111111",
+    "screenshots": []
+  }
+}

package/plugins/claude-code-learner/AGENTS.md

@@ -0,0 +1,40 @@
+# claude-code-learner plugin (generic / Codex loader)
+
+This plugin provides a generic learning-agent loop for any harness that supports skills + subagent dispatch + hooks.
+
+## Tool name mapping
+
+> Names below are best-effort guidance; harness tool surfaces evolve. The canonical contract is the **capability** described in the Generic column — confirm against your harness's docs before wiring.
+
+The `learn` skill and the sibling prompt files use Claude Code tool names by default. On other harnesses, substitute equivalents:
+
+| Claude Code | Codex | Pi.dev | Generic |
+|---|---|---|---|
+| `Skill` | `skill` | (extension load) | "load named instructions into current session" |
+| `Task` (general-purpose) | `spawn_agent` | (subprocess) | "spawn fresh-context subagent with an inline prompt body" |
+| `Bash` | `shell` | `bash` | shell tool |
+| `Read`/`Write`/`Edit` | `file_read`/`file_write` | `fs` tools | filesystem |
+| `Glob`/`Grep` | `glob`/`grep` | `fs` search | "filesystem search by pattern / content" |
+| `Monitor` (wait) | (bespoke) | (built-in) | "block until duration/deadline/condition" |
+
+## Subagent dispatch contract
+
+The learner workflow is written against generic harness capabilities, not a specific subagent API. The harness projects these operations onto its native tools:
+
+- Dispatch a fresh-context subagent with an inline role prompt body plus explicit inputs.
+- Wait on returned subagent handles until every required phase artifact exists.
+- Release/close completed subagents after their outputs are verified and their summaries are captured.
+- Pass absolute filesystem paths in subagent inputs; subagents should not rely on inheriting the coordinator's current working directory.
+
+## Entry point
+
+The harness adapter provides the task payload and paths at session start. The harness/plugin projection makes this skill available to the model; this skill drives the full seven-phase pipeline when selected by the runtime.
+
+## Components
+
+See `CLAUDE.md` for the same component listing — both loaders cover the same plugin contents; this file just notes the cross-harness tool mapping.
+
+## Spec
+
+- Pipeline + artifacts: `docs/superpowers/specs/2026-04-23-default-learning-restorer-design.md` v1.1.
+- Plugin layout + decoupling: `docs/superpowers/specs/2026-05-06-claude-code-learner-plugin-simplification-design.md` v1.1.

package/plugins/claude-code-learner/CLAUDE.md

@@ -0,0 +1,33 @@
+# claude-code-learner plugin (Claude Code loader)
+
+This plugin provides a generic learning-agent loop.
+
+## Entry point
+
+When a session starts, the harness adapter provides the task payload and paths. The harness/plugin projection makes this skill available to the model; this skill drives the full seven-phase pipeline when selected by the runtime.
+
+## Components
+
+**Skill:**
+- `skills/learn/SKILL.md` — single orchestrator. Sequences Orient → Strategize → Plan → Execute → Debrief → Improve → Memory consolidation. Each phase dispatches a fresh-context subagent using the prompt body from the matching sibling file.
+
+**Subagent prompt files (siblings of SKILL.md):**
+- `explorer-prompt.md` — info gatherer (used by Orient and Debrief, parallel-dispatched)
+- `strategist-prompt.md`, `planner-prompt.md`, `step-worker-prompt.md`, `analyst-prompt.md`, `promoter-prompt.md`, `consolidator-prompt.md` — one per specialized role
+
+**Hook:**
+- `hooks/session-start` — runs once at session start; ensures `implStateDir` is a git repo and sets `claude-code-learner` author identity.
+
+## Conventions
+
+- All durable self-modification lives in `implStateDir/**` (git-backed).
+- Episode artifacts live under `workingDir/**`; the harness harvests `workingDir` once the orchestrator returns.
+- Subagents are one level deep only — they do not spawn further agents.
+- Strategize-frozen success criteria + timing posture must not change during the run.
+- Subagent dispatch is by inlined prompt body (read from a sibling `*-prompt.md`), not by named-subagent registry. This keeps the plugin portable across harnesses.
+- The plugin does not interpret `goal.kind` semantically. Domain-specific knowledge belongs in other plugins or in the harness layer.
+
+## Spec
+
+- Pipeline + artifacts: `docs/superpowers/specs/2026-04-23-default-learning-restorer-design.md` v1.1.
+- Plugin layout + decoupling: `docs/superpowers/specs/2026-05-06-claude-code-learner-plugin-simplification-design.md` v1.1.

package/plugins/claude-code-learner/README.md

@@ -0,0 +1,59 @@
+# claude-code-learner — generic learning agent plugin
+
+A drop-in plugin for any agent harness that supports skills + subagent dispatch + hooks. Runs a goal through a seven-phase learning loop (Orient → Strategize → Plan → Execute → Debrief → Improve → Memory consolidation) and self-improves between runs by mutating its own state directory.
+
+## What it provides
+
+- **1 orchestrator skill** — `skills/learn/SKILL.md`. Drives the seven-phase pipeline end-to-end inside one harness session.
+- **7 sibling subagent prompts** — `skills/learn/<role>-prompt.md` for `explorer`, `strategist`, `planner`, `step-worker`, `analyst`, `promoter`, `consolidator`. Each is the prompt body the orchestrator passes to a fresh-context subagent dispatch.
+- **1 hook** — `hooks/session-start` initializes `implStateDir` as a git repo and sets author identity.
+
+## Installing
+
+The plugin is consumed by harnesses that load skills from a plugin directory.
+
+**Claude Code (local development — recommended for first install):**
+
+```bash
+# Point a Claude Code session at the plugin directory:
+claude --plugin-dir /path/to/claude-code-learner [other args]
+```
+
+For a permanent install via the Claude Code marketplace, use `claude plugin install <plugin>@<marketplace>` once a marketplace listing is published. Until then, `--plugin-dir` is the supported path.
+
+**Codex / OpenCode / other harnesses:** consult your harness's documentation for how to point it at a local plugin directory. The plugin layout (`.claude-plugin/plugin.json` + `skills/` + `hooks/` + `hooks/hooks.json`) is Claude-Code-shaped; harnesses with a different convention may need an adapter.
+
+## What the harness must provide
+
+These are the runtime primitives the plugin assumes the harness exposes (Claude Code names; substitute equivalents on other harnesses):
+
+- `Skill` — load a named skill into the current session.
+- `Task` (general-purpose) — spawn a fresh-context subagent with an inline prompt body.
+- `Bash` — for git commands and other shell calls.
+- `Read`, `Write`, `Edit`, `Glob`, `Grep` — filesystem.
+- A wait primitive — block until duration / deadline / condition (Claude Code: `Monitor`).
+
+The harness adapter is responsible for projecting the generic subagent lifecycle onto its own tool surface: dispatch a fresh-context role worker, wait for required artifacts, and release completed workers. Subagent inputs should use absolute paths so workers do not depend on inheriting the coordinator's current working directory.
+
+If the harness lacks `Skill`, generic `Task`-style subagent dispatch, `Bash`, or filesystem read/write/edit, the plugin will not run. The wait primitive gates time-anchored plans only — the plugin can run for `early-return` postures without it.
+
+## Inputs the harness adapter passes
+
+The orchestrator skill expects these as session inputs (typically via the harness adapter's initial prompt or environment):
+
+- `goal` — `{ id, description, kind?, deadline?, spec? }`. Free-form payload describing what to achieve.
+- `workingDir` — ephemeral path for this run's artifacts.
+- `implStateDir` — the agent's persistent self-state (git-backed).
+- `msUntilDeadline` — function returning remaining time.
+- An abort signal that fires at the goal's deadline.
+
+The plugin does not interpret `goal.kind` semantically. Domain-specific behavior (e.g. how to forecast a prediction market, how to rebalance a portfolio) belongs in domain-specific plugins loaded alongside this one, OR in the harness adapter / harvester layer.
+
+## Optional environment
+
+- `LEARNER_PHASE_RANGE=pre-execute|post-execute|full` — limits which phases run. Used by harnesses that wrap a domain-specialist Execute path between meta-pre and meta-post passes.
+
+## Spec
+
+- Pipeline + artifacts: `docs/superpowers/specs/2026-04-23-default-learning-restorer-design.md` v1.1.
+- Plugin layout + decoupling: `docs/superpowers/specs/2026-05-06-claude-code-learner-plugin-simplification-design.md` v1.1.

package/plugins/claude-code-learner/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start\"",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/claude-code-learner/hooks/session-start

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# claude-code-learner session-start hook.
+#
+# Runs once at the start of every claude-code-learner session. Ensures
+# implStateDir is a git repo and sets the author identity so any
+# subsequent `git commit` from inside the plugin's agents uses the
+# claude-code-learner identity automatically.
+#
+# Inputs (from environment):
+#   IMPL_STATE_DIR — path to the operator's implStateDir
+#
+# Idempotent: safe to re-run. No remote, no signing — implStateDir
+# history is operator-private.
+
+set -euo pipefail
+
+# Derive PLUGIN_ROOT from this script's location, then export so
+# subsequent skills/agents can find the plugin without a hardcoded path.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+export PLUGIN_ROOT
+
+if [[ -z "${IMPL_STATE_DIR:-}" ]]; then
+  echo "session-start: IMPL_STATE_DIR not set" >&2
+  exit 1
+fi
+
+mkdir -p "$IMPL_STATE_DIR"
+cd "$IMPL_STATE_DIR"
+
+if [[ ! -d .git ]]; then
+  git init --initial-branch=main --quiet
+  git commit --allow-empty -m "init implStateDir" --quiet
+fi
+
+git config user.name "claude-code-learner"
+git config user.email "claude-code-learner@local"
+
+echo "session-start: implStateDir ready at $(pwd) (HEAD=$(git rev-parse HEAD))"