OpenProgram Docs
Activity and control
Activity does not show an error during initial loading, reconnecting, or cursor resynchronization. A failure notice requires a confirmed request failure owned by the current conversation; changing conversations cannot display the previous conversation’s error. Actual failed reads retain saved records and automatic retries.
What is counted, what needs your attention, and what happens when you pause or stop a task.
Activity counts conversation branches. Sending another message on the same branch does not add another History item.
Branch details use a short branch heading and an execution count. The request appears only in its execution row. Declined waits are labelled Declined, and open waits are labelled Waiting for your response. Declining does not execute the pending operation. The durable checkpoint preserves the previously displayed text, reasoning blocks, and tool calls; the terminal projection publishes a session reload after saving the outcome.
Opening an existing execution store does not renumber historical events. Sequence backfill belongs to the migration that adds the sequence column; function subprocess startup must not hold a history-wide write transaction. Standalone function progress frames address the existing code node when there is no assistant caller, so the transcript receives internal steps before completion. Function completion releases foreground occupancy before optional model-generated session naming.
Recovery considers a resolved wait only while its checkpoint is still the execution’s current checkpoint. Outcomes from earlier questions cannot resume, fail or cancel a newer wait. Repeated recovery is idempotent. Regression coverage includes an answered first wait followed by an open or answered second wait. Implementation status: specification and quality reviews pass; controlled recovery tests cover sequential waits and repeated startup recovery.
Resuming the same turn
A resumed Agent run restores the same session, turn, reply, runtime and tool bindings as the initial entry, and releases them on completion, suspension or error. Browser page capabilities remain bound to the original owner; resuming never accepts another owner’s token. A browser rejection is an explicit tool error with its original reason preserved. Exhausting the configured iteration limit ends the run as unsuccessful, not Completed, while retaining its text and operation history.
Pending approval is shown near its owning assistant message only when the authoritative execution update identifies that message in the same session. The composer remains the decision surface. Reconnecting or restoring pending questions requests the existing canonical execution replay; message ownership comes from the snapshot display metadata, with compatibility for older input envelopes. Missing ownership evidence never attaches another run’s decision to a message.
Acceptance covers a suspended and resumed public Agent entry, fresh browser discovery followed by observation with the returned token, binding cleanup on error, foreign-owner rejection, iteration exhaustion, and approval isolation between messages and sessions. Implementation status: specification and quality reviews pass. Controlled regression coverage verifies resumed browser capability ownership, explicit browser errors, binding release, iteration exhaustion as Failed, and message-scoped approval display. Default-App acceptance remains a separate release check.
Automatic continuation after interruption
Closing a conversation tab or disconnecting its view leaves worker-owned execution running. When the worker actually stops, the restart window defaults to -1 (no time limit). Zero disables automatic restart; a positive value sets an explicit duration. Unlimited intents persist a null deadline. A finite interval is measured from the orderly shutdown intent or the abandoned attempt's last durable activity, not from the next startup. Existing finite intents remain finite across upgrade; restarting again does not extend them.
Agent provider decisions and completed tool actions publish their existing canonical checkpoint and effect receipt atomically during ordinary execution. Owner recovery can retain a compatible, current checkpoint as Paused. An orderly stop requests cooperative pause before process teardown. The original execution ID, immutable inputs, permissions, budgets and original continuation commands remain authoritative; queued Jobs use the existing resource queue.
Only a pause owned by restart recovery can resume automatically. User pause, cancellation, unanswered approval, unresolved external effects, stale checkpoints and incompatible runtime contracts remain explicit recovery states. A shutdown during an unconfirmed external operation cannot safely replay that operation. Expiry keeps the checkpoint for manual continuation and never deletes conversation data. Self-update maintenance still controls admission and verification.
Restart intents are canonical execution events, stored with the execution transition. Fixed command identities make repeated startup idempotent. No second execution database, scheduler, process owner or permission path is introduced. Acceptance covers ordinary checkpoint publication, restart within and beyond two hours, repeated startup, real foreground and queued Job continuation, explicit user pause/cancel, maintenance and uncertain effects.
Resume ownership records the exact inherited checkpoint; a second interruption before a new effect retains that checkpoint. Shutdown retries a racing checkpoint version at most three times within the same attempt and original deadline. Shutdown disables dispatch and restart reconciliation in the exiting runner before pause requests. New Jobs own stable user and assistant message IDs at admission, so resumed checkpoints validate against the same turn. Pause completion releases resources using the completed attempt and resource lease identities retained by the Job waiter.
Startup classifies abandoned ownership before the initialized runner applies the same bounded restart policy. Provider-only or never-activated chat admissions can continue from their immutable input within the original activity deadline. Unknown external tool results retain reconciliation-required state; recovery never fabricates a not-committed tool receipt. Legacy paused records without a restart intent require explicit continuation.
Self-update task continuation uses the same configured duration, measured from the completed update’s last persisted activity. Its fixed deadline and expiry are saved in the existing update directory. Resume, contract-repair planning and original-session follow-up all honor it. This does not stop an update that remains actively running for longer than the continuation window.
Function versions and durable continuation
Execution policy first selects keep_original or use_latest, with a global default and a persisted per-execution override. The default is keep_original. Relevant function and dependency identity, rather than an unrelated repository edit, determines whether code changed. A policy change is a version-fenced execution command and does not create a new call implicitly.
Manual function calls and functions invoked by an Agent share the function continuation mechanism. A manual call updates its original result record. An Agent-owned call returns its result to the original tool-call position before the Agent proceeds. The surrounding chat and the function retain distinct code and continuation identities. Delivering an already committed function result does not execute the function again.
A durable function records immutable source identity, dependency identity, input, completed step identities and results, the next safe position, serializable state, and outstanding effects. Original code must remain loadable; the implementation cannot label current code as an old revision. Switching to new code preserves completed results with their original provenance and validates the remaining continuation. State conversion and step correspondence must be explicit; ambiguous edits remain paused with specific differences. A missing source, unavailable dependency, nonserializable state or unsupported execution boundary cannot silently degrade to fresh execution.
Completed effects are reused. An in-flight step without a confirmed result remains unresolved unless its own protocol proves safe recovery. Cooperative pause stops at a persisted safe boundary; crash recovery uses the last durable boundary and fences the former owner. Nested calls retain parent identity, parallel branches retain separate progress, and a stored result awaiting handoff is delivered without re-execution. Repeated resume and a second crash cannot duplicate accepted effects.
A pause accepted after a durable step checks its boundary, but before effect registration or dispatch admission, suspends the function through the existing pending Pause command. An admission-closed conflict is converted only when that real command is pending; other collisions, stale ownership and terminal admission failures retain their errors. If the same owner registered a planned intent that never dispatched, it records a not-started receipt before publishing the pause. Cancellation takes precedence. A successfully dispatched operation cannot be classified as not started; completed results are retained and unknown results still require reconciliation. Explicit Continue retains the function call cursor and reuses committed steps. This boundary handling never automatically resumes a user-paused execution.
The existing restart deadline applies to automatic continuation. Explicit cancellation, manual pause, unanswered approvals, permissions and resource admission retain authority. An incompatible use_latest selection does not fall back to keep_original or retry from the beginning. Retry remains a separate explicit new execution.
The implementation uses explicit synchronous step, nested workflow and named parallel boundaries. Pure orchestration reconstructs local JSON state from committed results. Existing execution events, blobs, checkpoints and the effect ledger own all durable data. A version-fenced Continue payload chooses policy. A compatible candidate becomes the retained active version before new work; later keep_original selections retain that adopted version. Imported dependency identity changes pause recovery if the retained dependency is unavailable. Source-defined Python helpers are retained recursively; helper-local imports and opaque non-standard-library module/class dependencies are rejected before external steps. Native frames, asynchronous orchestration and live handles are outside this contract.
Implementation status
Acceptance requires independent specification and quality reviews, controlled manual and chat recovery checks, and the complete release gate. This contract applies only to declared synchronous durable functions; existing Agent restart recovery does not establish recovery for arbitrary Python functions.
1. Three things to distinguish
| Object | Meaning | Where it appears |
|---|---|---|
| Conversation branch | One path through a conversation. A real fork creates another path. | One counted Activity row. |
| Execution | One task run: for example, producing a reply to a message. | Inside branch details. Its ID identifies the exact target of a control command. |
| Managed process | A command started by a tool, such as a script. | Attached to the execution that started it, with its own output and stop control. |
2. How branches are counted
| Example | Count | Details |
|---|---|---|
| Send a message, then say “continue”. | 1 | Both executions stay in the same branch. |
| Create an alternative reply from an earlier point. | 2 | The original and the new branch each have a row. |
| A later execution on the same branch fails. | 1 | The failure is retained in details; it does not create a branch. |
| Two branches share earlier messages. | 2 | Shared earlier executions may appear in both details. They do not add rows. |
History counts ended branches. The other sections list branches that still need attention or contain active work.
3. Which status should I see?
| Situation | Section | Meaning |
|---|---|---|
| An approval, question, pause, or unresolved tool result needs action. | Needs attention | Open details to see the actual request. A new message does not dismiss it. |
| An execution, child task, or owned process is running. | In progress | An Agent finishing its reply does not mean its background process has stopped. |
| The branch has ended, with no active work or actionable request. | History | Failures and outputs remain available in details. |
| The owner ended; only the model response record is missing. No active wait or pending non-cancel control remains. | History | Shown as “Ended · response record incomplete”. An old Cancel request does not make this actionable. Cancel is available only if a child task is still active. This does not claim success. |
Ordinary branch status comes from its newest execution. Real waits, active descendants and owned processes are also checked. Missing records are never used to guess a new branch.
4. What each control does
| Control | Result | Boundary |
|---|---|---|
| Pause | Request a stop at the next safe point. | The current action may finish first. It does not freeze an arbitrary line of code. |
| Continue | Resume the same execution from saved progress. | Available only when its saved state and capability permit it. |
| Step | Run one declared step, then pause again. | A step is a tool action or another declared boundary, not a source-code line. |
| Steer | Add instructions for work that has not run yet. | Already completed work stays unchanged. |
| Cancel | End the selected execution and its execution descendants. | Cannot undo external actions already completed. A managed process also has its own control. |
| Fork / Retry | Create an independent child execution from an allowed saved point. | The original history stays. Agent chat children start paused and need Continue; other execution types follow their scheduler. |
The UI offers only controls supported by that execution. A visible “accepted” response means the request was saved; “applied” means it took effect.
5. What survives a restart?
Automatic continuation of running conversations
Conversation execution records are persisted during normal operation. Each completed provider decision and tool result records the next action in the existing checkpoint and receipt transaction, without a pause command. Restart does not require a special save step or a graceful exit.
Startup claims abandoned running Agent executions once and activates the original execution, revision, turn and assistant reply from their durable input and latest continuation record. Manually paused, cancelling, cancelled and completed executions are not automatically continued. An interrupted model request can be regenerated from committed context; completed tools are skipped. An unresolved external operation is not blindly repeated and remains subject to result reconciliation. A missing first model response can restart from the existing admission input.
Closing or reconnecting the interface preserves the transcript. Worker interruption is not an assistant failure, does not append an error reply and does not introduce restart or recovery loading messages. Real provider and tool failures retain their existing presentation.
Acceptance uses isolated stores and controlled production entry points: resume with the same identities after owner loss, repeat startup without duplicate dispatch, recover before the first response, skip committed tools, preserve uncertain tool operations and user stop intent, and retain transcript content on reconnect. No live restart reproduction is required. Implementation status: implemented. Specification and quality reviews pass. Controlled verification covers repeated startup, original reply identity, complete provider context, committed tool coverage, and independent conversation controls. The full non-browser, non-live Python suite and Web, Desktop, documentation, and static checks pass.
| Record | Plain meaning | Why it matters |
|---|---|---|
| Checkpoint | The next action recorded after a model decision or tool result. | Continue starts here; it does not restore a frozen thread. |
| Effect receipt | Whether a model or tool request finished and what was confirmed. | Confirmed work is not blindly repeated. An uncertain external action must be checked first. |
| Attempt ownership | Which worker may currently update this execution. | An old worker cannot overwrite a replacement worker’s state. |
Command completion is idempotent when terminal reconciliation wins the same completion race: after a compare-and-swap conflict, the service accepts only an already applied command for the same execution and result version. It preserves the stored receipt and propagates other conflicts. Acceptance interleaves reconciliation at the public cancellation observer and verifies that rejected or mismatched results remain errors.
Engineering reference: identifiers and safety rules
| Identifier | Purpose |
|---|---|
session_id | Conversation scope and authorization; never a control target. |
run_id | Groups related original, fork and retry executions. |
execution_id | Exact control target. Pause/Continue keep it; a fork or retry creates another. |
attempt_id | One activation of a worker; resuming can create a new attempt. |
revision_id | An immutable version of the program and its contract. |
command_id + expected_version | Prevent duplicate actions and reject stale commands. |
- All transports use one command service. It saves the command before the owner applies it. UI state does not authorize an operation.
- Cancellation takes precedence over pause, step/continue and steering. Only the current owner can publish progress or a final state.
- Known model errors and aborts get response records. Unknown tool outcomes remain unresolved; the History label does not clear them.
- Forks validate the saved point, immutable revision and permission. Changes to program, model or tool contracts retain independent review requirements.
- Agent and background Job work share the same execution owner. For Jobs, job_id equals execution_id. Resource allocation stays separate from execution state.
- Branch membership comes from the existing conversation graph and message IDs. Compaction retains earlier associations. The current stored project location is read before loading a session.
- Reads and controls are restricted to the authorized conversation. Reconnect uses saved versions and event positions; it does not create a duplicate task.
- Managed processes retain identity, ownership and bounded output. Restart recovery checks the supervisor; a saved PID alone is not permission to send a signal.
6. Implementation and verification
| Area | Recorded implementation | Acceptance check |
|---|---|---|
| Branch counts | One row per real conversation branch; executions remain in details. | One linear conversation → History 1. A conversation with three tips → History 3. |
| Attention | Provider-only missing response records are distinguished from real waits and uncertain tool effects. | A real approval remains visible; an ended model request alone does not request confirmation. |
| Execution controls | Shared commands, checkpoints and revision controls are integrated; capabilities differ by execution. | Test only the controls the selected execution advertises. Forced-tool, spawn and merge paths retain restrictions. |
| Processes and recovery | Default macOS App checks cover process ownership, separate stop, output retention and refresh. | These checks do not establish Windows or Linux runtime results. |
Limits: no arbitrary thread-stack restoration, automatic undo, or reconstruction of process records that were never saved. Runtime calls that ask questions inside an ordinary function still need a declared interaction boundary. Separate accounting for waiting deadlines and Job budgets is not yet connected to resource management.
References and related designs
| Reference | Idea used |
|---|---|
| Debug Adapter Protocol | Separate observation from control; advertise supported controls. |
| Temporal Workflow Execution | Persist execution state. |
| Temporal Workflow Pause | Pausing does not undo work already started. |
| LangGraph persistence | Save progress at checkpoints. |
| LangGraph interrupts | Wait for input and resume at a defined boundary. |
| LangGraph time travel | Keep original history when creating alternatives. |
| Kubernetes Pod lifecycle | Request termination, then confirm owner shutdown. |
Workflow questions
Questions from a running Python Workflow wait within its current process. The process runner binds the exact execution, attempt and generation. The question request uses the canonical wait store and existing question UI; it does not checkpoint the Workflow or restart its Python call stack. An answer returns to the original call. Browser refresh reloads the pending request.
Only a live, leased owner may create or answer a live Workflow question. Cancellation, execution termination or loss of its process owner invalidates that question. Worker restart does not replay the Workflow. Existing Agent tool questions with declared pre-wait checkpoints keep their durable continuation behavior.
The subprocess publishes the saved question through the existing queue bridge. Unexpected runtime and transport errors propagate rather than becoming an unanswered result. Global CLI handlers and headless calls retain their existing behavior. Verification covers actual question display, answer and same-call continuation, browser refresh, concurrent ownership isolation, duplicate answers and cancellation.
User decision panels and receipts
Pending user decisions appear in session-owned panels above the composer. The header, option rows and Back/Next/Submit flow follow the user-supplied Claude screenshots. Navigation and collapse retain drafts and send no command; final submission retains existing acknowledged command semantics. Skip declines the whole question request. Terminal receipts remain in the conversation. Explicit approval scopes, discussion, session ownership, ordinary draft and focus remain unchanged.
Questions, confirmations, forms and permission approvals are session-scoped panels above the composer; terminal receipts remain in the conversation. Each card owns its answer fields, submission controls and delivery status. The ordinary composer retains its draft, attachments, function form, focus and normal send/queue semantics. New requests never capture the composer or move focus.
Submitting immediately shows the actual submitted answer and a sending state. An applied command produces an answered receipt; unknown delivery retains the same command identity and answer for retry. Rejected or expired requests cannot imply approval. Multiple requests are separate keyed cards, scoped to their session and execution, including split views. Existing approval scopes and discussion semantics remain unchanged.
Reuse canonical question events and execution commands. Session UI receipts are not Workflow checkpoints; refreshing reloads pending questions, while this change does not add historical receipt persistence. Workflow answers return to the original process without execution-stack persistence or restart continuation. Acceptance checks composer isolation, immediate feedback, successful first answer, uncertain retry without duplicate execution, and native display.
Implementation status
Output cards use the shared question renderer and canonical command receipts. The verification scope includes composer isolation, answer feedback, session ownership, retry identity and native acceptance.