Sessions

A session is the durable record of your work, stored on your machine. Polytoken writes every event in order as it happens (your prompts, the model’s replies, tool calls, and markers for compactions and clears) and replays those events to reconstitute the conversation. The session holds them all, however few the model is working from on a given turn.

Compacting and clearing change what the model works from without removing recorded events. Rewinding returns the session to an earlier event and removes every later event from the disk record. Those removed events do not come back.

Exporting a session

Use the offline exporter to make a standalone HTML transcript of a retained session:

polytoken export-session <session-id> --output-file ./transcript.html

Polytoken exports the local session snapshot without loading configuration, starting a daemon, contacting a provider, or changing the session. By default, the exporter reads sessions from $XDG_DATA_HOME/polytoken/sessions (default: ~/.local/share/polytoken/sessions) and from the sibling sessions-v1 directory, which holds sessions in the newer format. Use --sessions-dir <dir> to select another retained-sessions root.

Create the output parent directory before exporting. To replace an existing output file atomically, pass --force. Polytoken refuses to overwrite an existing file without that flag. Even with --force, Polytoken refuses a destination that is a directory, a symlink, a path inside the selected session directory, or an alias of a source session file.

The transcript keeps user and assistant prose in recorded order and includes full tool inputs and outputs. Recognized saved references display in their @ form; malformed or unknown reference tags remain literal text. Ordinary tool entries start folded for navigation; question and plan-handoff entries start open, with the recorded questions and the saved plan visible. Folding is presentation only, not redaction: included tool content may contain sensitive values. The transcript omits reasoning/thinking, notifications, injected reminders, audit records, and subagent lifecycle transcripts. Markers for text compaction, context clears, facet switches, and model switches appear in place, and every earlier entry stays in the transcript. A native compaction boundary and its later conversion to portable text leave no marker in the export.

Each export is a self-contained HTML file with inline styles and native expandable sections. It uses no JavaScript and loads no remote resources. Remote Markdown images appear as their alt text with a safe source link.

When the recorded active plan identifies a root plan.md or plan-*.md inside the selected session directory, the exporter includes the whole file at export time inside its handoff entry and labels it Saved plan file at export time. It never guesses a newer plan or reads outside the selected session directory. When a plan is missing, unsafe, or unreadable, the exporter shows an unavailable note and keeps the recorded handoff content.

Context

The context is what the model works from on a given turn: the events Polytoken draws from the session and sends to the model. A model can take in only so much at once, so the context is bounded while the session keeps growing. Compacting and clearing both act on the context, not the session: they change what the model works from without touching the events on disk.

The context gauge

The status line shows the percentage of context left, such as 62% context left. Polytoken calculates the percentage from the effective request limit for the current model. The effective request limit can be lower than the model’s advertised context window.

A ~ prefix means Polytoken is showing a local estimate because no fresh provider-reported figure is available yet, such as immediately after switching models. The next provider-reported figure replaces the estimate. While a turn runs, the gauge keeps its last value. After /clear, the gauge briefly reads context: n/a until Polytoken refreshes the value.

The gauge is a stable measurement taken between requests, not a prediction of the next request’s size. The next request can grow past the limit between two measurements, for example when a tool returns a large result. If that happens, Polytoken rejects the request before sending it, and the error names the measured usage, the estimated size of the rejected request, and the effective limit.

When the gauge shows little room, see Compacting for how Polytoken frees context while preserving the session record.

When a provider temporarily rejects a request, Polytoken waits and tries again rather than failing the turn. During the wait, the turn status line shows the reason, a countdown to the next retry, and which retry is next. If you cancel the turn while Polytoken is waiting, the status line states how far into the wait the cancel arrived. Waits of a minute or longer read in minutes and hours (for example 1m 30s or 2h 1m) instead of a large second count. The wait line survives detaching and reattaching: if you reconnect while a retry wait is still running, the status line picks the countdown back up from the current remaining time rather than restarting the full delay.

Polytoken checks each request against the model’s context limit before sending it. If the request would not fit, Polytoken tries one automatic compaction. If the request still exceeds the limit, the turn ends with an error saying the conversation no longer fits the model. Polytoken does not send that request; use /compact or /clear to make room before continuing.

When automatic compaction fails repeatedly, Polytoken shows an always-visible remediation card. The card names /compact, rewind, and /clear so you can choose a recovery action before sending another request.

