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

package/dist/harnesses/manifest/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Daemon-side manifest types. Same shape as the SDK manifest type;
+ * mirrored locally so the client doesn't have to depend on
+ * @jinn-network/sdk/harness at runtime (the SDK is a publish-time
+ * boundary).
+ */
+export interface CapabilityAllowEntry {
+    chainId: number;
+    to: `0x${string}`;
+    selector: `0x${string}`;
+    description?: string;
+}
+/**
+ * EIP-712 typed-data domain allow-list entry. The daemon's scoped
+ * signer refuses any `signTypedData` call whose domain does not
+ * match one of these entries.
+ *
+ * - `chainId` MUST match exactly.
+ * - `verifyingContract` / `name` / `version` match only when set on
+ *   the entry; an unset field on the entry means "any value".
+ * - An empty / omitted `typedDataDomains` array means default-deny:
+ *   every `signTypedData` call throws.
+ */
+export interface TypedDataAllowEntry {
+    chainId: number;
+    name?: string;
+    version?: string;
+    verifyingContract?: `0x${string}`;
+}
+export interface ManifestRpcAllow {
+    chainId: number;
+    methods: ReadonlyArray<'eth_call' | 'eth_getBlockByNumber' | 'eth_getLogs' | 'eth_getTransactionReceipt' | 'eth_chainId' | 'eth_blockNumber' | 'eth_getBalance' | 'eth_getCode'>;
+    rateLimit?: {
+        perSec: number;
+    };
+}
+export interface JinnManifest {
+    schemaVersion: '1.0.0';
+    name: string;
+    version: string;
+    description?: string;
+    supportedSolverTypes: readonly string[];
+    entry: string;
+    package: {
+        cid: string;
+        hash: `sha256:${string}`;
+    };
+    capabilities: {
+        signer?: {
+            selectors: ReadonlyArray<CapabilityAllowEntry>;
+            typedDataDomains?: ReadonlyArray<TypedDataAllowEntry>;
+        };
+        rpc?: ReadonlyArray<ManifestRpcAllow>;
+        secrets?: ReadonlyArray<{
+            name: string;
+            description: string;
+            required: boolean;
+        }>;
+    };
+    signature: {
+        alg: 'ed25519';
+        publicKey: string;
+        sig: string;
+    };
+    author?: {
+        name: string;
+        url?: string;
+    };
+    license?: string;
+}
+export interface SignerTrustEntry {
+    alg: 'ed25519';
+    publicKey: string;
+    label?: string;
+}

package/dist/harnesses/manifest/types.js

@@ -0,0 +1,8 @@
+/**
+ * Daemon-side manifest types. Same shape as the SDK manifest type;
+ * mirrored locally so the client doesn't have to depend on
+ * @jinn-network/sdk/harness at runtime (the SDK is a publish-time
+ * boundary).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/harnesses/manifest/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/harnesses/manifest/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/harnesses/manifest/verify.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Manifest signature verifier (ed25519).
+ *
+ * Canonicalisation: RFC 8785 JCS over the manifest with the `signature`
+ * field stripped. Authors sign the resulting bytes.
+ */
+import type { JinnManifest, SignerTrustEntry } from './types.js';
+/**
+ * Canonicalise a manifest for signing/verification: RFC 8785 JCS with
+ * the signature field stripped. Recursive (nested objects sort their
+ * own keys), so a third-party verifier with any standard JCS library
+ * can reproduce the signing pre-image byte-for-byte.
+ */
+export declare function canonicaliseManifest(manifest: JinnManifest): string;
+export declare function verifyManifestSignature(manifest: JinnManifest, trustedSigners: readonly SignerTrustEntry[]): Promise<boolean>;

package/dist/harnesses/manifest/verify.js

