@jskit-ai/agent-docs 0.1.250 → 0.1.251

package/guide/agent/app-extras/assistant-conversation.md

@@ -84,7 +84,16 @@ Its authorized operations use the existing action catalogue and HTTP router.
 Read, send, cancel and delivery inspection use the existing `createAssistantApi`
 request client, including its surface header and workspace path. Inspection is
 an authenticated POST operation because it may recover and save native receipts;
-it never dispatches another model request. Browser inputs cannot set the actor,
+it never dispatches another model request. Cancelling one message is
+`POST …/deliveries/:messageId/cancel` (`cancelConversationDelivery`), which
+always answers success for an unsent, unconfirmed or failed message, without
+waiting for work queued in that conversation. The runtime records the message
+as cancelled, so a send of it that is still queued, or arrives later, is refused
+as not sent with `conversation_message_cancelled`. It also stops a submission
+that holds the message, and afterwards discards its unconfirmed request or
+pending native attempt. A message already accepted stays history. An
+application conversation provides this as `cancelDelivery({ messageId })`;
+without it the operation answers `conversation_unsupported`. Browser inputs cannot set the actor,
 native host or engine context.
 `readConversation(id, { beforeTurnId, limit, signal })` optionally requests an
 earlier or bounded page through the same authenticated GET. Its query contains
@@ -716,6 +725,10 @@ uses more layout work for long histories. The default is false and retains the
 existing remove-and-follow behavior and offscreen layout optimization.
 Scrolling upward within 160 CSS pixels of the transcript's top requests older
 history through `loadMore`, including touch, wheel and keyboard scrolling.
+New replies are followed while the reader is within 48 CSS pixels of the end.
+The reader's own upward touch, wheel or keyboard scrolling (Home, Page Up, Arrow
+Up, Shift+Space) stops following from its first frame, even within that
+distance; scrolling back down to the end resumes it.
 Only one request runs at a time, and prepending preserves the reading position.
 Initial positioning and conversation selection do not fetch older pages.
 `loadMoreError` pauses automatic loading; the older-messages button remains
@@ -877,7 +890,18 @@ message with attachments while an earlier delivery is pending.
 
 Retry keeps the same payload and message ID; the backend must deduplicate that
 ID. Edit moves failed text into the composer while preserving a newer draft;
-Cancel removes only the failed local entry. Neither action stops native work.
+Cancel never removes a message on the browser's own authority. `cancel(id)`
+marks a pending, uncertain or failed entry `cancelling` (shown as
+Cancelling…, with Retry and Edit hidden), and a queued entry cancelled while
+it waits is never delivered. The caller removes it with `remove(id)` once its
+server agrees, or calls `cancelFailed(id, error)` to keep it with Cancel again
+(by default "Couldn't reach the server — Cancel again"). The runtime's
+`cancelMessage(id)` does all of this: it aborts that message's unsent request
+and running delivery check, calls the server's delivery cancel, removes the
+message on agreement and reloads. A cancel that could not reach the server is
+retried on the next snapshot after reconnecting, including after a page reload
+with `draftStorage`. Without an application `cancel` action, the element
+removes only a failed message.
 Retry leaves the current draft untouched. Attachment bytes and removal on
 acceptance remain with the application's attachment owner.
 
@@ -896,7 +920,10 @@ streaming and provider execution remain separately observable application work.
 
 For canonical receipt observation, supply reactive `receiptTurns` and
 `uncertainOnError: true`. Unknown transport failures then retain an uncertain
-entry for inspection; they do not expose Retry, Edit or Cancel. Explicit
+entry for inspection; they expose Retry (the delivery check) and, with
+`cancellableDelivery`, Cancel, which stays enabled while the check runs. The
+runtime binding sets `cancellableDelivery`, because its server always accepts
+a delivery cancel. Explicit
 pre-admission rejection can still return `{ ok: false, error }`. Use `accept(id)`
 only after the backend confirms admission. `restoreUncertain(request, savedTurns)`
 restores the public pending request without sending it again.