Polytoken asks the model to answer when the model streams only reasoning without a visible reply. If that pattern persists, Polytoken discards the unproductive attempts and retries once from the last completed exchange of messages and tool calls. A turn that still produces no reply ends with a visible note explaining that the model did not answer. Polytoken removes the reasoning from those discarded attempts from the context.

Repeated tool calls have a bound as well. When the model calls the same tool with the same arguments again and again, whether those calls succeed or fail, a reminder card tells the model to change course. If the model continues, the turn ends with an error that names the call.

Model groups and failover

A model group is an ordered list of model selectors that Polytoken can reuse as one routing target. A group’s value is a single selector, a group reference, or an ordered list of either. Nested groups flatten in authored order, and duplicate positions remain distinct. Configure groups under modelgroups; see the configuration reference.

Model groups reverse the usual configuration precedence: user/global definitions replace project definitions, and project definitions replace shipped ones. Each winning group value replaces the complete lower-priority value. A group member cannot be null. Omit the group’s key under modelgroups to remove that layer’s override and restore the lower-priority definition. Polytoken validates every layer on its own, so an invalid definition still fails the load even when a higher-priority layer overrides that group’s name.

When a provider attempt fails, Polytoken first moves past a rate-limited candidate when another group position remains available. Other provider errors use the retries configured for the current model before Polytoken moves to the next position. A rate limit does not remove a candidate from future use. When every candidate is rate-limited, Polytoken returns to the first available candidate and waits before retrying. A successful response makes the selected candidate sticky for later turns. When you or the model explicitly selects a group again, the route restarts at the first position.

When a provider reports a Retry-After hint with a rate limit, Polytoken also remembers a cooldown for that provider until the hint expires. Cooldowns last for the daemon session only and are keyed by the configured provider name, so a reload or re-authentication does not reset one. A new prompt whose route contains a cooling provider skips it and starts on the next usable candidate. When every candidate of a route is cooling, Polytoken waits visibly until the earliest cooldown expires before dispatching anything: you can cancel the wait, and the wait countdown appears in the session state. Cooldown waits do not change how an in-flight attempt retries.

By default, Polytoken also tries the next candidate in a group after repeated responses with no output and no reported token usage. Change daemon.empty_stream_failover_threshold in your configuration file to choose how many consecutive empty responses trigger the switch. Omit the key to use the built-in default; 0 keeps the current model. A response with output or reported token usage starts the count over. See the configuration reference.

Polytoken keeps the available leaves of an authored group when another leaf references a provider or model that is unavailable. The session can use the remaining candidates, and the TUI shows a warning card naming each skipped leaf. A fully broken authored group blocks config loading and names the leaves that need attention; fully broken means every leaf is confirmed unavailable, not merely absent right now. For dynamic providers, Polytoken waits for that provider’s catalog before treating an undiscovered model as unavailable, and a group whose only remaining leaves are still waiting on that catalog is withheld with a warning rather than rejected.

In polytoken config ui, when you add a concrete model that supports reasoning effort or thinking, the configurator asks you to choose an effort level before it adds the member. Choose Default to add only the model name. Cancel the effort-level prompt to discard the pending addition.

The configurator shows shortcut hints only for controls you can use in the current focus state. When a dialog is open, the dialog receives keyboard input before the configurator: hints for the controls it covers disappear, and plain characters go to the dialog’s filter. Enter accepts the dialog rather than triggering the action a hint names. In the member editor, D deletes the focused member when no dialog is open; while the add dialog is open, pressing D types d into the dialog’s filter instead. Because the dialog receives every keystroke, a half-typed group name remains in its filter until you accept or cancel the dialog.

When you reference a model group in a prompt or on the command line, the reference needs one of four prefixes: @modelgroup:name, @mg:name, modelgroup:name, or mg:name. A bare group name never resolves as a group.

Select a model group from the prompt with a reference:

Summarize the findings from both audits. @mg:polytoken:researcher

Select one for a non-interactive polytoken exec run with the --model flag:

polytoken exec --model mg:polytoken:plan_facet "review this handoff plan"

During a reload, Polytoken keeps the route on the current position when the reloaded group still contains that selector. When the selector appears more than once, the route stays on the occurrence the session was already using rather than jumping to the first match. A reload that drops the selector from the group moves the route to the group’s first member. When the reloaded configuration no longer defines the selected group at all, the session keeps using the current model as a plain selection and rejoins a group the next time you or the model explicitly selects one.

