experimental-ash 0.3.0-alpha.9 → 0.4.0-alpha.1

package/README.md

@@ -7,6 +7,7 @@ You author an agent as a directory on disk. The directory is the contract:
 - `system.md` and `system/` define always-on instructions
 - `skills/` define optional procedures
 - `tools/` define typed executable integrations
+- `connections/` define external MCP server connections
 - `sandbox/` overrides the agent's single sandbox (optional) and seeds workspace files
 - `channels/` define message ingress and delivery
 - `subagents/` define specialist child agents
@@ -51,6 +52,7 @@ my-agent/
     ├── system/
     ├── skills/
     ├── tools/
+    ├── connections/
     ├── sandbox/
     ├── channels/
     ├── subagents/
@@ -122,6 +124,7 @@ Start here:
 3. [`docs/public/project-layout.md`](docs/public/project-layout.md)
 4. [`docs/public/agent-ts.md`](docs/public/agent-ts.md)
 5. [`docs/public/typescript-api.md`](docs/public/typescript-api.md)
+6. [`docs/public/connections.md`](docs/public/connections.md)
 
 ## Repo Guide
 

package/bin/ash.d.ts

@@ -41,6 +41,11 @@ export interface BootstrapCliModule {
 
 export interface BootstrapDependencies extends BootstrapBuildDependencies {
   importModule?: (specifier: string) => Promise<BootstrapCliModule>;
+
+  /**
+   * Node.js version string used by tests to exercise the bin version guard.
+   */
+  nodeVersion?: string;
 }
 
 /**

package/bin/ash.js

@@ -7,6 +7,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const require = createRequire(import.meta.url);
+const minimumNodeMajorVersion = 24;
 
 function createBootstrapOptions(overrides = {}) {
   const packageRoot =
@@ -105,6 +106,27 @@ function inputTsconfigPath({ packageRoot }) {
   return resolve(packageRoot, "tsconfig.json");
 }
 
+function parseNodeMajorVersion(version) {
+  const match = /^v?(\d+)/.exec(version);
+  return match ? Number(match[1]) : undefined;
+}
+
+function assertSupportedNodeVersion(version = process.version) {
+  const majorVersion = parseNodeMajorVersion(version);
+
+  if (majorVersion !== undefined && majorVersion >= minimumNodeMajorVersion) {
+    return;
+  }
+
+  throw new Error(
+    [
+      `Ash requires Node.js ${minimumNodeMajorVersion} or newer.`,
+      `You are running ${version}.`,
+      "Please upgrade Node.js and try again.",
+    ].join(" "),
+  );
+}
+
 function resolveTsgoCliPath({ tsgoCliPath }) {
   if (tsgoCliPath) {
     return tsgoCliPath;
@@ -203,6 +225,8 @@ export async function ensureBuiltCli(overrides = {}, dependencies = {}) {
  * Runs the compiled Ash CLI, building the workspace package on demand when needed.
  */
 export async function runAshCli(argv = process.argv.slice(2), overrides = {}, dependencies = {}) {
+  assertSupportedNodeVersion(dependencies.nodeVersion);
+
   const cliEntrypointPath = await ensureBuiltCli(overrides, dependencies);
   const importModule = dependencies.importModule ?? ((specifier) => import(specifier));
   const cliModule = await importModule(pathToFileURL(cliEntrypointPath).href);
@@ -238,5 +262,11 @@ if (await isDirectExecution()) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(message);
     process.exitCode = 1;
+  } finally {
+    // The CLI bootstraps build/dev toolchains that can leave native service
+    // handles alive after the command has completed. Once the top-level
+    // command resolves, terminate the bin process explicitly so commands like
+    // `ash dev` + `/exit` do not hang on leaked implementation details.
+    process.exit(process.exitCode ?? 0);
   }
 }

package/dist/docs/internals/README.md

