feat(local-runner): add notebook orchestration pipelines - #435

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/local-runner/orchestration/README.md`:
- Around line 3-4: Update the pipeline description in the README to clarify that
the two source notebooks fan out in parallel during local execution, while cloud
execution runs them sequentially to avoid create-if-missing races. Preserve the
existing description of their output feeding the third notebook and its agent
block.

In `@examples/local-runner/orchestration/run.mjs`:
- Around line 9-11: Update the process.loadEnvFile error handling to ignore only
missing-file (ENOENT) errors; rethrow all other errors so unexpected .env
loading failures are not swallowed and do not silently switch execution to local
mode.

In `@examples/local-runner/README.md`:
- Around line 3-22: Update the stale sentence immediately following the examples
table to reflect all four listed examples, specifically describing that the run
app and snapshot viewer use two committed artifacts; preserve the surrounding
guidance and avoid implying that only two examples exist.

In `@examples/local-runner/run-app/README.md`:
- Around line 67-93: Update the “Run the pipeline” description and live-graph
diagram to show fan-out to GPT-5.5 and Claude Sonnet 5, followed by the Deepnote
Auto arbiter, instead of a single agent decision or final memo. Revise the
provider/arbiter execution paragraph to match serve.mjs: without DEEPNOTE_TOKEN,
those notebooks are skipped and report that they run in Deepnote Cloud; do not
claim a local OPENAI_API_KEY-driven agent step. Preserve the existing
descriptions of regional recovery, aggregation, and notebook links.

In `@examples/local-runner/workflow-orchestration/package.json`:
- Around line 11-17: Regenerate the workspace lockfile to include the
dependencies declared in the workflow-orchestration package manifest. Run pnpm
install from the repository root, then commit the updated pnpm-lock.yaml so pnpm
install --frozen-lockfile succeeds in CI.

In `@examples/local-runner/workflow-orchestration/workflows/sales-report.ts`:
- Around line 191-237: Update regionalResult and its caller runRegion so missing
RESULT_MARKER or invalid JSON produces a null RegionalResult instead of
throwing, allowing successful steps with malformed output to reach
needsRecovery. Preserve valid-output parsing and add coverage in
sales-report.test.ts for a success: true step with bad or missing output.

In `@packages/local-runner/src/serve-static.ts`:
- Around line 196-207: Update the local request handler’s sendFrame function to
return without writing when the response has ended, finished, or been destroyed.
Keep all event, result, and error frame behavior unchanged while ensuring late
orchestrationRunner emissions cannot write to a closed response or throw outside
the try block.

---

Outside diff comments:
In `@packages/local-runner/README.md`:
- Around line 183-191: Update the README TypeScript example using serveStatic to
import orchestrate from the appropriate package or module before it is called in
orchestrationRunner, while preserving the existing buildPipeline and onEvent
wiring.

---

Nitpick comments:
In `@examples/local-runner/workflow-orchestration/api/run.post.ts`:
- Around line 5-14: Validate the parsed body at runtime before passing it to
start in the request handler, rather than directly casting it to
SalesDecisionRequest. Reject malformed or incorrectly typed fields, including
numeric fields such as demandShockPct, with an HTTP 400 response, and only
invoke salesDecisionWorkflow after validation succeeds.

In `@packages/local-runner/src/orchestrate.ts`:
- Around line 300-306: Clarify the callback deduplication in the onStatus
handler by documenting that the identity comparison prevents invoking the same
function reference twice, or use a Set-based unique-callback approach if
consistent with the surrounding code. Preserve inherited callback invocation,
step-specific callback invocation for distinct references, and the step_status
emission.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/local-runner/workflow-orchestration/run-api.test.ts`:
- Line 26: Update the assertion for startMock in the relevant test to verify it
was called once with salesDecisionWorkflow and the validated request argument,
rather than only checking invocation count. Ensure the test fully covers the
start invocation contract for the new workflow orchestration behavior.

In `@examples/local-runner/workflow-orchestration/workflows/sales-report.test.ts`:
- Around line 151-159: Add a negative qualityThreshold case to the existing
parseSalesDecisionRequest rejection table, using a value below 0, so the
parser’s lower-bound validation is covered alongside the existing out-of-range
upper-bound case.

---