Cache warming

OpenAI Responses and Codex models reuse a cached copy of a conversation’s prompt prefix when a later request repeats it. While a conversation waits on long background work, the cached copy can expire, so the next turn pays full processing for the prefix again. Cache warming sends a small extra request during those waits to keep the prefix cached. Changes that rewrite the prompt prefix have the same cost: see the flush note in TUI Orchestrators for one example.

A warm request is an inference request, not a network ping. Polytoken sends the conversation’s prompt prefix unchanged, appends a single instruction asking the model to reply only OK, and discards the reply. Warm requests run no tools and append nothing to the session, so what the model works from never changes. Each warm request draws on your API spend or subscription quota like any other request, and a completed refresh does not guarantee a cache hit on the next turn: providers route cached prefixes under load and promise nothing.

When warming runs

The daemon.cache_warming key in your user/global config controls when Polytoken may send warm requests. A project config cannot set the key.

• when_waiting is the default. Polytoken refreshes a conversation only while that conversation owns at least one running or queued background job, such as a subagent, a backgrounded shell command, or a tool flow. A long foreground shell or tool call runs inside the turn rather than as a background job, so on its own it never starts a refresh.
• always refreshes whenever a conversation sits idle between requests. This value also covers waits inside long foreground tool calls and the time after you step away from a live session.
• never stops every warm request for every model, including models whose built-in default enables warming. Use this value to spend nothing on warming.

Refresh limits and cache misses

Polytoken bounds successful warm requests per conversation, regardless of the policy. The user/global key daemon.cache_warming_max_refreshes defaults to 3 for the main conversation. The user/global key daemon.cache_warming_max_refreshes_subagent defaults to 1 for each subagent conversation. Both values must be at least 1. A new successful ordinary provider attempt resets the conversation’s count and starts a fresh idle stretch. Failed warm requests do not count, and failed ordinary attempts do not reset the count. When new conversation activity interrupts a refresh, Polytoken excludes that incomplete refresh from the count.

When a completed warm reports zero cached tokens, Polytoken stops warming that conversation immediately. A provider that omits cache usage does not count as a miss. Set daemon.cache_warming_refresh_limit_enabled to false to disable counting and cache-miss stops while retaining the regular warming policy. All three refresh-limit keys are user/global-only. A project config cannot set or erase them.

Failed warm requests

Polytoken retries a failed warm request at the next interval, but stops after a short run of consecutive failures. A failure that retrying cannot fix, such as an expired login, stops warming immediately. In either case, the conversation shows a pause card. Your next successful prompt resumes warming for that conversation. Warming also stops when the conversation reaches its refresh limit or a cache miss shows that the provider did not reuse the cached copy.

Model intervals

Warming runs only for models with an interval. Set models.<name>.cache_warming_interval_secs to a number of seconds between refreshes, anywhere from 1 to 86400:

models:
  openai/gpt-5.6-terra:
    cache_warming_interval_secs: 1200
  openai/gpt-5.6-luna:
    cache_warming_interval_secs: 0

The 0 value above turns warming off for that model. Omit the key to inherit the model’s built-in default. The shipped catalog enables warming at 1560 seconds (26 minutes) for GPT-5.6 sol, terra, and luna, for GPT-6 sol, luna, and Astra, and for GPT-6.1 sol, including the Codex -1m variants of those models; every other model defaults to warming off. That 26-minute interval matches what those specific models keep, and other models differ: earlier models hold a cached prefix for less time, so pick an interval below the retention your model actually keeps.

Only OpenAI Responses and Codex models act on an interval. A model served another way keeps the setting in your config for later, and Polytoken warns that the model’s backend does not support warming.

Refresh results in the interface

Each refresh attempt shows a compact Cache refresh card naming the model and, for a subagent’s own refresh, the subagent. A cache hit shows the cached input-token count. For a completed refresh without a hit, the card states that the provider reported no cache hit; when the response has no usage figures, cache usage appears as unavailable. Failed refreshes show the failure category.

Refresh results describe only that request, not whether the next request will hit the cache. Polytoken keeps refresh cards in the interface rather than the session record and removes them when you reload, clear, or rewind the conversation.