@@ -0,0 +1,34 @@
+# Internals
+
+The architecture is a three-layer split:
+
+- **Channels** normalize platform input, define continuation tokens, and own delivery policy.
+- **The harness** does one unit of AI work and returns `{ session, next }`.
+- **The runtime** persists state, follows `next`, streams events, and owns workflow primitives.
+
+All runtime state flows through a single `AshContext` bound by one `AsyncLocalStorage`. Authored code should not know anything about workflow orchestration.
+
+## Start Here
+
+If you want the shortest path through the architecture, read these in order:
+
+1. `packages/ash/src/protocol/routes.ts`
+2. `packages/ash/src/protocol/message.ts`
+3. `packages/ash/src/channel/types.ts`
+4. `packages/ash/src/harness/tool-loop.ts`
+5. `packages/ash/src/harness/types.ts`
+6. `packages/ash/src/context/container.ts`
+7. `packages/ash/src/context/keys.ts`
+8. `packages/ash/src/execution/workflow-entry.ts`
+9. `packages/ash/src/execution/workflow-runtime.ts`
+
+## Guides
+
+- [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md) — the repo-level architecture map
+- [`core-beliefs.md`](./core-beliefs.md) — the principles behind Ash's architecture rules
+- [`mechanical-invariants.md`](./mechanical-invariants.md) — detailed constraints that should become lints or structural tests
+- [`context.md`](./context.md) — the unified context system
+- [`compiler-and-artifacts.md`](./compiler-and-artifacts.md) — how authored files become `.ash/` artifacts
+- [`discovery.md`](./discovery.md) — how the framework finds authored sources
+- [`message-runtime.md`](./message-runtime.md) — the HTTP surface and runtime execution
+- [`testing.md`](./testing.md) — test tiers and helpers

package/dist/docs/internals/compiler-and-artifacts.md

@@ -0,0 +1,52 @@
+# Compiler and Artifacts
+
+The compiler takes discovery output and freezes it into inspectable artifacts under `.ash/`. This is the bridge between the authoring tree and the runtime — the runtime never crawls the raw authoring tree.
+
+## Flow
+
+```
+resolveDiscoveryProject()  →  discoverAgent()  →  writeCompilerArtifacts()
+```
+
+Artifacts are written even when discovery has errors, so `ash info` and inspection always work. `CompileAgentError` is thrown after writing.
+
+## Artifact Layout
+
+```
+.ash/
+  discovery/
+    agent-discovery-manifest.json   # serialized discovery result (compiler input)
+    diagnostics.json                # accumulated diagnostics + summary counts
+  compile/
+    compiled-agent-manifest.json    # normalized runtime-facing manifest
+    compile-metadata.json           # hashes, status, artifact paths
+    module-map.mjs                  # static imports keyed by (nodeId, sourceId)
+```
+
+## Module Map
+
+Discovery avoids executing authored code. The module map is the handoff — it statically imports every module-backed authored source so the runtime can resolve tool execute functions, sandbox lifecycle hooks, and model instances from stable `(nodeId, sourceId)` coordinates.
+
+`lib/` modules are not indexed directly but come in transitively through normal imports.
+
+## Key Artifacts
+
+**`compiled-agent-manifest.json`** — the normalized runtime-facing manifest. Preserves config, prompt, skill, sandbox, schedule, and tool metadata; flattened subagent nodes with explicit `subagentEdges`; manifest kind and version. `sandbox` is `null` or one entry, and `sandboxWorkspaces` is an array of size 0 or 1 (single-sandbox model).
+
+**`compile-metadata.json`** — artifact paths, SHA-256 digests, diagnostics summary, compile status, generator version, and `sourceGraphHash`. The `sourceGraphHash` drives sandbox template cache invalidation — runtime and Vercel build-time prewarm both derive template keys from it.
+
+**`module-map.mjs`** — frozen object keyed by `(nodeId, sourceId)`. Authored sandbox modules are indexed directly (runtime needs their lifecycle hooks); `lib/` modules come in transitively.
+
+## Bundled Artifacts
+
+Both Nitro handlers and workflow bundles need compiled artifacts without re-deriving them at request time. `compiled-artifacts.ts` generates a bootstrap module that embeds the manifest, context, workspace, metadata, and module map, then installs them into the runtime loader.
+
+Schedule resolution only happens after a clean compile — core artifacts are always written, but registration requires valid compiled state.
+
+## Invariants
+
+- Keep artifacts inspectable and versioned.
+- Do not move runtime behavior into the compiler.
+- Do not make runtime request paths depend on rediscovery.
+- Keep module execution deferred until runtime.
+- Preserve stable `sourceId` keys across discovery, compiler, and runtime.