@@ -0,0 +1,53 @@
+/**
+ * Manifest signature verifier (ed25519).
+ *
+ * Canonicalisation: RFC 8785 JCS over the manifest with the `signature`
+ * field stripped. Authors sign the resulting bytes.
+ */
+import * as ed from '@noble/ed25519';
+import { sha512 } from '@noble/hashes/sha2.js';
+import { canonicalJson } from '../engine/canonical-json.js';
+// @noble/ed25519 v3 needs sha512 wired for synchronous use; the
+// async path (verifyAsync/signAsync) prefers WebCrypto where available
+// but falls back to ed.hashes.sha512 when WebCrypto is missing.
+ed.hashes.sha512 = (m) => sha512(m);
+/**
+ * Canonicalise a manifest for signing/verification: RFC 8785 JCS with
+ * the signature field stripped. Recursive (nested objects sort their
+ * own keys), so a third-party verifier with any standard JCS library
+ * can reproduce the signing pre-image byte-for-byte.
+ */
+export function canonicaliseManifest(manifest) {
+    const { signature: _omit, ...body } = manifest;
+    return canonicalJson(body);
+}
+function b64ToBytes(s) {
+    return new Uint8Array(Buffer.from(s, 'base64'));
+}
+export async function verifyManifestSignature(manifest, trustedSigners) {
+    if (manifest.signature.alg !== 'ed25519')
+        return false;
+    const trustHit = trustedSigners.find((t) => t.alg === 'ed25519' && t.publicKey === manifest.signature.publicKey);
+    if (!trustHit)
+        return false;
+    const body = canonicaliseManifest(manifest);
+    const msg = new TextEncoder().encode(body);
+    let pk;
+    let sig;
+    try {
+        pk = b64ToBytes(manifest.signature.publicKey);
+        sig = b64ToBytes(manifest.signature.sig);
+    }
+    catch {
+        return false;
+    }
+    if (pk.length !== 32 || sig.length !== 64)
+        return false;
+    try {
+        return await ed.verifyAsync(sig, msg, pk);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=verify.js.map

package/dist/harnesses/manifest/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../src/harnesses/manifest/verify.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAG5D,gEAAgE;AAChE,uEAAuE;AACvE,gEAAgE;AAChE,EAAE,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAa,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAsB;IACzD,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,QAAQ,CAAC;IAC/C,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,QAAsB,EACtB,cAA2C;IAE3C,IAAI,QAAQ,CAAC,SAAS,CAAC,GAAG,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACvD,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAClC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,IAAI,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,SAAS,CAAC,SAAS,CAC3E,CAAC;IACF,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5B,MAAM,IAAI,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE3C,IAAI,EAAc,CAAC;IACnB,IAAI,GAAe,CAAC;IACpB,IAAI,CAAC;QACH,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC9C,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAExD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/harnesses/mode-state.d.ts

@@ -0,0 +1,7 @@
+export interface ModeState {
+    mode: 'train' | 'frozen';
+    switchedAt: number;
+}
+export declare function defaultModeStatePath(): string;
+export declare function readModeState(path?: string): ModeState | null;
+export declare function writeModeState(state: ModeState, path?: string): void;

package/dist/harnesses/mode-state.js

@@ -0,0 +1,43 @@
+/**
+ * Mode-switch metadata persistence.
+ *
+ * Tracks `lastModeSwitchAt` so the dashboard's HarnessStatusPanel can report
+ * when the operator most recently flipped between train and frozen. Written
+ * by `jinn harnesses mode <train|frozen>`; read by the harness-status API
+ * endpoint and by `harness status`.
+ *
+ * Stored at `<configDir>/harness/mode-state.json` (configDir defaults to
+ * `~/.jinn-client/`). Failure to read is non-fatal — callers fall back to
+ * `lastModeSwitchAt: undefined`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+export function defaultModeStatePath() {
+    // Tests + CI set JINN_HARNESS_MODE_STATE_PATH to a tmp path so they don't
+    // leak writes into the developer's `~/.jinn-client/`.
+    const env = process.env['JINN_HARNESS_MODE_STATE_PATH'];
+    if (env && env.length > 0)
+        return env;
+    return join(homedir(), '.jinn-client', 'harness', 'mode-state.json');
+}
+export function readModeState(path = defaultModeStatePath()) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf-8'));
+        if (raw.mode !== 'train' && raw.mode !== 'frozen')
+            return null;
+        if (typeof raw.switchedAt !== 'number')
+            return null;
+        return { mode: raw.mode, switchedAt: raw.switchedAt };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeModeState(state, path = defaultModeStatePath()) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+}
+//# sourceMappingURL=mode-state.js.map

package/dist/harnesses/mode-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-state.js","sourceRoot":"","sources":["../../src/harnesses/mode-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAOlC,MAAM,UAAU,oBAAoB;IAClC,0EAA0E;IAC1E,sDAAsD;IACtD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;IACxD,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACtC,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,cAAc,EAAE,SAAS,EAAE,iBAAiB,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe,oBAAoB,EAAE;IACjE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAuB,CAAC;QAC1E,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC/D,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACpD,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAgB,EAAE,OAAe,oBAAoB,EAAE;IACpF,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3D,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACtE,CAAC"}

package/dist/harnesses/names.d.ts

@@ -0,0 +1,6 @@
+export declare const CLAUDE_CODE_HARNESS = "claude-code";
+export declare const CODEX_HARNESS = "codex";
+export declare function canonicalHarnessName(name: string): string;
+export declare function harnessNameMatches(candidate: string, requested: string): boolean;
+export declare function canonicalHarnessNameSet(names: readonly string[]): Set<string>;
+export declare function harnessStateDirName(name: string): string;

package/dist/harnesses/names.js

@@ -0,0 +1,24 @@
+export const CLAUDE_CODE_HARNESS = 'claude-code';
+export const CODEX_HARNESS = 'codex';
+const HARNESS_ALIASES = {
+    'claude-code-learner': CLAUDE_CODE_HARNESS,
+    'codex-code-learner': CODEX_HARNESS,
+};
+export function canonicalHarnessName(name) {
+    return HARNESS_ALIASES[name] ?? name;
+}
+export function harnessNameMatches(candidate, requested) {
+    return canonicalHarnessName(candidate) === canonicalHarnessName(requested);
+}
+export function canonicalHarnessNameSet(names) {
+    return new Set(names.map((name) => canonicalHarnessName(name)));
+}
+export function harnessStateDirName(name) {
+    const canonical = canonicalHarnessName(name);
+    if (canonical === CLAUDE_CODE_HARNESS)
+        return 'claude-code-learner';
+    if (canonical === CODEX_HARNESS)
+        return 'codex-code-learner';
+    return canonical;
+}
+//# sourceMappingURL=names.js.map

package/dist/harnesses/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../../src/harnesses/names.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAC;AACjD,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC;AAErC,MAAM,eAAe,GAA2B;IAC9C,qBAAqB,EAAE,mBAAmB;IAC1C,oBAAoB,EAAE,aAAa;CACpC,CAAC;AAEF,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,SAAiB;IACrE,OAAO,oBAAoB,CAAC,SAAS,CAAC,KAAK,oBAAoB,CAAC,SAAS,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAAwB;IAC9D,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,SAAS,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,SAAS,KAAK,mBAAmB;QAAE,OAAO,qBAAqB,CAAC;IACpE,IAAI,SAAS,KAAK,aAAa;QAAE,OAAO,oBAAoB,CAAC;IAC7D,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/harnesses/types.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Harness-impl interface — §6.7 of the portfolio.v0 design spec.
+ *
+ * Pure type definitions; no runtime side effects.
+ */
+import type { Task } from '../types/task.js';
+import type { OutputArtifact, RationaleEntry, Snapshot } from '../types/portfolio.js';
+import type { TrajectoryCollector } from '../trajectory/index.js';
+import type { ScopedSigner, ScopedRpc, ScopedSecrets } from './capability/index.js';
+export interface RuntimePlugin {
+    name: string;
+    version: string;
+    source: string;
+    sourceKind?: string;
+    solverType?: string;
+    supports?: string[];
+    root: string;
+    manifestPath: string;
+    sha256: string;
+    cid?: string;
+    provenance: 'default' | 'configured';
+}
+export interface HarnessContext {
+    task: Task;
+    /** On-chain / persisted request id for this run. May differ from task.id. */
+    requestId?: string;
+    solverNet?: {
+        name: string;
+        solverType: string;
+        model?: string;
+    };
+    runtimePlugins?: RuntimePlugin[];
+    solverPluginRoots?: string[];
+    /**
+     * IPFS CID of this Task payload (from Marketplace / observe).
+     * Harnesses' submission manifests should reference the same CID; evaluators
+     * compare it via integrity.signedTask_ref. May be an empty string when
+     * provenance is missing (dev / legacy).
+     */
+    taskCid?: string;
+    /** Persistent directory for impl-specific state. */
+    implStateDir: string;
+    /** Ephemeral working directory (cleared between attempts). */
+    workingDir: string;
+    log: (event: {
+        level: 'info' | 'warn' | 'error';
+        msg: string;
+        data?: unknown;
+    }) => void;
+    /** Fires at window.endTs. */
+    abort: AbortSignal;
+    msUntilEndTs: () => number;
+    /**
+     * In-run trajectory collector. Impls call ctx.trajectory.addSpan(...)
+     * (or use the traced wrappers) to emit spans. The engine emits the
+     * collected trajectory to IPFS before envelope assembly and populates
+     * envelope.trajectory with the resulting { cid, sha256 }.
+     */
+    trajectory: TrajectoryCollector;
+    /**
+     * Scoped signer capability. Present when the daemon is providing a
+     * signing surface to this impl per its manifest allow-list. Absent
+     * for stub-mode CLI introspection.
+     * Spec: `spec/2026-05-executor-trust-boundary.md` §3.2.
+     */
+    signer?: ScopedSigner;
+    /**
+     * Scoped read-only RPC client. Method-filtered, rate-limited, and
+     * chain-scoped per the impl's manifest.
+     * Spec: `spec/2026-05-executor-trust-boundary.md` §3.3.
+     */
+    rpc?: ScopedRpc;
+    /**
+     * Per-impl secret bag, populated by `onEnable`.
+     * Spec: `spec/2026-05-executor-trust-boundary.md` §3.4.
+     */
+    secrets?: ScopedSecrets;
+    /**
+     * Harness execution mode. See @jinn-network/sdk/harness HarnessContext.mode
+     * for full documentation.
+     */
+    mode: 'train' | 'frozen';
+}
+export interface Solution {
+    venueRef: {
+        name: string;
+    };
+    /** Optional — evaluation Harnesses that do not operate on a venue leave these undefined. */
+    preSnapshot?: Snapshot;
+    postSnapshot?: Snapshot;
+    fills?: unknown[];
+    /** Shape is per solverType convention. */
+    gating: Record<string, unknown>;
+    informational?: Record<string, unknown>;
+    /**
+     * Full solution payload for Harnesses whose solverType has a non-portfolio payload
+     * schema (e.g. prediction.v1, prediction.apy.v0).
+     *
+     * When set, engine.pack() uses this directly as the envelope payload
+     * (validated against the solverType's solution schema) instead of building the
+     * portfolio-shaped { preSnapshot, postSnapshot, fills, gating } wrapper.
+     * Portfolio impls MUST leave this undefined (engine falls back to legacy shape).
+     */
+    solutionPayload?: Record<string, unknown>;
+    /**
+     * Full verdict payload for evaluation Harnesses (taskRole === 'evaluation').
+     *
+     * When set, engine.pack() uses role='verdict' and passes this as the
+     * envelope payload directly (validated against the solverType's verdict schema).
+     * Restoration impls MUST leave this undefined.
+     */
+    verdictPayload?: Record<string, unknown>;
+    artifacts?: OutputArtifact[];
+    rationale?: RationaleEntry[];
+}
+/**
+ * Context-free readiness probe. "Are this Harness's external dependencies
+ * satisfied right now, regardless of any specific Task?" Used by
+ * `jinn solver-nets doctor` and by the claim-policy gate that refuses
+ * to spend gas claiming a Task whose Harness cannot execute.
+ */
+export interface ReadyStatus {
+    ready: boolean;
+    reason?: string;
+    /** Optional hint for the operator/agent on how to become ready. */
+    nextStep?: {
+        description: string;
+        cli?: string;
+        url?: string;
+    };
+}
+/** Use when a Harness is built in CLI `stub` mode (no live fleet / signer). */
+export declare const REQUIRES_LIVE_DAEMON_READINESS: ReadyStatus;
+/**
+ * Argument a SolverNet-specific enable flow wants from the operator, surfaced
+ * via `enableMetadata()`.
+ */
+export interface EnableArgDef {
+    name: string;
+    description: string;
+    required: boolean;
+}
+/**
+ * Metadata that `jinn solver-nets doctor` uses to teach the operator (or agent)
+ * what's needed to enable a SolverNet. Returned without running the flow.
+ */
+export interface HarnessEnableMetadata {
+    /** Human-readable summary of what opting in to this SolverNet entails. */
+    description: string;
+    requiredArgs?: EnableArgDef[];
+    /** External URLs the operator/agent will need (e.g. exchange UI). */
+    externalResources?: Array<{
+        name: string;
+        url: string;
+    }>;
+}
+/**
+ * Outcome of a single Harness/SolverNet enable invocation.
+ *
+ * The flow is idempotent: the agent reruns the same command until
+ * `status === 'ready'`. Each intermediate state carries enough info for
+ * the agent to know what to do next (show a URL, collect more args,
+ * surface an error).
+ */
+export type EnableResult = {
+    status: 'ready';
+    /** Anything the impl wants to surface (e.g. master address, wallet address). */
+    details?: Record<string, unknown>;
+} | {
+    status: 'waiting_for_external_action';
+    /** What the operator has to do out-of-band (e.g. approve an api-wallet). */
+    action: {
+        description: string;
+        url?: string;
+    };
+    details?: Record<string, unknown>;
+    /** The exact CLI the agent should re-run once the action is done. */
+    nextInvocation: {
+        cli: string;
+        purpose: string;
+    };
+} | {
+    status: 'missing_args';
+    required: EnableArgDef[];
+    example: {
+        cli: string;
+    };
+} | {
+    status: 'error';
+    message: string;
+    details?: Record<string, unknown>;
+};
+export interface HarnessEnableContext {
+    solverNet?: {
+        name: string;
+        solverType: string;
+    };
+    runtimePlugins: RuntimePlugin[];
+    args: Record<string, string | undefined>;
+}
+/**
+ * Thrown by a {@link Harness} when the attempt should be recorded as a
+ * deliberate skip (no failure / no claim retry), e.g. Claude CLI unavailable.
+ */
+export declare class SkippableError extends Error {
+    readonly reason: string;
+    constructor(reason: string, message?: string);
+}
+export interface Harness {
+    name: string;
+    /** semver */
+    version: string;
+    /**
+     * Return true if this Harness should handle the given (solverType, role) pair.
+     *
+     * `role` reflects Task.role:
+     *   - 'restoration' (or undefined — legacy default): the impl runs a restoration attempt
+     *   - 'evaluation': the impl runs as an evaluator producing a verdict
+     *
+     * A Harness for solverType=X should return true for role !== 'evaluation'.
+     * An evaluator Harness for solverType=X should return true for role === 'evaluation'.
+     */
+    supports(ctx: {
+        solverType: string;
+        role?: 'restoration' | 'evaluation';
+    }): boolean;
+    canAttempt?(task: Task): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    run(ctx: HarnessContext): Promise<Solution>;
+    /**
+     * Readiness probe. Zero-dep impls can omit this (treated as `{ ready: true }`).
+     * The optional context lets Harnesses report readiness for a specific
+     * SolverType/role pair without reintroducing global plugin or wrapper state.
+     */
+    isReady?(ctx?: {
+        solverType: string;
+        role?: 'restoration' | 'evaluation';
+    }): Promise<ReadyStatus>;
+    /**
+     * Describes what `onEnable` wants from the caller.
+     */
+    enableMetadata?(): HarnessEnableMetadata;
+    /**
+     * Idempotent enable-state machine. Called by `jinn harnesses enable <name>`
+     * for direct Harness setup, or by SolverNet-specific enable flows when a
+     * SolverNet's selected Harness also needs setup.
+     *
+     * Contract:
+     *   - Zero-dep impls return `{ status: 'ready' }` on every call.
+     *   - Impls with external deps advance as far as they can without
+     *     blocking, then return a `waiting_for_external_action` envelope
+     *     the agent surfaces to the operator.
+     *   - Subsequent invocations pick up where the previous left off.
+     *   - Calling after already-enabled is a no-op that returns `ready`.
+     *
+     * `ctx.args` is the raw `--key=value` map parsed from the CLI. Harnesses
+     * validate and coerce as needed; missing required args should return
+     * `{ status: 'missing_args', required: [...], example: {...} }`.
+     *
+     * Impls that omit this method cannot be enabled by the generic CLI;
+     * they are either always-on (zero-dep) or require manual config.
+     */
+    onEnable?(ctx: HarnessEnableContext): Promise<EnableResult>;
+    /**
+     * Optional inverse of `onEnable`. Invoked when the operator runs
+     * `jinn solver-nets disable <name>`. Should NOT destroy unrecoverable
+     * state (generated key material, on-chain registrations); reserve
+     * that for explicit `jinn solver-nets purge` or similar (out of scope
+     * for this interface).
+     */
+    onDisable?(): Promise<void>;
+}

package/dist/harnesses/types.js

@@ -0,0 +1,28 @@
+/**
+ * Harness-impl interface — §6.7 of the portfolio.v0 design spec.
+ *
+ * Pure type definitions; no runtime side effects.
+ */
+/** Use when a Harness is built in CLI `stub` mode (no live fleet / signer). */
+export const REQUIRES_LIVE_DAEMON_READINESS = {
+    ready: false,
+    reason: 'requires live daemon',
+    nextStep: {
+        description: 'Run the daemon with a configured fleet and wallet',
+        cli: 'jinn run',
+    },
+};
+// ── Sentinel errors (impl → engine) ───────────────────────────────────────────
+/**
+ * Thrown by a {@link Harness} when the attempt should be recorded as a
+ * deliberate skip (no failure / no claim retry), e.g. Claude CLI unavailable.
+ */
+export class SkippableError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message ?? reason);
+        this.name = 'SkippableError';
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/harnesses/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/harnesses/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkIH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,8BAA8B,GAAgB;IACzD,KAAK,EAAE,KAAK;IACZ,MAAM,EAAE,sBAAsB;IAC9B,QAAQ,EAAE;QACR,WAAW,EAAE,mDAAmD;QAChE,GAAG,EAAE,UAAU;KAChB;CACF,CAAC;AA+DF,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,MAAM,CAAS;IAExB,YAAY,MAAc,EAAE,OAAgB;QAC1C,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type DesiredState, type RequestId, type RestorationRequest, type RestorationResult, type DeliveredResult } from './types/index.js';
+export { type Task, type RequestId, type TaskRequest, type TaskResult, type DeliveredResult } from './types/index.js';
 export { TransientError, PermanentError } from './types/index.js';
 export { type ExecutionAdapter } from './adapters/adapter.js';
 export { LocalAdapter } from './adapters/local/adapter.js';

