feat(kernel): surface-diff harvest + Prime Agent harness integration contract

docs/README.md

@@ -47,6 +47,7 @@ These are internal working documents: design theses, research narrative, and roa
 
 | Doc | Role | Purpose |
 |---|---|---|
+| [design/prime-agent-harness-integration.md](./design/prime-agent-harness-integration.md) | integration contract | Prime Agent as a sandbox-materialized harness: the boundary, the anti-reinvention map, the substrate wish-list, and the first gated experiment. |
 | [simplification-plan.md](./research/simplification-plan.md) | historical tracker | Earlier simplification analysis. The active execution and API convergence plan is [agent-managed-compute/roadmap.md](./agent-managed-compute/roadmap.md). |
 | [research/README.md](./research/README.md) | research index | Forward-looking design threads + decision log. Not the canonical spine. |
 | [archive/](./archive/) | retired notes | Superseded/niche docs kept for history (delivery manifest, conversation economics, artifact-lifecycle, go-live, results, benchmark-matrix consolidation). |

docs/api/primitive-catalog.md

@@ -524,7 +524,7 @@ Import from `@tangle-network/agent-runtime/intelligence` — 166 exports.
 
 ### Execution kernel — recursive atom, supervision, executors, round-synchronous loop
 
-Import from `@tangle-network/agent-runtime/kernel` — 745 exports.
+Import from `@tangle-network/agent-runtime/kernel` — 755 exports.
 
 | Symbol | Kind | Summary |
 |---|---|---|
@@ -544,6 +544,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 745 exports.
 | `auditIntent` | function | The route-rigor analyst: compare declared vs revealed vs user intent over a trajectory and return aligned / drifting / diverged with evidence and one recommended intervention. |
 | `authorStrategy` | function | Author + load a strategy from losses. Throws when the author emits no loadable module; |
 | `bestSoFar` | function | The best-so-far fold — the ONE definition of "how good was the run after k results", shared by |