package/dist/docs/internals/context.md

@@ -0,0 +1,100 @@
+# Unified Context
+
+Ash uses a single `AshContext` container bound by one `AsyncLocalStorage` instance. No secondary storage, no custom dehydration, no out-of-band parameter passing.
+
+## Core Model
+
+`ContextContainer` holds a durable map and a virtual overlay. Reads check the virtual overlay first, then the durable map. Writes always target the durable map.
+
+```ts
+interface AshContext {
+  get<T>(key: ContextKey<T>): T | undefined;
+  require<T>(key: ContextKey<T>): T;
+  has<T>(key: ContextKey<T>): boolean;
+  set<T>(key: ContextKey<T>, value: T): T;
+  set<T>(key: ContextKey<T>, updater: (current: T | undefined) => T): T;
+  ensure<T>(key: ContextKey<T>, create: () => T): T;
+}
+```
+
+`loadContext()` returns the active context or throws. Public accessors (`getSession()`, `getSandbox()`, `getSkill()`) delegate to it.
+
+## Type Hierarchy
+
+```
+ContextReader    { get, require, has }
+    ↑ extends
+ContextAccessor  { set, ensure }
+    ↑ extends
+AshContext        { entries() }
+```
+
+## Seed Keys
+
+Set by the runtime entry point. Serialized at `"use step"` boundaries via their codec. Keys self-register in a global registry — the serialization layer resolves string names back to typed keys from this registry.
+
+| Key                    | Type                         |
+| ---------------------- | ---------------------------- |
+| `AuthKey`              | `SessionAuthContext \| null` |
+| `InitiatorAuthKey`     | `SessionAuthContext \| null` |
+| `SessionIdKey`         | `string`                     |
+| `RunIdKey`             | `string`                     |
+| `ContinuationTokenKey` | `string`                     |
+| `ModeKey`              | `RunMode`                    |
+| `NodeSelectorKey`      | `string`                     |
+| `ParentSessionKey`     | `SessionParent`              |
+| `ChannelKey`           | `Channel`                    |
+| `BundleKey`            | `CompiledBundle`             |
+| `SessionPreparedKey`   | `boolean`                    |
+
+## Virtual Keys
+
+Created by providers during `runStep`. Never serialized — reconstructed each step.
+
+| Key          | Type            | Provider          |
+| ------------ | --------------- | ----------------- |
+| `SessionKey` | `Session`       | `sessionProvider` |
+| `SandboxKey` | `SandboxAccess` | `sandboxProvider` |
+| `SkillKey`   | `SkillAccess`   | `skillProvider`   |
+
+## Providers
+
+Providers implement `ContextProvider<T>` and run in dependency order during `runStep`:
+
+1. `sessionProvider` — depends on seed keys only
+2. `sandboxProvider` — depends on `BundleKey`, `SessionIdKey`
+3. `skillProvider` — depends on `BundleKey`
+4. Channel-declared public providers — depend on whatever is visible after `onDeliver()`
+
+Framework providers use a superset `FrameworkContextProvider` that also receives the harness session and may commit provider-owned session data after the step.
+
+## Step Runner
+
+`runStep` orchestrates the provider lifecycle:
+
+1. Clear the previous step's virtual overlay
+2. Build framework virtual providers in dependency order
+3. Build channel-scoped public providers
+4. Run the callback inside `contextStorage.run(ctx, ...)`
+5. Call framework provider `commit` hooks for provider-owned session state
+
+Authored hook lifecycle dispatch (`lifecycle.session`, `lifecycle.turn`)
+runs inside step (4)'s ALS scope, before the harness step. See
+[`./hooks.md`](./hooks.md) for the full pipeline and the
+`SessionPreparedKey` flag's failure semantics.
+
+## Channel Context
+
+Channels set custom durable context keys inside `onDeliver(ctx, payload)`. The method receives a `ContextAccessor` and returns `Promise<StepInput>`. This runs once per turn (both initial `run()` and each `deliver()`), after auth keys are seeded. Channel code stays workflow-agnostic because it only touches the accessor.
+
+Auth lives on the run and deliver inputs:
+
+- `RunInput.auth` — the caller for the current run
+- `RunInput.initiatorAuth` — the caller that started the durable session
+- On `deliver()`, `AuthKey` updates from `DeliverInput.auth` so `session.auth.current` reflects the follow-up caller while `session.auth.initiator` stays the same.
+
+## Step Boundary Serialization
+
+At each `"use step"` boundary, `serializeContext` iterates all entries and calls each codec. `deserializeContext` resolves string names back to typed keys via the global registry. Keys without a codec must be JSON-safe.
+
+The workflow runtime serializes the durable context at `start()` time, then threads the latest serialized context forward after every durable step. Each step boundary deserializes, `onDeliver()` mutates for the turn, and providers reconstruct virtual values.

