feat: add generation preview capture for local sessions

[mikeylong]

Summary

• add to the local-llm generation-session branch
• keep the change focused on Playwright-based preview capture for recorded attempts
• preserve existing local-llm tool support used by the SurfaceOps local workbench

Verification

@surfaces/interfacectl-cli@0.1.0 build /Users/mike/SurfacesPlatform/.worktrees/interfacectl-local-llm-tool/packages/interfacectl-cli
pnpm run build:deps && pnpm run clean && tsc -p tsconfig.json

@surfaces/interfacectl-cli@0.1.0 build:deps /Users/mike/SurfacesPlatform/.worktrees/interfacectl-local-llm-tool/packages/interfacectl-cli
pnpm --filter @surfaces/interfacectl-validator run build && pnpm --filter @surfaces/interfacectl-extractor run build

@surfaces/interfacectl-validator@0.1.0 build /Users/mike/SurfacesPlatform/.worktrees/interfacectl-local-llm-tool/packages/interfacectl-validator
pnpm run clean && tsc -p tsconfig.json && node ./scripts/copy-schema.mjs

@surfaces/interfacectl-validator@0.1.0 clean /Users/mike/SurfacesPlatform/.worktrees/interfacectl-local-llm-tool/packages/interfacectl-validator
rm -rf dist

@surfaces/interfacectl-extractor@0.1.0 build /Users/mike/SurfacesPlatform/.worktrees/interfacectl-local-llm-tool/packages/interfacectl-extractor
pnpm run clean && tsc -p tsconfig.json

@surfaces/interfacectl-extractor@0.1.0 clean /Users/mike/SurfacesPlatform/.worktrees/interfacectl-local-llm-tool/packages/interfacectl-extractor
rm -rf dist

@surfaces/interfacectl-cli@0.1.0 clean /Users/mike/SurfacesPlatform/.worktrees/interfacectl-local-llm-tool/packages/interfacectl-cli
rm -rf dist

• TAP version 13

Subtest: generation adapter: workspace mode uses contract/normalized.json from the bundle

ok 1 - generation adapter: workspace mode uses contract/normalized.json from the bundle

duration_ms: 506.773459
type: 'test'
...

Subtest: generation adapter: descriptor mode loads a valid bundle and returns bundle provenance

ok 2 - generation adapter: descriptor mode loads a valid bundle and returns bundle provenance

duration_ms: 333.573375
type: 'test'
...

Subtest: generation adapter: rejects missing bundle manifest

ok 3 - generation adapter: rejects missing bundle manifest

duration_ms: 0.840833
type: 'test'
...

Subtest: generation adapter: rejects unsupported bundle version

ok 4 - generation adapter: rejects unsupported bundle version

duration_ms: 313.115709
type: 'test'
...

Subtest: generation adapter: rejects missing surface bundle entry

ok 5 - generation adapter: rejects missing surface bundle entry

duration_ms: 313.793667
type: 'test'
...

Subtest: generation adapter: rejects missing sibling ref files

ok 6 - generation adapter: rejects missing sibling ref files

duration_ms: 310.364792
type: 'test'
...

Subtest: generation adapter: rejects legacy contractPath request field

ok 7 - generation adapter: rejects legacy contractPath request field

duration_ms: 311.923375
type: 'test'
...

Subtest: generation adapter CLI maps block findings to exit code 30

ok 8 - generation adapter CLI maps block findings to exit code 30

duration_ms: 595.11975
type: 'test'
...

{"event":"surfaces.validateGeneration","status":"block","requestId":"req-1","tool":"codex","surfaceId":"demo-surface","findings":1,"timings":{"totalMs":28},"payload":{"mode":"descriptor"}}

Subtest: generation adapter server returns HTTP 422 for block findings

ok 9 - generation adapter server returns HTTP 422 for block findings

duration_ms: 367.371584
type: 'test'
...

Subtest: generation session commands freeze bundle input, record attempts, and emit canonical run artifacts

ok 10 - generation session commands freeze bundle input, record attempts, and emit canonical run artifacts

duration_ms: 1936.015042
type: 'test'
...

Subtest: generation session commands reject invalid bundle roots, duplicate sessions, invalid assessments, and missing sessions

ok 11 - generation session commands reject invalid bundle roots, duplicate sessions, invalid assessments, and missing sessions

duration_ms: 1829.232041
type: 'test'
...

Subtest: generation session summary aggregates recurring finding and repair codes

ok 12 - generation session summary aggregates recurring finding and repair codes

duration_ms: 263.990625
type: 'test'
...
1..12

tests 12

suites 0

pass 12

fail 0

cancelled 0

skipped 0

todo 0

duration_ms 4094.696708

• live SurfaceOps local workbench rerun against LM Studio succeeded once preview capture was available

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 935b83ee83

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reject non-numeric attempt identifiers

parseAttemptNumber currently uses Number.parseInt, so inputs like --attempt 2foo or --attempt 2.9 are accepted and coerced to 2 instead of being rejected. In capture-generation-preview this can silently capture and overwrite the wrong attempt's preview files (002.preview.*), which corrupts session artifacts when operators mistype the flag. Validate that the full value is an integer string before converting.

Useful? React with 👍 / 👎.