@piagent/platform 1.37.1 → 1.38.2

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.38.2 - 2026-10-23
+
+A folder tree as in VS Code, colour themes, and an editor and terminal that stay in view.
+
+### Added
+
+- **Colour themes.** Settings → Appearance → Color theme, or `Color theme: …` in the command palette (⌘K): Piagent Dark and Light, Dracula, One Dark, Monokai, Nord, Tokyo Night, Catppuccin Mocha, Gruvbox Dark, Solarized Dark and Light, GitHub Dark and Light. A theme colours the interface, the editor's syntax (no longer CodeMirror's light default on a dark page) and the terminal's ANSI palette; Light/Dark switches to that mode's Piagent theme. Kept in this browser like the language.
+
+### Changed
+
+- **The editor and terminal stay in view.** On wide screens they are pinned under the header while the conversation beside them scrolls, so a long conversation no longer carries them away; the Files/Terminal switches are pinned too, on every width. A splitter (drag, or ←/→ when focused) sets the editor's width, kept in this browser. On phones the folder tree is narrower and the editor's actions stay on one line.
+- **The files panel is a folder tree, as in VS Code.** Folders open in place under their parent (▸/▾) instead of replacing the list, each read when first opened and refreshed while open; the open file is highlighted and a file opened from search, a link or Cmd/Ctrl+P shows in its folder. **New file** starts in the last folder chosen.
+
+## v1.38.1 - 2026-10-23
+
+v1.38.0 was tagged but never published: its release checks failed on two tests. This is the same release.
+
+### Tests
+
+- `tests/managed-terminal-boundary.test.mjs`: the Linux fixture says it is a Linux boundary, as the real one does (the macOS Seatbelt path was taken on Linux and failed).
+- `tests/managed-network-approval-web.test.mjs`: the approval card gets 30 s to appear on slow runners.
+
+## v1.38.0 - 2026-10-23 (not published)
+
+Piagent becomes an editor: files, terminals, inline review and checkpoints in the dashboard, and Bypass that asks nothing (company conversations too, where the Harness allows it).
+
+### Added
+
+- **Bypass, as in Codex.** A new `bypass` permission mode (`/permission bypass`, `piagent-auto --bypass`, `PIAGENT_PERMISSION_PROFILE=bypass`, or **Bypass** in the dashboard's access menu) turns every Piagent gate off in a personal session: nothing is asked or blocked, deletes, pushes, migrations, external sends and protected or read-only paths included. Tool output is still redacted and each turn still gets its `/undo` checkpoint. A policy can forbid it by leaving `bypass` out of `permissionProfiles.allowedModes`. **Full access** (`trusted-full-access`) is unchanged.
+- **Bypass in company conversations, where the Harness allows it.** A company conversation now has three levels: Ask first, **Full access** (what the dashboard called Bypass before: asks only what must be confirmed) and **Bypass**, which asks nothing (internet, Docker, the member's machine, pushes, deploys, migrations) while plain commands stay in the sandbox. Bypass needs the Harness's `bypass_mode` (Agent Studio, on by default; an administrator can turn it off) carried by an Agent Watch that knows the field; without an explicit yes it is not offered, and a conversation left in Bypass after it is turned off applies as Full access. `/bypass on|full|off` in the dashboard and in `piagent studio`.
+- **Editor-like workspace.** Square 2px edges across the dashboard; file and terminal tabs close with their own ×; the files and terminal panels hide with a × of their own; the editor sits above the terminal and both share the window height.
+
+### Fixes
+
+- **A checkpoint that cannot be taken no longer stops the agent's edit.** Personal snapshots failed on a submodule, a file over 16 MB, a tree over 64 MB or a file changing mid-snapshot, and every write was then refused. Snapshots now hash the whole tree in one Git call (about 0.5 s instead of 35 s on a 4,000-file repository), include tracked files of any size, skip untracked files over 100 MB and leave submodules out. A turn whose snapshot fails has no checkpoint and ends the history before it; only another live owner of the session's history makes an edit wait. Company checkpoints get the same snapshot.
+- **Restoring a turn no longer overwrites a file the member saved from the editor during it.** Such files are reported as conflicts by `/undo` and Timeline restore.
+- **Checkpoint snapshots stay out of the project's refs.** They live in a private repository inside the Git directory that borrows the project's objects, so `git push --mirror` cannot publish untracked files; conversations untouched for 30 days lose their checkpoints.
+- **The company explorer, editor and review panels no longer wait behind the agent's running command.** Reads run beside it (three at a time) and the editor's permission poll no longer stacks requests.
+- **A flood of terminal output no longer drops the dashboard connection.** Output is paced at about 4 MB/s, the writer is paused while the browser catches up, output it cannot keep up with is marked as skipped, and a terminal tab never stops rendering for good. Company terminal workers pause instead of exiting when their pipe backs up. A flood of short lines no longer stalls the Gateway: tiny PTY reads are joined before pacing and the replay buffer trims its window once it doubles instead of on every line.
+- Restored files the turn had deleted get a new file's usual mode instead of owner-only.
+- **Company terminals work on macOS.** The company Gateway creates the PTY and starts only the shell under the agent's offline Seatbelt profile, which gains terminal ioctls and `/dev/tty`; opening any other terminal stays denied, and nothing runs on the host. Company terminals also write the project's Git directories and package caches like the agent's offline commands, so `go build` and `git` in a worktree work.
+- **Terminals:** background jobs stop with their terminal (the shell's tree is watched while it runs); actions refused before anything ran are reported as refused, not "may have run"; a stale revision is resent instead of dropping queued keystrokes; `@terminal` naming no open terminal attaches nothing instead of blocking the message; the personal shell no longer inherits the Gateway's `PI_*`/`PIAGENT_*` variables.
+- **Editor:** **Rename** and **Delete** for the open file, applied only to the version shown; new files get the usual mode and their missing folders; creating a file never replaces one that appeared meanwhile; refusals that changed nothing (oversized file, linked folder) are reported as such. Kept hunks survive a page reload in the same browser.
+- **Checkpoints:** a restore that stopped midway finishes what is left instead of refusing its own work; a refusal before any file changed is reported as refused; a file ignored since the turn is refused rather than overwritten; folders the turn created and its undo emptied are removed; any shell command not provably read-only takes the turn's checkpoint; a lock or capture left by a process from before a reboot, or whose number was reused, no longer blocks.
+
+- Company inline review preserves exact agent observations across trusted internal snapshot reads; ordinary shell commands still invalidate attribution.
+
+### Added
+
+- Timeline checkpoint restoration previews affected files, requires confirmation and reverses safe turns until a member-edit conflict. Personal `/undo` shares the checkpoint service with company mode; personal history is bounded and pins Git trees without changing HEAD or the index. Browser retries retain the same request across tab reloads.
+
+- Company Session Hub terminals run inside the Linux/WSL bubblewrap boundary through the company Gateway and authenticated relay, with no network, credential masking and sandbox process cleanup. Disconnects reconnect for replay without automatically resending commands. Doctor reports prerequisites. The complete browser workflow is qualified on Linux arm64; native Linux x64 and WSL remain unverified.
+
+- Personal Session Hub terminals open up to four project shells with lazy xterm tabs, resizing, Ctrl+C and reconnect replay. Session teardown cleans terminal processes. Explicit `@terminal`/`@terminal:2` sends attach bounded redacted output. Optional native PTY failures leave the dashboard usable and appear in Doctor; company terminals never fall back to host execution.
+
+- Session Hub reviews exact observed agent hunks inline, with Keep, preview-confirmed Revert, hunk navigation/counts and current/removed-line comments to the composer. Clean tabs refresh after agent changes; dirty drafts retain conflict handling. Company source review and revert run in the existing sandbox. New untracked agent files support review; deletion through hunk revert remains unavailable.
+
+- Session Hub edits and atomically saves files with Cmd/Ctrl+S, dirty tabs, new files and digest conflicts (Reload/Compare/confirmed Overwrite). Live permission and protected-path checks apply in personal and company mode. Durable receipts prevent duplicate saves; member edits notify the next agent turn and invalidate stale agent edits.
+- Session Hub opens project files in read-only editor tabs, with Files/Search navigation, Cmd/Ctrl+P, line links from tool calls, source changes and @mentions, and a drawer on smaller screens. Protected files stay locked. Company file reads and searches run inside the session's existing sandbox through its Gateway.
+
 ## v1.37.1 - 2026-10-22
 
 Closes, helper reports and team-memory lessons Studio can trust (from the 2026-10-22 upstream audit), and two outbound-address fixes from the 2026-10-22 security review.

package/README.md

@@ -138,8 +138,9 @@ Project profiles can declare a runtime `permissionProfile`:
 | `read-only` | Scout, audit, review | Allows `read`, `grep`, `find`, `ls`, and piagent state tools; blocks shell, `write`/`edit`/`apply_patch`, and unknown tools. |
 | `workspace-write` | Normal implementation | Default profile. Keeps protected-path, read-only-path, shell and capability checks, and asks before destructive or external actions. |
 | `trusted-full-access` | Trusted local automation | Expands workspace tool/scope autonomy, but still enforces protected paths, secret redaction, capability lock integrity, and destructive/external confirmation. |
+| `bypass` | You accept every risk, as with Codex's `--dangerously-bypass-approvals-and-sandbox` | No Piagent gate asks or blocks: deletes, pushes, migrations, external sends, protected and read-only paths all run. Tool output is still redacted and each turn still gets its `/undo` checkpoint. Remove `bypass` from `permissionProfiles.allowedModes` to forbid it in personal sessions. In a company conversation Bypass asks nothing either (internet, Docker, the member's machine, pushes, deploys), plain commands stay in the sandbox, and the team's Studio administrator can turn it off in the Harness (`bypass_mode`); it then applies as Full access. |
 
-For one run, set `PIAGENT_PERMISSION_PROFILE=read-only|workspace-write|trusted-full-access`, or use `piagent-auto --read-only`, `--workspace-write`, or `--full-access`.
+For one run, set `PIAGENT_PERMISSION_PROFILE=read-only|workspace-write|trusted-full-access|bypass`, or use `piagent-auto --read-only`, `--workspace-write`, `--full-access`, or `--bypass`.
 
 Inside an active Pi session, use `/permission` for the menu or a session-local switch:
 
@@ -150,6 +151,7 @@ Inside an active Pi session, use `/permission` for the menu or a session-local s
 /permission workspace-write
 /permission full-access
 /permission full-access Implement the requested trusted repo task.
+/permission bypass
 ```
 
 Legacy aliases still work: `/permission-status`, `/read-only`, `/workspace-write`, and `/full-access`. Full-access also accepts a task after the command. The guard switches the current session to `trusted-full-access`, then forwards the remaining text as the next user request.
@@ -346,7 +348,7 @@ This repository intentionally excludes:
 
 ## Maturity
 
-The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.37.1` or a reviewed commit.
+The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.38.2` or a reviewed commit.
 
 Ready for:
 
@@ -364,7 +366,7 @@ Application-level policy layer:
 - The guard extension is an accident-prevention layer for agent mistakes and common prompt-injection patterns.
 - Raw path-like tool access to protected paths is blocked before execution. This covers Pi built-ins such as `read`, `write`, `edit`, `grep`, `find`, `ls`, and custom/MCP tools when their input contains path-like strings, including nested objects, arrays, and `file://` URIs.
 - The default MCP proxy carrier is decoded only from bounded object-shaped JSON. Provider/action confirmation and protected/read-only path checks then apply to the effective MCP tool; malformed, oversized, scalar, array, or excessively nested proxy payloads fail closed.
-- Runtime permission profiles control autonomy: `read-only`, `workspace-write`, and `trusted-full-access`. The full-access profile is explicit and auditable; it does not disable protected-path checks, secret redaction, capability lock integrity, or destructive/external confirmations.
+- Runtime permission profiles control autonomy: `read-only`, `workspace-write`, `trusted-full-access`, and `bypass`. The full-access profile is explicit and auditable; it does not disable protected-path checks, secret redaction, capability lock integrity, or destructive/external confirmations. `bypass` does, only when chosen explicitly (and, in a company conversation, only while the team's Harness allows it); it keeps output redaction and turn checkpoints.
 - Protected paths are matched case-insensitively, existing aliases are resolved to their canonical repository path, and scope-aware filesystem tools reject repository escape or symbolic-link traversal.
 - Path-like strings are percent-decoded once before matching. Excessively nested tool input fails closed instead of being silently skipped.
 - Known content fields such as `content`, `query`, `pattern`, `text`, and `command` are excluded from generic path extraction to preserve normal search/edit behavior. Tool-specific checks still validate `grep.glob` and `find.pattern` when they explicitly target protected paths.

package/README.vi.md

@@ -74,7 +74,7 @@ hình chỉ đọc, không command nào mở lượt model.
 | Command | Mục đích |
 |---|---|
 | `/profile` | Xem hoặc đổi project profile; `/profile setup` chọn tech cho từng vai trò |
-| `/permission` | Đổi permission mode trong session |
+| `/permission` | Đổi permission mode trong session; `/permission bypass` (hoặc `piagent-auto --bypass`) tắt mọi cổng kiểm soát của Piagent như bypass của Codex, vẫn che secret trong output và giữ `/undo`; cuộc trò chuyện company dùng `/bypass on` khi admin Studio để Bypass bật trong Harness |
 | `/context` | Xem Context Engine, index, retrieval và telemetry |
 | `/usage` | Xem session, model, thinking và context usage |
 | `/piagent-inspector` | Mở menu read-only để xem task diff, command fail/block, safety warning và context budget; panel bốn dòng tự hiện sát footer native, `toggle` để ẩn trong session |
@@ -179,7 +179,7 @@ Xem [bằng chứng benchmark](https://piagent.io.vn/benchmark) và
 
 Gate này chạy architecture check, test, typecheck, capability validation, runtime smoke và docs consistency trước khi release.
 
-Bản phát hành hiện tại là `v1.37.1`. Với team hoặc production, hãy pin tag này
+Bản phát hành hiện tại là `v1.38.2`. Với team hoặc production, hãy pin tag này
 hoặc một commit đã review thay vì dựa vào nguồn package không cố định.
 
 ## Security

package/catalog/capabilities.json

@@ -26,8 +26,8 @@
           "path": "evals/scenarios/capability-resolution.json"
         },
         {
-          "byteSize": 7631,
-          "digest": "sha256:e50361eda8ca41dc75afdff2ff21498499147b494ad4ed7b444a4a29279ba884",
+          "byteSize": 7647,
+          "digest": "sha256:422b26bca154240747970d948cdf1ded57b9dcb544d6547dedb4d1ddfda4b4da",
           "id": "base-policy",
           "kind": "policies",
           "path": "packages/piagent-core/policies/base-policy.json"

package/docs/command-reference-vietnamese.md

@@ -130,7 +130,7 @@ Các command này đến từ package `piagent-core`; tất cả chạy ngay và
 | `/piagent-inspector` | Muốn xem Piagent đang làm gì, sửa file nào, diff bao nhiêu dòng, command nào fail/block và context còn bao nhiêu. | Mở menu `summary/files/commands/security/context/toggle`; read-only, không gọi model. |
 | `/piagent-orchestration` | Xem chính sách helper/subagent. | Mode, giới hạn helper, review lens, Field Guide; không gọi model. |
 | `/context` | Xem index/search/pack/impact/efficiency/preflight/compact. | Menu context, không gọi model. |
-| `/permission` | Xem/đổi quyền runtime. | Menu status/read-only/workspace-write/full-access. |
+| `/permission` | Xem/đổi quyền runtime. | Menu status/read-only/workspace-write/full-access/bypass. |
 | `/fast status\|on\|off` | Xem/bật/tắt Fast service tier cho session OpenAI Codex. | Chạy ngay, 0 model token; giữ nguyên model/thinking. Session trống mặc định tắt, environment override hoặc state đã lưu khi resume có thể được ưu tiên. |
 | `/memory` hoặc `/memory-policy` | Xem memory policy. | Chạy ngay, không gọi model. |
 | `/piagent-mcp` | Xem/quản trị MCP trong Pi. | Menu MCP, không gọi model. |
@@ -477,8 +477,8 @@ Các lệnh này chạy ngoài Pi.
 | Command | Dùng khi nào |
 |---|---|
 | `npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts @piagent/platform@1.37.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.37.1` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.38.2` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.38.2` | Cài pinned release khi cần reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Cài latest package platform cho máy cá nhân/sandbox. |
 | `piagent-update --check` | Báo version hiện tại vs version sẽ lên cho cả ba thành phần; không cài gì. |
 | `piagent-update` | Full update global một lệnh cho cả máy: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. |
@@ -500,6 +500,7 @@ Các lệnh này chạy ngoài Pi.
 | `piagent-auto --read-only -p "<task>"` | Auto-run scout/read-only; guard chặn shell/write/unknown tool. |
 | `piagent-auto --full-access -p "<task>"` | Trusted automation style; không tắt protected paths/redaction/human gates. |
 | `pi` rồi `/permission full-access <task>` | Một lệnh trong Pi để bật full-access cho session và giao task. Alias `/full-access <task>` vẫn chạy. |
+| `piagent-auto --bypass`, `/permission bypass` | Bypass như Codex: không hỏi, không chặn gì (xoá, push, migration, gửi ra ngoài, file được bảo vệ đều chạy). Output vẫn che secret, `/undo` vẫn hoàn tác từng lượt. Company: `/bypass on` (Bypass), `/bypass full` (Toàn quyền), `/bypass off` (Hỏi trước); admin Studio tắt được Bypass trong Harness, khi đó cuộc trò chuyện chạy như Toàn quyền. |
 | `pi --list-models` | Xem model Pi thấy được theo credentials hiện tại. |
 | `piagent-install --with-mcp --with-subagents` | Cài global package + MCP + subagent baseline từ package bin. |
 | `piagent-setup <project> --profile auto` | Setup đầy đủ cho một project khi muốn preseed bằng bin. |

package/docs/distribution-standard.md

@@ -15,9 +15,9 @@ Repo này phải chạy được cho nhiều project/domain khác nhau. Vì vậ
 
 | Use case | Package source |
 |---|---|
-| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.37.1` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.38.2` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.37.1` |
+| Registry distribution | `npm:@piagent/platform@1.38.2` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -54,7 +54,7 @@ Root `package.json` có `pi` manifest trỏ tới:
 Do đó team có thể:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.37.1
+pi install git:github.com/Vt-mmm/piagent@v1.38.2
 ```
 
 Không cần biết internal folder `packages/piagent-core`. Source không pin chỉ dành cho personal/sandbox như bảng channel ở trên.
@@ -66,12 +66,12 @@ Team nên install global package một lần:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0
-npm install -g --ignore-scripts @piagent/platform@1.37.1
+npm install -g --ignore-scripts @piagent/platform@1.38.2
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.37.1` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.37.1`.
+`pi install git:github.com/Vt-mmm/piagent@v1.38.2` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.38.2`.
 
 Support matrix hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy smoke trước rollout; native Windows chưa phải target rollout team; WSL2 experimental. Chi tiết và version runtime nằm trong [release/install policy](release-install-policy.md).
 
@@ -118,7 +118,7 @@ Nếu muốn commit sẵn `.pi/piagent-profile.json` vào repo hoặc bootstrap
 ```bash
 bash scripts/setup.sh /path/to/project \
   --profile be-readonly-fe \
-  --package-source git:github.com/Vt-mmm/piagent@v1.37.1 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.38.2 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/en/maintainer-guide.md

@@ -2,6 +2,14 @@
 
 [Tiếng Việt](../vi/maintainer-guide.md)
 
+## Full test runs
+
+`npm test` runs at most two test files concurrently, matching `npm run verify`.
+Several integration files own real SDKs, sandbox workers and browsers; limiting
+competing files avoids exhausting their existing deadlines. The limit does not
+change test selection or assertions. Place Node runner options before file paths;
+appending `--test-concurrency=2` after `npm test --` does not configure this script.
+
 ## Placement rule
 
 Before adding code, answer one ownership question:

package/docs/en/workspace-editor.md

@@ -0,0 +1,222 @@
+# Read and edit project files in Session Hub
+
+[Tiếng Việt](../vi/workspace-editor.md)
+
+Open a conversation in `piagent dashboard`, then choose **Files**. On a wide
+screen the sidebar lists the project tree and the editor sits beside chat. On
+smaller screens Files opens a drawer. Choose **Sessions** to return to the
+conversation list.
+
+Choose a file to open an editor tab. Cmd/Ctrl+P searches file names. **Search**
+finds literal text and opens results at their line. File links on tool cards,
+source changes and `@path:line` mentions also open the editor. **Open in VS Code**
+remains available in source changes.
+
+The tree respects Git ignore rules and loads one directory at a time. Lists and
+searches have limits and say when results are truncated. Without ripgrep, search
+uses an existing Context Engine index; it does not create an index and may only
+find indexed files. The view reports when search is unavailable.
+
+Protected files show a lock and cannot be opened. Binary and oversized files show
+a notice instead of content. Unsafe paths and symlinks are refused. Company
+requests go through the company Gateway and read files inside the session's
+existing sandbox. Writes use that same boundary. Browser access never receives a Studio grant.
+
+JavaScript, TypeScript, JSON, Markdown, Python, HTML and CSS parsers load when
+needed; other files remain readable as plain text.
+
+With write access, edit text and press **Cmd/Ctrl+S** or **Save**. A dot marks
+unsaved tabs. Closing a dirty tab asks before discarding it; hiding Files or
+switching conversations keeps drafts in this page's memory. Leaving the page
+warns about unsaved drafts. Drafts are not restored after a browser restart.
+**New file** accepts a relative path; missing folders are created when you save.
+New files get the usual mode for your umask. **Rename** and **Delete** act on the
+open file with no unsaved changes, only if it is still the version shown: a file
+changed on disk, or a new name that already exists, is refused. Delete asks first;
+Git can restore a committed file.
+
+Saving checks the current permission profile, protected/read-only paths and the
+file digest. If the file changed, choose **Reload**, **Compare** or **Overwrite**.
+Overwrite requires confirmation and still checks the version shown in the dialog.
+A connection failure keeps the draft; retrying the save uses the same command so
+it cannot write twice. An uncertain result asks you to reload and check first.
+
+A notice says when the agent is running. A successful member save refreshes
+Source Changes and gives the next agent turn a short note naming the edited
+files. An agent that read an older version must read again before edit/write.
+Company reads and writes share the agent's queue inside the existing sandbox.
+Read-only access disables saving, and the server checks access again on each save.
+
+## Review agent changes
+
+Open files show proven agent hunks with added lines, removed-line blocks and gutter
+markers. Each open tab shows its remaining hunk count. **Alt+ArrowDown/Up** moves
+between hunks. **Keep** removes a hunk from review without changing the file; it
+survives closing the drawer and reloading the page in this browser (only paths,
+digests and hunk references are stored, never code), and changed content needs
+review again.
+
+**Revert** opens a preview and requires confirmation. It uses the existing guarded
+source revert and preserves the Git index. If the response is lost, **Check again**
+asks about the same command. Revert is unavailable for mixed member/agent hunks,
+stale content, protected paths and unsupported changes. Newly created untracked
+agent files can be reviewed and kept; deleting them through revert is not yet
+supported. A pre-existing member file is not treated as wholly agent-authored.
+
+Agent activity refreshes clean open files. Unsaved drafts stay intact and show the
+same conflict choices as saving. Hunk decorations disappear while editing a draft.
+**Comment on current line** or **Cmd/Ctrl+Shift+M** opens LineReview. Removed lines
+have their own comment button and retain the old line number and text. **Put in the
+composer** appends comments to your draft; send the message to ask the agent to act.
+
+Attribution requires an exact observed write/edit/patch in this session and a
+current, complete, unredacted diff. CRLF and missing final newlines are compared
+exactly. Unobserved shell edits and observations lost on runtime restart do not
+receive agent hunk markers. Company review and revert run inside its sandbox.
+
+## Personal terminal
+
+Choose **Terminal** beside Files, then **+** to open the member's shell in the
+conversation's project. Each conversation supports four tabs. The panel sits
+below the editor on wide screens and opens a bottom drawer on smaller screens.
+Drag the separator to change its height, or focus it and use the arrow keys.
+The terminal follows the current theme; Ctrl+C interrupts the foreground command.
+
+Typed commands run with the member's host privileges, without an agent approval
+prompt. Personal terminal execution is not a sandbox. Closing a terminal,
+releasing or restarting its session, or shutting down the Gateway stops its
+process group and every process started from it. The shell's tree is watched
+while it runs, so a background job (`cmd &`, then `exit`) stops with its terminal
+too; a process meant to outlive the terminal should be started elsewhere.
+
+A command that prints faster than the browser can draw (`yes`, a large `cat`)
+is paced: the terminal pauses its writer while the page catches up, and output
+the page could not keep up with is replaced by an `[… output skipped …]` marker.
+The conversation on the same connection is not interrupted.
+
+Hiding the panel or reloading the page preserves the shell while its Gateway
+runtime remains alive. Reopening replays up to 64 KB of retained output per tab.
+Replay and agent attachments redact recognized secrets; the live terminal shows
+the member's own raw output. Restarting the Gateway clears terminals and buffers.
+If a command's receipt is lost, input pauses: **Check command again** asks about
+the same command. Check the terminal before choosing **Checked, continue**.
+Pending commands survive panel changes in page memory, not a page reload.
+
+Write `@terminal` (terminal 1) or `@terminal:2` in the composer, then press Send
+to attach the current redacted output. Repeated mentions attach a tab once, with
+at most four tabs and a combined 64 KB of output. A mention of a terminal that
+is not open attaches nothing and the message is sent as written. Output is quoted as untrusted evidence; merely typing a mention sends
+nothing. Tab numbers increase within the runtime and are not reused after close.
+
+The optional native PTY module can be unavailable. The panel explains this and
+`piagent-doctor --json` reports `productReadiness.personalTerminal`; other dashboard
+features remain usable. Doctor checks module loading and does not claim a shell
+spawn test; a shell that cannot start is reported when you open a terminal. An
+action refused before anything ran (no project folder, an exited terminal) says
+so instead of "the command may have run". Native Windows is unavailable; use WSL.
+
+
+## Company terminal
+
+Company conversations use the same terminal panel through the company Gateway,
+including when opened from the personal dashboard. The shell runs inside the
+conversation's tool boundary: bubblewrap on Linux and WSL, Seatbelt on macOS. It
+has no internet, package proxy or Docker access. Writes reach the project, its Git
+directories, the project's package caches and a private temporary directory, as
+the agent's own offline commands do; a read-only profile keeps the project read-only. Credential
+files are masked, and protected paths retain the boundary's restrictions.
+The shell is Bash without startup files; it does not load the member's shell config.
+
+Up to four terminals belong to each conversation. Closing a terminal, releasing
+its conversation or shutting down the company Gateway stops its sandbox and
+all descendants, including detached children. Hiding the panel and reloading the
+browser preserve the terminal while the company runtime lives. A lost relay
+connection disables input and reconnects for state and replay; it never resends
+commands automatically. Explicit terminal mentions are attached inside the
+company Gateway, and Studio grants stay there.
+
+On macOS, Seatbelt refuses to create a PTY, so the company Gateway creates it
+and starts only the shell under the agent's offline Seatbelt profile. That profile
+gains two rules: terminal control calls on terminal devices, and `/dev/tty`. The
+shell can reach only the terminal it was handed; opening any other terminal stays
+denied. No company shell ever runs on the host. Native Windows is unavailable; use WSL.
+
+`piagent-doctor --json` reports `productReadiness.companyTerminal`. A supported
+result checks runtime files and prerequisites only (`ptySpawnVerified: false`);
+it is not proof that this machine can spawn a sandboxed PTY. The complete
+Gateway, relay and browser workflow was qualified on Linux arm64 in Docker and on
+macOS arm64. Native Linux x64 and WSL were not independently qualified.
+
+## Restore an agent turn
+
+In a Git project, a completed turn that changed files has **Restore before this
+turn** in the Timeline. Open it to preview the affected files and number of turns,
+then choose **Confirm restore**. Restoration runs from the newest turn back to
+the selected turn. It removes files created by those turns and restores the
+previous contents of files they changed. HEAD, commits made during a turn and
+the member's staging area remain unchanged.
+
+If a member changed an affected file afterward, restoration stops at that turn
+and names the conflicting files. Newer safe turns may already have been restored;
+the result reports how many. A running agent, changed preview or revoked write
+permission requires a fresh preview. Protected and read-only paths retain their
+restrictions. A project without Git has no checkpoints.
+
+A file the member saved from the editor after a turn began counts as the
+member's: restoring that turn names it as a conflict instead of putting it back.
+A file that is on disk but outside the current snapshot (ignored since the turn,
+or an untracked file too large to snapshot) is refused the same way. If a restore
+stopped midway, a fresh preview lists only what is left: files already back as
+they were count as done, not as conflicts. A refusal before any file changed is
+reported as refused, not uncertain. Folders the turn created and the restore
+emptied are removed. Any shell command that is not provably read-only takes the
+turn's checkpoint first.
+Edits typed into a terminal are not tracked this way; the drift check still
+refuses files changed after the turn ended.
+
+Personal Pi TUI also supports `/undo` for the latest turn without asking the
+model. Personal history retains up to 64 checkpoints per project and session in
+owner-only `.pi/piagent-state/checkpoints` files; a conversation untouched for
+30 days loses its checkpoints. Snapshots are kept in a private repository inside
+the Git directory (`.git/piagent/checkpoints.git`), which uses the project's
+objects but has its own refs: `git push --mirror` never publishes them, and the
+project's garbage collection does not remove them. Snapshots include tracked files of any size,
+skip untracked files over 100 MB and leave submodules out; undo never touches
+what a snapshot left out. When a snapshot cannot be taken, the agent's edit
+still proceeds; that turn has no checkpoint and earlier checkpoints are dropped,
+because restoring past it would claim a state it never recorded. Only another
+live runtime holding the same session's history makes an edit wait. If a personal runtime stops before the final snapshot, recovery leaves its
+file edits intact and discards only the unfinished checkpoint metadata. Earlier
+completed checkpoints still apply their member-edit conflict checks. Company checkpoint
+operations run inside the existing sandbox; company history lasts for the runtime.
+
+If the browser loses a restore response, **Check result again** sends the same
+request key. The pending request survives reload in the same browser tab; reload
+never submits it automatically. Keep that tab until the result is known. If the
+browser cannot save the pending request, it refuses a new restore. An unconfirmed
+result may mean files already changed: inspect them before continuing. Checking
+the same request does not automatically repeat an uncertain file operation. If
+only some files changed or the history save failed, the retained checkpoint can
+report a conflict; inspect and resolve the files before a fresh restore attempt.
+
+
+## Try the complete workflow
+
+Use a disposable Git project with an initial commit and a passing test command.
+For personal mode, open it in `piagent dashboard`. For company mode, select its
+company conversation.
+
+1. Open a tracked file in Files, make a small change and save with Cmd/Ctrl+S.
+2. Open Terminal, run the project's test command and inspect its exit status.
+3. Keep a different tracked file open. Ask the agent to read and edit that file
+   using edit/write. After the turn, inspect the added and removed inline lines.
+4. Choose Keep and check that the file content stays unchanged. Ask for a second
+   turn creating a small new file. Avoid shell edits for this attribution check.
+5. On the first agent turn, choose Restore before this turn. Check that the
+   preview lists both turns and both files, then confirm.
+6. Verify that the original file is restored, the new file is removed, and your
+   saved change from step 1 remains. HEAD and the staging area stay unchanged.
+
+The `ide-editor-terminal` soak scenario separately exercises guarded editor saves
+and terminal tests through the WebUI protocol. Its oracle self-check and transport
+tests do not by themselves prove a completed run against a live model.

package/docs/languages.json

@@ -21,8 +21,8 @@
       "en": "README.md",
       "vi": "README.vi.md",
       "consistentAt": {
-        "en": "5bc07f53997a89aeede83ee1208b1978d390b256",
-        "vi": "44f4ce7fbda88734c40295a1b5d7bcc5082c46f2"
+        "en": "3a2494ac972f9c6859c66a7b977a3d0d12a65aca",
+        "vi": "c13e5aba7ff4b785d25a242617f57440b6b782eb"
       }
     },
     {
@@ -48,8 +48,8 @@
       "en": "docs/en/maintainer-guide.md",
       "vi": "docs/vi/maintainer-guide.md",
       "consistentAt": {
-        "en": "e04ab2a64da66c59fbc2f52b472db481815c6ea5",
-        "vi": "8ce84e7221156cfa3882e29d50045be989d1ea7d"
+        "en": "f54ad1af538e0dcde9f899219a3c70f76aeb8fef",
+        "vi": "51420ffcc8c4675eefaf31e08be9231c6521c2b9"
       }
     },
     {
@@ -60,6 +60,15 @@
         "en": "8bf18c59e1a99a57747a1d68775f43379d24e7af",
         "vi": "b6681a5be29c2891568d0cdbc26890b3b8f9570f"
       }
+    },
+    {
+      "topic": "workspace-editor",
+      "en": "docs/en/workspace-editor.md",
+      "vi": "docs/vi/workspace-editor.md",
+      "consistentAt": {
+        "en": "5e0866a133a9cf965abfd0877205d9177eb0fde6",
+        "vi": "cad370bbfb798d2b6459e1067b4bd5f9d9b47ed3"
+      }
     }
   ]
 }

