feat: add a developer-facing self-improvement meta-harness

docs/api/durable.md

@@ -269,6 +269,61 @@ NDJSON body to return as the platform `Response` body.
 
 Content type for the response.
 
+***
+
+### DurableCoordinationStreamIdentity
+
+#### Properties
+
+##### runId
+
+> `readonly` **runId**: `string`
+
+##### ownerIds
+
+> `readonly` **ownerIds**: readonly `string`[]
+
+Exact owner ids present in the side-log, sorted for deterministic display.
+
+##### unscopedRecords
+
+> `readonly` **unscopedRecords**: `number`
+
+Records written before owner-scoped coordination identities were introduced.
+
+##### recordCount
+
+> `readonly` **recordCount**: `number`
+
+***
+
+### DurableSupervisionDiscovery
+
+Identities discoverable from one `supervise({ runDir })` directory without
+already knowing the root node or coordination run id stored inside it.
+
+#### Properties
+
+##### runDir
+
+> `readonly` **runDir**: `string`
+
+##### spawnJournalPath
+
+> `readonly` **spawnJournalPath**: `string`
+
+##### coordinationLogPath
+
+> `readonly` **coordinationLogPath**: `string`
+
+##### roots
+
+> `readonly` **roots**: readonly `string`[]
+
+##### coordinationStreams
+
+> `readonly` **coordinationStreams**: readonly [`DurableCoordinationStreamIdentity`](#durablecoordinationstreamidentity)[]
+
 ## Functions
 
 ### handleChatTurn()
@@ -342,3 +397,28 @@ Wire integration:
 #### Throws
 
 `RangeError` when `turnIndex` is invalid or the result exceeds 256 bytes.
+
+***
+
+### discoverDurableSupervisionRun()
+
+> **discoverDurableSupervisionRun**(`runDir`): `Promise`\<[`DurableSupervisionDiscovery`](#durablesupervisiondiscovery)\>
+
+Discover the stable identities recorded by Runtime's durable supervision
+files. This is the developer-facing first step before calling
+`FileSpawnJournal.loadTree(root)`, `loadSpawnForest(journal, root)`, or
+`FileCoordinationLog.load(runId, ownerId)`.
+
+Missing files produce empty collections. A malformed committed JSONL record
+still fails loud through the same parser used by the runtime; a torn final
+append is ignored because it was never acknowledged as committed.
+
+#### Parameters
+
+##### runDir
+
+`string`
+
+#### Returns
+
+`Promise`\<[`DurableSupervisionDiscovery`](#durablesupervisiondiscovery)\>

docs/api/index.md

@@ -6144,6 +6144,105 @@ Exact materialized profile presented for validation before any candidate run.
 
 ***
 
+### CreateProfileImprovementHarnessOptions
+
+#### Type Parameters
+
+##### TScenario
+
+`TScenario` *extends* `Scenario`
+
+##### TArtifact
+
+`TArtifact`
+
+#### Properties
+
+##### profile
+
+> **profile**: `AgentProfile`
+
+Exact baseline profile. It is parsed, detached, and frozen at construction.
+
+##### executionRef
+
+> **executionRef**: `` `sha256:${string}` ``
+
+Immutable identity of the bound executor, models, tools, component mapping,
+and every closure or external setting that can change measured behavior.
+
+##### agent
+
+> **agent**: [`ImproveProfileAgent`](#improveprofileagent)\<`TScenario`, `TArtifact`\>
+
+Execute one exact materialized profile on one scenario.
+
+##### validateCandidate?
+
+> `optional` **validateCandidate?**: [`ImproveCandidateValidator`](#improvecandidatevalidator)
+
+Optional validator shared by every run from this harness.
+
+***
+
+### ProfileImprovementHarness
+
+A small, reusable front door over `improve(profile, options)`.
+
+The harness freezes the baseline and binds execution identity once, which
+removes the two easiest sources of accidental experiment drift when a
+developer runs several methods, surfaces, or held-out suites against the
+same agent. It does not replace or narrow `improve`; callers retain every
+method option and may still use the lower-level API directly.
+
+#### Type Parameters
+
+##### TScenario
+
+`TScenario` *extends* `Scenario`
+
+##### TArtifact
+
+`TArtifact`
+
+#### Properties
+
+##### profile
+
+> `readonly` **profile**: `object`
+
+Detached immutable baseline actually used by every run.
+
+##### profileDigest
+
+> `readonly` **profileDigest**: `` `sha256:${string}` ``
+
+Canonical digest of the bound baseline profile.
+
+##### executionRef
+
+> `readonly` **executionRef**: `` `sha256:${string}` ``
+
+Exact execution identity bound at construction.
+
+#### Methods
+
+##### run()
+
+> **run**(`options`): `Promise`\<[`ImproveMethodResult`](#improvemethodresult)\>
+
+###### Parameters
+
+###### options
+
+[`ProfileImprovementHarnessRunOptions`](#profileimprovementharnessrunoptions)\<`TScenario`, `TArtifact`\>
+
+###### Returns
+
+`Promise`\<[`ImproveMethodResult`](#improvemethodresult)\>
+
+***
+
 ### RawTraceDistillerOptions
 
 #### Properties
@@ -11364,6 +11463,30 @@ Official SkillOpt configuration plus bounded Runtime findings context.
 
 ***
 
+### ProfileImprovementHarnessRunOptions
+
+> **ProfileImprovementHarnessRunOptions**\<`TScenario`, `TArtifact`\> = `Omit`\<[`ImproveMethodOptions`](#improvemethodoptions)\<`TScenario`, `TArtifact`\>, `"executionRef"` \| `"agent"` \| `"validateCandidate"`\> & `object`
+
+#### Type Declaration
+
+##### validateCandidate?
+
+> `optional` **validateCandidate?**: [`ImproveCandidateValidator`](#improvecandidatevalidator)
+
+Override the harness-level validator for this run.
+
+#### Type Parameters
+
+##### TScenario
+
+`TScenario` *extends* `Scenario`
+
+##### TArtifact
+
+`TArtifact`
+
+***
+
 ### DeepReadonly
 
 > **DeepReadonly**\<`T`\> = `T` *extends* (...`args`) => `unknown` ? `T` : `T` *extends* readonly infer TItem[] ? readonly [`DeepReadonly`](#deepreadonly)\<`TItem`\>[] : `T` *extends* `object` ? `{ readonly [TKey in keyof T]: DeepReadonly<T[TKey]> }` : `T`
@@ -12620,6 +12743,41 @@ to the strategy contract (author-blind, conserved budget, one module out).
 
 ***
 
+### PROMPT\_INSTRUCTION\_COMPONENT\_PREFIX
+
+> `const` **PROMPT\_INSTRUCTION\_COMPONENT\_PREFIX**: `"prompt.instruction:"` = `'prompt.instruction:'`
+
+Stable component-name prefix used for `profile.prompt.instructions`.
+
+***
+
+### promptInstructionsProfileComponents
+
+> `const` **promptInstructionsProfileComponents**: [`ImproveProfileComponents`](#improveprofilecomponents)
+
+Canonical `ImproveProfileComponents` mapping for the ordered
+`AgentProfile.prompt.instructions` list.
+
+Use it with `surface: 'agent-profile'` when an optimizer should rewrite the
+exact instruction texts without being allowed to change their count, order,
+labels, or any unrelated profile field:
+
+```ts
+await improve(profile, {
+  surface: 'agent-profile',
+  profileComponents: promptInstructionsProfileComponents,
+  // method, scenarios, judge, executionRef, agent, ...
+})
+```
+
+Component names are zero-padded and stable. Runtime's existing component
+materializer requires every candidate to preserve the exact key set and
+verifies that `apply(read(profile))` reproduces the baseline profile. A
+profile with no prompt instructions is refused rather than inventing a
+sentinel instruction that could accidentally ship.
+
+***
+
 ### ROLLOUT\_POLICY\_EXTENSION
 
 > `const` **ROLLOUT\_POLICY\_EXTENSION**: `"structural-rollout"` = `'structural-rollout'`
@@ -13954,6 +14112,36 @@ Build a complete method backed by Microsoft's official SkillOpt trainer.
 
 ***
 
+### createProfileImprovementHarness()
+
+> **createProfileImprovementHarness**\<`TScenario`, `TArtifact`\>(`options`): [`ProfileImprovementHarness`](#profileimprovementharness)\<`TScenario`, `TArtifact`\>
+
+Bind one exact profile and executor into a repeatable self-improvement
+harness. The returned `run` method remains generic over every existing
+profile surface, optimization method, split, gate, and budget option.
+
+#### Type Parameters
+
+##### TScenario
+
+`TScenario` *extends* `Scenario`
+
+##### TArtifact
+
+`TArtifact`
+
+#### Parameters
+
+##### options
+
+[`CreateProfileImprovementHarnessOptions`](#createprofileimprovementharnessoptions)\<`TScenario`, `TArtifact`\>
+
+#### Returns
+
+[`ProfileImprovementHarness`](#profileimprovementharness)\<`TScenario`, `TArtifact`\>
+
+***
+
 ### rawTraceDistiller()
 
 > **rawTraceDistiller**\<`TScenario`, `TArtifact`\>(`options?`): (`input`) => `Promise`\<readonly `ProposalFinding`[]\>