package/dist/docs/internals/core-beliefs.md

@@ -0,0 +1,71 @@
+# Core Beliefs
+
+This document explains the model behind the rules in [`AGENTS.md`](../../AGENTS.md).
+Rules say what to do; this file explains why those rules exist.
+
+## The Filesystem Is The Authoring Surface
+
+Ash apps should be readable before they are executed. A contributor should be
+able to inspect `agent/` and understand the agent's instructions, tools,
+connections, channels, hooks, schedules, and subagents without tracing
+generated code.
+
+That is why authored identifiers are derived from paths. A file path is a single
+source of truth; a repeated `name` field is a second source that can drift.
+
+The hooks surface (`agent/hooks/`) deliberately reuses the unified
+`AshContext` rather than introducing a parallel state-patch channel:
+hooks read and write through `ctx.ash` like every other authored
+function. One context, one set of keys, one place to look when debugging.
+
+## Durable Work Belongs In The Runtime
+
+Workflow primitives are runtime concerns. Channels should understand platforms,
+harnesses should understand one unit of AI work, and runtime/execution should
+understand persistence, workflow steps, resumptions, and streams.
+
+Keeping that split intact gives Ash a small set of places where durable behavior
+can be reasoned about, tested, and changed.
+
+## The Harness Decides Control Flow
+
+The harness returns `next`: continue with another step, wait for a follow-up, or
+finish with output. The runtime follows that instruction. Re-creating model,
+tool, or platform policy in the runtime loop makes behavior harder to inspect
+and easier to fork accidentally.
+
+## Context Is A Single Ambient Contract
+
+Ash uses one `AshContext` container for runtime state. Seed keys carry
+serializable values across step boundaries; providers derive values for the
+current step. Additional `AsyncLocalStorage` instances or hidden dehydration
+protocols create parallel contracts that agents and humans must rediscover.
+
+## Public APIs Need A Harness
+
+Every public API should have documentation and a fixture. The documentation
+teaches app authors and coding agents how to use the API; the fixture proves the
+surface works through the same shape users will depend on.
+
+## Scenario Tests Are The Verification Ritual
+
+Scenario tests are not only a test tier. They are the place where a contributor
+can verify that an Ash behavior works from the outside: compile an app, run the
+runtime, exercise the channel or route, and inspect the result.
+
+If a scenario test is too complex to read quickly, split it. The goal is not just
+coverage; it is a legible proof of behavior.
+
+## Pre-1.0 Means Prefer Correctness
+
+Ash is still pre-1.0. When a current design is wrong, fix the contract instead
+of layering compatibility around it. Backwards compatibility matters for shipped
+behavior, persisted data, and stable public interfaces; it should not preserve
+in-progress mistakes on the current branch.
+
+## Plans Are Part Of The System
+
+Active plans are design intent, not chat transcripts. If
+[`research/active/`](../../research/active/README.md) says one thing and the code
+says another, treat that as spec drift. Either update the code to match the plan
+or update the plan in a separate PR before continuing.

package/dist/docs/internals/discovery.md