On the Codex backend, the endpoint rejects an output-token cap, so a warm request cannot bound its reply the way the OpenAI backend caps the reply at a few tokens. Replies stay short in practice and Polytoken cancels a stalled request, but the cost of a Codex warm request is not capped.

Compacting

/compact summarizes the conversation so far. Polytoken writes a summary and appends it to the session as a compaction event. From then on the model works from the summary instead of the full transcript, which frees up room in the context.

Compacting is also what lets a session run for a long time. When the context fills past a threshold, Polytoken compacts on its own, so the conversation continues instead of stopping when the context is full. Your todos live on the session rather than the context, so they survive a compaction. The model keeps its plan even as the older conversation becomes a summary.

Polytoken checks every summary request against the model’s limit before sending it. If trimming cannot make the request fit, compaction stops with a message naming the part of the conversation that exceeds the limit. For diagnosis, Polytoken logs message counts and sizes for each rejected summary request, without conversation content.

You can pass guidance with /compact to steer what the summary keeps.

Polytoken includes applicable project instruction files in conversation context, from global instructions through ancestor directories, the project root, and the current working-directory stack. Files too large to include whole appear as paths for the model to read. An unchanged resume avoids duplicate instruction reminders. Clearing, compacting, or changing which files apply allows Polytoken to deliver the instructions again; editing an already encountered file does not by itself trigger another reminder. Tool activity can also discover instruction files and add their contents after a tool batch. See Project Context for instruction-file discovery and precedence.

Compaction preserves applicable project instructions and a selection of recent instruction-file contents. Polytoken keeps paths to other encountered files so the model can read those files again. A context reset can restore instructions that the session encountered earlier.

Recent images in the retained conversation also remain visible to the model after text compaction. Polytoken retains a bounded selection of recent unique images and represents older images with text notices. Native compaction keeps images in the provider’s continuation state instead.

During a long turn, new tool results can grow the context again after an automatic compaction. Polytoken compacts again at the next safe point when the context crosses the compaction threshold, allowing the turn to continue with room for more tool calls. Polytoken limits these automatic repeats for one turn. A compaction card marks each pass in the TUI.

Reloading configuration

Use /daemon-reload (or /reload) after changing configuration, facets, skills, hooks, permissions, or project context. Polytoken applies an idle reload immediately. If a turn is running, Polytoken queues one reload and returns a queued response. The running response always finishes naturally first: the reload starts after the current response completes, never in the middle of one. A long-running turn delays the reload until the turn ends or you cancel it. The interface flashes a queued notice. When the reload finishes, Polytoken flashes a completion notice and refreshes the displayed session state. The event stream reports these milestones as ReloadQueued and ReloadCompleted.

A second reload request while one waits returns the reload_already_queued conflict. A reload request cannot join the queue when pending user input already waits behind the running turn, so Polytoken returns reload_blocked_queued_input. Send the reload again after the queued prompt starts or finishes.

Native and text compaction

Polytoken uses text compaction for most models. Built-in Codex configurations for GPT-5.6 sol, terra, and luna, GPT-6 Astra, and their one-million-token Codex variants support native compaction and use it by default. Native compaction keeps the provider’s continuation state rather than creating a readable summary. The compaction card identifies the native method without displaying that state.

Native compaction reports provider usage separately from the context gauge. After native compaction, the gauge remains unmeasured until the next ordinary request reports usable input-token usage. Polytoken records that measurement for the native context.

To leave room within the model’s context window, Polytoken may trim trailing text tool output before requesting native compaction. Encrypted native items and structured tool content remain intact. The provider determines whether the request fits the full context-window limit. If the provider rejects native compaction, Polytoken tries text compaction once and marks the card as a fallback.

When a model switch, facet change, reload, account refresh, or resume makes the provider’s native state incompatible with the new selection, Polytoken converts the context to portable text before sending the next request. Polytoken saves the conversion with the selection so restarting preserves the compatible text context.

Each subagent starts with its own context rather than inheriting the main session’s native context. A subagent using a supported model compacts natively with the same gauge and conversion behavior. A fork using the same model keeps a measured native context; a fork using a different model converts that context to text.

Other models, including built-in OpenAI configurations and custom endpoints, use text compaction. The models.<name>.compaction_strategy key selects the strategy for one model. Set local to always use text compaction, or native to request native compaction on a supported built-in configuration. Omit the key to inherit the model’s built-in choice.

Compacting between steps