package/docs/operator-manual-vietnamese.md

@@ -19,12 +19,12 @@ Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 +
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0
-npm install -g --ignore-scripts @piagent/platform@1.37.1
+npm install -g --ignore-scripts @piagent/platform@1.38.2
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.37.1`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.38.2`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
 
 Nếu đang ở source checkout của platform, dùng helper theo channel để preview trước khi đổi:
 
@@ -100,7 +100,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0
-npm install -g --ignore-scripts @piagent/platform@1.37.1
+npm install -g --ignore-scripts @piagent/platform@1.38.2
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -285,7 +285,7 @@ Không phải daily default. Dùng khi muốn tạo sẵn `.pi` files cho projec
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --project-only \
   --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.37.1 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.38.2 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -999,8 +999,8 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 
 | Command | Dùng để |
 |---|---|
-| `npm install -g --ignore-scripts @piagent/platform@1.37.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.37.1` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.38.2` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.38.2` | Install pinned release cho reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Install latest platform package cho máy cá nhân/sandbox. |
 | Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. Mỗi release pin một Pi host chính xác; lấy đúng version của release đang cài trong [release/install policy](release-install-policy.md). |
 | Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá lại dependency findings của host cũ trước khi hạ version. |
@@ -1096,7 +1096,7 @@ Mở lại Pi session sau khi install.
 Cài lại terminal helper đúng release rồi kiểm tra `PATH`:
 
 ```bash
-npm install -g --ignore-scripts @piagent/platform@1.37.1
+npm install -g --ignore-scripts @piagent/platform@1.38.2
 command -v piagent-install
 ```
 