package/dist/main.d.ts

@@ -10,11 +10,15 @@
  *   2. Config file (~/.jinn-client/config.json or --config <path>)
  *   3. Built-in defaults
  *
- * JINN_PASSWORD (env-only) is required for keystore encryption.
+ * Keystore password (used to encrypt the wallet at rest) resolves in this
+ * order: JINN_PASSWORD env var → ~/.jinn-client/keystore-password file →
+ * auto-generated random value (persisted mode 0600 to that same file). A
+ * brand-new operator can run `jinn run` with no env var and no input.
  *
  * Canonical operator command:
  *   jinn run
  */
+import { type ErrorEnvelope } from './errors/envelope.js';
 export interface DaemonStartupInfo {
     schemaVersion: 1;
     generatedAt: string;
@@ -29,4 +33,15 @@ export interface DaemonStartupInfo {
     serviceIndex: number;
     serviceId: number | null;
 }
-export declare function main(): Promise<DaemonStartupInfo>;
+export interface SetupHaltedInfo {
+    schemaVersion: 1;
+    generatedAt: string;
+    kind: 'setup_halted';
+    pid: number;
+    network: 'testnet' | 'mainnet';
+    phase: 'phase-1b' | 'phase-0';
+    apiPort: number;
+    dashboardUrl: string;
+    error: ErrorEnvelope;
+}
+export declare function main(): Promise<DaemonStartupInfo | SetupHaltedInfo | void>;