@@ -1203,7 +1230,7 @@ fields; disable or omit `models` independently when supplying fixed agent settin
 
 ```js
 {
-  enabled: true, pending: false, error: "",
+  enabled: true, pending: false, stopPending: false, error: "",
   goal: { objective: "Finish the report", status: "active",
     elapsedSeconds: 120, sampledAt: Date.now() },
   set({ objective, tokenBudget }), pause(), resume()
@@ -1216,7 +1243,9 @@ surface failures in `error`; return `false` on unsuccessful creation. The shared
 `AssistantGoalControl` owns the form and presentation, not a scheduler or goal
 storage. Supported statuses are `active`, `paused`, `blocked`, `usageLimited`,
 `budgetLimited`, and `complete`. The UI offers creation only without an unfinished
-goal and offers Pause/Resume only for their applicable statuses.
+goal and offers Pause/Resume only for their applicable statuses. `pending`
+disables Set and Resume; `stopPending` disables Pause and Cancel, which the
+supplied binding never blocks on message sending or unknown delivery.
 
 An active goal flashes red; a paused goal stays orange. `elapsedSeconds` is the
 accumulated **active running time**, and `sampledAt` is its sample time in epoch
@@ -2544,8 +2573,10 @@ message returns its receipt without resending.
 
 Codex uses its active-turn steering operation. Claude writes the instruction as a
 plain user message on the same process; Claude Code acknowledges it as queued and
-reads it after the running tool call, so steering never interrupts a running
-command. OpenCode admits the instruction in the same session
+reads it when the running tool call returns. Steering never interrupts a running
+command: Claude's Ctrl+B control moves a long foreground command to the background,
+where it keeps running, so Claude reads the instruction at its next step. OpenCode
+admits the instruction in the same session
 and follows the new input through completion. No adapter recreates the native
 conversation to imitate steering.
 
@@ -2754,9 +2785,10 @@ The native identity, working directory and credential-home binding remain in
 server-side runtime metadata. Prompt changes replace the process while preserving
 native history; compatible model/effort changes use native controls. Account changes
 are rejected by default. An application that owns its conversations and authorizes
-the current workspace account may opt into `host.allowAccountChange: true`. The
-existing account guard confirms the old process has stopped before saving the new
-identity and resuming the same native history. Failed cleanup blocks adoption
+the current workspace account may opt into `host.allowAccountChange: true`. At
+the conversation's next idle admission, the existing account guard confirms the
+old process has stopped before saving the new identity and resuming the same
+native history; it never stops a running turn. Failed cleanup blocks adoption
 until the existing Stop recovery succeeds. Completed response receipts still
 require their original saved account; this option cannot rebind past effects. Application access
 is checked again after native preparation and before dispatch. Built-in tools are
@@ -2840,6 +2872,17 @@ observer connections on a shared server per account/runtime scope. Stopping or
 closing one conversation leaves other consumers' work and shared server intact. The
 former process-per-conversation launcher has been removed.
 
+Every Codex process this owner launches (the shared app-server in interactive and
+Helper mode, and a local `codexInteractiveArguments()` terminal) starts with
+`-c features.plugins=false -c features.apps=false`. Codex otherwise syncs the
+openai/plugins repository into `<CODEX_HOME>/.tmp/plugins` and downloads plugin,
+app and connector catalogues into `<CODEX_HOME>/cache` at start, roughly 100-250 MB
+per home that is refreshed and never pruned; no conversation uses either. A
+terminal started with `--remote` uses its app-server's setting. The same
+processes pass `-c features.daemon_auto_start=false`, because Codex's terminal
+(on by default in 0.163) otherwise starts a shared app-server daemon whose detached
+updater keeps it running after the terminal closes.
+
 The existing owner preserves per-directory startup serialization, waiter
 revalidation, compatibility and liveness checks, verified retirement, helper
 preparation and startup/publication cleanup. Execution and credential facilities
@@ -2853,7 +2896,11 @@ The existing native connection/thread owner has also moved into
 `CodexAppServerAgentProvider` under `/server/codex-provider`. It consumes that shared
 runtime with execution and credential-state facilities. Its native behavior includes
 helper token activation/refresh, bounded inventories, control recovery, goals,
-hook trust, exact command interruption and history export. The existing
+hook trust, exact command interruption and history export. Inventories bound
+the thread IDs they keep (1,000 threads, 512-character IDs), not the preview
+text Codex sends and the inventory discards; an existence check stops at the
+page that holds its thread. A refused inventory names the check and thread that
+failed. The existing
 native consumer now supplies only its host policy and application callbacks. The common
 driver uses this backend. Ordinary applications use the common conversation API
 with its supplied execution and credential defaults.
@@ -2920,16 +2967,39 @@ native work running; failed stop or final persistence remains retryable. Recover
 uses the recorded native owner after reopening and never replays the request.
 Applications using the common runtime do not supply Codex recovery callbacks.
 
-OpenCode provider credentials are cached for a shared server lifetime. The
-application's private `publish` operation enters that same owner's acquisition
-fence after validating the selected provider. Pending starts drain before the
-owner checks all consumers. Another provider, an unowned driver target or an
-unconfirmed native terminal refuses publication before stopping work; the
-previous saved credential stays available. When only owned selected users remain,
-the original cleanup and verified server exit retire the native cache before
-publishing. New acquisitions refuse during this interval and can retry afterwards.
-The application supplies terminal inventory from its existing PTY owner; no
-second process owner or credential refresh proxy is involved.
+OpenCode reads provider credentials into each directory's native instance and
+keeps them until that instance is disposed. An OpenCode connection change
+(connecting, replacing or removing a key) never stops, kills or waits for running
+turns, retained conversations or the shared server. After the application's
+private `publish` operation saves the change, the owner reads the host's saved
+connections from the invalidation preparation's `connections()`, writes each
+changed key to the running server (`PUT /auth/{provider}`), removes each removed
+one, and returns `{ closed: 0, ok: true }`. Directories with no turn in flight
+reload at once (`POST /instance/dispose`). A directory with a turn in flight
+reloads when its last turn there ends, so that turn finishes on the credentials
+it started with. New work in a directory still awaiting its reload (a new main,
+temporary or renewal turn, or a native terminal) waits for that reload and so
+never starts on credentials the server no longer holds; the only wait is that
+directory's own running turn, and a steer joins it. The server client records
+every directory it has loaded (`instanceDirectories()`), so a directory that
+only served storage reads reloads too, and `disposeInstance()` reloads one
+directory. `ensure(selected, start, readConnections)` applies the same update
+when an acquisition finds a changed key. It reads the saved connections instead
+of trusting the caller's, so a preparation resolved before the change cannot
+restore an older key. Without `readConnections`, or when a provider's route
+changes, the shared server is replaced as before. A turn whose provider was
+removed ends as a credential failure with "`<provider>` isn't connected. Connect
+it again, then send your message again." An unconfirmed native terminal still
+refuses the change before publication through the application's
+`assertConnectionChange`; no second process owner or credential refresh proxy is
+involved.
+
+When the shared OpenCode server exits without being stopped, the owner stops
+what remains of it at once (reason `opencode-server-exited`) through the same
+stop as a failed health check, rather than leaving its execution and leftover
+processes until the next health check, connection change or close.
+`createOpenCodeServerProcess()` exposes that exit as `unexpectedExit`; hosts
+wire nothing for it.
 
 An application's selected provider credential change uses the existing owner's
 `invalidateRuntimes({ modelProviderId, includeOwned, toolHomeSource })` branch.
@@ -2944,6 +3014,26 @@ process retirement only after every loaded/cached thread is proved to belong to
 that provider; mixed-provider homes refuse retirement. Genuine account/socket
 changes retain the original whole-runtime invalidation and recovery.
 
+A Codex account change (the runtime lifecycle's `includeOwned` invalidation)
+never stops or waits for a running turn. A Codex process reads its credentials
+once, so runtimes whose loaded threads are idle stop at once through the
+verified stop, while a runtime with a running native turn is marked stale: its
+active goals are paused so it starts no further turn, its provider still serves
+that turn's output, steer and interrupt, never restarts its runtime and never
+marks the current account after a rejection. The owner result lists it under
+`deferred`; it stops through the same verified stop once its turn completes
+and its output is recorded, or before the session's next runtime starts. The
+application gives each sign-in its own runtime directory and provider key, so
+the next message starts at once on the current account. The run owner's
+`continueGoalAfterAccountChange(sessionId, { threadId })` option resumes a goal
+the change paused once the previous runtime stopped; without it the goal stays
+paused. A runtime that cannot be inspected stops as before. When the
+application's `identity.write` returns `supersededRuntimeDir` (the runtime
+directory the session recorded before), the owner removes that directory once
+its runtime has verifiably stopped; a stale runtime still finishing its turn
+keeps no exit proof when it stops. Helper cleanup treats an absent directory as
+retired.
+
 The application owns independently saved orchestrator/provider records and
 validation before publication. This native lifecycle facility copies no keys
 and validates no other provider. Changed account fingerprints still require an
@@ -3137,9 +3227,11 @@ retained runtime handle. Closure during host preparation prevents acquisition.
 `inspectTemporaryActivity` and reads the selected owner's existing temporary-work
 inventory. Its configured host supplies `{ sessionId: id, engine, native, context }`.
 It opens no Main conversation and remains available during cleanup after runtime
-closure. Native restoration and activity exclusions are those of the same owner;
-there is no additional cache. This advanced server operation has no browser route
-or caller-supplied owner/engine override.
+closure. Activity exclusions are those of the same owner; there is no additional
+cache. Claude answers from the temporary work this server runs and reopens no
+saved conversation: a turn an earlier server saved as active ended with that
+server. This advanced server operation has no browser route or caller-supplied
+owner/engine override.
 
 An existing application's renewal transaction can invoke
 `runtime.generateNativeRenewalHandover({ id, context, input })` and
@@ -3165,12 +3257,21 @@ its existing renewal authorization before native cleanup.
 The same native owners preserve their original contracts: Codex validates
 application renewal authority before its lifecycle queue, then reads saved runtime
 facts inside that queue and releases persisted proof only after shared-peer checks;
-Claude closes through its existing entry/terminal cleanup; OpenCode predecessor
+Claude stops the session's retained work, closes its terminals and forgets the
+session, reopening no saved conversation and writing nothing for an idle one (the
+session's own close already recovered saved custody); OpenCode predecessor
 cleanup awaits close before consuming proof, while successor cleanup only consumes
 proof. OpenCode retains its original distinction between a resolved failed close
 (which still consumes proof) and rejected close (which leaves proof retryable).
+Deleting a scoped OpenCode conversation returns its scope's exit proof as
+`providerExit` and keeps none, because no renewal ever releases a scope's proof.
 Applications retain result projection and successful binding retirement.
 
+Closing a session stops what this server runs for it and then reopens only the
+saved custody an earlier server left (an execution whose exit is unproven, or a
+turn saved as active), so a verified stop can retire it. Claude leaves idle saved
+conversations closed and names an unreadable saved conversation by ID.
+
 `runtime.disposeNative({ namespace, sessionId, context, options })` also supports
 cleanup when no ready retained handle exists. It authorizes operation `dispose`
 and requests `{ id: sessionId, context, input: options, operation: "dispose" }`
@@ -3184,6 +3285,21 @@ existing early-retirement fence before falling back to the configured owner.
 These server-only operations accept no caller-selected owner or engine and add
 no browser endpoints. Ordinary applications still use their conversation handle.
 
+A host can bind a logical conversation through its own `commands`, `read` and
+`readStream`, for example an application's temporary chat. `open()` keeps one
+entry for each such namespace, and browser handles opened per request share it.
+When the application deletes or archives that logical conversation, call
+`runtime.retireOpenConversation({ namespace, sessionId })` from the same trusted
+server transaction. It retires the open entry, closes its handles and listeners,
+and returns `{ retired: true }`. A namespace with no open entry returns
+`{ retired: false }`: nothing is opened to retire it. Native and storage-owned
+conversations are refused; they keep `dispose()` and `runtime.disposeNative()`.
+The application has already stopped and removed the logical conversation's work
+through its own commands; this operation stops nothing and has no browser endpoint.
+A logical conversation streams through its own `readStream`, so retiring or
+disposing it leaves the live reply of another conversation that shares its id,
+such as the session's Main conversation, unchanged.
+
 Historical native records can predate an application's retained scope identity.
 An advanced host can clean up those exact records through
 `runtime.interruptNativeDetachedConversation({ id, context, input })` or
@@ -3209,8 +3325,13 @@ no inference authorization or runtime-closure rule to the original storage polic
 Storage work borrows the shared native process; it is not a user that keeps it
 running. Codex and OpenCode stop a process a storage read started about one
 minute after the last such read (so one maintenance pass shares it), unless a
-conversation, terminal or helper uses it by then. Any real Codex use of that
-provider claims it, and goal and plan-usage reads ignore a borrowed provider.
+conversation, terminal or helper uses it by then. Persistent (Temporary chat)
+conversations borrow it the same way: creating them, reading their history or
+status, stopping idle work, deleting them and changing their settings borrow the
+provider; a running persistent turn or an active goal holds it until it ends,
+and it then stops after the same idle minute unless something else uses it. Any
+other real Codex use of that provider claims it, and goal and plan-usage reads
+ignore a borrowed provider.
 All four operations are server-only, accept no caller-supplied native owner or
 host, and have no HTTP, socket or client route. Ordinary applications continue
 using their conversation handles.
@@ -3223,6 +3344,18 @@ and synchronously returns `{ engine, native, context, input }` with its existing
 native owner and application preparation. Codex, Claude and OpenCode support this
 advanced operation. It opens no conversation or retained handle and remains
 retryable after runtime closure, including when credentials have been revoked.
+Claude closes each of the project's sessions from its retained entries alone,
+independently and together, and then forgets them. A session that cannot close
+is reported by ID in `failed` (with a combined `error`) while every other session
+still stops.
+Codex stops each scoped conversation through the provider that observes it,
+then retires saved Helper records through the providers it stops, and stops every
+provider of the project's sessions, including one that a Temporary chat or a
+read borrowed and no Main thread names. A conversation
+that cannot be stopped is reported in `failed` while the others still stop. A
+saved Helper record that cannot be restored (for example, one whose account was
+removed) stays on disk for a later connection; the result reports it under
+`helperRestore.failed` with its session and thread instead of failing the stop.
 
 `runtime.invalidateNativeRuntimes({ context, input })` uses the same trusted
 server boundary for account changes and shutdown. Its configured host receives
@@ -3231,10 +3364,31 @@ synchronously. The runtime returns the native operation directly: shutdown
 fences and synchronous errors are not deferred behind another await. The host
 retains account policy and result presentation; the native owner retains its
 original cleanup sequence and retryable failures. No conversation is opened:
-each native owner stops the processes this server runs, since none outlives the
-server that started it, and saved conversations are not reopened to be stopped.
-Failed cleanup can be retried after runtime closure. This is not a browser
+at shutdown each native owner stops the processes this server runs, since none
+outlives the server that started it, and saved conversations are not reopened to
+be stopped. Claude stops its sessions together, leaves an idle chat untouched
+(nothing to stop, nothing written) and reports a session that cannot stop by ID
+in `failed` while the others still stop. It stops them even when its
+account-query cleanup fails; that failure is still the call's result. Once
+shutdown has invalidated the owner, a later session close only releases retained
+work. Failed cleanup can be retried after runtime closure. This is not a browser
 operation or a way to submit a caller-selected native owner.
+A running Codex app-server keeps the credentials it started with. A Codex turn
+whose OpenAI credentials were rejected after a sign-out or account switch
+(ChatGPT's token-refresh failure, or a 401 from OpenAI) ends with "Codex (OpenAI)
+isn't connected. Sign in to Codex, then send your message again."; another
+provider's rejected key keeps its own error.
+
+A Claude account change (sign-in, sign-out or switching accounts) stops and
+waits on nothing. Claude Code reads its credentials for every request, so a
+running turn continues on the newly connected account, and a conversation whose
+account signed out ends its next request at once with "Claude isn't connected.
+Sign in to Claude, then send your message again." The Claude owner only drops
+the account's cached model and usage reads, without waiting for cancelled reads
+to finish. Each conversation applies the account guard below at its next idle
+admission; a status read during a running turn keeps that turn. A provider-key
+change (`modelProviderId`) still stops the conversations using that provider,
+because their key is fixed when the process starts.
 
 `runtime.reconcileNativeSessions({ context, sessions, options })` restores an
 application's saved session collection through those same configured native
@@ -3442,8 +3596,9 @@ reuses the host's existing terminal snapshot before attaching, records the
 returned terminal ID on that target, and clears matching IDs after the host's
 existing PTY close resolves. The host supplies only its original read, close
 and namespace functions; a thrown close keeps the native attachment retryable.
-Project cleanup restores the same Helper records, closes the scoped native
-conversations and selects their providers through these existing owners.
+Project cleanup closes the scoped native conversations, then restores the same
+Helper records and selects their providers through these existing owners; a
+record it cannot restore is reported rather than keeping providers running.
 Conversation preparation also applies Helper restoration or ordinary-thread
 ledger exclusion before admission. Native activity and plan-usage queries read
 the same owned maps; hosts retain authorization and result presentation.
@@ -3587,12 +3742,19 @@ The turn owner preserves the production receiver's block lifecycle: deltas are
 temporary, block-stop removes them, and completed snapshots use their native
 UUIDs. It does not group distinct history snapshots into a synthetic reply.
 The retained owner's `createAccountQueries({ accountIdentity, createProcess })`
-composes the existing native model/usage query owner with its own process inventory
-and closing state. A managed host supplies its authorized identity reader and
+composes the existing native model/usage query owner with its own process inventory,
+configuration root and closing state. A managed host supplies its authorized identity reader and
 account-process factory. The original query caches, pending-query sharing and
 retryable cleanup remain unchanged; account queries share already-owned processes
 and the same conversation shutdown boundary. Matching owned processes
-are reused; temporary query processes must prove cleanup. Failed stops remain
+are reused for plan usage; temporary query processes must prove cleanup. The
+model list is read through a temporary query process (a live conversation's list
+dates from its start) and kept for its account until the account's
+`.credentials.json` or the answering process's `command` changes by file
+metadata: sign-in, sign-out, a token refresh or plan change, or a Claude Code
+update. Rereading it otherwise starts nothing. A bare command name has no
+metadata, so only the credentials refresh its list. A started process exposes
+the `command` it ran. Failed stops remain
 owned and are retried before another native query. `invalidate()` drains pending
 queries, clears both caches and retries retained cleanup while new work is
 blocked. For managed bindings, the existing retained conversation owner also
@@ -3603,10 +3765,17 @@ terminal cleanup and product error conversion. These trusted server lifecycle
 operations use the configured common runtime and are not browser actions.
 The account owner's usage normalization retains only native windows whose values and reset times
 are valid; it does not invent refreshed allowance. Plan usage keeps one reading
-per account. It reads through a matching live conversation process at most once
-a minute; with none, or when that answer cannot prove it is current, it starts
-one temporary query process at most every five minutes and stops it when the
-read finishes. A refused fallback keeps the last reading. Only an answer carrying the usage
+per account in the server process, shared by every account-query owner, page and
+session that asks with the same `accountIdentity`, so that identity must name one
+account. A request that arrives during the account's read shares it. It reads
+through the asking owner's matching live conversation process at most once a
+minute per account; with none, or when that answer cannot prove it is current,
+it starts one temporary query process only when neither a verified reading nor a
+temporary read is from the last five minutes, and stops it when the read
+finishes. An account therefore starts at most one temporary Claude every five
+minutes however many pages poll, and none while nothing asks; clients should
+poll only while the page is visible. A refused fallback keeps the last reading.
+`invalidate()` forgets the readings that owner used. Only an answer carrying the usage
 endpoint's `limits` list replaces the reading: Claude Code's fallback answer,
 taken from the answering process's last response headers while its endpoint read
 fails or is held, can be hours old and has no age. A reading is returned as
@@ -3705,13 +3874,16 @@ policy. Both compatibility probes retain their sanitized connection errors;
 neither operation is a conversation or an account store.
 `readClaudeCodeAuthStatus` uses a supplied capture runner for native account
 inspection. Hosts select the executable and credential home and retain their
-execution policy; the reader returns only public account fields. The ordinary
-runtime supplies this integration automatically. When the runner reports that a
-read timed out (`timedOut`) or was refused for now (`retryable`), the reader
-returns Claude's last answer if the account files are unchanged and that answer
-is under five minutes old, instead of reporting the account as signed out.
-Such a read, with or without that answer, is reused for 30 seconds so a busy
-host is not asked again by every caller.
+execution policy; the reader returns only public account fields. Reads of one
+account (configuration root, credential home and Claude identity variables)
+share one answer whichever runner or executable asks, kept until a sign-in,
+sign-out or token refresh changes `.credentials.json`; Claude Code's own
+`.claude.json` rewrites, during turns and after each status run, do not repeat
+the read. The ordinary runtime supplies this integration automatically. A read
+the runner reports as timed out (`timedOut`) or refused for now (`retryable`) is
+reported and reused for 30 seconds, so a busy host is not asked again by every
+caller; a read that ran and failed is asked again next time. macOS reuses
+nothing, because file metadata cannot show Keychain changes.
 The retained owner stops its native process or recovers its durable execution
 identity through the supplied host. Its internal stop operation preserves the
 original stop-proof contract and throws `claude_stop_unconfirmed` when cleanup
@@ -3826,6 +3998,14 @@ Set transport limits appropriate to the host; the default payload limit is
 unbounded. A request abort retires the local request; interrupt a running native
 turn with `turn/interrupt` when cancellation must stop provider work.
 
+`prepareCodexModelCatalog({ command, runtimeDir, bundled, additionalModels,
+codexHome, signal })` from the same entry point exports a runtime's
+`models.json` with the CLI's `debug models` and reuses it until its revision
+changes: the absolute command's file identity, `bundled`, `additionalModels`, or
+the metadata of `auth.json` and `config.toml` in `codexHome` (default
+`CODEX_HOME`, then `~/.codex`). A bare command name exports every time. Isolated
+tests pass their own `codexHome`.
+
 The original public import contracts remain available alongside these host and
 testing surfaces. `/server/codex-client` exports `CodexAppServerJsonRpcClient`
 and `socketPathFromCodexAppServerEndpoint`; `/server/codex-events` retains its
@@ -3952,8 +4132,14 @@ call the same Helper owner directly for thread lookup and retirement, without a
 host inspection callback. A returned retirement promise retains the original
 admission-release order; native dispatch remains awaited.
 It also rejects ordinary access to a retained Helper thread and aggregates
-restoration failures without changing their retryability. The host decides when
-successful restoration is required and supplies its authorized storage root.
+restoration failures without changing their retryability. An unreadable ledger
+or a host notice the host refuses is reported as a restoration failure, not a
+rejection. The host decides when successful restoration is required and supplies
+its authorized storage root; the required-restoration error names the first
+failing session, thread and cause. Closing a session or project reports
+unrestorable records and still stops its live work. Reconciliation continues
+for every session and retires each stale provider independently. Account-change
+invalidation does not restore saved records.
 Stable-account capture and completion validation also belong to the shared run
 owner, independently of the optional retained Helper ledger. They preserve the
 account check after native resume, and the exact current-turn guard before
@@ -4025,6 +4211,17 @@ and `codexCatalogReasoningEfforts` retain native IDs, display-name fallbacks and
 reasoning-option order. Hosts choose offerings, defaults, connection visibility
 and product labels; they may use the original row fields `model`, `hidden`,
 `isDefault` and `defaultReasoningEffort` for that policy.
+`codexHomeDisposablePaths(codexHome, { retired = false })` returns the sorted
+absolute paths of Codex-owned entries no JSKIT-launched Codex uses: the plugin
+and app leftovers in `.tmp` (`plugins*`, `git-*`, `bundled-marketplaces`) and
+`cache` (`remote_plugin_catalog`, `codex_apps_tools`, `codex_apps_server_info`,
+`codex_app_directory`, `bundled_plugin_exclusions`). With `retired: true`, for a
+home that will not launch again, it returns `logs_<n>.sqlite` with its `-wal` and
+`-shm` files, `.tmp`, `cache` and `tmp`, and keeps auth, config, the catalogue,
+sessions and the state, goal, memory, queue and thread-history databases that
+retained conversations may still read. It never follows a linked home or
+subdirectory, returns a link as itself and reads no file content. The host
+removes the paths, and only while no Codex process uses that home.
 `codexProviderFileConfiguration(provider, key, codexHome)` formats the original
 private `config.toml` text from the host's authorized provider record and key.
 The record supplies `id`, `label`, `baseUrl`, `webSearch` and the selected first
@@ -4192,7 +4389,8 @@ unconfirmed or rejected stop remains retryable. The execution facility receives
 the native stop reason and three-second termination grace period.
 The application still owns its database path and retention. Startup errors retain
 the execution ID and cleanup proof; optional host `readLogs()` supplies bounded
-diagnostics. If cleanup is unconfirmed, the error also retains `retryCleanup`,
+diagnostics. A server that exits before readiness names why in its message: its
+last stderr line as plain text, at most 300 characters. If cleanup is unconfirmed, the error also retains `retryCleanup`,
 the same native stop operation. The shared owner holds that operation until exit
 is verified and blocks replacement startup while cleanup remains unconfirmed.
 Its `cleanupPending` flag lets a managed host retry cleanup during project close
@@ -4336,7 +4534,14 @@ For an existing scoped binding, explicit deletion calls
 its scope/persistence policy from that current context. Read, wait and Stop use
 the same preparation without the deletion descriptor; closing the handle still
 uses its supplied close operation. The driver does not interpret application
-scope fields to choose deletion policy.
+scope fields to choose deletion policy. A Codex ephemeral thread lives only in
+the process that created it, so deleting one this server no longer holds needs
+no native delete. Deleting a scoped conversation stops only what this server
+runs for the scope: its live providers, and a runtime whose earlier stop could
+not prove its exit (a runtime other providers share stays theirs). It never
+starts a provider to stop it, so it needs no account, tool home or workdir. Closing a session stops each
+persistent temporary conversation through the provider that observes it and
+reports those it could not stop, which stay retryable.
 A host supplies authorized startup and its application removal notification.
 `openCodeServerForDirectory` keeps each consumer's native client scoped to its
 working directory. `openCodeEnvironmentForDirectory` and
@@ -4504,9 +4709,18 @@ keep using the shared owner for steering and goal admission.
 
 Claude steering and active-turn goal Set/Resume never interrupt the running turn.
 The new input is written as a plain stream-json user message. Claude Code 2.1.307
-acknowledges it with a `queued` command lifecycle event, finishes the running
-foreground tool, then reads the input in the same loop (or in its next loop when
-it arrives after the final model request). The ordinary receipt owner admits it
+acknowledges it with a `queued` command lifecycle event and reads the input when
+the running foreground tool call returns, in the same loop (or in its next loop when
+it arrives after the final model request). So that a long foreground command or a
+wait loop cannot hold the input for minutes, each steer sends the
+`background_tasks` control request (Claude's Ctrl+B equivalent) after its write,
+and again on each `task_started` event until Claude reads it. Foreground Bash
+commands and subagents keep running in the background and report completion with
+a task notification; the blocked tool call returns at once.
+Claude Code 2.1.308 supports the control. A refused control (an older CLI) only
+leaves the input waiting for the tool call and publishes the
+`steering_background_failed` diagnostic; `steering_backgrounded` reports success.
+The ordinary receipt owner admits it
 on that acknowledgement or replay. One native result can then finish the original
 and the queued input; inputs not yet started stay in flight until their own result.
 Interrupting for a steer would kill a running foreground tool such as a deploy.

package/guide/agent/app-extras/assistant.md

@@ -172,6 +172,9 @@ NDJSON routes, conversation IDs, message rows and request-claim table remain the
 integration boundary. A tool reservation is committed to its original
 `tool_call` row before execution; the matching `tool_result` row retains the
 verified result. No second transcript is stored in conversation metadata.
+Each chat turn opens its conversation in the runtime and the last of a
+conversation's overlapping turns releases it when it settles, so a finished
+conversation keeps no server memory; the next turn opens it again.
 
 The surface's bounded, client-selected history remains request context. It is
 authorized for attachments and sent to the API model without being inserted into
@@ -542,7 +545,9 @@ it, the UI shows sending status. A delivery failure offers Resend, Edit and Canc
 beside the message. Resend retains the original message ID, text, selected
 integration, history and attachment IDs; newer typing and newly attached files
 remain untouched. Edit moves failed text into the composer and preserves newer
-text. Cancel removes only that local failed entry.
+text. Cancel asks the server to cancel that message; it shows Cancelling… and
+leaves only once the server agrees, or stays with Cancel again when the server
+cannot be reached.
 
 After acceptance, the runtime displays provider progress and streamed answers.
 An execution failure before an answer restores the request as a draft only if the

package/guide/agent/app-extras/realtime.md

@@ -23,6 +23,14 @@ when an event has an explicit realtime name and audience. The event name,
 scope, payload, and reconnect behavior are public product contracts—not a
 generic “something changed” escape hatch.
 
+The `event_scope` audience, the default for action entity-change and CRUD
+`record.changed` events, delivers to the room of the event's `user`,
+`workspace`, or `workspace_user` scope. An event without such a scope, for
+example one written from a public route or by a job, reaches nobody and logs a
+warning; `event_scope` never widens to all users. Broadcast to every signed-in
+user only through the explicit `all_users` audience; a CRUD feature selects it
+with `defineCrudJsonApiFeature({ realtimeAudience: "all_users" })`.
+
 Client features register listeners through `@jskit-ai/realtime`. Keep query
 invalidation close to the resource that owns the query keys.
 
@@ -83,6 +91,46 @@ The in-process adapter is correct for one server process. Set
 `REALTIME_REDIS_URL` only when multiple processes need a shared backplane.
 Credentials stay outside Git and never enter public client config.
 
+## Shutdown
+
+Realtime shutdown refuses new Socket.IO requests and closes its engine, adapter
+and Redis connections. Clients see their transport close, as with
+`Server#close()`, so Socket.IO's own reconnection reaches the next server; the
+server never sends a disconnect that would stop it. It never closes the HTTP
+server: that belongs to its owner (Fastify closes its own after feature
+shutdown), so another route's open WebSocket or stream does not hold realtime
+shutdown. Code that passes its own `httpServer` to `createSocketIoServer` closes
+that server itself after `closeSocketIoServer`.
+
+## Client updates
+
+An open page keeps running the client code it loaded until it reloads, so after
+an update it can run old code indefinitely. JSKIT's Vite plugin
+(`createJskitClientBootstrapPlugin`) names each production-built HTML page's
+build in `<meta name="jskit-client-build" content="...">`: a digest of the page,
+whose content-hashed script and style names change whenever any built code or
+style does. The same source builds the same id. Vite's development pages have
+none.
+
+On every connection, including the reconnection to a restarted server, the
+realtime server sends `realtime.served-client-build` with `{ buildId }`: the
+build of the page the app serves now, read from `dist/index.html` under
+`runtime.app-root`. It is read for each connection, so a page rebuilt while the
+server runs counts at once. With no built page, nothing is sent. The client
+capability's `onServedClientBuild(listener)` calls the listener with each
+announced id, and at once with the latest one; it returns the unsubscribe
+function. There is no polling and no extra request.
+
+When `@jskit-ai/shell-web` is installed, a page whose own build differs from the
+served one reports an `app-recoverable` notice, a banner under the default
+policy: "*Title* was updated. Reload to get the latest version.", where *Title*
+is the page's `<title>` as it loaded ("This app" without one), with a **Reload**
+action. The page never reloads by itself, because the person may be in the
+middle of something. **Reload** checks that the server answers, then reloads
+the same address. The notice appears once per served build: a reconnection to
+the same build does not repeat it, closing it keeps it closed until a newer
+build, and a server back on the page's own build withdraws it.
+
 ## Visible connection state
 
 A status indicator is optional product UI. When wanted, register it through the

package/guide/agent/app-setup/existing-application-migration.md

@@ -67,7 +67,13 @@ or operation boundary. A Feature declares stable named `requires`, optional
 inputs, and `provides`; `setup()` receives those values directly and returns
 only the promised outputs. Named actions capture the exact feature APIs they
 need. Register structural catalogue entries during `setup()` and reserve
-`boot()` for long-lived work that starts after composition.
+`boot()` for long-lived work that starts after composition. `shutdown()` stops
+that work. The runtime shuts Features down in reverse order and keeps going
+after one fails; it then rejects with an `AggregateError` holding one error per
+failed Feature, each naming its `providerId`. While shutdown runs,
+`diagnostics().providerShutdowns` lists every shutdown with its status
+(`stopping`, `stopped` or `failed`) and duration, so a host can log which one is
+slow.
 
 Capability ids, action ids, routes, events, resources, and placements are
 stable identities. They are not permission to fetch arbitrary dependencies by