The model can also compact on its own between the steps of a long piece of work, using the compact_context tool. It acts only when the context is at least 40% full; below that it returns guidance and keeps working, because a mostly-empty context has nothing to reclaim. The model supplies a directive with the call, saying what to do once compaction finishes, and the directive may reference a skill. Polytoken appends the directive as the continuation the model follows after the compaction event, so a long plan keeps starting each step with as much working context as possible instead of waiting for the automatic threshold.

The model can pass an optional facet argument with compact_context to switch to a different facet before Polytoken compacts the context. Using facet requires the active facet to expose switch_facet; the plan facet does not expose it, so from plan the model can use handoff_plan to move from planning to execution.

If the switch is declined, Polytoken keeps the current facet and skips compaction. If the switch succeeds but compaction later fails, Polytoken keeps the new facet and the turn continues. The switch-first order means the requested facet shapes the summary Polytoken writes and the system prompt for the requests that follow.

Clearing

/clear resets the context. The model starts fresh, as if the conversation had just begun, and Polytoken records the reset as a clear event in the session. Before the reset, Polytoken cancels any running subagents so their output does not leak into the new context. Your todos are part of the session, so clearing the context leaves them untouched. Shell environment changes made during the session survive the clear. Variables that existed at startup retain their current values, and variables created during the session remain available. If a variable that existed at startup was removed, Polytoken restores its original value.

Use /reset-shell when you want the full shell environment restored to the state captured at startup. Polytoken undoes all changes to variables, PATH, aliases, functions, and shell options without clearing context, appending a clear event, or changing your conversation history.

Polytoken carries flagged files into the new context after a clear. An included flag preserves the file’s contents; a referenced flag preserves only the file’s name.

Set daemon.disable_context_clear to true in your user/global config to prevent clearing the context; a project config cannot set the key. With this flag on, Polytoken rejects /clear and hides the plan handoff option to implement with a new context. You can still compact the context.

Rewinding

Polytoken keeps the rewind picker closed while a turn runs or while cancellation is still in flight. The picker also closes automatically if a new turn starts while the picker is open. Wait for the turn or cancellation to finish, then use Esc twice, /rewind, or a card rewind action.

Choose a point to return to in the rewind picker. The picker lists every rewind point in conversation order: prompts, facet switches, compaction summaries, context-clear boundaries, and ask_user_question tool calls. Rewinding an ask_user_question call removes the whole assistant message that carries the question, including any preamble, the question answer, and every later event.

Rewinding a question restores the same question and options. Before you confirm, the dialog explains that Polytoken will ask the question again. You can answer the restored question without typing a new prompt; the conversation shows a prompt card from Polytoken for that question.

If Polytoken cannot send the restored question, for example because a referenced file or skill no longer resolves, Polytoken rejects the rewind and leaves the conversation unchanged. Rewinding other cards does not ask a question again.

Two limits are worth knowing. The restored question rides the same queue as any prompt you sent while a turn was busy; if a sibling queued item references something that no longer resolves, Polytoken discards the whole queued batch after the rewind lands and tells you through a PendingTurnInputDiscarded event, so you would need to issue the question again. A queued question is also persisted in its resolved form (a written-out reference tag rather than the shorthand you typed), so the session record holds the resolved payload.

For a prompt, Polytoken drops the prompt and every event after it, and the prompt text returns to the input area so you can edit and resubmit. For a facet switch, Polytoken returns the conversation to the previous facet and model. A plan handoff rewinds as one boundary, so the plan returns to its editable draft state with the handoff changes removed. For a compaction or context-clear boundary, Polytoken removes that boundary card and every card after it. The rewind is destructive, and the dropped events do not come back.

Because the session is one continuous record, a rewind can move past a clear or a compaction. Rewind to an earlier point and the clear or compaction event disappears along with everything after it. The model returns to the complete conversation it had before the clear or compaction. Polytoken restores your todos to the state they were in at the point you rewound to.

You cannot rewind into the middle of a tool call. Polytoken returns you to a clean boundary: before the call or after its result.

Detaching and re-attaching

Polytoken runs as two parts: the daemon, which holds your session and does the work, and the TUI, the interface you read and type in. Because they are separate, closing the interface does not end the work.