@@ -0,0 +1,55 @@
+# Discovery
+
+Discovery answers: given an app root and agent root, what authored sources exist? It does not execute authored code.
+
+## Project Resolution
+
+`resolveDiscoveryProject()` walks upward from a start path looking for a supported layout:
+
+- **nested**: app root has `package.json`, agent lives under `agent/`
+- **flat**: project root is the agent root
+
+## Agent Scan
+
+`discoverAgent()` reads the agent root, sorts entries by name (for stable manifest ordering), and scans each slot:
+
+- `system.md` / `system/` — prompt sources
+- `agent.ts` — optional config module (reference only)
+- `tools/` — module-backed, never imported. File stem becomes runtime tool name.
+- `hooks/` — module-backed lifecycle and stream-event subscribers, recursively discovered. Path-relative slug becomes the hook id.
+- `skills/` — flat markdown/module files, or packaged `skills/<name>/SKILL.md`
+- `sandbox/` — single folder. Optional `sandbox.<ext>` lifecycle module + `workspace/**` seed files.
+- `subagents/` — local subagent packages, recursively discovered
+- `schedules/` — each schedule is a directory containing `schedule.ts` (module definition with `cron` and `channel`) and `prompt.md` (prompt text)
+- `lib/` — package-local helpers, not a runtime surface
+
+**Markdown sources** are read and lowered into definition objects during discovery. **Module sources** are preserved as `ModuleSourceRef` (`logicalPath`, `sourceId`, optional `exportName`) — never imported.
+
+The output is `DiscoverAgentResult` with `diagnostics` and `manifest` (`AgentSourceManifest`). The manifest is the compiler input contract, not the runtime manifest.
+
+## Subagents
+
+Local subagents (`subagents/<name>/`) are recursively discovered. Each gets its own `AgentSourceManifest` with its own `system`, `tools/`, `skills/`, `sandbox/`, and nested `subagents/`. An `agent.ts` config module is required (subagents reuse the same `defineAgent` surface as the root agent).
+
+## Diagnostics
+
+Discovery accumulates diagnostics instead of failing early. Partial results are always preserved — even a broken subagent appears in the manifest. This makes `ash info` and artifact inspection useful regardless of errors.
+
+## Unified Slot Walker
+
+`channels/`, `hooks/`, and `tools/` all ride the unified
+`discoverNamedModuleDirectory` helper in `discover/grammar.ts`. It supports both
+flat (`tools/`) and recursive (`channels/`, `hooks/`) walks, plus per-segment
+validation (used by `channels/`, `hooks/`, `tools/`). Adding a new authored
+module slot typically means: register a directory name in `filesystem.ts`, add
+a slug validator in `grammar.ts`, call `discoverNamedModuleDirectory` from the
+parent discoverer.
+
+`schedules/` retains a bespoke `discoverScheduleSources` walker because each
+schedule is a directory containing `schedule.ts` plus `prompt.md`, which does
+not fit the flat-or-recursive "module-only" shape the unified helper expects.
+When the helper grows a markdown extension, `schedules/` collapses into it.
+
+## Extension Pattern
+
+Adding a new authored slot: teach discovery to find it → extend the manifest → teach the compiler to write artifacts → teach the runtime to resolve it.

package/dist/docs/internals/hooks.md

