@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.33

package/docs/session-bridge.md

@@ -0,0 +1,80 @@
+# One session, many sources
+
+Supported since DSCODE 0.2.0. A running dscode Host holds the single Agent/session; other terminals and scripts attach to it over a Unix socket. A client never starts another Harness, resumes a session, or opens a session write handle.
+
+Built-in agent communication tools, `defer` notes, a persisted mailbox and anti-loop budgets are covered in [Agent-to-agent tasks](session-communication.md). The read/watch cursors below still belong to the native session log; the mailbox uses its own cursor.
+
+## Usage
+
+Start or resume the TUI first. Inside the TUI, `/session` shows the full session ID and the socket address. From another terminal:
+
+```sh
+dscode sessions
+dscode send SESSION_ID --source script "check why the tests fail first"
+dscode send SESSION_ID --source ci --title "fix the build failure" "look at this build log"
+dscode send SESSION_ID --source editor --steer "also: change only the parser module"
+dscode read SESSION_ID
+dscode watch SESSION_ID
+```
+
+`send` delivers into the next turn by default; `--steer` delivers into the next step without interrupting the running model request or tool. A source name may contain letters (Latin or CJK), digits and `_.:@/-`, up to 64 characters. A message body is at most 64000 bytes. Put a body that starts with `-` after `--`.
+
+`--title` explicitly sets the current session's title, persisted through the native title service and announced to the TUI; later automatic naming will not overwrite it. A title is stripped of control characters, whitespace-collapsed and truncated to the native limit (80 UTF-8 bytes by default). An empty title is refused; omitting the option changes nothing and calls no model. `sessions`, `read` and the send response all carry the current `title`, which is `null` while unnamed.
+
+In the TUI an external message shows its full body with an `[External source: ...]` label and also enters the native pending-message queue. The log still marks it as a plugin relay: it never impersonates local user input or a permission approval. The source label is for recognition, not authentication; under one OS user, any process able to reach the socket has session access.
+
+`sessions` lists only running root sessions in the current state directory. Either the full ID or a unique prefix works; when several Hosts carry the same ID, the send is refused. An exited session must be resumed in the TUI first. Child agents expose no direct write entry point.
+
+`sessions` and `read` also return the descriptive `card` (project, workspace, recent user-request topics) and the separate `cardState` update status. The TUI `/session` shows them too. A card carries no conclusions; see [Session cards](session-cards.md).
+
+The source entry point looks in the project `.runtime` by default; the npm launcher uses `$DSCODE_HOME` or `~/.local/share/dscode-hub`. Every client command accepts `--home /absolute/state/directory` to reach another installation or a temporary profile.
+
+## Writing and retrying
+
+A message enters the inbox through the native `Agent.followup()` / `Agent.steer()`, and the model and its tools are still scheduled by the single native driver. There is no asynchronous gap between validation, de-duplication and inbox submission; a slow model request holds no write lock. TUI input and external input share one inbox.
+
+```sh
+dscode send SESSION_ID --source ci --request-id build-123 "the build failed, please look"
+```
+
+An `accepted: true` response means the message passed the native session's persistence flush barrier; it does not mean the task is done. The client prints the request ID to stderr before submitting, so a lost response is retried with the same ID, source, mode and body. A repeated request returns `duplicate: true` and is not delivered again; the same ID with different content is an error.
+
+With `--title`, the title is part of the request identity and must stay the same on a retry. A repeated request will not pull a later title change back to the old value.
+
+De-duplication evidence comes from persisted inbox events, so it survives a normal exit and a resume. Cancelling or deleting a queued message does not erase the fact that it was received; use a new ID to genuinely send it again.
+
+This is message-reception de-duplication, not an exactly-once guarantee for tool side effects. When sources send at the same time, the order is whatever order the Host actually completes inbox submission in; the wall-clock send order of different processes is not preserved.
+
+## Reading without contending for the write lock
+
+`read` returns JSON: an immutable event page, the current status, the inbox, a page-tail `cursor` and the log tail `head` at snapshot time. Keep paging while `cursor < head`:
+
+```sh
+dscode read SESSION_ID --after 123 --limit 100
+```
+
+`--after` is the last event sequence already received and defaults to `-1`; `--limit` defaults to 100 and caps at 500. Take the next page from the previous `cursor`; do not use `head` to skip events you have not read.
+
+`watch` emits NDJSON: `ready` first, then the history after `after`, then `caught-up`, then every new event as it happens. Subscribing and taking the snapshot happen in the same synchronous boundary, and overlapping events are de-duplicated by sequence. Leaving the session emits `closed`; an unexpected disconnect is an error, and the client can reconnect manually with the last `event.seq` it received:
+
+```sh
+dscode watch SESSION_ID --after 123
+```
+
+What is subscribed here is the persisted model's event stream: messages, inbox, tool and status events. It does not carry uncommitted per-token assistant chunks. An event can be observed live before it reaches the disk persistence barrier; a cursor that jumps past the recovery log across a crash is reported as an explicit error and needs a fresh baseline read. Reading acquires no session write lock, but it still pays serialisation and disk-flush cost, so no strict lock-free algorithm is claimed.
+
+A slow subscriber that exceeds the 8 MiB send buffer is disconnected rather than blocking the agent's writes; the client should catch up from the last sequence it received. A single oversized response or event also disconnects, so this interface is not a way to move large files: reference files by path instead.
+
+## Local protocol and implementation
+
+A Host creates its own socket under `/tmp/dscode-UID-HASH/`, isolated by a hash of the state directory. The directory is mode 0700, the socket mode 0600, and nothing listens on TCP. The socket path stays short enough for macOS. Each connection accepts one newline-terminated JSON request:
+
+```json
+{"method":"send","sessionId":"...","source":"editor","requestId":"edit-123","mode":"queue","text":"check the change"}
+```
+
+The methods are `list`, `send`, `read` and `watch`. A normal response is `{"result":...}`, a failure `{"error":"..."}`. `watch` emits the event frames above. A Host releases its socket on shutdown; a stale socket left by a crash is ignored by discovering clients when it refuses the connection.
+
+The implementation reuses the native Agent inbox, session snapshots, event notifications and persistence flush. It adds no second task queue and mounts neither the Web Session Controller's media upload nor its web gateway and other dependencies. A future ACP layer can adapt the same entry point.
+
+Verification: `node --test tests/session-bridge.test.mjs`; `node scripts/verify-session-bridge.mjs` uses a real Harness and a local deterministic model to check two client processes, queue/steer while busy, reads, persisted de-duplication and recovery. The tests need permission to listen on a local Unix socket.

