| sessions |
Browse sessions grouped by execution machine and directory |
Session summaries; titles, locations, timestamps, pin/archive flags |
persisted metadata; ephemeral grouping |
owner; guests see their shared session |
web; server supplies summaries |
session catalog, access, worker status |
| sessions |
Put pinned sessions first within a directory |
One boolean per session |
persisted |
owner |
web; server |
session catalog |
| sessions |
Rename a session through its options sheet |
Nonempty title |
persisted |
owner |
web; server |
session catalog |
| sessions |
Archive a session through its options sheet |
Session identity |
persisted |
owner |
web; server |
archive operation, worker stop, access revocation |
| sessions |
Restore an archived session when opening it |
Session identity; optional child conversation |
persisted |
owner |
web; server |
restore operation, navigation |
| sessions |
Browse child conversations and archived children |
Child IDs, names, models, activity, archive flags |
persisted metadata; ephemeral expansion |
owner, guest read, guest write within shared session |
web |
conversation listing, access |
| sessions |
Remember choices for the next new session |
One location and model/thinking choice |
until restart of page |
owner |
web |
environment selection, model selection |
| sessions |
Show work, unread answers and worker failures in session lists |
Busy conversation IDs, unread flag, error string |
ephemeral display; read marks supplied by session storage |
owner; scoped status for guests |
web, TUI |
activity reporting, read-mark tracking, worker lifecycle |
| sessions |
Pause a worker safely for cloning |
Session ID, admission fence, prior running state |
ephemeral coordination |
system for owner operation |
server, session worker |
task inspection, worker stop, external database/blob copying |
| sessions |
Stop a worker before archive/delete cleanup |
Session ID; lifecycle operation queue |
ephemeral coordination |
system for owner operation |
server, session worker |
worker shutdown; catalog/blob cleanup is outside core |
| conversations and agent |
Open a session’s durable conversation store |
One SQLite database per session; size grows with history and work |
transcript-bound |
worker, system |
session worker |
exclusive process lock, model configuration, execution environment |
| conversations and agent |
Initialize the root conversation |
Model, thinking level, cwd |
transcript-bound |
worker, system |
session worker |
session catalog, durable storage |
| conversations and agent |
Reject startup when the saved root model is unavailable |
Model identity and configured model inventory |
until restart; failure remains until retry |
owner sees failure; worker validates |
session worker, server |
model configuration, worker error reporting |
| conversations and agent |
Resume interrupted durable work after worker restart |
Persisted tasks and submissions |
transcript-bound |
worker, system |
session worker |
durable storage, installed tools and prompt resources |
| conversations and agent |
Open an archived session for indexing without resuming work |
Startup flag; archived transcript |
ephemeral mode; transcript-bound input |
system |
server, session worker |
worker startup, search rebuilding |
| conversations and agent |
Wait for initial prompt resources before accepting input |
Readiness/cancellation state |
ephemeral |
worker, system |
session worker |
prompt-resource loading |
| conversations and agent |
Keep tool definitions consistent throughout an executing phase |
Immutable definition snapshot |
until phase ends |
worker, system |
session worker |
tool availability, reload coordination |
| conversations and agent |
Enforce conversation-specific human-input restrictions |
Read-only reason; conversation ID |
ephemeral policy |
worker enforces; owner/guest write affected |
session worker |
conversation ownership; stop remains separately allowed |
| conversations and agent |
Attribute human input independently of typed text |
Author kind, stable ID, display name, text, attachment IDs/names |
transcript-bound |
owner, guest read, guest write; worker assigns |
session worker, web, TUI |
authenticated principal, owner-name setting |
| conversations and agent |
Put authoritative speaker identity before model-visible input |
One short structured speaker block |
transcript-bound |
worker produces; model consumes |
session worker |
author attribution |
| conversations and agent |
Read legacy speaker and attachment encoding (drop? old-session compatibility only) |
Leading speaker block and trailing attachment note |
transcript-bound |
worker, owner, scoped guests |
session worker, web, TUI |
legacy transcript |
| conversations and agent |
Make unanswered model failures visible after crashes and reconnects |
Display-only error entry and deduplication receipt per failed input; recovery scans 100 records/page |
transcript-bound |
worker writes; session viewers read |
session worker, web, TUI |
submission settlement, durable commits |
| conversations and agent |
Build a readable transcript from committed and live activity |
Entries, streaming response, tool results, nested calls, pending inputs, reset/compaction markers |
ephemeral projection of transcript-bound data |
owner, guest read, guest write |
web, TUI; worker supplies data |
conversation snapshots, retained history |
| conversations and agent |
Preserve visible history when context resets or compacts |
Loaded entries merged by entry ID |
until restart of client; bounded number of retained conversations, not total history bytes |
owner, scoped guests |
web, TUI |
history paging |
| conversations and agent |
Load older transcript pages without accepting stale replies |
Paging cursor, snapshot epoch, loaded entries |
ephemeral |
owner, scoped guests |
web, TUI, session worker |
history retrieval |
| conversations and agent |
Keep recently visited conversations inexpensive to reopen |
Four inactive history stores; conversation references linger two minutes, cap four |
until restart; timed retention |
owner, scoped guests |
web, TUI |
subscription lifetime, history cache |
| conversations and agent |
Reveal a searched or quoted message, loading history if necessary |
Session, conversation and entry IDs |
ephemeral |
owner, scoped guests |
web |
navigation, history paging |
| conversations and agent |
Show thinking, streamed answers and tool progress |
Potentially large text; expandable tool/thinking cards |
ephemeral display; transcript-bound source |
owner, scoped guests |
web, TUI |
transcript projection |
| conversations and agent |
Show tool-specific results and nested script calls |
Commands, paths, diffs, files, artifacts, child-agent links, nested call statuses |
ephemeral display; transcript-bound source |
owner, scoped guests |
web, TUI |
transcript projection, file/artifact/conversation navigation |
| conversations and agent |
Estimate current context usage |
Active entries with edits applied; token estimate and model limit |
ephemeral derived values |
owner, scoped guests |
session worker, web, TUI |
active transcript, model metadata |
| conversations and agent |
Show latest-response cache effectiveness |
Input/cache-read/cache-write token counts |
transcript-bound source; ephemeral calculation |
owner, scoped guests |
web, TUI |
usage accounting |
| conversations and agent |
Inspect response costs separately from session totals |
One cost/model/time/result row per response; charts |
transcript-bound source; ephemeral display |
admitted conversation viewers |
web; session worker supplies rows |
usage accounting, active transcript |
| conversations and agent |
Record a user-run shell command without starting an agent turn |
Author, command, exit/cancel/error state, output tail ≤2,000 lines/50 KiB, optional spill path |
transcript-bound; spill file separately stored in execution environment |
owner, guest write; scoped viewers read result |
session worker, remote env, web, TUI |
shell execution, durable write |
| conversations and agent |
Choose whether shell output enters the next model context |
Inclusion flag: ! includes, !! display-only |
transcript-bound |
owner, guest write |
session worker, web, TUI |
shell-result recording |
| composition |
Keep an unsent web draft through navigation |
App-scoped text, send mode, reply target, submission identity, errors |
until restart; text also persisted in tab storage |
owner, guest write |
web |
current conversation, send operation |
| composition |
Restore the matching web draft after page reload |
One saved conversation key and draft string |
persisted in tab storage |
owner, guest write |
web |
browser storage |
| composition |
Retain pending attachments across web navigation |
Native files, upload IDs, preview URLs; ≤25 MiB/file |
until restart of page |
owner, guest write |
web |
file selection, upload |
| composition |
Show an image preview before upload |
Browser object URL and original image |
until restart of page |
owner, guest write |
web |
attachment selection |
| composition |
Keep a reply target scoped to its conversation |
Entry ID and display name |
ephemeral; cleared on conversation change |
owner, guest write where replies enabled |
web |
transcript selection, reply support |
| composition |
Retain stop/restored-draft state without attaching it to another conversation |
Stopped conversation identity; restored text supplied by send/stop implementation |
ephemeral; restored text can enter saved draft |
owner, guest write |
web, TUI |
stop/dequeue and draft restoration outside core |
| composition |
Keep TUI drafts and uncertain submissions per conversation |
Text; request ID and steer/follow-up mode per session/conversation |
until restart; carried across UI-worker replacement |
owner, guest write |
TUI |
send acknowledgements, snapshot transfer |
| composition |
Expand prompt commands before sending |
Draft text and expanded template/skill text |
ephemeral; sent result becomes transcript-bound |
owner, guest write |
web, TUI, session worker |
prompt resources |
| composition |
Complete cwd-relative file references |
Query ≤200 characters; ≤100 requested results, truncation flag |
ephemeral |
owner, guest write; not guest read |
web, TUI, session worker, remote env |
confined file index, filesystem changes |
| composition |
Insert quoted path completions correctly |
Cursor location, token prefix, file/directory suggestion |
ephemeral |
owner, guest write |
web, TUI |
file completion |
| composition |
Keep agent mentions and slash commands distinct from file completion |
Short input token; @pi and slash-command context |
ephemeral |
owner, guest write |
web, TUI |
command completion |
| environments and execution |
Select local or remote execution for a session |
Environment name, cwd, connection |
persisted location; until restart connection |
owner configures; worker uses |
server, session worker, remote env |
environment configuration |
| environments and execution |
Use a local execution daemon when available |
Daemon path and lazy connection; otherwise direct Node execution |
until restart |
worker, system |
session worker |
local execution support |
| environments and execution |
Resolve each conversation’s own working directory |
Per-conversation cwd and environment cache |
transcript-bound cwd; until restart cache |
worker, system |
session worker, remote env |
conversation configuration, session location |
| environments and execution |
Repair cwd-following conversations before work resumes |
Root and follower IDs; changed cwd values committed together |
transcript-bound |
worker, system |
session worker |
conversation listing, durable commits |
| environments and execution |
Refuse relocation while work cannot safely move |
Active calls, tasks, pending submissions, busy conversations, refusal reason |
ephemeral |
owner requests; worker/system enforce |
server, session worker |
liveness, durable inspection, relocation checks |
| environments and execution |
Move an idle running session without losing client views |
New machine/cwd; location revision; switched environment connections |
persisted catalog and conversation cwd; ephemeral connections |
owner; system coordinates |
server, session worker, remote env |
admission fence, catalog update, environment opening |
| environments and execution |
Recover a failed or hung relocation |
Committed target location; 60-second move timeout |
persisted target; ephemeral recovery |
system; owner sees failure |
server, session worker |
worker restart, current catalog |
| environments and execution |
Reopen location-dependent resources after a move |
Location revision and notifications |
ephemeral |
worker, system |
session worker, remote env |
committed relocation, prompt/workspace watches |
| background and long-running work |
Start a session worker on demand |
Session initialization, selected capabilities, generation, PID |
until restart |
system for authorized session access |
server, session worker |
session authorization, catalog, exclusive lock |
| background and long-running work |
Prevent duplicate workers opening the same store |
Lock keyed by real data directory and session ID |
ephemeral OS-held lock |
system |
server, session worker |
process locking |
| background and long-running work |
Bound worker startup |
Readiness state; 60-second timeout |
ephemeral |
system; owner sees error |
server, session worker |
worker bootstrap |
| background and long-running work |
Stop workers only after genuine inactivity |
Viewer, active-call and durable-task counts; default five-minute idle interval |
ephemeral |
system |
server, session worker |
liveness reporting |
| background and long-running work |
Keep detached active work from appearing idle |
Active-call lease for work outside ordinary request lifetime |
ephemeral |
worker, system |
session worker |
work cancellation/completion |
| background and long-running work |
Distinguish shutdown from capability removal |
Stopping flag; interrupted-work state |
ephemeral flag; transcript-bound work |
worker, system |
session worker |
durable resumption, reload disposal |
| background and long-running work |
Report worker crashes without corrupting newer status |
Generation, exit code/signal, redacted stderr tail ≤4,000 characters |
until restart |
owner; system produces |
server |
worker lifecycle, log redaction |
| background and long-running work |
Retry a failed worker explicitly |
Session ID; clears sticky startup failure and related notices |
until restart |
owner |
server, web, TUI |
worker stop, fresh access |
| background and long-running work |
Shut down workers on server loss or termination |
Shutdown signal; three-second forced-exit fallback |
ephemeral; durable work remains persisted |
system |
server, session worker |
storage close, execution cleanup |
| access |
Identify the owner, scoped guest or worker behind a request |
Role, device ID or guest ID/session/mode/revision; worker generation |
ephemeral authenticated identity; credentials elsewhere persisted |
system assigns |
server, session worker, web, TUI |
credential authentication, transport provenance |
| access |
Admit only known local or trusted tunnel origins |
Loopback address/port; allowed HTTPS hosts; forwarded-header checks |
until restart configuration |
system |
server |
listener configuration |
| access |
Reject cross-origin browser control and framing |
Origin and Fetch Metadata; nonce-based CSP; trusted relay-frame exception |
ephemeral per request |
system |
server, web |
request provenance |
| access |
Preserve local-owner and guest-cookie distinctions |
Per-port loopback-owner cookie; existing owner/guest credentials |
persisted cookies |
owner, guest read, guest write |
server, web |
credential authentication |
| access |
Authorize access to a particular session before starting its worker |
Session ID and current guest grant |
ephemeral decision |
owner, session-scoped guests; system |
server |
grant validity |
| access |
Separate reading from sending, stopping and uploading |
Guest view/full mode |
persisted grant; ephemeral checks |
owner, guest read, guest write |
server, session worker, web, TUI |
authenticated identity |
| access |
Revoke live access, not just future sign-ins |
Device ID, guest ID or session; grant revision |
persisted revocation externally; immediate ephemeral teardown |
owner/system |
server, session worker, web, TUI |
live connection tracking |
| access |
Show guest names as unverified identities |
Guest name ≤40 characters; read/write label |
persisted grant; ephemeral display |
owner, guest read, guest write |
web, TUI |
authenticated identity |
| remote access |
Redeem an owner link in the TUI |
Origin-bound token → owner cookie; ten-second request timeout |
persisted launcher credential |
owner |
TUI, server |
owner-link service |
| remote access |
Redeem a share link in the TUI |
Origin-bound token, sanitized name, existing guest cookie → session/cookie; response ≤2 KiB |
persisted launcher credential |
guest read, guest write |
TUI, server |
share service |
| remote access |
Keep owner and guest credentials separate per server |
Origin-keyed cookie records; private directory 0700, file 0600 |
persisted |
local TUI user; never downloaded UI code |
TUI |
local configuration |
| remote access |
End reconnect loops when access is revoked |
HTTP 401/403 or admitted-session probe |
ephemeral |
owner, guest read, guest write |
web, TUI, server |
authentication checks |
| remote access |
Forget revoked TUI credentials and offer a fresh link |
Credential kind and origin; replacement link |
persisted credential removal |
local TUI user |
TUI |
access-ended detection |
| remote access |
Sign out one or all owner devices from the TUI |
Confirmed scope; credential deletion |
persisted |
owner with launcher confirmation |
TUI, server |
device revocation |
| links and transport |
Carry authorized calls and live state between clients and workers |
JSON/state frames; server input ≤1 MiB, 32 pending calls/connection |
ephemeral |
owner, scoped guests, worker, system |
server, session worker, web, TUI |
authentication, session routing |
| links and transport |
Disconnect slow or oversized clients without killing the process |
Output backlog budget 4 MiB beyond largest unfinished frame |
ephemeral |
system |
server |
socket accounting |
| links and transport |
Reconnect and rebuild client subscriptions from snapshots |
Connection state and held interests; exponential backoff from 250 ms, capped at five seconds |
ephemeral |
owner, scoped guests |
web, TUI |
live transport |
| links and transport |
Avoid replaying stale TUI connection traffic |
Frame/queue budget 4 MiB; ten-second handshake; no redirects |
ephemeral |
system |
TUI |
connection replacement |
| links and transport |
Refresh an outdated browser protocol implementation |
Local and server protocol versions |
ephemeral |
system |
web |
reconnect handshake, page reload |
| models and settings |
Validate and save agent defaults and execution policy |
Small JSON: model/thinking, streaming/retry/cache, compaction, tool concurrency, queue modes, codemode, owner name |
persisted |
owner; worker/system read |
server, session worker |
settings parsing, coordinated file writes |
| models and settings |
Configure an ordered model-cycling scope |
≤500 patterns, each ≤300 characters; optional thinking suffix |
persisted |
owner |
server, TUI |
model inventory, settings |
| models and settings |
Resolve environment-provided default model |
Provider/model pair; rejects half-configured pair |
until restart |
owner/system |
server |
startup configuration |
| models and settings |
Accept old default-model environment aliases (drop? migration compatibility only) |
Two legacy environment names |
until restart |
owner/system |
server |
default-model resolution |
| models and settings |
Search models available through signed-in providers |
Model/provider names, IDs, context limits, thinking options; web shows ≤300 matches |
ephemeral display of configuration |
owner where model controls exposed |
web, TUI |
model inventory, credential-status summaries |
| models and settings |
Choose thinking level supported by the selected model |
One enum value; unsupported previous choice resets to off |
transcript-bound conversation setting |
owner or permitted conversation configurator |
web, TUI, session worker |
model metadata, configure operation |
| models and settings |
Save the selected model as the new-session default |
Model identity and thinking level |
persisted |
owner |
web, TUI, server |
settings write |
| models and settings |
Observe configuration and prompt files without losing changes during reads |
Watched paths, generation counters, last valid state; invalid-save retry after 200 ms |
until restart cache; files persisted |
system |
server, session worker, remote env |
file watches, fallback polling |
| models and settings |
Serialize private configuration writes |
Lock, current file, validated replacement; 30-second stale/deadline window |
persisted |
owner/system |
server |
private filesystem, cancellation |
| models and settings |
Keep provider HTTP failures from wedging an entire origin |
HTTP/1.1 connection pool; fetch/body errors |
ephemeral |
system |
server, session worker |
outbound network |
| session files and blobs |
Display attachment and generated-file cards |
File ID/name/size, authorized URL; small metadata |
transcript-bound references |
owner, guest read, guest write |
web, TUI |
file storage and authorization |
| session files and blobs |
Preview safe stored-file types |
Text ≤1 MiB by declared size; raster image/audio/video URLs |
ephemeral preview; persisted file |
owner, scoped guests |
web |
authorized downloads, conservative type allowlist |
| session files and blobs |
Open versioned artifacts explicitly |
Artifact name/version/type; view/download URLs |
persisted artifact; ephemeral viewer state |
owner, scoped guests |
web, TUI |
artifact service; executable preview isolation supplied there |
| session files and blobs |
Sanitize display/download filenames |
Basename stripped of path/control syntax; bounded strings |
ephemeral derived metadata |
system |
server, web, TUI |
uploaded/generated filename |
| workspace |
Browse the viewed conversation’s working tree |
Directory entries, sizes, ignored/link markers; UI reports 2,000-entry listing cap |
ephemeral |
owner, guest write; not guest read |
web, session worker, remote env |
workspace authorization, confined filesystem reads |
| workspace |
Find a file by fuzzy name |
Indexed paths; query ≤200 characters; top 200 displayed; UI reports 50,000-file index cap |
ephemeral |
owner, guest write |
web, session worker, remote env |
file listing/index |
| workspace |
Search file contents with include/exclude filters |
Literal query ≤200 characters; each glob field ≤500; bounded matches |
ephemeral |
owner, guest write |
web, session worker, remote env |
workspace search |
| workspace |
Inspect working-tree changes |
Status letters, renamed paths, grouped change tree |
ephemeral |
owner, guest write |
web, session worker, remote env |
repository status |
| workspace |
Browse commit history |
Commit summaries, upstream/unpushed markers; 30/page, refresh ≤500 |
ephemeral projection of repository history |
owner, guest write |
web, session worker, remote env |
repository queries |
| workspace |
Inspect a file or diff at a selected commit |
Commit hash, path, text/diff; historical media download not offered by this shell |
ephemeral projection of repository history |
owner, guest write |
web, session worker, remote env |
repository file/diff queries |
| workspace |
Switch among file, diff and preview views |
Path, line, view, context-line count, wrap preference |
ephemeral route; persisted wrap preference |
owner, guest write |
web |
file reads, preview policy |
| workspace |
Upload files into the selected working directory |
Selected files, target folder, progress/error |
persisted filesystem changes |
owner, guest write |
web, server, session worker, remote env |
authorized workspace upload |
| workspace |
Draft line-linked review comments |
Path, line/range, quote, text, view and optional commit |
persisted in browser local storage |
owner, guest write |
web |
workspace file/diff display |
| workspace |
Preserve an unfinished review-comment editor |
Editor location and in-progress text |
persisted in browser local storage |
owner, guest write |
web |
review comments |
| workspace |
Send selected review comments as a conversation message |
Sorted comments; remove only successfully sent draft IDs |
transcript-bound after send; local drafts until then |
owner, guest write |
web, session worker |
message submission |
| workspace |
Refresh visible workspace data without flashing away old results |
Watch revision; 500-ms debounce; 300 cached query answers |
until restart of page |
owner, guest write |
web |
filesystem changes, query cache |
| workspace |
Preserve workspace navigation and layout |
Tab, folder/file/commit/search, expanded folders, panel width and scroll positions |
ephemeral expansion; persisted route/layout portions |
owner, guest write |
web |
navigation, browser storage |
| terminals |
Expose the session terminal panel without granting it to guests |
Terminal identity and start intent |
ephemeral route |
owner only |
web; server/session machine provide terminal |
terminal service, session location |
| UI shells |
Serve authenticated installable web pages and content-named assets |
HTML, manifest, icons, JS/CSS/assets; UUID session and positive conversation routes |
until restart bundles; browser-cached immutable files |
owner, scoped guests |
server, web |
access gate, UI build |
| UI shells |
Provide themed sign-in, join and access-ended pages |
Small server-rendered HTML; escaped titles; nonce-protected scripts |
ephemeral |
owner, guest read, guest write, unauthenticated visitor as appropriate |
server, web |
access flow |
| UI shells |
Adapt navigation to desktop, mobile Back and embedded browsers |
Conversation route, drawer/sheet/viewer stack, workspace/terminal route |
persisted in tab history/storage |
owner, scoped guests |
web |
browser navigation facilities |
| UI shells |
Restore per-step scroll positions |
Up to 200 saved positions; content arrival wait ≤2 seconds |
persisted in tab storage |
owner, scoped guests |
web |
navigation, asynchronous content |
| UI shells |
Follow new answers without moving someone reading older text |
Bottom-follow flag and visible-element anchors |
ephemeral |
owner, scoped guests |
web, TUI |
transcript updates, layout measurement |
| UI shells |
Preserve transcript reading position across TUI replacements |
Entry/item key and line offset per conversation |
until restart; included in replacement snapshot |
owner, scoped guests |
TUI |
history loading, snapshot transfer |
| UI shells |
Render rich text without executing transcript HTML |
Markdown, tables, code/diff blocks, permitted inline formatting and validated links |
ephemeral display |
owner, scoped guests |
web, TUI |
transcript text, syntax rendering |
| UI shells |
Render diagrams according to user display policy |
Mermaid source; off/final/streaming preference |
ephemeral display; persisted preference |
owner, scoped guests |
TUI |
Markdown transformation |
| UI shells |
Remember browser theme and sidebar state |
System/light/dark choice; collapsed flag |
persisted in browser local storage |
owner, scoped guests |
web |
browser storage/theme |
| UI shells |
Discover and invoke context-appropriate TUI commands |
Command IDs, slash names, shortcuts, role/screen/focus conditions |
until restart; configurable bindings persisted |
owner, scoped guests according to command |
TUI |
current access and screen |
| UI shells |
Explain and report shortcut conflicts |
Resolved bindings, conflicting contexts, unknown IDs, source labels |
ephemeral |
local TUI user |
TUI |
command resolution, preference validation |
| UI shells |
Customize local TUI appearance and interaction |
Whitelisted settings; preference file ≤256 KiB; ≤64 custom themes, ≤1 MiB combined |
persisted |
local TUI user |
TUI |
trusted local-file reads, validation |
| UI shells |
Merge server display defaults below local preferences |
Built-in → server → local pi files → p2 preferences; privileged keys excluded from server control |
persisted sources; ephemeral merged state |
owner supplies server defaults; each visitor controls local settings |
server, TUI |
preference validation |
| UI shells |
Hot-reload local TUI preferences |
Changed preference/theme files; 100-ms debounce; ≤50 diagnostics |
until restart derived state; source files persisted |
local TUI user |
TUI |
filesystem watches |
| UI shells |
Save UI-requested local preferences only after showing the diff |
Validated patch; excludes launcher-owned privilege settings |
persisted |
local TUI user confirms |
TUI launcher |
trusted confirmation, current preference file |
| UI shells |
Replace downloaded TUI code while preserving selected UI state |
Hash-verified bundle ≤8 MiB; manifest ≤8 KiB; snapshot ≤1 MiB |
until restart; snapshot survives replacement only |
system; visitor can request reload |
server, TUI |
bundle publication, sandbox startup, snapshot validation |
| UI shells |
Read old TUI snapshot formats (drop? replacement-version compatibility only) |
Legacy session-keyed drafts and screen names |
ephemeral migration |
system |
TUI |
snapshot restoration |
| TUI local safety |
Keep downloaded UI code away from local files, network and credentials |
Permission-dropped worker; empty environment; narrow message bridge |
ephemeral |
system enforces for every visitor |
TUI launcher |
supported Node runtime |
| TUI local safety |
Bound downloaded UI memory and startup |
Heap limits 96/16 MiB; code range 64 MiB; stack 4 MiB; process RSS watchdog 512 MiB; startup 10 seconds |
ephemeral |
system |
TUI launcher |
sandbox lifecycle |
| TUI local safety |
Filter terminal output before it reaches the real terminal |
Complete frames ≤64 KiB; limited cursor/style/mode controls; OSC/DCS discarded |
ephemeral |
system |
TUI launcher |
output parser, local mouse policy |
| TUI local safety |
Authorize one privileged local action from a real user gesture or confirmation |
Action, origin, UI-worker identity, session/conversation, cancellation signal; ten-minute grant lifetime |
ephemeral |
local TUI user |
TUI launcher |
trusted input and confirmation |
| TUI local safety |
Cancel local-action authority after navigation or UI replacement |
Grant IDs and target identity |
ephemeral |
system |
TUI launcher |
navigation, sandbox lifecycle |
| TUI local safety |
Copy text using trusted local clipboard access |
Selected/last-answer text ≤1 MiB; selection gesture window two seconds |
ephemeral; external clipboard persists |
local TUI user |
TUI launcher |
user key, selection gesture or explicit confirmation |
| TUI local safety |
Upload a locally chosen file without trusting server-supplied file facts |
Verified regular-file descriptor; no final symlink; ≤25 MiB |
persisted server upload; ephemeral local grant |
owner, guest write with local consent |
TUI launcher, server |
file picker, upload authorization |
| TUI local safety |
Paste clipboard files, images or text safely |
Up to ten files; confirmed image upload; sanitized bracketed text paste |
ephemeral or persisted upload |
local TUI user; upload requires write access |
TUI launcher, server |
clipboard access, attachment upload |
| TUI local safety |
Download a file without overwriting local files |
Authorized session file/artifact; ≤25 MiB; 60-second timeout; safe unique filename |
persisted local file |
admitted visitor with local confirmation |
TUI launcher, server |
download authorization, bounded streaming, cancellation cleanup |
| TUI local safety |
Open a browser URL without forwarding TUI credentials |
Confirmed HTTPS external URL or allowlisted same-origin resource |
ephemeral |
local TUI user |
TUI launcher |
URL validation, trusted confirmation |
| TUI local safety |
Edit draft text in the visitor’s external editor |
Text ≤1 MiB; private temporary file; result tied to original grant |
ephemeral; temporary file removed |
local TUI user |
TUI launcher |
local editor preference, terminal handoff |
| TUI local safety |
Suspend and resume the TUI process cleanly |
Terminal modes, process job-control state |
ephemeral |
local TUI user |
TUI launcher |
terminal handoff; unavailable on Windows |
| TUI local safety |
Restore terminal state after overlays, external programs, reloads and crashes |
Mode state, title/progress/status, dimensions clamped to 500×200 |
ephemeral |
system |
TUI launcher |
terminal lifecycle |
| dev and reload |
Detect source changes without applying them automatically |
File hashes, loaded dependencies, bundle inputs; dirty status |
until restart |
owner, system |
server, session worker, web, TUI |
source watching |
| dev and reload |
Distinguish reloadable changes from runtime restart requirements |
Changed source paths and loaded baselines |
until restart |
owner, system |
server |
dependency/input tracking |
| dev and reload |
Apply explicitly selected capability changes across running processes |
Candidate selection; readiness/refusal report; previous/current code versions |
until restart |
owner; authorized local automation |
server, session workers |
compatible reload, dependency checks |
| dev and reload |
Refuse removing functionality still in use |
Provider/consumer use records across server and workers |
ephemeral |
system; owner sees reasons |
server, session workers |
active-use tracking |
| dev and reload |
Publish UI code only after successful backend change |
Prepared web/TUI bundles; each ≤8 MiB excluding web source maps |
until restart |
system |
server |
successful reload |
| dev and reload |
Let just-served old web pages finish loading during a reload |
At most two previous bundles retained for 60 seconds |
ephemeral |
owner, admitted guests |
server, web |
content-named assets |
| dev and reload |
Detect changed web code and reload the page |
Manifest version; five-second visible-page polling plus visibility check |
ephemeral |
system |
web |
bundle publication, stored draft/navigation state |
| dev and reload |
Detect changed TUI code and replace its sandbox |
Manifest version; one-second polling |
ephemeral |
system |
TUI |
bounded download, snapshot transfer |
| dev and reload |
Accept local development commands without exposing a network-admin socket |
Protected Unix socket; 0700 directory; POST body ≤16 KiB; 120-second timeout |
ephemeral |
owner, authorized local process |
server/local host |
filesystem permissions, command validation |
| dev and reload |
Restart through the supervisor and reopen previously running sessions |
Running-session IDs and supervisor result |
until restart handoff |
owner/system |
server, session workers |
supervisor outside core, worker startup |
| dev and reload |
Retry transient operations interrupted by compatible code changes |
Fresh execution context; at most 20 conflict retries |
ephemeral |
system |
server, session worker |
cancellation, reload/version detection |
| logs and notices |
Capture diagnostics without altering actual stdout/stderr behavior |
UTF-8 lines, original binary stream behavior; capture queue ≤256 KiB |
until restart |
system captures; owner reads diagnostic copies |
server, session worker, detached hosts |
stream tee |
| logs and notices |
Redact secrets before storing diagnostic copies |
Known/current/rotated literals plus structural credential patterns |
until restart redaction set |
system; owner sees redacted output |
server, session worker, detached hosts |
private configuration/env discovery |
| logs and notices |
Bound retained diagnostic history |
≤128 sources; each ≤1,000 lines/256 KiB; lines >16 KiB omitted; partial lines >64 KiB discarded |
until restart |
owner |
server |
redaction, log capture |
| logs and notices |
Preserve bounded detached-host logs across process exits |
Atomic redacted JSON snapshot; private file; 50-ms publication debounce |
persisted |
owner; system writes |
terminal host/dev supervisor, server |
redacted log store |
| logs and notices |
Surface operational failures separately from raw logs |
One latest notice/source, ≤50 notices; source/time/message |
until restart |
owner |
server, web, TUI |
worker/dev/server failure reporting |
| logs and notices |
Merge and dismiss duplicate owner notices |
Notice identities; no log text in dismissal storage; success hides after five seconds |
persisted error-dismissal IDs; ephemeral success notices |
owner |
web |
log/dev notice feeds |
| logs and notices |
Inspect logs without waking stopped workers |
Source selector and retained snapshots |
until restart or persisted detached snapshot |
owner |
server, web, TUI |
diagnostic storage, not worker acquisition |
| logs and notices |
Show short local TUI feedback |
Latest three messages; repeated last message becomes a count |
ephemeral; cleared on navigation |
local TUI user |
TUI |
command/action outcomes |
| system operations |
Expose readiness without requiring credentials |
Tiny health response; only accepted hosts/origins |
ephemeral |
system, local/remote launcher |
server |
listener/access-origin validation |
| system operations |
Run only one server for a data directory |
Process lock and private sessions directory |
ephemeral lock; persisted directory |
system |
server |
local filesystem |
| system operations |
Close sockets, workers, watches and storage on shutdown |
Resource handles and shutdown ordering |
ephemeral cleanup |
system |
server, session worker |
all active resource lifetimes |
05dc8d239d