@@ -0,0 +1,202 @@
+# Hooks
+
+Hooks are the first-class extension point for authored agent code that needs
+to run **around** a turn instead of inside it. Tools answer the model;
+hooks answer the runtime.
+
+This page explains the discovery → compile → resolve → dispatch pipeline
+and the runtime contract every authored hook handler relies on. The
+end-user-facing reference lives at
+[`docs/public/hooks.md`](../public/hooks.md).
+
+## Architectural Rationale
+
+Plugins and authored agent code need to subscribe to the same lifecycle
+moments. Shipping hooks first closes the gap between "extension authored
+inside the agent" and "extension contributed by a plugin": both flow
+through one runtime registry, one `HookContext`, one set of ordering
+rules.
+
+The hooks surface deliberately reuses the unified `AshContext`:
+`HookContext.ash` is the same `ContextAccessor` tools, providers, and
+channels get. There is no parallel state-patch channel — one
+`AshContext`, one set of keys, one place to look when debugging.
+
+`HookContext` itself is intentionally tiny: `agent`, `channel`, `session`
+identity plus the `ash` accessor. Per-turn `turnId` and `sequence` come
+from `LifecycleHookInput.turn` for lifecycle hooks, and from
+`event.data.{turnId, sequence}` for stream-event hooks — never duplicated
+on the context.
+
+## Authoring shape
+
+```ts
+defineHook({
+  lifecycle?: {
+    session?: LifecycleHook;
+    turn?: LifecycleHook;
+  };
+  events?: {
+    [K in HandleMessageStreamEvent["type"]]?: StreamEventHook<…>;
+    "*"?: StreamEventHook<HandleMessageStreamEvent>;
+  };
+});
+```
+
+The split between `lifecycle:` and `events:` is structural so the
+contract is explicit at the call site. `lifecycle:` may return
+`{ modelContext? }` — visible to the next model call only, never written
+to durable history. `events:` is observe-only.
+
+## Pipeline
+
+Discovery (`src/discover/discover-agent.ts` and `discover-subagent.ts`)
+walks `agent/hooks/` recursively via the unified
+`discoverNamedModuleDirectory` helper, validates each path segment with
+`createHookNameDiagnostic` (charset identical to `TOOL_SLUG_PATTERN`),
+and emits `ModuleSourceRef[]` on the `hooks` field of
+`AgentSourceManifest`.
+
+Compile (`src/compiler/normalize-hook.ts`) derives the path-relative
+slug (`agent/hooks/auth/load-profile.ts` → `"auth/load-profile"`) and
+produces `CompiledHookDefinition` entries on the compiled manifest. The
+compiler performs no per-handler validation — hook handlers are
+arbitrary functions and can only be inspected at runtime.
+
+Resolve (`src/runtime/resolve-hook.ts`) loads the authored module
+export and reads its nested `lifecycle` and `events` maps directly. Each
+declared handler must be a function; mismatches throw
+`ResolveAgentError` so typos surface at boot. There is no hardcoded
+list of valid event types — unknown event keys are accepted at resolve
+time and simply never fire at dispatch time.
+
+Registry (`src/runtime/hooks/registry.ts`) builds a
+`RuntimeHookRegistry` per resolved agent node:
+
+- `session` — flat ordered array of `lifecycle.session` subscribers.
+- `turn` — flat ordered array of `lifecycle.turn` subscribers.
+- `streamEventsByType` — bucketed map keyed by event type.
+- `streamEventsWildcard` — flat array of `*` subscribers.
+
+The registry hangs off `ResolvedRuntimeAgentNode.hookRegistry` and is
+also surfaced on the `CompiledRuntimeAgentBundle` for direct access from
+the workflow path.
+
+## Dispatch
+
+Lifecycle dispatch lives in `src/context/hook-lifecycle.ts`. Both
+runtime entry points (`execution/workflow-steps.ts` for the durable
+workflow path and `execution/continuous-entry.ts` for the in-memory
+continuous path) call `runHookLifecycleStep` once per turn, **inside**
+the active ALS scope so hook code can read and write `ctx.ash` like
+every other authored function. `runHookLifecycleStep` wraps
+`dispatchHookLifecycle`, lowers a `turn-failed` outcome into a parking
+`StepResult` (`{ next: null }` for conversation mode,
+`{ next: { done: true, output } }` for task mode), and otherwise hands
+off to the supplied harness step callback with the (possibly
+augmented) input.
+
+Both runtime entry points gate dispatch on
+`getHarnessEmissionState(session).turnId === ""` so tool-loop
+continuations and runtime-action resumes (which are continuations of
+an existing turn) skip the lifecycle stack.
+
+Stages, in order:
+
+1. **`lifecycle.session`** runs sequentially in registry order, but
+   only when `ash.sessionPrepared` is unset. The dispatcher sets the
+   flag **before** running the chain so a thrown hook does not retry on
+   the next turn — `lifecycle.session` errors are terminal session
+   failures (`session.failed`).
+2. **`lifecycle.turn`** runs sequentially. Each hook may return
+   `{ modelContext? }`. Contributions from session and turn are
+   concatenated; the resulting `modelContext` becomes a one-shot
+   addition to the next model call's message list. A thrown hook is
+   caught here and lowered into a recoverable `turn.failed` cascade
+   (`session.started` once → `turn.started` → `message.received` →
+   `step.failed` → `turn.failed` → `session.waiting`).
+
+If an event hook subscribed to one of the failure-cascade events
+itself throws while the dispatcher is emitting the recoverable
+`turn.failed`, the throw escalates and the runtime emits
+`session.failed` instead. This is the bounded second-order behavior
+when both a `lifecycle.turn` and a `turn.failed` event hook fail.
+
+Stream-event dispatch is `dispatchStreamEventHooks`, called from each
+runtime's `HarnessEmitFn` composer **after** the channel adapter's
+event handler runs. The dispatcher reads the typed bucket
+(`registry.streamEventsByType.get(eventType)`) followed by the flat
+wildcard bucket (`registry.streamEventsWildcard`); thrown errors
+propagate through the emit composer. The existing harness error path
+catches them and emits the recoverable `turn.failed` cascade.
+
+## `SessionPreparedKey`
+
+Lives in `src/context/seed-keys.ts`. JSON-safe boolean, no codec. Set
+**before** the `lifecycle.session` chain runs so a thrown hook leaves
+the flag set — the next turn does not retry. Compaction does not clear
+the flag.
+
+## Subagent Isolation
+
+Subagent hooks are fully isolated by structural construction:
+
+- Each subagent runs through its own `runStep(ctx, …)` ALS scope,
+  established by the existing subagent invocation pipeline. Hooks
+  resolve from the subagent node's `hookRegistry`, not the parent
+  agent's.
+- `ctx.ash` reads hit the subagent's container, not the parent's.
+- Lexicographic ordering applies within a subagent's hook set only.
+  Parent and child registries do not interleave.
+
+The `discover/discover-subagent.ts` path walks each local subagent's
+`hooks/` directory using the same unified helper as the root agent.
+
+## Error Containment
+
+| Stage               | On throw                                                                               |
+| ------------------- | -------------------------------------------------------------------------------------- |
+| `lifecycle.session` | Re-thrown by dispatcher → terminal session failure (`session.failed`)                  |
+| `lifecycle.turn`    | Caught by dispatcher → recoverable `turn.failed` cascade emitted                       |
+| Stream-event hooks  | Propagated through the emit composer → existing harness error path emits `turn.failed` |
+
+The contract with `HarnessEmitFn`: the wrapped emit fn calls the
+channel adapter's event handler first, writes the (possibly
+transformed) event to the durable stream, **then** fans out to authored
+stream-event hook subscribers. The durable record is consistent with
+what was written even if a downstream hook throws.
+
+## Testing Strategy
+
+- Unit tests live alongside the implementation
+  (`src/runtime/hooks/registry.ts` ⇄ `runtime/hooks/registry.test.ts`,
+  `src/compiler/normalize-hook.ts` ⇄ `compiler/normalize-hook.test.ts`,
+  `src/runtime/resolve-hook.ts` ⇄ `runtime/resolve-hook.test.ts`).
+- Lifecycle dispatcher behavior is covered by
+  `src/context/hook-lifecycle.integration.test.ts` (synthetic context,
+  session/turn modelContext threading, recoverable turn-failed path,
+  stream-event fan-out, error propagation).
+- Discovery integration is folded into
+  `src/discover/agent.integration.test.ts` (recursive walk,
+  slug-charset rejection).
+- End-to-end on-disk → bundle → dispatch wiring is pinned by
+  `test/scenarios/hooks-end-to-end.scenario.test.ts`.
+
+## Mechanical Invariants
+
+The plan calls these out as lints / structural tests to land alongside
+hook adoption. They are not yet enforced mechanically and live as
+documented expectations:
+
+- Hook modules never import workflow primitives (`start`, `resumeHook`,
+  `createHook`, `getWritable`).
+- Hook return shapes have no `state` field — durable state goes through
+  `ctx.ash`.
+- Subagent hooks never read parent ALS context.
+
+## Related Pages
+
+- [`docs/public/hooks.md`](../public/hooks.md) — author-facing reference
+- [`./discovery.md`](./discovery.md) — discovery layout and the unified slot walker
+- [`./context.md`](./context.md) — `AshContext` surface shared by hooks
+- [`./message-runtime.md`](./message-runtime.md) — runtime stream events