package/docs/session-cards.md

@@ -0,0 +1,53 @@
+# Descriptive session cards
+
+Supported since DSCODE 0.2.0, session cards appear in `dscode sessions`, `dscode read SESSION_ID` and the TUI `/session`. A card has just three fields:
+
+```json
+{
+  "project": { "name": "dscode", "id": "github.com/qiz029/dscode" },
+  "workspace": "/work/dscode-feature",
+  "topics": [
+    { "text": "add project, workspace and recent-request topics to a session", "sourceSeqs": [125, 129] },
+    { "text": "cancel the whale animation plan", "sourceSeqs": [98, 112] }
+  ]
+}
+```
+
+The project comes from local Git information: the credential-free origin repository identity when one is recognisable, otherwise the path of the Git common directory. Worktrees of one repository therefore share a project, while the workspace keeps the session's original cwd: a session binds to the folder it is created in, and resuming it elsewhere still runs it in that folder. A non-Git directory has a `null` project, so the model is never asked to guess one. Reading Git information does not touch the network.
+
+A topic describes what the user asked for: at most 5 by default, ordered by most recent mention, each citing the event sequence numbers of the original user messages. The extraction prompt requires consecutive follow-ups to be merged, an explicit cancellation or replacement to be described, and a bare acknowledgement to be ignored; it forbids conclusions, results, completion states and inferred agent plans. Structural validation rejects extra fields and message references that do not exist, while the meaning of the text still depends on how well the model follows the prompt.
+
+## Background updates
+
+Project and workspace are available immediately (Git detection completes asynchronously). Topic extraction starts after 3 non-empty user text inputs by default; new input waits 1.5 seconds to be merged, and two extractions for one session are at least 60 seconds apart. Only user text in raw `user/message` events is scanned: assistant output, tool results and external plugin relays are not read. That is why `dscode send` never becomes "a topic the user asked for".
+
+Each extraction reads at most the latest 32 user texts, 16000 characters in total and 4000 characters per message; earlier topics may no longer be retained. This is an index of recent requests, not a summary of the whole session. Common credential patterns are redacted, but no guarantee is made that every sensitive string is recognised.
+
+The extraction uses the session's provider/model, at a fixed, independent `low` effort that does not inherit the main agent's ultra; a provider/model can be configured separately. Each Host runs at most one extraction at a time, with a 30-second timeout; it creates no second Agent, uses no tools and writes nothing into the session context. New user input invalidates an older version still being generated; a failure keeps the previous version and retries with backoff. This background call costs extra model usage: its call count and token usage are recorded in the card cache and are not currently part of the TUI's session cost figures.
+
+`cardState` sits outside `card` and provides `status`, `updatedAt`, `coveredUserSeq` and `latestUserSeq`. The status can be `empty`, `insufficient`, `pending`, `updating`, `ready`, `error` or `disabled`, which lets a consumer recognise a stale card. A background card update is not a persisted session event, so `watch` does not push it; call `sessions` or `read` again when you need it.
+
+The derived cache is written atomically under `session-cards/` in the state directory and holds only cards and generation metadata, never a second copy of the user's text. A resumed session can reuse an unchanged card, and a corrupt cache can be rebuilt. `sessions` still lists running root sessions only; no offline session directory and no automatic cross-session sending were added.
+
+## Configuration
+
+Configure the existing plugin in the Harness profile overlay:
+
+```yaml
+- id: dscode-session-cards
+  config:
+    enabled: true
+    topicCount: 5
+    minMessages: 3
+    debounceMs: 1500
+    cooldownMs: 60000
+    timeoutMs: 30000
+    maxMessages: 32
+    maxInputChars: 16000
+    # provider: your-provider
+    # model: your-model
+```
+
+`enabled: false` stops model extraction while local project, workspace and cached topics remain readable. provider/model must be configured as a pair. `minMessages` cannot exceed `maxMessages`.
+
+Verification: `node --test tests/session-cards.test.mjs` and `node scripts/verify-session-cards.mjs`. The latter uses a real Harness, native sessions, a Unix socket and a deterministic local model to cover the independent effort, input isolation, reads and recovery; it does not mean topic text quality from a real remote model has been accepted.

