84 lines
4.8 KiB
Markdown
84 lines
4.8 KiB
Markdown
# Session export handoff gate
|
|
|
|
Production model visits may publish their output to subsequent stages only after
|
|
their exact recorded native session has settled and a complete, nonempty,
|
|
nontruncated export file has passed normal-file and size verification. Ownership
|
|
reads and final export attempts have bounded contexts independent of execution
|
|
cancellation. Unconfirmed cleanup never exports or advances.
|
|
|
|
An export failure retains the computed step, outcome, target, output and file
|
|
evidence. The run parks nonterminally in `waiting`, with
|
|
`export_pending_sequence` identifying the computed visit and no `finished_at`.
|
|
This is not a human decision or a model failure. A separate
|
|
`session_export_gates` checkpoint is committed with the
|
|
step and its existing durable export job. Model retry is refused for that
|
|
checkpoint: recovery reads only the original session. Missing exact ownership
|
|
cannot be reconstructed or guessed and remains blocked.
|
|
|
|
The checkpoint reserves the workspace durably even though no agent is executing.
|
|
`SessionExportReservations` supplies those reservations to launch admission;
|
|
`PendingSessionExportGate(runID, sequence)` identifies the exact quiescent visit
|
|
eligible for export-only repair. Cancellation releases the reservation without
|
|
discarding or replaying the computation, and prevents automatic continuation.
|
|
The repair handler must permit `waiting` only when that predicate is true for
|
|
the requested sequence; unrelated human/resource waits remain ineligible.
|
|
|
|
Both CLI wait paths keep waiting for export recovery; `run --wait` still pauses
|
|
for genuine human decisions. Lifecycle events carry the same pending sequence,
|
|
and a lifecycle frame with zero/absent sequence clears it. Status-less repair
|
|
freshness frames leave it unchanged. Continuation is `waiting -> running`, never
|
|
terminal -> running. Startup normalizes historical failed/interrupted export
|
|
checkpoints back to waiting before clients attach.
|
|
|
|
After a successful automatic or manual repair, the worker re-verifies ownership
|
|
(including backend/reference) and the actual file, then rebuilds memory, turn
|
|
history and stage budgets from the recorded visits and follows the saved target.
|
|
Starting the successor consumes the gate in the same transaction as `BeginStep`;
|
|
terminal targets consume it with `FinishRun`. A restart before either transaction
|
|
can resume the saved target, but never replays the completed owner. Cancellation,
|
|
unconfirmed cleanup or an overlapping active workspace prevents continuation.
|
|
|
|
New repair files belong in the original private visit directory, not public
|
|
handoff files. Historical public repair paths remain verifiable for compatibility.
|
|
Only unowned injected test executors are exempt from native-session enforcement.
|
|
An original computation failure routed directly to failure stays a failure even
|
|
when its best-effort diagnostic export cannot be recovered.
|
|
|
|
## Verification (2026-10-20)
|
|
|
|
Integrated changes use authenticated direct V2 API exports, tracked text-only
|
|
model prompts, and native settled Pi JSONL export. V1 retains its native CLI
|
|
export path. Native messages are retained as escaped JSON alongside the readable
|
|
HTML projection so provider metadata and inline tool content are not dropped.
|
|
|
|
The original run #19 sessions were read without running any stage or changing
|
|
production evidence. Complete, nontruncated HTML exports in the approved
|
|
OpenCode temporary `run19-export-proof/` directory contained:
|
|
|
|
| Stage | Messages | HTML bytes |
|
|
| --- | ---: | ---: |
|
|
| Survey | 14 | 1,253,234 |
|
|
| Code | 11 | 325,930 |
|
|
| Review | 10 | 308,622 |
|
|
| UIReview | 16 | 1,358,507 |
|
|
| Land | 11 | 320,557 |
|
|
|
|
The old CLI silently cut exports at 262,144 bytes. These readbacks verify recovery
|
|
is possible for these exact original sessions; they are not production repair
|
|
records. Historical message-less `/generate` sessions cannot be reconstructed.
|
|
|
|
Checks passed after integration: full Go suite, build/vet, focused gate/recovery
|
|
race tests, and browser audit fixtures. The browser fixture verifies export-only
|
|
retry and refresh of an already-open Session tab. Large (>256 KiB) API fixtures,
|
|
wrong identity, partial/empty exports, restart, cancellation, workspace reservation,
|
|
and exactly-once successor admission have focused regressions. A full ordinary
|
|
artifact inventory no longer blocks versioned audit repair.
|
|
Repairs have a separate bounded allowance (twenty attempts, each at most 2 MiB),
|
|
so neither the ordinary inventory's file count nor its byte budget consumes the
|
|
mandatory audit-recovery capacity. The ordinary scan limits remain unchanged.
|
|
|
|
No shared service was restarted or redeployed. Production run #19's original
|
|
evidence remains unchanged. A new real multi-stage run against the installed
|
|
gate and native Linux execution remain unverified; source tests and read-only
|
|
native readbacks do not substitute for those deployment checks.
|