humanish 0.0.1 → 0.15.0

package/dist/run.d.ts

@@ -0,0 +1,784 @@
+import { type CodexAppServerTrace } from "./codex-app-server.js";
+import { type ActorTrace } from "./actor-contract.js";
+import { type CapturedGitState } from "./core/git-state.js";
+import { type E2BDesktopModule } from "./e2b-desktop-launch.js";
+export declare const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v1";
+export declare const SHARED_WORLD_SCHEMA = "humanish.shared-world.v1";
+export declare const REVIEW_SCHEMA = "humanish.review.v1";
+export declare const VERIFY_SCHEMA = "humanish.verify-result.v1";
+export declare const RUNS_SCHEMA = "humanish.runs-result.v1";
+export declare const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
+export declare const CLEANUP_SCHEMA = "humanish.cleanup-result.v1";
+export declare const PUBLIC_TARGET_CWD = "[target-cwd]";
+export interface RunOptions {
+    cwd: string;
+    actor?: string;
+    actorCommand?: string[];
+    appUrl?: string;
+    dryRun?: boolean;
+    runId?: string;
+    simCount?: number;
+    timeoutMs?: number;
+}
+export type RunStreamKind = "ui" | "browser" | "terminal" | "tui" | "codex-ui" | "artifact" | "summary";
+export type RunSimulationStatus = "queued" | "preparing" | "running" | "passed" | "complete" | "blocked" | "timed_out" | "failed" | "contract_proof_only";
+export interface RunStreamCompletion {
+    actorLogPath?: string;
+    actorLogTail?: string;
+    actorLastMessageTail?: string;
+    actorPid?: number;
+    actorStatus?: "not_started" | "running" | "passed" | "failed" | "blocked" | "timed_out" | "suspended" | "unknown";
+    appLogPath?: string;
+    appPid?: number;
+    appReason?: string;
+    appStatus?: "not_started" | "running" | "blocked" | "failed" | "missing" | "unknown";
+    appUrl?: string;
+    checkedAt: string;
+    exitCode?: number;
+    logTail?: string;
+    nestedObserverPresent?: boolean;
+    nestedVerifyPassed?: boolean;
+    reason: string;
+    status: "running" | "passed" | "failed" | "blocked" | "timed_out";
+    visualReason?: string;
+    visualStatus?: "not_started" | "visible" | "blocked" | "unknown";
+    visualWindowCount?: number;
+    meaningfulUse?: RunMeaningfulUseScore;
+}
+export interface RunSetupQualitySnapshot {
+    schema: "humanish.setup-quality.v1";
+    generatedAt: string;
+    redaction: {
+        status: "passed";
+        rawPreviews: "included" | "suppressed";
+        notes: string;
+    };
+    summary: string;
+    status: "passed" | "needs_review" | "blocked";
+    checks: Array<{
+        id: string;
+        label: string;
+        ok: boolean;
+        detail: string;
+    }>;
+    tree: Array<{
+        path: string;
+        type: "file" | "directory";
+        sizeBytes?: number;
+    }>;
+    previews: Array<{
+        path: string;
+        language: "json" | "yaml" | "typescript" | "markdown" | "text";
+        truncated: boolean;
+        text: string;
+    }>;
+    studyQuality?: {
+        schema: "humanish.study-quality.v1";
+        rating: "none" | "ceremonial" | "useful" | "high_leverage";
+        summary: string;
+        checks: Array<{
+            id: string;
+            label: string;
+            ok: boolean;
+            detail: string;
+        }>;
+        signals: {
+            appUrlProofBlocked: boolean;
+            appUrlProofMentioned: boolean;
+            actorInsightCaptured: boolean;
+            coverageCustomized: boolean;
+            personaCustomized: boolean;
+            scenarioCustomized: boolean;
+        };
+    };
+    packageScripts: Record<string, string>;
+    humanish: {
+        configPresent: boolean;
+        personaCount: number;
+        scenarioCount: number;
+        packageScriptPresent: boolean;
+        gitignoreContainsRuntimeIgnore: boolean;
+    };
+}
+/**
+ * The CLOSED set of core meaningful-use scoring components. Closed by design: these are the generic
+ * dimensions core itself meters (setup/filesystem/nested/actor/product/feedback). A product-specific
+ * scorecard does NOT extend this enum (that would be closed-taxonomy rot — every adopter's nouns
+ * leaking into core); it ships as a thin in-repo extension that emits a namespaced `RunAdapterScore`
+ * via the lane's `score` hook, leaving its own component breakdown in that score's `data`. Exported
+ * so a thin adapter can type against core's score shape without forking.
+ */
+export type RunMeaningfulUseComponentId = "setup-correctness" | "filesystem-evidence" | "nested-humanish-evidence" | "actor-activity" | "product-surface" | "feedback-quality";
+export interface RunMeaningfulUseScore {
+    schema: "humanish.meaningful-use-score.v1";
+    status: "pass" | "partial" | "fail";
+    score: number;
+    summary: string;
+    hardFailures: string[];
+    components: Array<{
+        id: RunMeaningfulUseComponentId;
+        label: string;
+        status: "pass" | "partial" | "fail";
+        score: number;
+        detail: string;
+    }>;
+}
+/**
+ * A namespaced, product-agnostic score a thin adapter attaches to the bundle via the terminal-product
+ * lane's `score` hook (the layer-6 extension seam, issue #154 acceptance #8). Core never reads its
+ * `data` and knows none of the adopter's nouns — the `namespace` (e.g. `"acme-pixelforge"`) scopes
+ * the whole record so core schemas stay product-agnostic and a future inert-field audit does not
+ * misfire on a noun core never owned. The adopter's real scorecard (component weights, product
+ * rubric) lives in ITS repo and is summarized into the generic status/score/summary; everything
+ * product-specific rides under `data`. This is NOT a built-in product scorer — it is the SEAM the
+ * adopter's scorer plugs into without forking core.
+ */
+export interface RunAdapterScore {
+    schema: "humanish.adapter-score.v1";
+    /** The adapter's namespace — non-core, product-scoped (e.g. an adopter slug). Required + non-empty. */
+    namespace: string;
+    status: "pass" | "partial" | "fail";
+    /** A 0-100 summary the adapter derived from its own (off-core) rubric. */
+    score: number;
+    summary: string;
+    /** Arbitrary product-specific payload (the adopter's component breakdown / nouns). Core never reads it. */
+    data?: Record<string, unknown>;
+}
+export interface RunFeedbackCandidate {
+    schema: "humanish.feedback-candidate.v1";
+    id: string;
+    run_id: string;
+    stream_id?: string;
+    adapter_id: string;
+    scenario_id: string;
+    persona_id: string;
+    actor: "codex-tui" | "codex-exec" | "codex-app-server" | "synthetic-dry-run" | "unknown";
+    substrate: "e2b-desktop" | "e2b-terminal" | "local-filesystem" | "codex-app-server" | "unknown";
+    failure_owner: "harness" | "target-app" | "actor" | "environment" | "unknown";
+    summary: string;
+    expected: string;
+    actual: string;
+    evidence: Array<{
+        path: string;
+        kind: "review" | "state" | "log" | "trace" | "screenshot" | "filesystem";
+        note: string;
+    }>;
+    redaction: {
+        status: "passed";
+        notes: string;
+    };
+    idempotency_key: string;
+    proposed_next_state: "watch" | "adapter-hardening" | "target-app-setup" | "actor-auth" | "setup-quality-review" | "study-quality-review";
+    acceptance_proof: string[];
+    /**
+     * OPTIONAL, ADAPTER-NAMESPACED product-noun block (the layer-6 extension seam, issue #154
+     * acceptance #8 + the "record product-specific concepts as NON-core nouns" list). A thin adapter
+     * records product-specific concepts — public CLI/product command observed, hosted product
+     * success-or-blocker, feedback id/draft observed, media/job/asset ids, explicit
+     * no-media/no-provider-spend proof, defection/friction risk — WITHOUT making any of them core
+     * primitives. They ride under a single namespaced field so core's feedback enums
+     * (`evidence.kind`, `proposed_next_state`) stay product-agnostic and a future inert-field audit
+     * never misfires on a noun core never owned. Core validates only the SHAPE (a non-empty
+     * `namespace` + a `data` record); the keys inside `data` are the adapter's, never core's.
+     */
+    adapter?: {
+        /** Non-core, product-scoped namespace (e.g. an adopter slug). Required + non-empty. */
+        namespace: string;
+        /** The adapter's product nouns. Core never reads these keys — it stays product-agnostic. */
+        data: Record<string, unknown>;
+    };
+}
+/**
+ * Optional, adapter-namespaced artifact references. These let a thin in-repo
+ * adapter attach product/state proof outputs to the Humanish evidence packet
+ * without teaching core product nouns or inventing fake streams.
+ */
+export interface RunAdapterArtifact {
+    schema: "humanish.adapter-artifact.v1";
+    namespace: string;
+    label: string;
+    path: string;
+    kind: "state" | "review" | "log" | "trace" | "screenshot" | "filesystem" | "summary";
+    note: string;
+}
+export interface RunSimulation {
+    id: string;
+    index: number;
+    personaId: string;
+    scenarioId: string;
+    status: RunSimulationStatus;
+    streamKind: RunStreamKind;
+    mode: "browser-sim" | "cli-sim" | "tui-sim" | "codex-app-sim";
+    progress: number;
+    currentStep: string;
+    summary: string;
+    streamIds: string[];
+    startedAt: string;
+    updatedAt: string;
+}
+export interface RunStream {
+    id: string;
+    simId: string;
+    /** Adapter-owned lane id for fan-out / target-swarm runs. Safe categorical metadata only. */
+    laneId?: string;
+    /** Adapter-owned actor class for grouping lanes, e.g. viewer/reviewer/admin. */
+    actorType?: string;
+    /** Adapter-owned product surface label for grouping lanes without parsing URLs. */
+    surface?: string;
+    /** Adapter-owned scenario/case grouping label. */
+    caseGroup?: string;
+    kind: RunStreamKind;
+    label: string;
+    status: RunSimulationStatus;
+    transport: "snapshot" | "polling" | "sse" | "pty" | "app-server";
+    updatedAt: string;
+    url?: string;
+    embed?: {
+        kind: "iframe" | "terminal" | "screenshot" | "placeholder";
+        url?: string;
+        title?: string;
+    };
+    viewport?: {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number;
+        isMobile?: boolean;
+    };
+    terminal?: {
+        title: string;
+        format: "ansi" | "plain";
+        stdin: "disabled" | "planned" | "sent";
+        tail: string;
+    };
+    ui?: {
+        actorStatus?: string;
+        appStatus?: string;
+        appUrl?: string;
+        route?: string;
+        intent?: string;
+        nestedObserverPath?: string;
+        nestedObserverUrl?: string;
+        screenshotUrl?: string;
+        state?: string;
+        visualStatus?: string;
+    };
+    codex?: {
+        provider: "codex-app-server";
+        eventCount?: number;
+        experimentalApi?: boolean;
+        model?: string;
+        sessionId?: string;
+        state: "not_connected" | "connecting" | "watching" | "running" | "completed" | "failed" | "blocked" | "timed_out";
+        contract: string;
+        threadId?: string;
+        trace?: CodexAppServerTrace;
+        tracePath?: string;
+        turnId?: string;
+    };
+    actor?: ActorTrace;
+    completion?: RunStreamCompletion;
+    artifacts: Array<{
+        label: string;
+        path: string;
+        kind: "bundle" | "review" | "observer" | "events" | "screenshot" | "trace" | "log" | "filesystem";
+    }>;
+}
+export interface RunEvent {
+    id: string;
+    at: string;
+    level: "info" | "warn" | "error";
+    type: string;
+    message: string;
+    simId?: string;
+    streamId?: string;
+}
+/**
+ * One executed (or declared) subject-state seed step. Live records carry execution fields
+ * (ok/exitCode/timedOut/durationMs); dry-run "declared, not run" records carry only the
+ * declaration (name, phase, command DIGEST). The command itself never persists — the digest
+ * pins "same recipe" across bundles while the lab YAML in the consumer's repo stays the
+ * plaintext source of truth (publish-safe by construction).
+ */
+export interface RunSubjectStateStepRecord {
+    name: string;
+    when: "before-build" | "before-start" | "after-ready";
+    /** sha256 hex of the exact command string, first 16 chars (the promptDigest convention). */
+    commandDigest: string;
+    /** Absent on declared-not-run records (dry-run; unreached steps are absent entirely). */
+    ok?: boolean;
+    exitCode?: number;
+    timedOut?: boolean;
+    durationMs?: number;
+}
+/**
+ * Structured subject provenance (invariant 5): what the subject WAS — code pin (repo/commit,
+ * or a local-tree archive digest) AND state story. Optional additive field on
+ * humanish.run-bundle.v1; absent on bundles from backends that have not adopted it (and on all
+ * pre-existing bundles).
+ */
+export interface RunSubjectProvenance {
+    source: "clone" | "app-url" | "local-tree";
+    /** Clone-route only. Honors policies.redactRepos exactly as the provenance event does. */
+    repo?: string;
+    /** Clone-route: the cloned commit SHA. Local-tree route: the host-side HEAD at pack time,
+     *  when the packed root was a git work tree. */
+    commit?: string;
+    /**
+     * Local-tree-route only (additive): 64 lowercase-hex sha256 over the sorted packed-entries
+     * list (docs/contracts/schemas.md). This is the provenance PIN for the local-tree route: a
+     * dirty working tree cannot be commit-pinned, so the archive content digest stands in for it.
+     */
+    archiveSha256?: string;
+    /**
+     * Local-tree-route only (additive): true when the host git work tree had uncommitted changes
+     * at pack time. Absent when the packed root was not a git work tree at all.
+     */
+    dirty?: boolean;
+    /** Declared env NAMES provisioned for the subject — names only, values never. */
+    envNames?: string[];
+    state: {
+        /**
+         * seeded: live run, steps declared, ALL ran ok, no external state declared.
+         * unpinned: external state declared (seed records, if any, still attached — migrating
+         *   an external DB is still unpinned overall).
+         * declared-not-run: steps declared but not (all) executed ok — dry-run contract bundles
+         *   and failed live provisioning.
+         * undeclared: no subject.state block (stateless apps, app-url subjects) — the explicit
+         *   "absence declared" marker invariant 5 requires.
+         */
+        provenance: "seeded" | "unpinned" | "declared-not-run" | "undeclared";
+        seed?: RunSubjectStateStepRecord[];
+        externalEnvNames?: string[];
+    };
+}
+/**
+ * How well a run attributed INTERACTION between actors — a new, ORTHOGONAL honesty axis to the
+ * persona-sampling evidence classes (which answer "how representative is the actor?"). Absent ==
+ * `isolated` (every existing bundle byte-stable). `shared-world` means N roles drove ONE mutable
+ * plane and their per-role attribution is weaker (its ceiling is pinned in `sharedWorld.attributionLimits`).
+ */
+export type RunAttributionClass = "isolated" | "shared-world";
+/** The ONE shared service-plane provenance for a shared-world run (#164): single commit + a
+ *  seed-recipe digest + the provisioned env NAMES (values never). */
+export interface SharedWorldPlane {
+    /** The cloned commit SHA of the shared plane (when the clone resolved one). */
+    commit?: string;
+    /** sha256-16 over the ordered seed-step command digests — the seeded-state RECIPE identity
+     *  (not the runtime state). Pins "same seed recipe" across bundles. */
+    seedDigest: string;
+    /** Declared env NAMES provisioned for the shared plane (values never surface). */
+    envNames: string[];
+    /**
+     * CONCURRENT route only (#164 phase 2): sha256-16 of the harness-minted `getHost` URL's ORIGIN
+     * (the first-class provisioned-subject target every actor drove — invariant 2). A DIGEST, not the
+     * raw URL: a getHost URL embeds the (live) sandbox id and matches the publish-safety e2b-URL
+     * redaction, so — like the stream URL and like sandbox ids — it never lands raw in a published
+     * bundle (the raw tokenless URL is surfaced only on the ephemeral lab result). The orchestrator
+     * confirms the URL is TOKENLESS (no authKey — invariant 1) before digesting. verify proves every
+     * actor drove this host by digest equality. Absent on the sequential route.
+     */
+    hostDigest?: string;
+    /**
+     * CONCURRENT route only: the author's REQUIRED attestation that the subject behind the
+     * internet-reachable getHost URL is synthetic seeded data (FIX-3). This is author-trust + a
+     * provenance gate, NOT a no-real-data guarantee. Verify fails closed if absent on the concurrent route.
+     */
+    exposure?: "synthetic";
+}
+/**
+ * CONCURRENT shape (#164 phase 2): one actor's harness-clocked activity window against the ONE
+ * shared plane. OVERLAPPING windows mechanically prove ≥2 personas were active simultaneously.
+ * `laneWindows` and `stateSeries` are INDEPENDENT series — there is deliberately NO per-delta→actor
+ * field (causation under concurrency is structurally inexpressible — FIX-7).
+ */
+export interface SharedWorldLaneWindow {
+    roleId: string;
+    actorType?: string;
+    surface?: string;
+    caseGroup?: string;
+    /** Resolves to a real RunSimulation in this bundle. */
+    simId: string;
+    /** Resolves to a real RunStream (the actor's trace) in this bundle. */
+    streamId: string;
+    /** ms on the ONE harness clock — the wrapped [start,end] the orchestrator MEASURED (FIX-1). */
+    startedAt: number;
+    endedAt: number;
+    /** The actor's terminal session verdict (per-persona). */
+    verdict: string;
+    /** sha256-16 of the ORIGIN of the getHost seat URL this actor drove. verify confirms it equals
+     *  plane.hostDigest — i.e. the actor drove EXACTLY the harness-minted host (invariant 2; FIX-2).
+     *  A digest, not the raw URL (a getHost URL is not publish-safe — see SharedWorldPlane.hostDigest). */
+    routeHostDigest: string;
+    /** The shared plane's commit this actor observed (omitted when unresolved). */
+    commit?: string;
+    /** The shared plane's seed-recipe digest this actor observed. */
+    seedDigest: string;
+}
+/** CONCURRENT shape: one cadence checkpoint of the shared world under load. DIGEST-ONLY — the
+ *  allowed-keys tripwire (SHARED_WORLD_STATESERIES_KEYS) permits ONLY {timestamp, digest}. */
+export interface SharedWorldStateSnapshot {
+    /** ms on the ONE harness clock. */
+    timestamp: number;
+    /** sha256-16 of the (scrubbed, redacted) combined probe output at this snapshot. */
+    digest: string;
+}
+/** CONCURRENT shape: one persona's OUTCOME against the contended world (the "M of N" headline). */
+export interface SharedWorldOutcome {
+    roleId: string;
+    actorType?: string;
+    surface?: string;
+    caseGroup?: string;
+    simId: string;
+    streamId: string;
+    /** Terminal session status. */
+    status: string;
+    completionReason?: string;
+    /** Reached its goal (terminal, engaged, no harness error). */
+    ok: boolean;
+}
+/** A timeline checkpoint: a read-only digest probe of the shared plane at one moment. Persisted
+ *  DIGEST-ONLY — `digest` is sha256-16(scrub+redact(stdout)); no raw value ever lands. */
+export interface SharedWorldCheckpoint {
+    kind: "checkpoint";
+    /** "cp-baseline" for the baseline snapshot; "cp-after-<roleId>" after each role's turn. */
+    name: string;
+    /** sha256-16 of the (scrubbed, redacted) combined probe output at this snapshot. */
+    digest: string;
+    /** True when this snapshot's digest differs from the previous checkpoint's — the observed
+     *  state changed across the intervening turn (delta attributed to the TURN, not an action). */
+    deltaFromPrev: boolean;
+}
+/** A timeline turn: one role's seat session against the shared plane. Carries the plane
+ *  provenance it observed (identical across turns by construction — the single-plane proof). */
+export interface SharedWorldTurn {
+    kind: "turn";
+    roleId: string;
+    /** Resolves to a real RunSimulation in this bundle. */
+    simId: string;
+    /** Resolves to a real RunStream (the role's actor trace) in this bundle. */
+    streamId: string;
+    /** The shared plane's commit the role observed (omitted when unresolved). */
+    commit?: string;
+    /** The shared plane's seed-recipe digest the role observed. */
+    seedDigest: string;
+}
+export type SharedWorldTimelineEntry = SharedWorldCheckpoint | SharedWorldTurn;
+/**
+ * The shared-world evidence block (`humanish.shared-world.v1`). TWO variants discriminated by
+ * `topologyMode` (FIX-8 — renamed off `RunBundle.mode` to avoid the dry-run|live collision):
+ *
+ * - SEQUENTIAL (`topologyMode: "sequential"`, the PoC): `sequence` + an alternating `timeline`
+ *   (cp-baseline → turn → cp → … → cp); limits `sequential-only` etc.
+ * - CONCURRENT (`topologyMode: "concurrent"`, #164 phase 2): `laneWindows` + `stateSeries` +
+ *   `outcomes`; limits `concurrent` etc. NO `timeline`.
+ *
+ * Additive + optional on `humanish.run-bundle.v1` — absent on every non-shared-world bundle.
+ * The mandatory `attributionLimits` are verify-enforced (FAIL CLOSED on a missing required or a
+ * present forbidden limit).
+ */
+export interface SharedWorldEvidence {
+    schema: typeof SHARED_WORLD_SCHEMA;
+    topology: "shared-world";
+    /** The substrate discriminator (FIX-8). Branched on FIRST by validateSharedWorldEvidence. */
+    topologyMode: "sequential" | "concurrent";
+    /** The DECLARED number of role seats. */
+    roleCount: number;
+    plane: SharedWorldPlane;
+    /** The pinned, verify-enforced attribution ceiling (the set differs per topologyMode). */
+    attributionLimits: string[];
+    /** The role ids that actually took a turn, in declared order. */
+    sequence?: string[];
+    timeline?: SharedWorldTimelineEntry[];
+    /** Per-actor harness-clocked windows (overlap proves simultaneity). */
+    laneWindows?: SharedWorldLaneWindow[];
+    /** Cadence digests of the shared world under load (baseline + periodic + final). */
+    stateSeries?: SharedWorldStateSnapshot[];
+    /** Per-persona outcomes (the "M of N succeeded" headline). */
+    outcomes?: SharedWorldOutcome[];
+}
+export interface RunBundle {
+    schema: typeof RUN_BUNDLE_SCHEMA;
+    runId: string;
+    mode: "dry-run" | "live";
+    simCount: number;
+    createdAt: string;
+    cwd: string;
+    artifactRoot: string;
+    source: {
+        packageName: string | null;
+        humanishSource: "present" | "missing";
+        git: CapturedGitState;
+    };
+    persona: {
+        id: string;
+        name: string;
+        source: string;
+        sourceDigest: string;
+    };
+    scenario: {
+        id: string;
+        title: string;
+        goal: string;
+        source: string;
+        sourceDigest: string;
+    };
+    lifecycle: Array<{
+        at: string;
+        event: string;
+        message: string;
+    }>;
+    simulations: RunSimulation[];
+    streams: RunStream[];
+    events: RunEvent[];
+    redaction: {
+        status: "passed";
+        notes: string;
+    };
+    artifacts: {
+        run: string;
+        reviewJson: string;
+        reviewMarkdown: string;
+        observerData: string;
+        events: string;
+    };
+    review: ReviewSummary;
+    feedbackCandidates: RunFeedbackCandidate[];
+    /** Structured subject provenance (invariant 5). Optional and additive: emitted by the
+     * computer-use backend; tolerated absent everywhere else. */
+    subject?: RunSubjectProvenance;
+    /**
+     * The custom E2B desktop TEMPLATE (image) the run's sandbox(es) actually launched on, from
+     * `execution.desktop.template` — so the evidence shows WHICH image ran (a subject needing
+     * runtimes the stock `desktop` image lacks runs on an adopter's template). Optional + additive:
+     * present only when a template was configured (absent == the stock `desktop` template, every
+     * pre-existing bundle byte-stable). A template name is public-safe (not a secret).
+     */
+    desktopTemplate?: string;
+    /**
+     * Browser family requested for hosted desktop actor lanes and the in-sandbox command that opened
+     * it, when explicitly configured. Optional + additive; absent means the historical default opener
+     * path was used or the backend does not create a headed desktop.
+     */
+    desktopBrowser?: {
+        requested: "default" | "chrome" | "chromium" | "firefox";
+        resolved?: string;
+    };
+    /**
+     * Optional lineage for a run that intentionally re-executes selected lanes from a prior
+     * multi-lane run. This keeps retry-like workflows explicit: the new run is linked to the old
+     * evidence, but it never mutates or silently "fixes" the original verdict.
+     */
+    rerun?: RunRerunLineage;
+    /**
+     * The interaction-attribution honesty axis (#164). Absent == `isolated` (every existing bundle
+     * byte-stable). Set to `shared-world` by the shared-world backend, paired with `sharedWorld`.
+     */
+    attributionClass?: RunAttributionClass;
+    /**
+     * Shared-world evidence block (`humanish.shared-world.v1`). Optional + additive; present only on
+     * shared-world runs. Verified fail-closed by validateSharedWorldEvidence.
+     */
+    sharedWorld?: SharedWorldEvidence;
+    /**
+     * OPTIONAL, ADAPTER-NAMESPACED product score (the layer-6 extension seam, issue #154 acceptance
+     * #8). A thin adapter's `score` hook returns a `RunAdapterScore`; the lane attaches it here
+     * WITHOUT core knowing any product noun (the score is namespaced + its breakdown lives in `data`).
+     * The default mission-based verdict (`review`) is unchanged when no scorer hook is given.
+     */
+    adapterScore?: RunAdapterScore;
+    /**
+     * OPTIONAL, ADAPTER-NAMESPACED product/state proof artifacts. Core validates
+     * shape and local relative artifact references, then verifies the referenced
+     * files exist. The adapter owns the payload schema under `namespace`.
+     */
+    adapterArtifacts?: RunAdapterArtifact[];
+    /**
+     * Provider resources this run owns and may clean up later by exact recorded id.
+     * Optional + additive: absent means the producer did not record any run-owned
+     * remote resources. Core cleanup never enumerates provider accounts.
+     */
+    providerResources?: RunProviderResource[];
+}
+export interface RunProviderResource {
+    schema: "humanish.provider-resource.v1";
+    provider: "e2b-desktop";
+    kind: "sandbox";
+    id: string;
+    owner: "humanish";
+    status: "running" | "killed" | "unknown";
+    simId?: string;
+    streamId?: string;
+    laneId?: string;
+    createdAt?: string;
+    cleanup?: {
+        killed: boolean;
+        reason: string;
+    };
+}
+export interface RunRerunLineage {
+    sourceRunId: string;
+    selectedLaneIds: string[];
+    previous: Array<{
+        laneId: string;
+        streamId?: string;
+        status: string;
+        reason?: string;
+        actorStatus?: string;
+        completionReason?: string;
+    }>;
+}
+export interface ReviewSummary {
+    schema: typeof REVIEW_SCHEMA;
+    verdict: "contract_proof_only" | "pass" | "fail" | "blocked" | "timed_out";
+    summary: string;
+    gaps: string[];
+}
+export declare function buildRunSource(args: {
+    cwd: string;
+    capturedAt?: Date | string;
+    humanishSource: RunBundle["source"]["humanishSource"];
+    packageName: string | null;
+}): Promise<RunBundle["source"]>;
+export interface RunResult {
+    schema: "humanish.run-result.v1";
+    ok: boolean;
+    runId?: string;
+    mode?: "dry-run" | "live";
+    simCount?: number;
+    cwd: string;
+    artifactRoot?: string;
+    bundlePath?: string;
+    reviewPath?: string;
+    latestPath?: string;
+    warnings: string[];
+    error?: {
+        code: "HUMANISH_ACTOR_FANOUT_UNIMPLEMENTED" | "HUMANISH_APP_URL_OPTION_CONFLICT" | "HUMANISH_BROWSER_APP_CAPTURE_FAILED" | "HUMANISH_CODEX_APP_SERVER_FAILED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_LOCAL_CODEX_EXEC_FAILED" | "HUMANISH_LOCAL_CODEX_TUI_FAILED" | "HUMANISH_INVALID_APP_URL" | "HUMANISH_INVALID_ACTOR_CONCURRENCY" | "HUMANISH_INVALID_CWD" | "HUMANISH_INVALID_SIM_COUNT" | "HUMANISH_INVALID_TIMEOUT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_ACTOR" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT";
+        message: string;
+    };
+}
+export interface VerifyResult {
+    schema: typeof VERIFY_SCHEMA;
+    ok: boolean;
+    cwd: string;
+    run: string;
+    bundlePath?: string;
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        message: string;
+    }>;
+    shareSafety: {
+        status: "share_ready" | "local_only" | "blocked";
+        reasons: Array<{
+            code: "VERIFY_FAILED" | "PUBLIC_SAFETY_FINDINGS" | "RAW_SCREENSHOTS";
+            message: string;
+        }>;
+    };
+    warnings: string[];
+    error?: {
+        code: "HUMANISH_RUN_NOT_FOUND" | "HUMANISH_INVALID_RUN_BUNDLE";
+        message: string;
+    };
+}
+export interface CleanupResourceResult {
+    provider: RunProviderResource["provider"];
+    kind: RunProviderResource["kind"];
+    id: string;
+    status: "killed" | "already_clean" | "failed" | "skipped";
+    message: string;
+}
+export interface CleanupAdapterResult {
+    id: string;
+    ok: boolean;
+    message: string;
+}
+export interface CleanupResult {
+    schema: typeof CLEANUP_SCHEMA;
+    ok: boolean;
+    cwd: string;
+    run: string;
+    runId?: string;
+    bundlePath?: string;
+    cleanupPath?: string;
+    checkedAt: string;
+    summary: {
+        resources: number;
+        killed: number;
+        alreadyClean: number;
+        failed: number;
+        skipped: number;
+    };
+    resources: CleanupResourceResult[];
+    adapterResults: CleanupAdapterResult[];
+    warnings: string[];
+    error?: {
+        code: "HUMANISH_RUN_NOT_FOUND" | "HUMANISH_INVALID_RUN_BUNDLE";
+        message: string;
+    };
+}
+export interface RunCleanupHooks {
+    loadDesktopModule?: () => Promise<E2BDesktopModule>;
+    cleanupAdapterResources?: (ctx: {
+        cwd: string;
+        runDir: string;
+        bundle: RunBundle;
+    }) => Promise<CleanupAdapterResult[]>;
+    now?: () => Date;
+}
+export interface RunsResult {
+    schema: typeof RUNS_SCHEMA;
+    ok: boolean;
+    cwd: string;
+    runs: Array<{
+        runId: string;
+        createdAt: string | null;
+        mode: string | null;
+        path: string;
+    }>;
+    latest: string | null;
+    error?: {
+        code: "HUMANISH_RUNS_UNAVAILABLE";
+        message: string;
+    };
+}
+export interface DoctorResult {
+    schema: typeof DOCTOR_SCHEMA;
+    ok: boolean;
+    cwd: string;
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        message: string;
+    }>;
+}
+export declare function runDryRun(options: RunOptions): Promise<RunResult>;
+type LocalActorTerminalStatus = Extract<RunSimulationStatus, "passed" | "failed" | "blocked" | "timed_out">;
+/**
+ * Strip ANSI/control noise from a captured terminal transcript into stable, scannable text.
+ * Pure (no IO). Exported so the terminal-product lane (src/e2b-terminal-lab.ts) normalizes its
+ * captured exec stream EXACTLY as the local-actor lanes do — the verdict-nonce scorer is only
+ * sound against the same normalization the marker is matched on, so the logic must not diverge.
+ */
+export declare function normalizeLocalActorTranscript(transcript: string): string;
+/**
+ * Extract the per-run verdict from a normalized transcript: the agent must print exactly
+ * `HUMANISH_ACTOR_VERDICT=<status> HUMANISH_ACTOR_NONCE=<nonce>`, and the nonce is mandatory so a
+ * bare marker (echoed or replayed from untrusted text) can never forge a verdict. Pure (no IO).
+ * Exported so the terminal-product lane scores its in-sandbox `codex exec` run by the SAME marker
+ * — divergent verdict logic would let the two lanes disagree about what "passed" means.
+ */
+export declare function extractLocalActorVerdict(transcript: string, verdictNonce: string): LocalActorTerminalStatus | null;
+export declare function verifyRun(cwdInput: string, runInput: string): Promise<VerifyResult>;
+export declare function cleanupRun(cwdInput: string, runInput: string, hooks?: RunCleanupHooks): Promise<CleanupResult>;
+export declare function loadRunBundle(cwdInput: string, runInput: string): Promise<{
+    bundle: RunBundle;
+    bundlePath: string;
+    runDir: string;
+} | null>;
+export declare function listRuns(cwdInput: string): Promise<RunsResult>;
+export declare function readReview(cwdInput: string, runInput: string): Promise<VerifyResult | (ReviewSummary & {
+    path: string;
+    runId: string;
+})>;
+export declare function doctor(cwdInput: string): Promise<DoctorResult>;
+export {};