package/docs/session-communication.md

@@ -0,0 +1,186 @@
+# Agent-to-agent tasks
+
+Supported since DSCODE 0.2.0. An agent can read session cards and use built-in tools to send messages to a loaded dscode root session in the same state directory. This is how one running session reaches another; to start an unattended run in a fresh or trigger-owned persistent session from an event — a schedule, a file change, a poll, a CI job — see [Triggers](triggers.md). The receiver keeps using the single native runtime; the TUI, the CLI and the agent tools share the session bridge. An offline session is never opened automatically.
+
+## Delivery modes
+
+| mode | Target idle | Target running |
+| --- | --- | --- |
+| queue | wakes a new turn | queued behind the current turn |
+| steer | wakes a new turn | joins the current execution at the next safe step, without cancelling tools |
+| defer | leaves a note, does not wake | claimed when the next turn starts, never in the current turn |
+
+defer is a one-shot note. Reading the mailbox or resuming the session does not wake it on its own. Notes beyond the current turn's batch size keep waiting for a naturally occurring turn; they never start extra turns.
+
+Message meaning is independent of delivery: `request` asks for work, `notify` passes information without requiring a reply, and `reply` is the single final answer tied to an original request. A notify may wake the target with queue or steer, or it may defer; the protocol never auto-replies "acknowledged".
+
+## CLI and TUI
+
+```sh
+dscode sessions
+dscode send SESSION_ID --kind request "check the parser's edge cases"
+dscode send SESSION_ID --steer --kind notify "also: only check UTF-8 input"
+dscode send SESSION_ID --defer --kind notify "watch this compatibility issue next time"
+dscode send SESSION_ID --defer --title "Parser compatibility" "check UTF-8 later"
+dscode mailbox SESSION_ID
+dscode mailbox SESSION_ID --after 12 --limit 50
+dscode watch-mailbox SESSION_ID --after 0
+dscode cancel SESSION_ID MESSAGE_ID
+dscode new-task SESSION_ID
+```
+
+`--steer` and `--defer` are mutually exclusive, and queue is the default. An explicit `--title` sets the title immediately instead of waiting for a defer to be claimed; a repeated send does not overwrite a title that was changed later. Before sending, the client prints the requestId to stderr; when the receipt is lost, retry with the same `--request-id`, target, kind, mode, body and title.
+
+The `/session` command shows the mailbox counts and CLI examples with the current
+state directory in `--home`; `/mailbox` lists messages and `/mailbox cancel
+MESSAGE_ID` cancels a request or an unclaimed message. The experimental
+[combined Desktop package](browser-use.md#install-the-experimental-combined-desktop-package)
+mounts these same services and commands. Use its printed `--home` when addressing
+a Desktop session from the separately installed DSCODE CLI; the terminal's
+default state directory can be different.
+
+## Time context for delayed work
+
+The terminal and experimental combined Desktop package give DSCODE agents clock
+readings when inbox messages enter a model step. Each reading names the time zone
+and UTC offset. A relay with a saved composition time also reports how long it
+waited, starting at one second. The following step can report the previous turn's
+end and duration. These readings describe the Host clock and delivery timing;
+they do not add instructions to the original message body.
+
+Marks are durable auxiliary context: they consume model context and replay with
+the session. Normal terminal and Desktop chat hide them; Desktop's **Trajectory**
+view shows them for inspection. Native Standard sessions receive no DSCODE marks.
+Runtime snapshots and skill catalogs are not inbox arrivals and receive no mark.
+
+Each step adds at most eight lines, with arrivals first. An arrival burst can
+omit arrival readings beyond that limit; it leaves pending turn endings for a
+later step. Resume or plugin reload recovers up to eight recent unreported turn
+endings from the native session log. A fresh load into an older session may
+therefore report recent endings that occurred while the plugin was absent.
+Unloading stops new marks and retains existing history.
+
+The `dscode-time-marks` plugin's `timeZone` setting accepts an IANA zone such as
+`UTC` or `America/Los_Angeles`; empty uses the Host zone. An invalid zone rejects
+the plugin configuration. Clock accuracy depends on the Host system clock.
+
+## Seeing the traffic in the terminal
+
+Cross-session traffic is visible as it happens, without expanding a tool card:
+
+- While a `send_session` or `reply_session` call is running, the activity line reads `⇄ sending to <peer>`; once the call settles and the message was a `request` with no answer yet, it reads `⇄ waiting for <peer>` until a relay from that peer arrives. A `notify` never shows as waiting, and a failed send stops waiting immediately.
+- A settled send prints one notice line (`→ <peer> <kind>`, plus `— failed` when the result was an error), and an inbound relay prints `← <peer> · <bounded text>`.
+- `/tasks` lists the same history on demand as one text block, newest last, with the delivery mode and whether each send is still `awaiting reply`; it reads the session's own log, so it shows what this session sent and received and nothing about other pairs.
+
+Both surfaces use the `steered` violet and the `⇄`/`→`/`←` glyph family, never the brand blue and `•` of ordinary local notices or the plain text of a tool result, so a line about another session is recognisable at a glance. The view is folded from the root session's own log — `tool/call` and `tool/result` for the outbound side, the bridge's relayed `user/message` for the inbound side — so a resumed session rebuilds the same history and a restart announces only traffic that happened in that session, not the whole past.
+ Stopping natively also cancels pending native inbox messages; a standalone defer note has to be cancelled explicitly in the mailbox. A message that is received and enters the context still shows as a relay with its source.
+
+`/session-new-task` or `dscode new-task SESSION_ID` explicitly starts a fresh communication budget while the session is idle. Ordinary follow-ups, automatic continuation and a resume do not reset the budget. When an older request returns later or an older note is claimed, it still carries its original chain and may therefore be limited by it again.
+
+The CLI can answer, on behalf of the current session, a cross-session request that was genuinely addressed to it:
+
+```sh
+dscode reply RECEIVING_SESSION_ID --reply-to REQUEST_MESSAGE_ID "final answer"
+```
+
+A request sent by an external script has no other agent session as a reply address; read its progress and output through read/watch.
+
+## Built-in agent tools
+
+- `list_sessions`: reads cards and run status, with exact project/workspace filtering and pagination.
+- `read_session`: reads the named session's native event page and the head of its mailbox, without waking it or claiming anything.
+- `send_session`: sends request/notify; the full session ID, mode, body and a stable `idempotency_key` are required.
+- `reply_session`: replies against the original request ID; the runtime determines the target, and queue is the default.
+
+A progress notify may carry `in_reply_to` back to the original requester; the target ID must match the original sender. Each request allows at most one final reply. A tool returns only the reception receipt, so a model should end its turn and wait for the answer rather than polling read in a loop.
+
+The sender's session identity is bound by a runtime credential; a model cannot supply its own chainId, budget, sender or new-task authorisation. A child agent inherits its parent's task chain, but in this first version cross-session send/reply is performed by root sessions only, and a child agent should hand back to its parent through the native collaboration entry points; a child agent is not an independent recipient address either. A session card still describes only the original user requests, and a relay never enters the card topics.
+
+## Choosing a target and a delivery mode
+
+Routing has two steps: pick a session from its card, then pick the delivery mode from the target's current status and the nature of this message. Where the fields come from and when they are produced is covered in [Session cards](session-cards.md); this section only covers how to use them.
+
+### 1. List targets
+
+With no filter, `list_sessions` returns every active root session in the same state directory; `project` and `workspace` are exact filters for when you already know whom you want:
+
+```json
+list_sessions({})
+list_sessions({ "workspace": "/abs/path/to/project" })
+list_sessions({ "project": "github.com/owner/repo" })
+```
+
+The result is ordered by session ID, not by activity or recency; `limit` defaults to 20 and caps at 100, so pass `limit: 100` to list everything and page with `nextCursor`. Cross-project collaboration needs no extra argument.
+
+### 2. Which fields to judge by
+
+| Field | Meaning |
+| --- | --- |
+| `card.project` | Normalised from the local Git origin into `name` and `id`; worktrees of one repository share a project, and a non-Git directory is `null`. |
+| `cwd` / `card.workspace` | The exact workspace path, and the basis of the `workspace` filter. |
+| `title` | A human-readable title, possibly unset (`null`). |
+| `card.topics[].text` | Recent user-request topics, the main semantic routing signal, though only an index of recent requests. |
+| `status` | `idle` or `running`, which decides the mode. |
+| `mailbox` | Current `queue`/`steer`/`defer` pending counts; a large number means the target already has a backlog. |
+| `cardState` | `status` is the card's update state; a gap between `coveredUserSeq` and `latestUserSeq` says whether new user input arrived after the card was built. |
+
+`card.project`, `card.workspace`, `card.topics` and `cardState` may all be absent; treat them as absent rather than assuming they exist.
+
+### 3. Pick a target
+
+Lock the project with `card.project.id` or `cwd` first; when several sessions share a project, use `title` and `card.topics` to tell which one is working on the relevant task.
+
+When `cardState.status` is `empty`, `insufficient`, `pending`, `updating` or `error`, the topics may be empty, not yet updated or stale: judge only by project, workspace and title, and do not read the target's current work from an old topic. `disabled` means card extraction is switched off, while project and workspace remain available.
+
+### 4. Pick a mode
+
+| Target status and intent | Choice |
+| --- | --- |
+| Idle, should start work, and you expect an answer | `queue` + `request` |
+| Running, adding a constraint or a correction you want inside this turn | `steer` + `request` |
+| Running, not urgent, let it pick the note up on its next natural turn | `defer` + `request` |
+| Only informing, no reply needed | set `kind: "notify"` and choose the mode from the timing rules above |
+
+kind and mode are independent. Use `request` when you want an answer and `notify` to pass information; a final `reply` must be tied to the original `request_message_id` and cannot answer another reply. `status` is only a snapshot: the target may have changed after you chose the mode, and the runtime's delivery semantics keep the message from being lost because of it.
+
+### 5. Common mistakes
+
+- Judging how far the target has got from a topic. A topic only describes what the user asked for, never a conclusion, a result or a completion state; use `read_session` on the event page for progress.
+- Forgetting pagination. Without `limit` you see 20 entries, which easily hides the target in cross-project work.
+- Confusing `status` with `cardState.status`. The first is the session's busy state, the second the card's update state.
+- Reading the `mailbox` counts as history. They count only unexpired accepted or admitted messages, not consumed ones.
+- Sending as soon as a target is picked. Read a page or two with `read_session` first (defaults `after: -1`, `limit: 50`, returning `cursor`/`head`) to confirm where it is, and avoid a duplicate ask or an interruption.
+
+## Anti-loop budgets and persistence
+
+This first version fixes these limits: 3 delegation levels per task chain, 8 request/notify messages, 1 reserved final reply per request, and a 1-hour validity window. An external send that creates a root request also counts towards the 8. Queue, steer and defer all count; once the new-message ceiling is reached, the reserved final reply can still return.
+
+Sending a new task to yourself or to an ancestor in the current delegation path is forbidden; a legitimate reply tied to the original request and a progress report are allowed to return. After several chains merge, all their constraints apply and you cannot choose the one with more remaining budget. An ordinary continuation, a reply and a notification keep their current causal relationship; when a new turn is started purely by communication requests, it adopts the chains those requests already have, so unrelated finished work is not mixed in. This creates no new budget. At most 32 distinct causal paths are retained; beyond that the request is explicitly refused rather than silently dropping the relationship, and the user has to draw the boundary of the new task.
+
+Each session's unclaimed mailbox holds at most 100 notes with 1 MiB of bodies in total; a single body is at most 64000 bytes, and a full envelope with metadata and headroom is at most 96000 bytes. A single defer batch is under the same full-size limit. An expired note keeps a readable record but is no longer claimed automatically.
+
+All Hosts share the state directory's `session-communication/mailbox.sqlite`. Admission, idempotency, budget and reply slots commit in short SQLite transactions. The ledger owns communication only; model execution keeps using the native inbox, and a session's write exclusivity is still guaranteed by the native JSONL kernel lock. The owner generation rejects stale runtime credentials, and a missing heartbeat times out and seizes the lock.
+
+Receipts and records are distinct:
+
+| delivery | Meaning |
+| --- | --- |
+| accepted | Persisted in the mailbox; a defer may stay here |
+| admitted | Entered the native inbox or the claiming flow |
+| consumed | Matched against a native user/message and flushed; does not mean the task is done |
+| cancelled / expired | No longer delivered automatically |
+| late | A final reply that arrived late; recorded only, no wake-up |
+
+A successful queue/steer receipt waits for the native inbox flush; defer waits for the mailbox commit. The gap where the ledger commits before the inbox write is recovered by re-delivering a stable messageId, and a message already in the native log is never added twice. Native-exit inbox cleanup and an explicit user cancellation are handled separately: the first allows unconsumed communication to be recovered from the ledger, the second never revives a cancelled message.
+
+**The cancellation boundary is the claim.** An unclaimed message with `alreadyClaimed: false` can be stopped from being claimed later; an already claimed input cannot be guaranteed recalled, and the receipt marks it true. A cancel request closes the reply relationship, so a late reply does not wake the target; it does not kill the target's other work or roll back tool side effects. A defer note's batch record and its native consumption acknowledgement are stored separately, so they can be checked again after an interruption.
+
+`watch-mailbox` uses its own monotonic event cursor and reads the shared ledger every 250ms; only a subscribed connection polls, and it drives no agent. It covers reception, admission, consumption, cancellation and refusal. `watch` keeps using the native session seq, and the two cursors cannot be mixed. read/list claims nothing, and a WAL snapshot acquires no session write lock.
+
+Under one OS user, a program that can read the state and credentials can still call the external entry points; these limits stop accidental loops in normal tool use and are not a security boundary against a program with arbitrary shell access. Tool loops and model usage inside a single agent still need its execution budget.
+
+## Verification
+
+`node --test tests/*.test.mjs` covers protocol validation, idempotency, loops/depth, budget, concurrent-process admission, expiry, cancellation and post-encoding size limits.
+
+`node scripts/verify-session-messaging.mjs` uses two real Harness Hosts and a local deterministic model to check sending through the registered tools, a model-invoked reply, the defer deadline boundary and its lack of a wake-up, recovery after a forced exit, recovery with a pre-existing native inbox, de-duplication, cancellation and mailbox subscription. `node scripts/verify-runtime-foundations.mjs` checks the kernel lock and the native input hooks. No claim is made that remote-model collaboration quality, human UI acceptance or side-effect exactly-once has been verified.

package/docs/session-metrics.md

@@ -0,0 +1,41 @@
+# Session footer
+
+## Experimental Desktop usage
+
+The experimental combined Desktop package adds **Open right sidebar → Session
+usage** for the selected open DSCODE session. It reads the same local ledger and
+live token meter as the terminal footer. The panel shows recorded cost, model
+calls, pending calls, context percentage, input cache share, smoothed request
+speed, session-average speed and the latest 50 per-turn cost estimates. The
+session total includes all recorded turns, attributed child calls and background
+work. Cost outside recorded turn windows is shown separately. Known cached
+provider balance or subscription figures are included; opening or refreshing the
+panel does not request new account data or start a model turn.
+
+The panel refreshes once per second while visible and clears its state when
+hidden or switched to another session. Refresh failures clear the old figures
+and display an error. Standard sessions and closed sessions have no DSCODE usage
+view. Unknown values remain explicit; `+` marks a partial cost and pending calls
+have not settled. Prices, historical gaps and speed definitions follow the same
+rules below. The panel displays a configured cost budget but does not introduce
+a Desktop spending enforcement mechanism.
+
+## Terminal presentation
+
+The footer keeps session identity and permissions on row 1. Row 2 places TPS, session-average TPS, context and the loaded skill count on the left; session cost, DeepSeek balance and peak/off-peak marker, optional last-turn cost, and cache rate form one group aligned to the right edge. Space separates the two groups, with `·` inside each group. When they cannot share a row, the financial group moves intact to a right-aligned third row. At narrow widths the average TPS yields before current TPS, context and skills; the metrics no longer disappear wholesale below 48 columns. Extremely narrow terminals may omit the optional last-turn cost and clip the financial group with an ellipsis. The composer and IME cursor account for the actual footer height. On the Grok and OpenCode Go subscription routes the money figure is the plan's usage instead of a cost: Grok's weekly credits, and Go's share of its five-hour, weekly and monthly caps (see [OpenCode Go](opencode-go.md)).
+
+- **current**: a normalized exponential moving average (EWMA) of the root agent's completed request rates. Each request's rate is its provider-reported final `outputTokens` / its full request duration, including the first-token wait. Each valid completion gives the new rate weight 1 and multiplies all older weights by `0.5`; the displayed rate is the weighted sum divided by the weight sum. Thus newer requests always carry more weight, and each newer valid request halves every older sample's weight. The first valid request initializes the reading. Idle time, tools and in-flight requests do not decay it; aborted or invalid/missing-usage calls do not update it. Starting a request with a different provider, model or reasoning effort clears the history; that route shows `--` until its first valid completion. Text lengths never estimate tokens, and auxiliary and child calls do not enter the root's rate. A resumed session starts without a smoothed reading. This is a smoothed request rate, not instantaneous output or a fixed time window.
+- **average**: settled assistant output tokens for the current root session / total LLM call time for those requests (each step from request start to settle, including the wait for the first token). Tool execution and idle time between two user turns do not count; child agent output does not count; a request still in flight does not count before it settles. If any message lacks exact usage or its step-start event, the figure shows `--`.
+- **context**: the current session's token-meter context estimate / the model context window, recomputed after compaction. It covers the currently visible context; extra text an adapter injects temporarily is not part of the local estimate. If live telemetry is unavailable, the footer falls back to the latest recorded prompt usage, including cache reads and writes, against the recorded model window. That fallback describes the last request rather than estimating subsequent output or edits. Before any usable reading exists, it shows `--`.
+- **session**: a dollar estimate accumulating the recorded model calls of the current session and its child agents, including compaction, title generation and auto review. A resumed session keeps the accumulated value; a new session starts over. Jev Decisions attempts are also included: a reported non-negative billed cost is used directly; a missing or invalid cost makes the total partial. MCP/API service costs outside the model are not included.
+- **cache**: cumulative cache-read tokens / cumulative all input tokens, weighted by tokens, not a request hit rate and not the average of per-request percentages.
+
+`+` means only part of the cost is computable; `--` means the data or the price is unknown; `…` means a request has not finished. The cost of the current request is not advanced before usage arrives. The footer refreshes every second and makes no extra model request.
+
+A small activity indicator beside the first TPS figure spins while the main model request is waiting or streaming. It stops when that request completes or aborts, including while tools are running. With animations disabled, an active request shows a static circle. The slot stays reserved while idle so the numbers do not shift. The indicator follows the footer's one-second refresh; its animation never interpolates or alters the TPS number, which changes only when a completed request supplies valid usage.
+
+`current` and `average` are each coloured by their own TPS: yellow below 75, green from 75 to below 150, blue from 150 to 250 inclusive, purple above 250. The cache rate is coloured the same way on its own bands: red below 90%, yellow to 95, green to 98, blue above. An unknown `--` keeps the normal colour; labels, units and separators never change colour with the figure.
+
+Prices use a 2026-09-11 snapshot of the [official DeepSeek price list](https://api-docs.deepseek.com/quick_start/pricing/), distinguishing peak and off-peak by request start time and matching only supported official providers/models. A price update means updating `plugins/session-metrics/pricing.mjs`; the figure shown is not a vendor invoice. An older session can recover part of its calls from the log, but historical review/title/child-agent usage may be incomplete, which is why it is marked as a partial total.
+
+Records are stored in `$DSH_HOME/session-metrics/` and contain only metadata such as model, times, usage and cost, never prompts or credentials. Every model call writes one `start` row (`time` is the request start, `purpose` is `agent`, `compaction`, `session-title`, `review`, `memory`, `session-card` or `doctor`) and one `end` row; an `end` row's `time` is still the start time (used for pricing), `endTime` is when the stream finished, and `firstTokenTime` is when the first text, reasoning or tool-argument increment arrived (omitted when there was no output), so a single LLM call takes `endTime - time` and its first-token latency is `firstTokenTime - time`. Calls for automatic permission review, code review, memory extraction, session cards and `/doctor` do not carry a `sessionId` in the request (avoiding session-log delivery, cache affinity and agent-only prompt rewriting) but are attributed through async context to the session that made them; memory extraction and consolidation keep the initiating session captured at run start, even if another session starts or that owner closes. Manual `/memories run` and `note` use their caller; see [Memory](memory.md) for periodic-run attribution. A call that cannot be attributed to a session (such as the `dscode doctor` command line) is not recorded. The raw session log gains no custom events.

package/docs/skills.md

@@ -0,0 +1,81 @@
+# Skills and workspace instructions
+
+Skill discovery and body loading come from `@deepseek-ai/dsh-skill-filesystem`, and workspace instructions come from `@deepseek-ai/dsh-agent-instructions`. This page covers what each one scans, how the upward-discovery switch is configured, and where the boundary between them lies.
+
+## Default discovery scope
+
+| rank | Source | Path |
+|---|---|---|
+| 100 | `project-dsh` | `<project root>/.dsh/skills` |
+| 200 | `project-agents` | `<project root>/.agents/skills` |
+| 300 | `custom` | `customSkillDirs` (the ancestor mode registers here) |
+| 400 | `user-dsh` | `$DSH_HOME/skills` (skipping its `.system` subdirectory) |
+| 500 | `user-agents` | `$DSH_AGENTS_HOME/skills` |
+| 600 | bundled | when `bundledSkillDir` is configured |
+
+The project root is the **nearest ancestor directory containing `.git`**, or the current directory when there is none. A lower rank is scanned first and wins, a duplicate name goes to the one that appeared first, and `/skills conflicts` lists them.
+
+Each root is scanned only for its **top-level** `<name>/SKILL.md` or `<name>.md`; a nested `**/SKILL.md` is deliberately not discovered. Frontmatter requires `name` and `description` and may add `user-invocable` and `disable-model-invocation`. The directory entries (name + description) are in the context every turn, and a body is read only when it is invoked.
+
+## Upward discovery (ancestor mode)
+
+On by **default**. The following three roots in **every** directory between the working directory and home are registered at rank 300:
+
+```
+<each level>/.dsh/skills
+<each level>/.agents/skills
+<each level>/.claude/skills
+```
+
+For example `~/Workspace/.dsh/skills` becomes visible to every project under `~/Workspace`. Rules:
+
+- **Only headers enter the catalog**; bodies stay lazy-loaded, exactly like a project-local skill.
+- **Nearest wins**: a directory closer to the cwd registers first. Rank 300 is below the project root's 100/200 and above the user roots' 400/500, so a project or ancestor skill beats a user-level one, and within rank 300 the roots are registered nearest-first, so a nearer ancestor beats a farther one. The single inversion is a directory between the working directory and the project root (for example `repo/src` while the session runs in it and `repo` is the project root): it ranks 300 while the project root's own `.dsh/skills` and `.agents/skills` rank 100/200, so the project root's definition of a duplicate name wins there.
+- A project root's `.dsh/skills` and `.agents/skills` are the provider's own roots and are **not registered twice**; a project root's `.claude/skills` is not one of the provider's roots, so it is included.
+- **Nothing above home is read**; when the cwd is not under home (for example `/Volumes/...`) no ancestor root is added.
+- The list is resolved **once at startup**: `/cd` inside a session, or creating an ancestor skill directory, needs dscode to be reopened before it takes effect (adding, changing and removing a skill file itself still has a watcher).
+
+### Switch
+
+Environment variable `DSCODE_SKILL_ANCESTORS`:
+
+| Value | Result |
+|---|---|
+| unset, empty, or any unrecognised value | on |
+| `0`, `off`, `false`, `no`, `none`, `disable` (case-insensitive) | off |
+
+How to turn it off:
+
+| Way | Command / location | Scope |
+|---|---|---|
+| One run | `DSCODE_SKILL_ANCESTORS=0 dscode` | this launch |
+| Persistent (source / tar) | the repository's or installation's `.env` (already gitignored) | every later launch |
+| Persistent (npm / Hub) | `$DSCODE_HOME/.env`, by default `~/.local/share/dscode-hub/.env` | every later launch |
+
+`config/harness.local.yml` has **no effect** on this switch: it is a DSH patch that only applies after the preset is mounted, whereas the ancestor list has to be computed before mounting.
+
+The launcher (source form) or the bundle's bootstrap (npm/Hub form) resolves the directory list and passes it to the preset's `customSkillDirs` through `DSCODE_SKILL_ANCESTOR_DIRS`; this internal variable does not need to be set by hand.
+
+## Workspace instructions AGENTS.md / CLAUDE.md
+
+**Project chain (on by default)**: from the project root down to the session working directory, each directory contributes `AGENTS.md` and `CLAUDE.md`, followed by `AGENTS.local.md` and `CLAUDE.local.md`; there is also a user-level `$DSH_HOME/AGENTS.md`. The project chain does **not** cover directories above the project root.
+
+**Above the project root (on by default, only when the file exists)**: the launcher aggregates `AGENTS.md` / `CLAUDE.md` from every level between home and the project root into `$DSH_HOME/workspace-instructions/AGENTS.md`, ordered **user-level original file first, then the farthest ancestor → the nearest ancestor**, and points the preset at that directory with `dshHome`, leaving rendering and de-duplication to upstream. When there is no ancestor instruction file at all, no file is written and `$DSH_HOME/AGENTS.md` is read exactly as before.
+
+The byte budget keeps upstream's `maxBytes: 65536`: over budget, a wider file is dropped whole first and the most specific file is truncated last, with a visible budget notice. The ancestor aggregate file itself has a 60 KiB cap (below `maxBytes`, leaving headroom): upstream drops a **wider file over budget whole**, and the aggregate file occupies the widest user-global slot, so without a cap one oversized ancestor file would take the user-level `AGENTS.md` down with it. A single source over budget is skipped whole rather than half-truncated, and the user-level file and the nearest ancestor are kept first.
+
+## Verification and troubleshooting
+
+| Command | Purpose |
+|---|---|
+| `/skills` | the effective catalog: source, provider, user/model invocation permission |
+| `/skills <name>` | description and effective path, without injecting the body |
+| `/skills conflicts` | same-name overrides and their effective source |
+
+To confirm ancestor mode is active, run `/skills` after startup: entries from an ancestor directory have `source` `custom`, and `/skills <name>` gives the file path directly. The footer's `skills` figure carries the same catalog's size and updates with it (`/statusline` toggles the item); it stays `--` until the first catalog read settles.
+
+## Limits
+
+- Ancestor discovery is on by default, so the content-cost of the wider scope and the fact that ancestor directories sit outside version control are the default experience; set `DSCODE_SKILL_ANCESTORS=0` to go back to the project and user roots alone.
+- The ancestor list is fixed at startup and does not follow `/cd`.
+- `/skills conflicts` cannot enumerate hidden candidates from a runtime or a remote provider.