package/docs/publishing-for-teams.md

@@ -41,6 +41,9 @@ pi install /path/to/piagent
 
 ## Versioning
 
+- `1.38.2`: khung Tệp là cây thư mục như VS Code; theme màu (Piagent, Dracula, One Dark, Monokai, Nord, Tokyo Night, Catppuccin Mocha, Gruvbox, Solarized, GitHub) cho giao diện, editor và terminal, lưu trên trình duyệt (`piagent-webui-theme`); editor và terminal ghim dưới header khi hội thoại cuộn, có thanh chia độ rộng.
+- `1.38.1`: nội dung như 1.38.0; 1.38.0 có tag nhưng không được publish vì hai test của bước kiểm tra phát hành (fixture Linux của terminal công ty, thời gian chờ thẻ duyệt).
+- `1.38.0`: (tag, không publish) dashboard thành editor (file, tìm kiếm, lưu có kiểm tra xung đột, đổi tên/xóa, terminal cá nhân và công ty, review hunk Giữ/Hoàn tác, Timeline khôi phục lượt dùng chung checkpoint với `/undo`); quyền `bypass` cho cuộc trò chuyện cá nhân; cuộc trò chuyện công ty có `bypass` khi `harness.configuration.bypass_mode` là `true` (Agent Studio 0.38.0, Agent Watch 0.15.14 / Windows 0.1.17), "Toàn quyền" là `trusted-full-access`; `/bypass on|full|off`.
 - `1.37.1`: đóng run lỗi rồi hỏi lại chỉ được ghi là đã đóng khi Agent Watch gửi lại thật (`close-retry`, Agent Watch 0.15.11 / Windows 0.1.16); với Agent Watch cũ run để mở và được khôi phục khi mở lại cuộc trò chuyện; đóng role của helper đi qua cùng cơ chế chờ Studio và không làm hỏng câu trả lời; settlement gửi lại khi lỗi tạm thời; bài học lệnh lỗi lặp theo cả câu lệnh; file feedback skill riêng cho từng tên; serve cũ bị bỏ khi đổi key; bảo mật: `web_fetch` và package proxy chặn địa chỉ nội bộ ở mọi dạng IPv6 (mapped/NAT64/6to4 dạng hex), package proxy kiểm tra và ghim địa chỉ cả khi có `HTTPS_PROXY`.
 - `1.37.0`: câu trả lời Studio báo "Request interrupted" (upstream bị cắt giữa chừng) được hỏi lại như `upstream_interrupted` thay vì dừng task; thêm `piagent studio --rpc` cho script điều khiển một cuộc trò chuyện công ty; bộ soak task dài `evals/long-task-soak-v1` (chỉ trong repo).
 - `1.36.1`: lỗi `managed-broker` (Agent Watch không tới được Studio) trong lúc Studio vẫn trả lời heartbeat được hỏi lại, chờ tăng dần từ 2 giây, tối đa 3 phút kể từ request thành công gần nhất, rồi mới báo lỗi; bước đóng run cuối lượt cũng vậy; mỗi lần chờ ghi vào `studio-link.jsonl` và báo về Studio (`broker_offline`).

package/docs/release-install-policy.md

@@ -153,7 +153,7 @@ Use this flow when the team needs both terminal commands and the Pi package:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0
-npm install -g --ignore-scripts @piagent/platform@1.37.1
+npm install -g --ignore-scripts @piagent/platform@1.38.2
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -179,7 +179,7 @@ bash scripts/install-global.sh --stable
 Use this only when terminal commands are not needed:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.37.1
+pi install git:github.com/Vt-mmm/piagent@v1.38.2
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.