Detach with /detach (or Ctrl+D) and the daemon keeps running with your session. Polytoken restores the terminal before it finishes bounded feedback submissions and prompt-history saves, and may print a brief one-line status while it finishes that background work. Run polytoken again in the same project and the TUI reconnects to the session. A single Ctrl+C cancels the active assistant turn, the same as Esc. Press Ctrl+C twice to quit. By default the second press opens a quit confirmation: when you confirm, the daemon stops and the session ends with it. Set tui.confirm-quit to false in your config to quit without the confirmation; the confirmation also offers a choice that stops asking again.

To start a daemon without opening the TUI, run polytoken new --no-attach. The command prints session_id=... port=... and returns to your shell. Reconnect later with polytoken continue <session-id>. Use polytoken attach <session-id> when you want Polytoken to fail unless the session’s daemon is already running. Run polytoken attach with no session ID to open the same interactive picker as polytoken continue with no argument: the same candidate list, search, and actions, including resuming a stopped session through its explicit Resume action. With a session ID named, attach stays strict: it fails unless that session’s daemon is already running, and it never starts one. You can also resume a stopped session without opening the interface.

When you attach while a turn is in flight, the status card shows what the model is waiting on, not just a running timer: Polytoken distinguishes waiting for the provider’s first response from an active response stream, with the time since the last provider activity. The daemon supplies this through its state snapshot, so the same information appears after a detach and re-attach in the middle of a turn. When the provider makes Polytoken wait before a retry, the existing retry countdown takes precedence.

When Polytoken manages the daemon before the interface starts or while it cleans up a failed startup, each bootstrap or cleanup request uses a ten-second budget. If Polytoken cannot read the credential during one of those flows, Polytoken prints one line naming the session, the daemon’s process ID, and the daemon’s port, then sends the request without credentials. If the request fails, kill the daemon process by that ID, or start polytoken again in the same project and quit from the interface. The TUI’s normal quit path uses its authenticated connection and does not use this bounded cleanup request or print this credential diagnostic.

If the TUI stops because terminal input reaches EOF, terminal input returns repeated errors, or the session event channel closes, Polytoken names the cause in the exit message and shows the command to reattach the session. A lost daemon attachment lease also shows the reattach command. When Polytoken writes a crash log for the lease loss, the message includes the log path.

The current TUI log remains available as an optional, bounded attachment when you send feedback. See Crash Reporting and Feedback.

Resuming after a crash

If the daemon stops unexpectedly while a turn is in progress (a crash, a kill, or a lost connection mid-response), resume the session with polytoken continue. Polytoken restores the conversation from the events on disk and brings the prompt back ready for your next message. If the session’s daemon is still running, continue reconnects to it instead of failing. When the selected session’s daemon log shows that the daemon exited only moments ago, Polytoken refuses the resume briefly and tells you to retry. Polytoken ignores missing, older, or uncertain log timestamps so a log problem does not block recovery. After you resume or rewind a long session, the scrollbar may adjust over a few frames.

Resuming from outside a session’s project directory starts the session in its original project directory. Polytoken sends the model a system reminder naming both directories. To work elsewhere, use pushd and approve the directory request; the approval also grants read access.

Resume restores the latest available facet from session history, rather than replacing that facet with your configured default. After a resume or rewind, Polytoken checks the facet recorded in history, the session’s initial facet, the configured default, and finally execute, in that order, and uses the first available candidate. Facets you choose at resume time or through later switches become part of the history. Rewind restores the latest available facet in the history that remains.

Polytoken restores the model recorded in history even if the corresponding facet is no longer available. A facet’s pinned model supplies a fallback only when history contains no model choice.

To resume without opening the interface, supply the session ID:

polytoken continue <session-id> --no-attach

When the daemon is stopped, Polytoken starts it and prints session_id=... port=..., then returns to your shell. When the daemon is already running, continue --no-attach verifies the session and prints the same connection details without starting a second daemon. The continue command requires a session ID for --no-attach and rejects the flag without one, because the session picker is interactive; omit --no-attach to open the picker. Use polytoken attach <session-id> when you want a failure unless the session is already running.

Session-scoped definition directories

Use new --skills-dir, new --facets-dir, or new --subagents-dir to add definition directories for a session. Polytoken saves their absolute paths in session.json and restores those directories when you continue the session. Combining a directory flag with --resume produces an error rather than replacing saved paths. If you rename or move a saved directory, Polytoken skips that missing path when the session resumes.

