nterminal 1.3.4 → 1.3.5

package/dist/shared/activityProbe.js

@@ -0,0 +1,24 @@
+// Transport controls are deliberately not activity journal or monitor events.
+export const activityProbeCapability = 'nonce-v1';
+export const activityProbeMaxBytes = 512;
+export const activityProbeIntervalMs = 30_000;
+export const activityProbeDeadlineMs = 10_000;
+export function decodeActivityProbe(text) {
+    if (text.length > activityProbeMaxBytes || new TextEncoder().encode(text).byteLength > activityProbeMaxBytes)
+        return null;
+    try {
+        const value = JSON.parse(text);
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return null;
+        const probe = value;
+        if (Object.keys(probe).length !== 3 || !Object.hasOwn(probe, 'type') || !Object.hasOwn(probe, 'version')
+            || !Object.hasOwn(probe, 'nonce') || !['activity.ping', 'activity.pong'].includes(probe.type)
+            || probe.version !== 1 || typeof probe.nonce !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(probe.nonce))
+            return null;
+        return probe;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=activityProbe.js.map

package/dist/shared/activityProbe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activityProbe.js","sourceRoot":"","sources":["../../src/shared/activityProbe.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,uBAAuB,GAAG,UAAU,CAAC;AAClD,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAC9C,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAQ9C,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,IAAI,CAAC,MAAM,GAAG,qBAAqB,IAAI,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,GAAG,qBAAqB;QAAE,OAAO,IAAI,CAAC;IAC1H,IAAI,CAAC;QACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC7E,MAAM,KAAK,GAAG,KAAsB,CAAC;QACrC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC;eACnG,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;eAC1F,KAAK,CAAC,OAAO,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACvH,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;AAC1B,CAAC"}

package/dist/shared/protocol.d.ts

@@ -225,6 +225,31 @@ export interface CodeServerStopRequest {
     instanceId?: string;
 }
 export type AccountProvider = 'codex' | 'claude';
+export interface AccountRefreshStatus {
+    state: 'success' | 'retrying' | 'reauth_required' | 'deferred';
+    lastAttemptAt: string | null;
+    lastSuccessAt: string | null;
+    nextRetryAt: string | null;
+    code: string | null;
+    httpStatus: number | null;
+}
+export interface AccountUsage {
+    status: 'available' | 'unavailable' | 'reauth_required' | 'unsupported';
+    checkedAt: string;
+    code: string | null;
+    windows: Array<{
+        kind: 'weekly' | 'session';
+        usedPercent: number;
+        resetsAt: string | null;
+    }>;
+}
+export interface AccountUsageResponse {
+    provider: AccountProvider;
+    profiles: Array<{
+        profileId: string;
+        usage: AccountUsage;
+    }>;
+}
 export interface AccountProfile {
     id: string;
     provider: AccountProvider;
@@ -233,6 +258,7 @@ export interface AccountProfile {
     updatedAt: string;
     expiresAt: string | null;
     refreshTokenExpiresAt: string | null;
+    refresh?: AccountRefreshStatus;
 }
 export interface AccountRunningPane {
     terminalId: TerminalId;
@@ -312,8 +338,27 @@ export interface TerminalTranscriptHistoryResponse {
     cursor: string | null;
     hasMore: boolean;
     output: string[];
+    page?: {
+        identity: string;
+        snapshot: string;
+        /** Settled readable end, excluding any incomplete trailing JSON. */
+        snapshotSize: number;
+        snapshotMtime: number;
+        startOffset: number;
+        endOffset: number;
+        stableBefore: number;
+        /** Display-capped blocks in ascending source order, without archive trailer. */
+        records: Array<{
+            id: string;
+            startOffset: number;
+            endOffset: number;
+            block: string;
+        }>;
+        unchanged?: boolean;
+    };
 }
 export interface TerminalTranscriptHistoryRequest {
+    ifSnapshot?: string;
     cursor?: string;
     limit?: number;
     maxLines?: number;

package/dist/shared/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/shared/protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/shared/protocol.ts"],"names":[],"mappings":"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"}

package/dist/shared/types.d.ts

@@ -16,7 +16,15 @@ export interface TerminalSummary {
     agentStatus?: {
         provider: 'codex' | 'claude';
         sessionId?: string;
-        state: 'working' | 'done' | 'stopped' | 'idle' | 'unknown';
+        state: 'working' | 'finishing' | 'waiting' | 'done' | 'stopped' | 'idle' | 'unknown';
+        source?: 'hook' | 'transcript';
+        revision?: number;
+        epoch?: string;
+        completion?: {
+            id: string;
+            outcome: TerminalCompletionOutcome;
+            occurredAt: string;
+        };
     };
     agentCache?: {
         source: {

package/docs/features.md

@@ -8,6 +8,7 @@
 - Soft close detaches terminals into restorable pills.
 - Tab rename, drag reorder, and drag-to-split controls.
 - Activity dots and completion badges show whether a tab is running, idle, exited, or finished in the background.
+- Working indicators are green and unread completion indicators are blue across themes, including mobile and favorites.
 - Detached terminal destroy uses a themed confirmation modal.
 - Tab titles sync with tmux window names when tmux persistence is active.
 
@@ -31,6 +32,15 @@
 - Trusted networks can be added by exact IP or CIDR to skip the re-auth prompt.
 - Security settings can revoke trusted devices, remove trusted networks, and disable TOTP.
 
+## Provider Accounts
+
+- Each server keeps its own encrypted Codex and Claude credential vault. Active credentials remain in the CLI's native file, not a second vault copy.
+- Account dialogs show access-token expiry, weekly usage remaining, reset time, and the last usage check. Quota checks are read-only, cached briefly, and never swap the active credential file.
+- Saved accounts renew independently, including while another account is running or a new login is unfinished. Refresh outcomes include the last attempt, success, retry time, and a redacted provider error code.
+- NTerminal defers direct refresh of an active credential while a native CLI owns it. An idle conversation does not mean authentication activity has stopped; native-owner refresh delegation is not implemented yet.
+- Expired access tokens and revoked refresh tokens are different states. A provider-revoked refresh token requires a new login, not repeated automatic renewal attempts.
+- Optional [provider lifecycle hooks](provider-hooks.md) can be installed from each server's account dialog or `nterminal hooks`. They provide verified session/activity signals without replacing native CLI authentication.
+
 ## Terminal Appearance And Settings
 
 - Settings is organized into Terminal, Shortcuts, Notifications, Security, and Servers sections.

package/docs/provider-hooks.md

@@ -0,0 +1,287 @@
+# Provider Lifecycle Hooks
+
+Lifecycle hooks are optional, per runtime user and per server. They improve
+Codex/Claude session identification and activity notifications without forwarding
+terminal output or changing the conversation. Existing transcript/process
+detection remains available when hooks are absent or a binding is ambiguous.
+
+## Enable
+
+Open the server's Codex or Claude account dialog, then choose **Install hooks**
+and confirm. Main and secondary servers use the same control, including outbound
+secondaries. Preview cannot change provider configuration.
+
+The equivalent commands, run as the NTerminal runtime user, are:
+
+```sh
+nterminal hooks status --provider codex
+nterminal hooks install --provider codex
+nterminal hooks install --provider claude
+nterminal hooks remove --provider codex
+nterminal hooks remove --provider claude
+```
+
+Codex requires native approval in `/hooks`. NTerminal does not write trust hashes
+or bypass provider policy. An unchanged hook definition retains its native trust;
+an edited definition may require review again. Reinstalling or upgrading updates
+NTerminal's hook groups in place, so their position (part of Codex's trust key)
+and the position of your own hooks do not change. A new command (for example
+after Node.js moved) still needs one review.
+
+Configuration defaults are `~/.codex/hooks.json` and `~/.claude/settings.json`.
+Runtime environment variables `CODEX_HOME` and `CLAUDE_CONFIG_DIR` override the
+respective homes. Provider homes and settings files may be symlinks you own (for
+example a dotfiles checkout); NTerminal edits the resolved file and keeps the
+link. A symlink into a directory owned by another user or writable by others is
+refused, and the error names that path. The state directory (`~/.nterminal`) may
+also be a symlink. Provider policy can disable hooks even when the entries exist.
+A configured hook is not necessarily active; the account dialog separately
+reports whether verified events have been observed. The CLI reads the same
+runtime `.env` as the launcher, including `export` assignments. Inherited
+environment values take precedence; relative paths resolve from the application
+directory, not the caller's working directory.
+
+NTerminal never restarts a CLI to activate hooks. A CLI that does not reload its
+configuration must be reopened by the operator. Use current provider versions
+that support the installed events (Codex 0.158 and Claude Code 2.1.284 were
+checked).
+
+### What Gets Installed
+
+One hook group per event, each running the same command:
+
+```sh
+[ -x '<node>' ] && [ -f '<state>/hooks/forward.cjs' ] && exec '<node>' '<state>/hooks/forward.cjs' '--provider' '<provider>' '--endpoint' '<state>/hooks/endpoint.json' || exit 0
+```
+
+`<state>` is the resolved (realpath) state directory. The command uses only
+POSIX `[`, `exec`, and `exit`, which `sh`, `bash`, `zsh`, and `fish` accept
+(Codex runs hooks with the user's shell, Claude with bash or `$SHELL`). If
+Node.js moved (for example an `nvm` upgrade) or the state directory was deleted,
+the hook exits 0 without output instead of showing a hook error. Reinstall to
+point the hooks at the current Node.js.
+
+- Codex: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,
+  `PermissionRequest`, `Stop`, `Interrupt`, `SessionEnd`.
+- Claude: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,
+  `PostToolUseFailure`, `PermissionRequest`, `Notification`, `Stop`,
+  `StopFailure`, `SessionEnd`.
+
+NTerminal never uses a hook's response, so tool, permission, notification, and
+interrupt hooks are `async: true`: the CLI does not wait for them. Only the turn
+and session boundaries (`SessionStart`, `UserPromptSubmit`, `Stop`,
+`StopFailure`, `SessionEnd`) stay synchronous, bounded by a 1-second timeout.
+Codex does not allow asynchronous `SessionEnd`, and a CLI may exit right after a
+boundary event. Events carry the helper's start time, so an asynchronous tool
+event that finishes late is still ordered before a later `Stop`. `Subagent*`
+events are not registered because child lifecycle events do not change a pane's
+status.
+
+Codex `notify` is not used. `hooks.json` provides `Stop`, and the session's
+transcript `task_complete` record confirms the turn within the regular status
+poll. `notify` is a single slot that may belong to you, and Codex passes its JSON
+as one command-line argument, which fails for payloads over 128 KiB. An existing
+`notify` (root or `[profiles.*]`) is left untouched and reported as
+`notify_foreign`. Earlier NTerminal versions installed a `# BEGIN/END NTerminal
+notify` block in `config.toml`; reinstalling or removing deletes that block (it
+is recognised even after Codex rewrote other parts of the file) and nothing else.
+
+## Remove And Uninstall
+
+`nterminal hooks remove --provider codex|claude` deletes only the hook groups
+recorded in NTerminal's ownership manifest. Your own hooks and settings stay as
+they were, including key order, indentation, and line endings. NTerminal also
+deletes the Codex trust records (`[hooks.state."<hooks.json>:<event>:<group>:0"]`)
+of the groups it removed, and nothing else in `config.toml`. A `hooks.json` or
+`settings.json` that NTerminal created is deleted when it becomes empty. When
+NTerminal's group is removed, your hooks listed after it in the same event move
+up one position; Codex may then ask you to review them again.
+
+`nterminal clean --force` and `nterminal uninstall --force` first remove
+NTerminal's hooks from both providers. This is best effort: a failure prints a
+warning and the command continues. Run `nterminal hooks status --provider
+<provider>` afterwards if a warning appears. Uninstall NTerminal's hooks before
+`npm uninstall -g nterminal`, because the hooks command is part of the package.
+
+## Troubleshooting
+
+`nterminal hooks status --provider <provider>` prints `reason` and `warnings`:
+
+- `node_unavailable`: the recorded Node.js no longer exists. The hooks exit 0
+  silently; reinstall to use the current Node.js.
+- `helper_missing`: `<state>/hooks/forward.cjs` is gone. Reinstall.
+- `unsafe_path` with `unsafePath`: that path is a symlink to a location NTerminal
+  will not edit, or a symlink inside the state directory.
+- `hooks_disabled`: hooks are off in `config.toml` (`[features] hooks = false`,
+  also in the active `profile`), in `/etc/codex/requirements.toml` or
+  `/etc/codex/managed_config.toml` (`allow_managed_hooks_only`, `features`), in
+  `settings.json` (`disableAllHooks`, `allowManagedHooksOnly`), or in Claude's
+  managed `/etc/claude-code/managed-settings.json` (and
+  `managed-settings.d/*.json`).
+- `ownership_conflict`: an NTerminal hook group or legacy notify command was
+  edited. NTerminal does not adopt edited entries; restore or delete them by
+  hand.
+- Warnings: `legacy_definitions` (installed by an earlier version; reinstall to
+  get asynchronous tool hooks and the guarded command), `notify_foreign`,
+  `notify_profile_override` (a profile's `notify` overrides NTerminal's legacy
+  notify), `profile_hooks_disabled` (a non-default Codex profile disables hooks),
+  and `managed_policy_unreadable`.
+
+Not checked: Claude project settings (`.claude/settings.json` and
+`.claude/settings.local.json` in a repository) can disable hooks for that
+project, and Codex hook trust is only visible in `/hooks`.
+
+## State And Notifications
+
+- Idle retains the theme's existing idle color.
+- Working is green; completion awaiting confirmation also stays active.
+- Unread completion is blue in tabs, workspaces, and favorites. Displaying the
+  completed pane clears its unread mark. On mobile, other split panes remain
+  unread until displayed; focusing an editor does not mark a hidden terminal
+  read. A background server's last selected tab is not considered visible.
+- Permission/input waits are not successful completion.
+- A Codex `Stop` is only a completion candidate. The rollout's matching
+  `task_complete` marker confirms the turn on the next status poll (about 2 s).
+  Installs from earlier NTerminal versions may still send the legacy `notify`
+  `agent-turn-complete`, which is honored as confirmation too; current installs
+  no longer add a `notify` command.
+- A Claude `Stop` is also provisional because another hook can continue the
+  turn. A matching post-turn `turn_duration` record confirms it when no pending
+  background agents/workflows remain. The record shape was checked against
+  Claude Code 2.1.283. A subsequent native idle notification can also confirm a
+  pending Stop. Missing/unknown evidence is not turned into success by a timer.
+- A lost prompt hook can recover from a later Stop and fresh post-turn evidence.
+  A competing still-active turn is not replaced by anonymous evidence; it stays
+  pending until its identity can be verified. A failure recorded for that
+  candidate remains a stopped outcome when the identity is later confirmed.
+- Errors and interruption produce a stopped outcome, not successful completion.
+- Child/background hooks do not finish the parent session. A completed foreground
+  turn does not imply that a long-running goal or every detached task is finished.
+
+Completion IDs are shared by live status, unread badges, animation notifications,
+and push routing. The activity stream works independently of an open pane socket.
+Reconnects replay a bounded recent metadata journal. A journal gap or server
+restart sends a non-notifying snapshot instead of replaying historical alarms.
+Missing entries in an activity snapshot never imply a terminal exit: remote
+snapshots can be retained during an outage. Explicit terminal lifecycle events
+and terminal discovery remain responsible for that state.
+Initial REST loading preserves newer live state, local layout edits, and explicit
+terminal deletion. It does not generate historical completion notifications.
+
+The browser checks the separate activity connection while visible and on resume.
+An unresponsive connection is replaced without reconnecting terminal output,
+replaying input, resizing panes, or changing keyboard focus. These checks cannot
+run while the browser suspends JavaScript; server-side push remains independent.
+
+## Ownership And Resource Limits
+
+The installed helper is kept under the persistent NTerminal state directory,
+outside the npm package. Updates refresh only a verified, previously opted-in
+helper; provider configuration and approval definitions are not silently changed.
+Removal deletes only entries whose ownership still matches the installation
+manifest. Concurrent edits and unknown existing commands fail closed.
+Interrupted installations retain an ownership journal. Installer locks are
+reclaimed only after verifying a dead owner; PID reuse, boot identity, and foreign
+hosts are checked. Without a stable machine ID, recovery is limited to the same
+boot. Unverifiable old locks are left intact, not removed based on age.
+
+Helper upgrades and rollback use one durable ownership journal shared by both
+providers. A failed configuration rollback retains any helper that a remaining
+hook may reference. User-modified helper files are never silently adopted.
+
+The receiver also recovers publication locks whose recorded owner is provably
+dead. An old, empty `hooks/.endpoint-lock` directory has no ownership record and
+cannot be recovered automatically. If that specific legacy marker blocks hook
+activation, stop every runtime sharing the state directory, verify the marker
+is an empty directory, and remove only that empty directory with `rmdir` before
+starting again. Do not delete ownership records or a lock held by a running
+runtime. Ordinary transcript/process detection remains available when hook
+activation is unavailable.
+
+Events are sent through a private Unix socket, authenticated with a runtime
+capability. The receiver checks the live helper/provider process ancestry and
+process start identities. A session is assigned to a pane using verified process
+ownership or an exact native binding, never just the working directory. Shared
+daemon ambiguity falls back to native discovery/manual history selection rather
+than assigning another pane's session. Claude hooks run as children of the
+pane's Claude process, so their binding is exact. Codex needs the extra rules in
+[Codex Shared Background Server](#codex-shared-background-server).
+A transient discovery gap does not retire an existing hook session. Old resume
+arguments cannot replace it, and process ownership is rechecked after asynchronous
+validation before publishing status or completion.
+Nested provider processes do not take over the parent pane's binding, including
+children sharing its foreground process group. Normal Codex npm launchers and
+provider commands that replace the pane shell remain supported.
+
+Transcript identity checks use 64 KiB chunks with a 512 KiB header limit, not a
+whole-history read. A bounded cache retains identity proofs rather than message
+text; changed files require prefix revalidation. Oversized headers need an exact
+live writable-file association. Incomplete, conflicting, or unprovable fork
+metadata stays unconfirmed instead of selecting a different conversation.
+
+Only lifecycle metadata is forwarded. Prompts, tool arguments, assistant bodies,
+credentials, and tokens are not included in event payloads or diagnostic logs.
+Queues, messages, sockets, journal size, and helper duration are bounded. Hook
+failures return neutral output so NTerminal cannot block or steer the native CLI.
+Under load, per-tool events (`PreToolUse`/`PostToolUse`, synchronous or
+asynchronous) are coalesced per session and dropped first. Start, stop, and
+completion events use a reserved part of the queue and evict waiting tool
+events, so a `Stop` is not refused while tool events are queued. Tool events for
+a session no pane is bound to never trigger a Codex daemon lookup. A failed
+lookup for a session is reused for 5 seconds unless a `SessionStart` or
+`UserPromptSubmit` for it arrives.
+JSONL remains the source for history, token usage, and completion reconciliation;
+hook-backed terminals use a slower usage refresh and a small cached tail check
+while confirming completion.
+
+## Codex Shared Background Server
+
+Codex 0.158 hands every interactive session to one shared background server
+(`codex app-server --managed-daemon`). Its hooks run as children of that
+server, not of the pane, so process ancestry cannot identify the pane. NTerminal
+instead follows each pane's Codex connection to the server and matches the
+server's open sessions by working directory. That match alone is not enough to
+bind a session to a pane, because another Codex client, such as another
+terminal or VS Code, can have a session open in the same directory.
+
+A new Codex binding therefore also needs evidence tied to that pane's Codex
+process:
+
+- the first binding after Codex starts: `codex resume <id>` names the session,
+  or the session was created while that Codex process was starting (Codex
+  session IDs record their creation time);
+- a later switch in the same process (`/new`, `/resume`): the session's
+  `SessionStart` arrived after the pane's last bound event.
+
+A session already bound to one pane is never moved to another pane. If several
+panes qualify, none is bound. A binding created by a completion event does not
+notify for that turn, because NTerminal did not see the turn start.
+
+Limits:
+
+- **One Codex per directory.** Hook binding needs one Codex session per working
+  directory on the shared server. With two sessions in the same directory, both
+  panes stay unbound. The account dialog lists these panes as not linked to hook
+  events, and they keep transcript-based status. To run several Codex sessions
+  in one directory with hooks, start them with `codex --no-daemon` (also
+  `codex resume --no-daemon <id>`). That runs the session inside the pane's own
+  Codex process, where binding is exact.
+- **About 60 seconds after `/new` or `/resume`.** The server keeps the previous
+  session loaded for about a minute. Until it unloads, the pane has two
+  sessions in the same directory and stays on its previous binding. Hook status
+  resumes with the next prompt or stop event after that. Codex also creates a
+  new session's file only when the session is first saved, so a new session has
+  nothing to match until its first prompt.
+- **After an NTerminal restart.** A Codex pane that switched sessions with
+  `/new` or `/resume` before the restart cannot be tied to its process again
+  until its next `/new` or `/resume`. It keeps transcript-based status until
+  then.
+- **Clients outside NTerminal.** NTerminal can only rule out other NTerminal
+  panes. If a Codex client outside NTerminal starts a session in the same
+  directory within 30 seconds of a new pane starting, or while a pane is
+  switching sessions and has nothing saved yet, NTerminal cannot tell the two
+  apart. One Codex per directory, or `--no-daemon`, avoids this.
+
+The local receiver currently requires Linux procfs and Unix sockets. Unsupported
+environments retain transcript/process detection. This integration does not
+change credential-switch or credential-refresh safety rules.

package/docs/terminal-history.md

@@ -45,10 +45,20 @@ JSONL records are loaded by cursor and rendered into readable user, assistant, a
 
 Loading older pages keeps previously loaded pages in the dialog, so ordinary scrolling can return to recent conversations without fetching them again.
 
+Closing History retains its conversation pages and reading position in a browser-memory cache. Reopening the same server/terminal/session restores them immediately while checking the latest source snapshot. Unchanged sources need no conversation payload. If output was appended, bounded backward pages bridge the previous stable prefix before replacing the mutable tail; disconnected ranges are never joined as if contiguous. Source replacement or truncation resets the snapshot. Text selection defers applying refreshed content. Search-result excerpts are kept separate from the browsing snapshot.
+
+The browser cache is cleared on logout or authentication loss, and late requests cannot refill it. Its 64 MiB approximate text budget and 30-minute idle expiry reclaim closed readers on cache activity, never truncate an active reader. Nothing is written to localStorage or IndexedDB. A full page reload therefore still fetches History from the server's disk cache.
+
 ### Derived Conversation Cache
 
 History and search share private derived files below the state directory's `transcript-cache` directory. Recent records are returned first. After a user opens or searches a session, a background worker fills the remaining archive, one approximately 1 MiB source window at a time with a pause between windows. Foreground requests take priority over subsequent background work. Completed archives are checked for changes every 30 seconds; appended JSONL output updates the tail while keeping valid older ranges. Source replacement, truncation, or a parser version change invalidates affected cache data. Previously visited sources are remembered in private cache metadata so prebuilding resumes after a server restart.
 
+Source extraction windows are independent of storage size. Background compaction merges adjacent stable segments toward 1 MiB of derived data, retaining original offsets and empty coverage. Mutable tail segments are excluded. Merges require balanced input sizes so small appends cannot repeatedly rewrite a large segment. Each pass handles at most 16 files and yields at file boundaries when foreground work arrives; deferred merges remain pending rather than being marked complete. New files are published through an atomic manifest replacement before old files are removed; existing cache data is reused without reparsing the JSONL. Read requests reuse parsed segments, avoid permission writes when modes are already private, and do not rewrite unchanged manifests. Access timestamps are persisted at most once per minute. Fragmented caches limit a page to 32 windows and retain a continuation cursor rather than performing unbounded small-file I/O.
+
+Files retired by invalidation or compaction are reclaimed by the bounded background maintenance scan, not by the request that replaces the manifest. They remain included in disk usage until cleanup accounts for their deletion. A parser upgrade therefore does not make the first History request wait for thousands of old cache files to be deleted.
+
+Parser v3 bounds Codex duplicate evidence to the same 64 KiB context used for stable-tail invalidation. Forward distances use the ends of the JSON payloads, excluding trailing whitespace and line delimiters, so a bounded read or a later newline cannot change the result. Duplicate evidence outside that range remains visible instead of changing old content depending on page size or future appends. Existing v2 Codex cache data is regenerated once for this semantic correction; v2 Claude records are reused without re-extraction.
+
 The cache survives an NTerminal restart and uses private directory/file permissions. There is no session-count or per-session size quota. Maintenance expires caches seven days after the last user History or search request, and evicts least recently used caches at an approximately 5 GiB total safety limit. Background activity does not renew retention. New writes pause when less than 512 MiB of disk space is available; cached reads and original JSONL reads remain available. Maintenance normally runs every five minutes, and also when the total limit is reached. It contains conversation text and source paths, so treat the state directory as sensitive. Source JSONL files remain authoritative and are never changed. Missing or invalid cache files are rebuilt on demand.
 
 Cache storage failures fall back to reading the source JSONL. Search continuation does not depend on the cache remaining available. Search text is extracted before display truncation; a result deep inside a long message opens an excerpt around the match.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nterminal",
-  "version": "1.3.4",
+  "version": "1.3.5",
   "license": "GPL-3.0-only",
   "type": "module",
   "packageManager": "npm@10.9.7",
@@ -22,6 +22,7 @@
     "docs/",
     "public/",
     "scripts/nterminalctl",
+    "scripts/nterminal-hook.cjs",
     "scripts/nterminal-tmux.conf"
   ],
   "scripts": {