+| `boxSurfaceReader` | function | A {@link SurfaceReader} over a sandbox box's filesystem — the same `box.fs.read` seam |
 | `breadthStrategy` | function | BREADTH: K independent rollouts (each own artifact), verifier picks the best. |
 | `buildSteerContext` | function | Build the `SteerContext` a combinator reads to steer (its `loopUntil.until`, `widen` gate, any |
 | `canDisplace` | function | The repair keep-best guard: a challenger displaces the incumbent only when it is |
@@ -614,9 +615,11 @@ Import from `@tangle-network/agent-runtime/kernel` — 745 exports.
 | `flatWidenGate` | function | The flat default `ScopeWidenGate` — never widens, keeping the R2 selector≠judge collision |
 | `formatPromptHandle` | function | The string form of a handle: `<surface>/v<n>`. |
 | `freeSlots` | function | Free worker slots under a simultaneity cap: `cap - live`, floored at 0, or `null` when there is |
+| `fsSurfaceReader` | function | A {@link SurfaceReader} over the local filesystem, for worktree/local workers. Every path — |
 | `gateOnDeliverable` | function | Wrap an `Executor` so its settlement `valid` reflects the deliverable check, not the |
 | `gitWorkspace` | function | A `Workspace` over a git checkout: materialize an isolated worktree at `ref`, commit produced changes (conflict-aware), and read `head` — hooks disabled, identity pinned. |
 | `harvestCorpus` | function | Batch the firewalled `observe()` analyst over completed runs and accrete the trace-derived facts into the durable corpus — the production-traces→corpus write side of the flywheel. |
+| `harvestSurfaceDiffs` | function | Re-read every mounted (and watched) surface and report the ones whose settled state differs from |
 | `inlineSandboxClient` | function | Adapt an `ExecutorFactory` into a `SandboxClient` for `runAgentRounds`. The factory is |
 | `inProcessSandboxClient` | function | Adapt a single `onPrompt(prompt, ctx)` callback into a `SandboxClient` for |
 | `isWaitOutcome` | function | Narrow a settlement's `out` to a wait outcome — a wait settles on the SAME cursor as workers, |
@@ -804,6 +807,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 745 exports.
 | `AuthorizedSpawnContext` | interface | Exact trusted context after a manager-authored spawn has passed product authorization. |
 | `BenchmarkCell` | interface | One strategy's outcome on one task — the per-task cell an optimizer consumes. |
 | `BenchmarkReport` | interface | Benchmark output: per-strategy means plus the full per-task × per-strategy losses table an optimizer mines. |
+| `BoxSurfaceReaderOptions` | interface | Retry and cancellation controls for {@link boxSurfaceReader}. |
 | `BridgeModelCredential` | interface | A live, request-scoped model credential reference for a local cli-bridge. |
 | `BridgeSeam` | interface | cli-bridge seam. A local OpenAI-compatible bridge that fronts harness CLIs |
 | `Budget` | interface | A budget envelope on a spawn or the root. All ceilings; the pool reserves against them. |
@@ -872,6 +876,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 745 exports.
 | `ForkCapableBox` | interface | Loop-side widening of the box's optional fork method. |
 | `GraphNode` | interface | A graph node: an id and a canonical `AgentProfile`. The profile is the ONLY way a node is |
 | `Handle` | interface | A live child handle. `abort()` is defined over the ACQUIRE lifecycle: it chains into |
+| `HarvestSurfaceDiffsOptions` | interface | Inputs to {@link harvestSurfaceDiffs}: the run's mount manifest, the read seam, and optional |
 | `InboxMessage` | interface | The worker-side receive end of the down-leg: a per-worker inbox an executor exposes as |
 | `InMemoryRunContext` | interface | The bundle of stores a supervised run needs, shaped to spread into `SupervisorOpts`. |
 | `InMemoryRunContextOptions` | interface | Options for a supervised run context. |
@@ -999,6 +1004,8 @@ Import from `@tangle-network/agent-runtime/kernel` — 745 exports.
 | `SupervisorSpanOutcome` | interface | How the supervised run ended, as `finish()` records it on the root span. |
 | `SupervisorToolDescriptor` | interface | One product-owned tool. It reuses the canonical MCP descriptor fields while Runtime supplies |
 | `SupervisorToolInvocationContext` | interface | Trusted context for one product-tool invocation. The node identity remains the same detached, |
+| `SurfaceDiff` | interface | One watched surface whose settled state differs from what was mounted (or from absence). |
+| `SurfaceReadBox` | interface | The minimal box surface the box-backed reader needs — structurally typed so the real |
 | `SurfaceWorkerConfig` | interface | How a worker runs the surface task (its router substrate + per-attempt bounds). |
 | `SurfaceWorkerOut` | interface | What a surface worker settles with — the surface verdict the driver + deliverable read. `resolved` is |
 | `ToolLoopCompaction` | interface | Self-compaction — bound the loop's OWN context window the way a fresh-respawn (dumb-Ralph) loop |
@@ -1013,6 +1020,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 745 exports.
 | `WaitOpts` | interface | Options for `Scope.wait`. `label` is the wait's identity within its parent scope — it is what |
 | `WaitOutcome` | interface | The `out` a settled wait node delivers through `Scope.next()`. `settled` is the outcome the |
 | `WaitProbeRegistry` | interface | Resolves a `poll` spec's `probe` name to its predicate. Threaded through `SupervisorOpts` so |
+| `WatchedSurface` | interface | A path to check at settle that was NOT necessarily mounted — where a harness is known to write |
 | `WidenGate` | interface | The progressive-widening gate (MCTS-PW). Decides whether a settled child is |
 | `WidenLineage` | interface | A lineage the gate may widen toward — the settled child that looked promising + the findings |
 | `WidenSpec` | interface | `widen({ gate })` (G5) — the STREAMING spawn-on-completion driver. Unlike the static-fanout |
@@ -1107,6 +1115,8 @@ Import from `@tangle-network/agent-runtime/kernel` — 745 exports.
 | `SupervisorNodeContextSeed` | type | Context known before `Agent.act`; Runtime adds the concrete node, profile, and task. |
 | `SupervisorProfile` | type | A supervisor is an exact canonical AgentProfile; no looser model/prompt shape exists. |
 | `SupervisorSpanAttributes` | type | OTLP span attribute values. Exported because `SupervisorSpanOptions.attributes` is public and |
+| `SurfaceReader` | type | The read seam: fetch the current bytes at a mounted path. Implemented by a sandbox box's |
+| `SurfaceReadOutcome` | type | Outcome of reading one surface back at settle. `missing: true` means the path no longer exists |
 | `ToolLoopCompactionOptions` | type | Public supervisor-facing compaction config: same knobs as the primitive, but `distill` is optional |
 | `ToolLoopMessageRecord` | type | Provider-neutral conversation record accepted by a tool-loop brain. |
 | `TrajectoryReportFn` | type | `trajectoryReport(...)` — the tree+cost reconstructor. Async (reads journal + optionally blobs). |

docs/api/runtime.md

@@ -16889,6 +16889,173 @@ returning an incomplete reproducibility receipt.
 
 ***
 
+### SurfaceDiff
+
+One watched surface whose settled state differs from what was mounted (or from absence).
+
+- `modified` — the surface exists with different bytes (`settledSha256`/`settledBytes` present).
+- `removed` — the surface no longer exists at its mounted path.
+- `created` — a watched path that was never mounted now exists (`settledSha256`/`settledBytes`
+  present, no `mountedSha256`) — the shape a harness's new memory/skill file takes.
+- `unreadable` — the read seam failed for a reason other than absence; `error` carries the
+  diagnostic. Reported rather than dropped so a permissions or transport failure cannot
+  masquerade as "nothing changed".
+
+#### Properties
+
+##### path
+
+> **path**: `string`
+
+The mounted/watched path, exactly as recorded.
+
+##### status
+
+> **status**: `"modified"` \| `"removed"` \| `"created"` \| `"unreadable"`
+
+##### mountedSha256?
+
+> `optional` **mountedSha256?**: `string`
+
+Hex SHA-256 of the bytes that were mounted (from the manifest). Absent for `created`.
+
+##### source
+
+> **source**: `string`
+
+Free-form origin: the manifest entry's `source`, or the watch entry's `source`.
+
+##### settledSha256?
+
+> `optional` **settledSha256?**: `string`
+
+Hex SHA-256 of the settled bytes. Present for `modified` and `created`.
+
+##### settledBytes?
+
+> `optional` **settledBytes?**: `number`
+
+Size of the settled bytes. Present for `modified` and `created`.
+
+##### error?
+
+> `optional` **error?**: `string`
+
+The read seam's diagnostic. Present only for `unreadable`.
+
+***
+
+### WatchedSurface
+
+A path to check at settle that was NOT necessarily mounted — where a harness is known to write
+ self-authored surfaces (a memory dir's files, a refinement log). A watched path that was also
+ mounted compares against its mount; one that wasn't reports `created` if it now exists.
+ `created` is an inference from the mount manifest, not a proof of authorship: a file the box
+ IMAGE shipped at a never-mounted path also reports `created`. Watch paths known absent at run
+ start (or enumerate the tree at start AND settle and watch the difference) to make the label
+ mean what it says.
+
+#### Properties
+
+##### path
+
+> **path**: `string`
+
+##### source?
+
+> `optional` **source?**: `string`
+
+Origin label carried onto the diff (default `'watched'`).
+
+***
+
+### HarvestSurfaceDiffsOptions
+
+Inputs to [harvestSurfaceDiffs](#harvestsurfacediffs): the run's mount manifest, the read seam, and optional
+ watch paths for surfaces the agent may have created.
+
+#### Properties
+
+##### mounts
+
+> **mounts**: readonly [`MountManifestEntry`](#mountmanifestentry)[]
+
+The run's mount manifest (`RunProvenance.mounts`). Entries sharing a path are collapsed to the
+ LAST entry — the bytes the agent actually saw at start.
+
+##### read
+
+> **read**: [`SurfaceReader`](#surfacereader)
+
+How to read a mounted path's current bytes.
+
+##### watch?
+
+> `optional` **watch?**: readonly [`WatchedSurface`](#watchedsurface)[]
+
+Additional paths to check that may not have been mounted (see [WatchedSurface](#watchedsurface)). The
+ caller enumerates them (it knows the harness's state layout — e.g. via the box's file tree);
+ the harvest stays layout-agnostic.
+
+***
+
+### SurfaceReadBox
+
+The minimal box surface the box-backed reader needs — structurally typed so the real
+ `@tangle-network/sandbox` box and a test double both satisfy it, no SDK import.
+
+#### Properties
+
+##### fs
+
+> **fs**: `object`
+
+###### read()
+
+> **read**(`path`): `Promise`\<`string`\>
+
+###### Parameters
+
+###### path
+
+`string`
+
+###### Returns
+
+`Promise`\<`string`\>
+
+***
+
+### BoxSurfaceReaderOptions
+
+Retry and cancellation controls for [boxSurfaceReader](#boxsurfacereader).
+
+#### Properties
+
+##### attempts?
+
+> `optional` **attempts?**: `number`
+
+Read attempts per path before settling on a failed outcome. The data plane can transiently
+ 404 a just-written file (the same blip `openSandboxRun`'s deliverable read retries for), and a
+ first-attempt 404 taken at face value turns a fresh self-edit into a false `removed`/dropped
+ `created`. Default 3.
+
+##### retryDelayMs?
+
+> `optional` **retryDelayMs?**: `number`
+
+Linear backoff base between attempts (delay = base × attempt). Default 250.
+
+##### signal?
+
+> `optional` **signal?**: `AbortSignal`
+
+Cuts the retry waits short when the run is abandoned. The reader still returns a typed
+ outcome — the harvest reports what it managed to read rather than rejecting.
+
+***
+
 ### CreateTangleSandboxExactProcessProviderOptions
 
 #### Properties
@@ -20507,6 +20674,34 @@ Terminal artifact of one worktree-CLI run — the canonical worktree-harness res
 
 ***
 
+### SurfaceReadOutcome
+
+> **SurfaceReadOutcome** = \{ `succeeded`: `true`; `value`: `Uint8Array`; \} \| \{ `succeeded`: `false`; `missing`: `boolean`; `error`: `string`; \}
+
+Outcome of reading one surface back at settle. `missing: true` means the path no longer exists
+ (a deletion — a valid, reportable outcome); any other failure carries its diagnostic.
+
+***
+
+### SurfaceReader
+
+> **SurfaceReader** = (`path`) => `Promise`\<[`SurfaceReadOutcome`](#surfacereadoutcome)\>
+
+The read seam: fetch the current bytes at a mounted path. Implemented by a sandbox box's
+ `fs.read`, a local worktree read ([fsSurfaceReader](#fssurfacereader)), or a test double.
+
+#### Parameters
+
+##### path
+
+`string`
+
+#### Returns
+
+`Promise`\<[`SurfaceReadOutcome`](#surfacereadoutcome)\>
+
+***
+
 ### SandboxControlClient
 
 > **SandboxControlClient** = `Pick`\<`Sandbox`, `"create"` \| `"get"` \| `"list"`\>
@@ -26112,6 +26307,88 @@ the shared valid-only `selectValidWinner` (never a judge).
 
 ***
 
+### harvestSurfaceDiffs()
+
+> **harvestSurfaceDiffs**(`options`): `Promise`\<[`SurfaceDiff`](#surfacediff)[]\>
+
+Re-read every mounted (and watched) surface and report the ones whose settled state differs from
+the manifest — modified, removed, or created. Unchanged surfaces and still-absent watched paths
+produce no entry; reads run concurrently; output preserves record order, mounts before
+watch-only paths. Mounts and watches sharing a path key are each collapsed to the LAST entry,
+and a watched path that was also mounted compares against its mount (never reports `created`).
+
+The harvest takes no `AbortSignal`: it is pure fan-out over the read seam and waits on nothing
+itself, so every cancellable moment belongs to the reader. Pass a signal to the reader instead
+([BoxSurfaceReaderOptions.signal](#signal-23), or close over one in a custom [SurfaceReader](#surfacereader)) —
+that cuts the backoff waits, and the harvest still returns the diffs it did establish rather
+than discarding settle-time evidence on a late cancellation.
+
+#### Parameters
+
+##### options
+
+[`HarvestSurfaceDiffsOptions`](#harvestsurfacediffsoptions)
+
+#### Returns
+
+`Promise`\<[`SurfaceDiff`](#surfacediff)[]\>
+
+***
+
+### boxSurfaceReader()
+
+> **boxSurfaceReader**(`box`, `options?`): [`SurfaceReader`](#surfacereader)
+
+A [SurfaceReader](#surfacereader) over a sandbox box's filesystem — the same `box.fs.read` seam
+`openSandboxRun` reads deliverables through, with the same transient-404 posture (bounded
+retry). The box wire returns UTF-8 TEXT (the SDK's binary path is `download()`), which profile
+surfaces are; hashes are computed over the UTF-8 encoding, and content the wire had to
+lossy-decode (a U+FFFD replacement character) is reported `unreadable` rather than hashed as
+mojibake. The SDK's not-found error is detected structurally (`err.name === 'NotFoundError'`)
+and maps to `missing: true` — unless its `resourceType` names something other than a file/path
+(the BOX or session being gone), which is a transport failure, not an absent surface.
+
+#### Parameters
+
+##### box
+
+[`SurfaceReadBox`](#surfacereadbox)
+
+##### options?
+
+[`BoxSurfaceReaderOptions`](#boxsurfacereaderoptions) = `{}`
+
+#### Returns
+
+[`SurfaceReader`](#surfacereader)
+
+***
+
+### fsSurfaceReader()
+
+> **fsSurfaceReader**(`root`): [`SurfaceReader`](#surfacereader)
+
+A [SurfaceReader](#surfacereader) over the local filesystem, for worktree/local workers. Every path —
+relative or absolute — must resolve INSIDE `root`: a path that escapes it (`../`, an absolute
+path elsewhere) fails as a contained non-missing outcome rather than reading outside the
+worktree, so a persisted or mistyped manifest path cannot turn the harvest into an
+existence/hash oracle over the host filesystem. Containment is checked twice — once on the
+lexical path, then again on the symlink-resolved path, because `readFile` follows a link and a
+link planted inside the root would otherwise read host bytes through a contained-looking name.
+Absence maps to `missing: true`; every other failure carries the error message.
+
+#### Parameters
+
+##### root
+
+`string`
+
+#### Returns
+
+[`SurfaceReader`](#surfacereader)
+
+***
+
 ### createTangleSandboxExactProcessProvider()
 
 > **createTangleSandboxExactProcessProvider**(`client`, `options?`): `AgentEnvironmentProvider`