Nitpick comments:
In `@examples/local-runner/workflow-orchestration/run-api.test.ts`:
- Line 7: Move the test file to the api directory alongside the run.post
endpoint, and update its import to reference ./run.post from the new location.
Preserve the existing test behavior while complying with the required test
co-location convention.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/local-runner/gallery/index.html`:
- Around line 106-116: Make the pipeline destination portable across static
hosts: in examples/local-runner/gallery/index.html lines 106-116, change the
Pipeline card to target ./pipeline.html; in
examples/local-runner/gallery/README.md lines 122-128, document the same .html
URL requirement and any /pipeline rewrite alternative if supported.

In `@examples/local-runner/gallery/pipeline.html`:
- Around line 484-499: Introduce a safe hash-decoding helper near the pipeline
initialization logic that catches decodeURIComponent failures and returns no
selection for malformed fragments. Use it for both the initial hash used to
compute initial and the hashchange handler before matching manifest.nodes, so
invalid fragments neither misreport artifact-loading failures nor throw uncaught
errors. Add a regression test covering malformed fragments such as “#%”.

In `@examples/local-runner/gallery/pipeline.json`:
- Around line 40-51: Update the detail field for the analyze-europe entry to
report the snapshot’s recorded quality score of approximately 83% instead of
92%. Keep the existing execution metadata and downstream recovery-threshold
behavior unchanged.

---

Nitpick comments:
In `@examples/local-runner/gallery/pipeline.test.ts`:
- Line 27: Update the manifest loading in pipeline.test.ts to parse the JSON as
unknown rather than casting it directly to PipelineManifest, then validate and
narrow it against the required PipelineManifest UI contract before test
consumption. Reuse an existing manifest validator if available; otherwise add a
type-safe validation path without any.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/local-runner/gallery/pipeline-data.js`:
- Around line 56-62: Update layoutNodes to assign columns using a topological
traversal rather than the input order: validate that every edge endpoint exists,
process zero-indegree nodes through a ready queue, and assign each node’s column
after its parents are resolved. Reject cyclic graphs when not all nodes are
processed, while preserving the existing root and parent-based column
calculation.

In `@examples/local-runner/gallery/pipeline.test.ts`:
- Around line 32-95: Extend the tests for normalizePipelineManifest with a
malformed manifest case that asserts the documented TypeError is thrown. Keep
the existing successful persisted-result test unchanged and use the invalid
input shape expected by normalizePipelineManifest to exercise its validation
path.

In `@packages/local-runner/src/orchestrate.ts`:
- Around line 577-584: Update the catch block in the orchestration flow so
failures from the failure-path saveState call cannot replace the original
orchestration error. Preserve the persisted failed status and error message when
possible, but contain or otherwise ignore saveState/persistenceWrites failures
before rethrowing the original error.
- Around line 302-303: Update the resumed-state timestamp initialization around
orchestrationStartedMs to validate the Date.parse result and fall back to
Date.now() when it is not finite, while preserving valid persisted timestamps
and the existing orchestrationStartedAt behavior.

In `@packages/local-runner/src/orchestration-state.ts`:
- Around line 131-135: Update the key sorting in the normalization logic used by
the fingerprint generation to use a deterministic code-unit comparison instead
of localeCompare. Preserve the existing Object.fromEntries and normalize
behavior while ensuring identical candidate keys produce the same order across
locales, machines, and Node builds.
- Around line 145-159: Extend isPersistedState to validate every checkpoints
entry before accepting persisted state. Add a per-entry guard requiring the
expected kind and fingerprint fields, and for notebook entries verify the
minimally required result shape, so invalid or truncated payloads are rejected
at the file-read trust boundary before orchestrate uses saved.result.

---

Outside diff comments:
In `@examples/local-runner/run-app/index.html`:
- Around line 305-311: Update the Claude node labels in the graph-node-link for
data-step-id “decision-claude” so the accessible data-label and visible
node-name use the same model name, specifically “Anthropic Claude Sonnet 5,”
while preserving the existing node structure and state text.

---

Nitpick comments:
In `@packages/local-runner/src/orchestrate.test.ts`:
- Around line 435-476: Add tests in the orchestration test suite covering
persistence.resume set to false and resuming with a cached step_failed result
for an allowFailure step. Exercise the fresh-start behavior when resume is
disabled and verify the cached failed step emits the expected result without
rerunning it, using the existing orchestrate and runnerMock test patterns.

In `@packages/local-runner/src/orchestrate.ts`:
- Around line 531-536: In the checkpoint assignment within the persisted state
update, simplify the `value` field expression to directly use `value` instead of
the redundant `value === undefined ? undefined : value` conditional; leave
`valueIsUndefined` and the surrounding checkpoint structure unchanged.

In `@packages/local-runner/src/orchestration-state.ts`:
- Around line 73-80: Update writePersistedState to wrap the temporary-file write
and rename operations in a try/finally block, and unlink the generated temporary
path in the finally cleanup. Preserve the existing successful atomic rename
behavior while ensuring cleanup runs when either writeFile or rename fails.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/local-runner/orchestration/run.mjs`:
- Line 17: Validate the ORCHESTRATION_TARGET value before selecting the
execution mode: accept only 'local' and 'cloud', while preserving the existing
default based on DEEPNOTE_TOKEN when the variable is unset or empty. Reject any
other non-empty value immediately instead of treating it as cloud.

---

Outside diff comments:
In `@examples/local-runner/run-app/index.html`:
- Around line 153-181: Make the pipeline graph interactive and keyboard
accessible by removing the SVG image role, giving each notebook-run node link a
real static href and accessible name, and preserving navigation when activated
with the keyboard. Update the graph node link markup and related rendering paths
around the notebook-run nodes, then add visible :focus-visible styling for the
link/group without relying on hover-only behavior.