@jinn-network/client 0.1.8 → 0.1.9-canary.023faefb

package/dist/pilot/repo.d.ts

@@ -0,0 +1,31 @@
+/** Git helpers for the pilot orchestrator, factored out so their fail-loud
+ *  behaviour is unit-testable with an injected runner (the orchestrator's own
+ *  I/O is validated by dry-run + smoke, per the pilot plan). */
+export type CmdRunner = (cmd: string, args: string[], opts?: {
+    cwd?: string;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;
+/** A git base-checkout step (clone/checkout) exited non-zero. The base repo is
+ *  unusable, so the INSTANCE is ungradeable — it MUST NOT silently proceed into
+ *  an empty repo where both arms score `passed:false` (that mis-attributes an
+ *  environment failure to the agent and understates the resolve rate). Caught at
+ *  run-pilot's per-instance boundary, which skips the instance and continues. */
+export declare class GitStepError extends Error {
+    readonly step: 'clone' | 'checkout';
+    readonly exitCode: number;
+    readonly detail: string;
+    constructor(step: 'clone' | 'checkout', exitCode: number, detail: string);
+}
+/** Clone `repo` into `baseDir` and check out `baseCommit`, FAIL-LOUD on a
+ *  non-zero exit from either step. A 404'd/renamed repo or an unfetchable commit
+ *  must throw here rather than leave an empty/wrong checkout that both arms then
+ *  "solve" into empty patches. */
+export declare function prepareBaseCheckout(run: CmdRunner, repo: string, baseCommit: string, baseDir: string): Promise<void>;
+/** Recover the working-tree patch, INCLUDING new (untracked) files: `git add -A`
+ *  stages everything, then `git diff --cached` emits the full diff. A plain
+ *  `git diff` misses untracked files, so a fix that ADDS a file would look like
+ *  an empty patch (a spurious not-resolved). */
+export declare function recoverPatch(run: CmdRunner, cwd: string): Promise<string>;

package/dist/pilot/repo.js

@@ -0,0 +1,42 @@
+/** Git helpers for the pilot orchestrator, factored out so their fail-loud
+ *  behaviour is unit-testable with an injected runner (the orchestrator's own
+ *  I/O is validated by dry-run + smoke, per the pilot plan). */
+/** A git base-checkout step (clone/checkout) exited non-zero. The base repo is
+ *  unusable, so the INSTANCE is ungradeable — it MUST NOT silently proceed into
+ *  an empty repo where both arms score `passed:false` (that mis-attributes an
+ *  environment failure to the agent and understates the resolve rate). Caught at
+ *  run-pilot's per-instance boundary, which skips the instance and continues. */
+export class GitStepError extends Error {
+    step;
+    exitCode;
+    detail;
+    constructor(step, exitCode, detail) {
+        super(`git ${step} failed (exit ${exitCode})${detail ? `: ${detail}` : ''}`);
+        this.step = step;
+        this.exitCode = exitCode;
+        this.detail = detail;
+        this.name = 'GitStepError';
+    }
+}
+/** Clone `repo` into `baseDir` and check out `baseCommit`, FAIL-LOUD on a
+ *  non-zero exit from either step. A 404'd/renamed repo or an unfetchable commit
+ *  must throw here rather than leave an empty/wrong checkout that both arms then
+ *  "solve" into empty patches. */
+export async function prepareBaseCheckout(run, repo, baseCommit, baseDir) {
+    const clone = await run('git', ['clone', `https://github.com/${repo}.git`, baseDir]);
+    if (clone.exitCode !== 0)
+        throw new GitStepError('clone', clone.exitCode, clone.stderr.trim().slice(0, 300));
+    const checkout = await run('git', ['checkout', baseCommit], { cwd: baseDir });
+    if (checkout.exitCode !== 0)
+        throw new GitStepError('checkout', checkout.exitCode, checkout.stderr.trim().slice(0, 300));
+}
+/** Recover the working-tree patch, INCLUDING new (untracked) files: `git add -A`
+ *  stages everything, then `git diff --cached` emits the full diff. A plain
+ *  `git diff` misses untracked files, so a fix that ADDS a file would look like
+ *  an empty patch (a spurious not-resolved). */
+export async function recoverPatch(run, cwd) {
+    await run('git', ['add', '-A'], { cwd });
+    const diff = await run('git', ['diff', '--cached'], { cwd });
+    return diff.stdout;
+}
+//# sourceMappingURL=repo.js.map

package/dist/pilot/repo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.js","sourceRoot":"","sources":["../../src/pilot/repo.ts"],"names":[],"mappings":"AAAA;;gEAEgE;AAQhE;;;;iFAIiF;AACjF,MAAM,OAAO,YAAa,SAAQ,KAAK;IAE1B;IACA;IACA;IAHX,YACW,IAA0B,EAC1B,QAAgB,EAChB,MAAc;QAEvB,KAAK,CAAC,OAAO,IAAI,iBAAiB,QAAQ,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAJpE,SAAI,GAAJ,IAAI,CAAsB;QAC1B,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED;;;kCAGkC;AAClC,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,GAAc,EACd,IAAY,EACZ,UAAkB,EAClB,OAAe;IAEf,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,sBAAsB,IAAI,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrF,IAAI,KAAK,CAAC,QAAQ,KAAK,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7G,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9E,IAAI,QAAQ,CAAC,QAAQ,KAAK,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,UAAU,EAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AAC3H,CAAC;AAED;;;gDAGgD;AAChD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAc,EAAE,GAAW;IAC5D,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC,MAAM,CAAC;AACrB,CAAC"}

package/dist/pilot/solve.d.ts

@@ -0,0 +1,22 @@
+export interface Arm {
+    name: 'A' | 'B';
+    skills: string[];
+}
+export interface SolveTokens {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    reasoningTokens: number;
+}
+/** The jinn-agent argv for one solve. Arm A = empty loadout enforced via
+ *  --ignore-rules (no memory/AGENTS.md/preloaded-skill leakage, spike §3.1);
+ *  arm B = arm A + `-s <skill>` for each loadout skill. When `provider`/`model`
+ *  are supplied they pin the inference endpoint for this invocation (e.g.
+ *  `openai-codex` + `gpt-5.4-mini`) without touching the global config default. */
+export declare function buildSolveArgs(arm: Arm, prompt: string, opts: {
+    maxTurns: number;
+    provider?: string;
+    model?: string;
+}): string[];
+export declare function parseSessionTokens(exportLine: string): SolveTokens;
+export declare function extractSessionId(stderr: string): string | null;

package/dist/pilot/solve.js

@@ -0,0 +1,37 @@
+/** The jinn-agent argv for one solve. Arm A = empty loadout enforced via
+ *  --ignore-rules (no memory/AGENTS.md/preloaded-skill leakage, spike §3.1);
+ *  arm B = arm A + `-s <skill>` for each loadout skill. When `provider`/`model`
+ *  are supplied they pin the inference endpoint for this invocation (e.g.
+ *  `openai-codex` + `gpt-5.4-mini`) without touching the global config default. */
+export function buildSolveArgs(arm, prompt, opts) {
+    const base = ['chat', '-q', prompt, '-Q', '--yolo', '--ignore-rules'];
+    const endpoint = [
+        ...(opts.provider ? ['--provider', opts.provider] : []),
+        ...(opts.model ? ['-m', opts.model] : []),
+    ];
+    const skills = arm.skills.flatMap((s) => ['-s', s]);
+    return [...base, ...endpoint, ...skills, '--pass-session-id', '--max-turns', String(opts.maxTurns)];
+}
+export function parseSessionTokens(exportLine) {
+    const o = JSON.parse(exportLine);
+    const num = (k) => {
+        const v = o[k];
+        if (typeof v !== 'number')
+            throw new Error(`session export missing numeric token field '${k}'`);
+        return v;
+    };
+    const optNum = (k) => (typeof o[k] === 'number' ? o[k] : 0);
+    return {
+        inputTokens: num('input_tokens'),
+        outputTokens: num('output_tokens'),
+        cacheReadTokens: optNum('cache_read_tokens'),
+        // Reasoning models (e.g. gpt-5.4-mini) report reasoning tokens separately;
+        // they are billed at the output rate. Absent for non-reasoning models → 0.
+        reasoningTokens: optNum('reasoning_tokens'),
+    };
+}
+export function extractSessionId(stderr) {
+    const m = stderr.match(/session_id:\s*(\S+)/);
+    return m ? m[1] : null;
+}
+//# sourceMappingURL=solve.js.map

package/dist/pilot/solve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve.js","sourceRoot":"","sources":["../../src/pilot/solve.ts"],"names":[],"mappings":"AAGA;;;;mFAImF;AACnF,MAAM,UAAU,cAAc,CAC5B,GAAQ,EACR,MAAc,EACd,IAA6D;IAE7D,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG;QACf,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1C,CAAC;IACF,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;AACtG,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACnD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAA4B,CAAC;IAC5D,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE;QAChC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACf,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,GAAG,CAAC,CAAC;QAChG,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxF,OAAO;QACL,WAAW,EAAE,GAAG,CAAC,cAAc,CAAC;QAChC,YAAY,EAAE,GAAG,CAAC,eAAe,CAAC;QAClC,eAAe,EAAE,MAAM,CAAC,mBAAmB,CAAC;QAC5C,2EAA2E;QAC3E,2EAA2E;QAC3E,eAAe,EAAE,MAAM,CAAC,kBAAkB,CAAC;KAC5C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAC9C,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1B,CAAC"}

package/dist/pilot/tally.d.ts

@@ -0,0 +1,35 @@
+export interface SolveOutcome {
+    instance_id: string;
+    arm: 'A' | 'B';
+    repeat: number;
+    passed: boolean | null;
+    costUsd: number;
+}
+export interface PilotReport {
+    n: number;
+    armA: {
+        resolveRate: number;
+    };
+    armB: {
+        resolveRate: number;
+    };
+    bothSolveTasks: number;
+    excluded: number;
+    quality: {
+        lowerBound: number;
+        nonInferior: boolean;
+        deltaPP: number;
+    };
+    /** `n` is the both-solve NON-ZERO cost-diff count the Wilcoxon actually uses;
+     *  `underpowered` marks n below its one-sided minimum-rejectable size (~5), so a
+     *  tiny-n verdict is not mistaken for a powered one. */
+    cost: {
+        verdict: 'lower' | 'not-lower' | 'inconclusive';
+        medianDeltaUsd: number;
+        n: number;
+        underpowered: boolean;
+    };
+}
+export declare function tallyPilot(outcomes: SolveOutcome[], opts: {
+    rng: () => number;
+}): PilotReport;

package/dist/pilot/tally.js

@@ -0,0 +1,61 @@
+import { nonInferiorityVerdict, pairedCostVerdict } from '../eval/capability-stats.js';
+/** One-sided Wilcoxon signed-rank cannot reject below ~5 non-zero diffs
+ *  (1/2^n ≥ α for n < 5), so a 'lower'/'not-lower' verdict on fewer is unpowered. */
+const WILCOXON_MIN_REJECTABLE_N = 5;
+export function tallyPilot(outcomes, opts) {
+    const byTask = new Map();
+    for (const o of outcomes)
+        (byTask.get(o.instance_id) ?? byTask.set(o.instance_id, []).get(o.instance_id)).push(o);
+    const rates = [];
+    const costDiffs = [];
+    let excluded = 0;
+    let aPassTot = 0, aTot = 0, bPassTot = 0, bTot = 0, bothSolve = 0;
+    for (const [, os] of byTask) {
+        const A = os.filter((o) => o.arm === 'A');
+        const B = os.filter((o) => o.arm === 'B');
+        const gradedA = A.filter((o) => o.passed !== null);
+        const gradedB = B.filter((o) => o.passed !== null);
+        if (gradedA.length === 0 || gradedB.length === 0) {
+            excluded++;
+            continue;
+        }
+        const pA = gradedA.filter((o) => o.passed === true).length / gradedA.length;
+        const pB = gradedB.filter((o) => o.passed === true).length / gradedB.length;
+        rates.push({ pA, pB });
+        aPassTot += gradedA.filter((o) => o.passed === true).length;
+        aTot += gradedA.length;
+        bPassTot += gradedB.filter((o) => o.passed === true).length;
+        bTot += gradedB.length;
+        // both-solve cost: mean cost on the repeats where BOTH arms passed (like-for-like)
+        if (pA > 0 && pB > 0) {
+            const meanCost = (xs, pass) => {
+                const f = xs.filter((o) => o.passed === pass);
+                return f.length ? f.reduce((s, o) => s + o.costUsd, 0) / f.length : NaN;
+            };
+            const ca = meanCost(gradedA, true), cb = meanCost(gradedB, true);
+            if (Number.isFinite(ca) && Number.isFinite(cb)) {
+                costDiffs.push(cb - ca);
+                bothSolve++;
+            }
+        }
+    }
+    const stockBaseRate = aTot > 0 ? aPassTot / aTot : 0;
+    const ni = rates.length
+        ? nonInferiorityVerdict(rates, { rng: opts.rng, stockBaseRate: Math.max(stockBaseRate, 1e-9) })
+        : { pass: false, lowerBound: NaN, relativeRegression: NaN, reasons: ['no gradeable pairs'] };
+    // pilot scale — small both-solve sets are expected; minN:1 lets the cost verdict go live rather than always 'inconclusive'.
+    // The verdict is still surfaced with its n + an `underpowered` flag so a tiny-n read isn't mistaken for a powered one.
+    const cost = pairedCostVerdict(costDiffs, { minN: 1 });
+    const median = (xs) => { if (!xs.length)
+        return NaN; const s = [...xs].sort((a, b) => a - b); const m = s.length >> 1; return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2; };
+    return {
+        n: rates.length + excluded,
+        armA: { resolveRate: stockBaseRate },
+        armB: { resolveRate: bTot > 0 ? bPassTot / bTot : 0 },
+        bothSolveTasks: bothSolve,
+        excluded,
+        quality: { lowerBound: ni.lowerBound, nonInferior: ni.pass, deltaPP: 100 * ((bTot > 0 ? bPassTot / bTot : 0) - stockBaseRate) },
+        cost: { verdict: cost.verdict, medianDeltaUsd: median(costDiffs), n: cost.n, underpowered: cost.n < WILCOXON_MIN_REJECTABLE_N },
+    };
+}
+//# sourceMappingURL=tally.js.map

package/dist/pilot/tally.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tally.js","sourceRoot":"","sources":["../../src/pilot/tally.ts"],"names":[],"mappings":"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"}

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

@@ -1,7 +1,7 @@
 {
   "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",
+  "version": "0.2.0",
   "author": {
     "name": "Jinn Network",
     "url": "https://github.com/Jinn-Network/mono"

package/dist/plugins/learner/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-learner",
-  "version": "0.1.0",
+  "version": "0.2.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",

package/dist/plugins/learner/hooks/session-start

@@ -35,4 +35,33 @@ 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))"
+# Operational readiness goes to STDERR. Claude Code parses a SessionStart hook's
+# STDOUT as JSON for `hookSpecificOutput`; any stray stdout would break that parse,
+# so stdout below carries nothing but the additionalContext payload.
+echo "session-start: implStateDir ready at $(pwd) (HEAD=$(git rev-parse HEAD))" >&2
+
+# Steer skill-selection toward this plugin's OWN learn loop. This is the agnostic,
+# plugin-owned mechanism: the learner plugin asserts its own behaviour from its own
+# SessionStart hook, without any other plugin or the harness prompt knowing it exists.
+#
+# It is delivered via the documented `hookSpecificOutput.additionalContext` contract,
+# which is injected into the model's context at session start. The previous plain
+# `echo` was logged as a hook event (visible to the harness via --include-hook-events)
+# but NEVER entered the model context — which is why, despite the learn skill being
+# projected and available, the model kept selecting a direct-solve skill and the loop
+# ran 0% of the time. (Verified: additionalContext reaches the model in headless
+# `-p` / stream-json mode on claude 2.1.x.)
+#
+# MODE-AWARE (extends the original train-only steer for the held-out exam): in
+# `frozen` mode the harness freeze-fences implStateDir, so running the learn loop's
+# Improve/Memory phases would WRITE implStateDir and trip the fence → the eval
+# aborts with a violation. The frozen steer therefore tells the model to CONSULT
+# the accumulated knowledge (read-only) and solve directly — which is exactly how
+# prior learning should raise the frozen score — and to NOT run the loop or modify
+# implStateDir. `JINN_HARNESS_MODE` is set by the harness adapter (default train).
+if [[ "${JINN_HARNESS_MODE:-train}" == "frozen" ]]; then
+  STEER="This is a FROZEN evaluation run. Before solving, CONSULT the accumulated learner knowledge under implStateDir (notes/, skills/, strategies/, patterns/, tests/) and apply any relevant strategy or pattern to this task. Then solve the task and call submit_typed_payload. Do NOT run the learn loop (no Orient/Improve/Memory phases) and do NOT create, edit, or commit anything under implStateDir — the harness verifies implStateDir is unchanged and will discard this run if it is modified."
+else
+  STEER="A seven-phase self-improvement loop is available as the learn skill (claude-code-learner:learn): Orient, Strategize, Plan, Execute, Debrief, Improve, then Memory consolidation. For this session your FIRST action MUST be to invoke the learn skill (via the Skill tool) and run the full loop end-to-end, instead of solving the task directly or selecting another skill first. The Execute phase still performs the actual task work and still calls submit_typed_payload; the surrounding phases capture reusable strategy and persist it to implStateDir so future runs improve. Do not skip the loop."
+fi
+printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$STEER"

package/dist/plugins/learner/skills/learn/consolidator-prompt.md

@@ -18,6 +18,10 @@ Anything that writes to `implStateDir` happens here, including:
 - **Unused skills / hooks / tools** — anything not invoked in the last N runs (default 20; check policy override). Move to `implStateDir/.archive/<ts>/` or delete per policy.
 - **Regressed promotions** — revert an Improve commit only when it actually made things worse. There are two triggers; act on either:
   1. **Qualitative trigger** — if the trend in `analysisPath` (the Debrief signal) indicates a recent change made things worse, `git revert <commit-sha>` it. Be specific: revert the exact commit identified, not a bulk rollback. The target sha is `improvePromotionsDir/<n>.json`'s `implStateDirShaAfter`.
+  > The graded score (Tier 2) lowers the variance of the keep/revert decision only.
+  > It never overrules the binary verdict, and it MUST NOT be used to size on-chain
+  > reward — that path is gated on the withheld-test challenge (#1019, design §5.5).
+
   2. **Quantitative trigger (#764)** — for each candidate Improve commit on recent `implStateDir` git history (the commits since `implStateDirShaBefore`, identified from each `improvePromotionsDir/<n>.json` `implStateDirShaAfter`), ask the network-truth indexer whether the commit's per-codeDigest pass rate is significantly worse than its parent's. **Do not hand-roll the codeDigest hash or the statistics — shell out to the CLI**, which exports each commit's tree (`git archive`, no `.git`) and hashes it the way production stamps codeDigest, then runs the documented test:
 
      ```bash

package/dist/plugins/local-trace-distiller/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "local-trace-distiller",
+  "description": "Local trace distillation tools and workflow for deriving experimental skills from private session traces.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Jinn Network",
+    "url": "https://github.com/Jinn-Network/mono"
+  }
+}

package/dist/plugins/local-trace-distiller/.codex-plugin/plugin.json

@@ -0,0 +1,41 @@
+{
+  "name": "local-trace-distiller",
+  "version": "0.1.0",
+  "description": "Local trace distillation tools and skill workflow for deriving experimental skills from private session traces.",
+  "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",
+    "distill",
+    "traces",
+    "skills",
+    "mcp"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Local Trace Distiller",
+    "shortDescription": "Derive experimental skills from local traces",
+    "longDescription": "Searches local captured session traces, clusters recurring patterns, and runs the existing Jinn distillation flow using the user's selected LLM provider.",
+    "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": [
+      "Use /distill to derive an experimental skill from local traces."
+    ],
+    "brandColor": "#2563EB",
+    "screenshots": []
+  }
+}

package/dist/plugins/local-trace-distiller/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "jinn-local-distil": {
+      "command": "jinn-distil-mcp",
+      "args": []
+    }
+  }
+}

package/dist/plugins/local-trace-distiller/README.md

@@ -0,0 +1,27 @@
+# local-trace-distiller
+
+Local trace distillation plugin for deriving experimental skills from private session traces.
+
+## Components
+
+- `skills/distill/SKILL.md` — `/distill` workflow. No argument defaults to `this`; `all` runs a capped cluster-first scan.
+- `.mcp.json` — launches `jinn-distil-mcp`.
+- `jinn-distil-mcp` tools:
+  - `distill_trace_search` — compact local trace cards.
+  - `distill_trace_read` — scoped trace reads with full-transcript gating.
+  - `distill_trace_cluster` — cheap repeated-signal candidate discovery.
+  - `distill_local` — confirmed local run through `jinn-layer distil`.
+
+## Local Capture Source
+
+Stop-hook captures are exported as `CapturedTask` JSON under:
+
+```text
+~/.jinn-client/harness-layer/captures
+```
+
+Set `JINN_LAYER_CAPTURES_DIR` to override the directory. The MCP server and `jinn-layer distil` use the same directory, so agents can search traces and then invoke the existing distillation flow without a second data path.
+
+## Status
+
+Generated skills are marked experimental and should be improved through user feedback before they are treated as stable. Public marketplace listing is intentionally out of scope for this version.

package/dist/plugins/local-trace-distiller/jinn.plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "@jinn-network/local-trace-distiller",
+  "version": "0.1.0",
+  "description": "Local trace distillation plugin. Searches private captures, clusters candidate skill opportunities, and invokes the existing Jinn skill distiller locally.",
+  "jinn": {
+    "supports": [
+      "jinn.local-distil"
+    ],
+    "capabilities": {
+      "tools": {
+        "jinn-local-distil": [
+          "distill_trace_search",
+          "distill_trace_read",
+          "distill_trace_cluster",
+          "distill_local",
+          "distill_feedback_record"
+        ]
+      }
+    },
+    "mcpServers": {
+      "jinn-local-distil": {
+        "command": "jinn-distil-mcp",
+        "tools": [
+          "distill_trace_search",
+          "distill_trace_read",
+          "distill_trace_cluster",
+          "distill_local",
+          "distill_feedback_record"
+        ]
+      }
+    },
+    "skills": [
+      "skills/distill/SKILL.md"
+    ]
+  }
+}

package/dist/plugins/local-trace-distiller/skills/distill/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: distill
+description: Use local trace tools to derive experimental skills from private session traces. Trigger on /distill, "distill this", "distill all", or requests to turn repeated local work into a reusable skill.
+tools: distill_trace_search, distill_trace_read, distill_trace_cluster, distill_local, distill_feedback_record
+---
+
+# Local Trace Distill
+
+Use this skill to help the user turn local work traces into experimental skills using the existing Jinn distillation methodology.
+
+## Arguments
+
+- No argument means `this`: focus on the current or most recent session.
+- `this`, `current`, or `recent`: inspect the most recent local trace cards, choose the best match for the current session, then distill only that trace unless the user chooses a broader set.
+- `all`: run a capped, cheap scan over local trace cards, cluster recurring signals, present candidates, and ask the user which candidate to distill.
+- A trace id, session id, or candidate trace list: inspect those traces and distill only the selected traces.
+
+## Tool Workflow
+
+1. Start with `distill_trace_search`, using compact cards. Do not read full transcripts first.
+2. For `all`, call `distill_trace_cluster` with a conservative cap. Default to `limit: 50` unless the user requested a different cap.
+3. Read only what is needed:
+   - Use `mode: "summary"` for orientation.
+   - Use `mode: "tool_calls"` to understand commands and edits.
+   - Use `mode: "transcript_excerpt"` with a query when one section matters.
+   - Use `mode: "full_transcript"` only when the skill cannot be safely derived from smaller reads, and set `allowFullTranscript: true` only after deciding it is necessary.
+4. Before calling `distill_local`, summarize the proposed source traces and the likely skill opportunity in one short paragraph.
+5. Call `distill_local` with `confirm: true` only after the user explicitly approves the run or has already requested an execution form such as "distill this now".
+6. Pass selected `traceIds` or `sessionIds` whenever the user chose a candidate. Avoid distilling every capture unless the user asked for `all` and then approved that broad run.
+
+## Distillation Methodology
+
+Reuse the existing Jinn distillation methodology rather than inventing a new prompt:
+
+- Prefer evaluator/user-accepted successful traces for success patterns.
+- Use failed or abandoned traces only for concrete lessons and failure avoidances.
+- Keep the skill grounded in repeated evidence when available; label single-trace outputs as experimental.
+- Preserve provenance through the generated skill metadata.
+- Run through the existing scrub, contamination, structure, and package gates via `distill_local`.
+
+## User Feedback Loop
+
+Generated skills are experimental. After a later session uses one, ask the user whether it helped, hurt, was mixed, or went unused. If the user gives feedback, call `distill_feedback_record` with the skill name, verdict, session id if known, and only user-approved notes or accepted changes. Convert accepted feedback into a targeted skill improvement instead of accumulating broad notes.
+
+## Future Marketplace
+
+Do not list local skills publicly in this version. Later versions may let users publish useful skills to a marketplace for others to use and pay for, but that requires explicit user approval and a separate publish flow.
+
+## Privacy
+
+Local traces are private by default. Do not export trace content or generated skills to a remote marketplace or shared corpus unless the user explicitly asks for that future publish flow.

package/dist/preflight/deployment-readiness.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Deployment-readiness preflight (issue #958).
+ *
+ * Hosted deploys have no boot-time guard that the environment is fit to run;
+ * misconfig fails silently or mid-run. This module adds a set of checks that
+ * answer "is this environment fit to run the daemon?" and a boot gate that
+ * **fails loud — but only in a deployment context**.
+ *
+ * Load-bearing constraint: a plain local `jinn run` (no `JINN_STATE_DIR`,
+ * running as the user) must NEVER be newly gated. The
+ * fail-loud boot gate fires only when `isDeploymentContext()` is true; outside
+ * that, every check is advisory (surfaced in `doctor`, never boot-fatal). The
+ * `doctor` command runs all checks regardless of context.
+ *
+ * The checks compose existing primitives where possible:
+ *   - `writable_volume`        — the one genuinely new primitive (write+fsync+unlink probe)
+ *   - `state_on_volume`        — assert resolved state lives on the configured volume
+ *   - `credentials_resolvable` — reuses `detectAuthContext`; presence-only, NEVER echoes secrets
+ *   - `agent_cli_non_root`     — uid 0 is unfit (the agent CLI refuses to run as root)
+ *
+ * Every check is side-effect-light and NEVER throws — a failure becomes a
+ * structured fail result, not an exception. The aggregate is the safe caller
+ * surface; the gate adds the fail-loud envelope on top.
+ */
+import { type EnvelopeSinks } from '../errors/envelope.js';
+import { detectAuthContext as defaultDetectAuthContext, type AuthContext } from './claude-auth.js';
+export interface DeploymentCheckResult {
+    name: 'writable_volume' | 'state_on_volume' | 'credentials_resolvable' | 'agent_cli_non_root';
+    ok: boolean;
+    detail: string;
+    remedy?: string;
+}
+/** Inputs that come from the resolved config / process — never secret values. */
+export interface DeploymentReadinessInputs {
+    /** `config.stateDir` — the volume root, when set (S3, JINN_STATE_DIR). */
+    stateDir: string | undefined;
+    /** `config.earningDir` — the resolved earning/state directory. */
+    earningDir: string;
+    /**
+     * `config.runtimeMode` — a persisted runtime mode (`'docker-compose'` /
+     * `'container'`) declared by the operator (via `jinn auth --mode` or the app
+     * setup) rather than via env / `/.dockerenv`. Threaded into
+     * `detectAuthContext` as `configuredMode` so a config-declared compose /
+     * container operator is detected as a deployment context (and the boot gate
+     * arms) even with no `JINN_RUNTIME_MODE` env var and no `/.dockerenv`.
+     * `undefined` leaves detection on env / filesystem signals only — preserving
+     * the bare-local regression guarantee.
+     */
+    runtimeMode: AuthContext | undefined;
+}
+/** Injectable dependencies — tests pass doubles; production uses the defaults. */
+export interface DeploymentReadinessDeps {
+    env: NodeJS.ProcessEnv;
+    /** `process.getuid` (undefined on platforms without it, e.g. Windows). */
+    getuid: (() => number) | undefined;
+    detectAuthContext: typeof defaultDetectAuthContext;
+}
+export interface DeploymentReadinessReport {
+    /** True when we are in a deployment context (gate is armed). */
+    deployment: boolean;
+    /** The auth context detected for this run. */
+    authContext: AuthContext;
+    checks: DeploymentCheckResult[];
+    /**
+     * True when the daemon must refuse to boot: deployment context AND at least
+     * one HARD check failed. Always false outside a deployment context.
+     */
+    bootFatal: boolean;
+}
+/**
+ * Deployment context = `JINN_STATE_DIR` set OR `config.stateDir` set OR the
+ * auth context is a container / docker-compose. A plain local operator (bare
+ * context, no state-dir) is NOT a deployment context, so the boot gate stays
+ * disarmed for them.
+ */
+export declare function isDeploymentContext(input: {
+    env: NodeJS.ProcessEnv;
+    authContext: AuthContext;
+    stateDir: string | undefined;
+}): boolean;
+/**
+ * Attempt to write + fsync + unlink a temp file under `dir`. ok when it
+ * succeeds; structured fail (never throws) on EACCES / EROFS / ENOSPC / missing
+ * dir / any other fs error.
+ */
+export declare function checkWritableVolume(dir: string): Promise<DeploymentCheckResult>;
+/**
+ * In a deployment context, assert resolved state lives on the configured
+ * volume — i.e. `stateDir` is set AND `earningDir` resolves under it. Advisory
+ * (always ok) outside a deployment context.
+ */
+export declare function checkStateOnVolume(input: {
+    deployment: boolean;
+    stateDir: string | undefined;
+    earningDir: string;
+}): DeploymentCheckResult;
+/**
+ * Presence-only credential check. In a bare context the operator authenticates
+ * the agent CLI interactively (claude session auth), so credentials are not
+ * env-resolvable and that is fine. In a container / compose context there is no
+ * interactive login, so SOME agent-CLI auth signal must be present in the env.
+ *
+ * NEVER returns or logs a secret value — only presence + context.
+ */
+export declare function checkCredentialsResolvable(input: {
+    context: AuthContext;
+    env: NodeJS.ProcessEnv;
+}): DeploymentCheckResult;
+/**
+ * ok when uid !== 0 (or no getuid on the platform). Fail when running as root —
+ * the agent CLI refuses to run as root, so a root daemon is unfit. Never throws.
+ */
+export declare function checkAgentCliNonRoot(getuid: (() => number) | undefined): DeploymentCheckResult;
+/**
+ * Run every deployment-readiness check and assemble a report. Detects the
+ * deployment context internally and decides `bootFatal` accordingly. Never
+ * throws — each check degrades to a structured fail.
+ */
+export declare function runDeploymentReadinessChecks(inputs: DeploymentReadinessInputs, deps: DeploymentReadinessDeps): Promise<DeploymentReadinessReport>;
+/**
+ * Boot gate for `jinn run`. Runs the readiness aggregate; in a deployment
+ * context, fail loud (emit `invalid_invocation` envelope + non-zero exit) when
+ * a hard check fails. Outside a deployment context, log advisories for any
+ * failing check and proceed. Mirrors `applyPidfileLivenessGate`'s contract:
+ * `emitEnvelope` does not return in production (it `process.exit`s).
+ */
+export declare function applyDeploymentReadinessGate(inputs: DeploymentReadinessInputs, deps: DeploymentReadinessDeps, sinks?: EnvelopeSinks): Promise<void>;