The directory flags on polytoken exec apply only to that invocation. A daemon also keeps directory flags only for its current run when no caller supplies a session ID, because Polytoken has no caller session record in which to save the paths.

Unattended launches

polytoken new, polytoken continue, and polytoken exec accept --accept-license-terms. Pass it to accept the current revision of the license agreement and privacy policy before launch, without the first-start acceptance dialog. The acceptance is recorded for the current revision only: when Polytoken ships a material change to those documents, the dialog appears again the next time you start an interactive session. exec runs never show the dialog; passing the flag to exec records the acceptance so later new and continue launches skip it. exec also performs no launch-time update check, so scripted runs never pause or print update notices.

Reaping local session daemons

Use polytoken reap to find live local daemons that have no attached TUI. The command lists each candidate as <session-id> <title> in session-ID order. Polytoken skips daemons marked as managed by an Outpost and skips any daemon whose attachment status cannot be verified.

The sweep asks for confirmation through /dev/tty and defaults to No. Type y or yes to continue. An empty line, another answer, end of input, or a missing controlling terminal leaves every daemon running. Use polytoken reap --force when you intentionally run the sweep without a terminal.

Use polytoken reap <session-id> to target one session. The explicit form does not check TUI attachment, so it can stop an attached session. Polytoken refuses an Outpost-managed session and directs you to stop that session through the Outpost.

Polytoken requests graceful shutdown first. During a sweep, Polytoken escalates only when the daemon confirms the attachment-safe shutdown request but does not exit within a bounded wait. If the daemon does not confirm the request, the sweep reports the failure and leaves that daemon running.

When you target a session explicitly, Polytoken escalates after a confirmed request fails to finish within the bounded wait. An unconfirmed request can also escalate if the target passes the stored process-start-token and process-group safety checks. Escalation sends SIGTERM and then SIGKILL to the daemon’s process group. Targets without a process-start token, or whose identity Polytoken cannot verify, remain running and produce a failure message.

Daemons launched by older Outpost versions may appear in the local sweep as ordinary local sessions. Outpost sessions stored in a custom Outpost data root do not appear in the default local sessions directory.

Reaping removes the live session listing but preserves log.jsonl and session.json, so you can resume the session.

Polytoken removes the daemon’s single-use credential file during graceful shutdown. When reap stops a daemon with signals, reap also removes the matching credential file. If Polytoken skips that cleanup or removal fails, the credential stays on disk as inert data.

Sessions created by this version that never receive a user turn are deleted when Polytoken shuts down gracefully. Polytoken removes the session directories and any public-history spool for that session. Polytoken keeps profiling dumps that an instrumented daemon collected and moves them to a profiling directory under the data directory before the deletion. Sessions with a saved goal or managed by Outpost remain, as do sessions created by older versions. A crash can leave a never-used session directory behind; remove it from the session picker if you do not need it.

Session picker

When you run polytoken continue without a session ID, Polytoken checks for an available update before opening the session picker. If you accept an update, the updated process skips the second check and opens the picker once. The update check also runs when Polytoken finds no resumable sessions. The picker lists sessions for your current project by default. Press Tab to toggle between your project and all sessions.

From the picker, press Enter to select a session, K to terminate a live session without an attached TUI, or N to create a session. Press D to delete a session after confirmation. Deletion removes the session history and its live record, so the session cannot be resumed. Press Ctrl+Shift+D to delete the selected session without confirmation.

Press Ctrl+R to search the visible session list. Type to filter by session title, recent message, session ID, or project name. Search works with either the current-project or all-sessions view. Press Tab during search to switch views, or Esc to clear the search and restore the prior selection. Press Enter during search to resume the highlighted filtered session; when the filtered session is live, Polytoken first asks you to confirm attaching, just as it does outside search. Press Up or Down during search to move within the filtered results.

polytoken sessions lists live sessions and removes stale registry entries. Pass polytoken sessions --all to list every session stored on disk, including historical sessions and legacy sessions that predate session metadata. When Polytoken cannot read the sessions directory, the --all listing reports no sessions; the live-only listing reports an error instead. The command accepts --format with human (the default), json, json-pretty, or yaml. With --all, the json format returns summary rows without pid or port fields, unlike live-only rows. You cannot resume a legacy session. polytoken sessions repair repairs index-order corruption in a stored session. See Troubleshooting for accepted session formats and directories you can pass with --sessions-dir.