@piagent/platform 1.1.7 → 1.1.9

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.1.9 - 2026-07-28
+
+### Fixed
+
+- The update notice reaches the install path people actually use. v1.1.8 decided a platform tree was a maintainer's working copy when it found a `.git` directory in it — but `pi install git:...` clones the repository, so an ordinary install carries a `.git` and every other file a working copy carries. There is no mark inside the tree that separates them, which meant the notice never appeared for anyone who installed the documented way.
+
+  What separates them is where they sit: Pi puts packages it installed under its own agent directory, and npm puts the global helper under `node_modules`. A tree anywhere else is a working copy and is still told nothing. `PI_CODING_AGENT_DIR` is honoured, and both paths are resolved before comparison, because a home reached through a symlink is ordinary — macOS reaches `/var` that way — and comparing a real path against a symlinked one made an install look like it was somewhere else.
+
+## v1.1.8 - 2026-07-28
+
+### Added
+
+- Pi says when a release is out, and names the command that takes it. The notice appears in the session-start line as `Piagent update available: 1.1.7 -> 1.1.8. Run \`piagent-update\` to move this machine to it.` Nobody has to remember to go and check, which until now was the only way to find out.
+
+  It costs the session nothing. The session reads a cache and, when that cache is older than a day, leaves a detached `npm view` behind to refresh it — so the first session after a release may still be quiet and the next one carries the notice. This is the only network traffic the guard originates, it sends nothing about the project, and the registry's answer reaches the terminal only if it is exactly `MAJOR.MINOR.PATCH`, so neither a hostile registry nor an edited cache can put chosen text in front of an operator. A checkout is never told to update. `PIAGENT_NO_UPDATE_CHECK=1` switches it off.
+
 ## v1.1.7 - 2026-07-28
 
 A platform update is one global install. It was not behaving like one: every project that selected capability packs stopped working after a release until its profile was reapplied by hand, and the policy a release corrected never reached a project that had already onboarded.

package/README.md

@@ -283,7 +283,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.1.7` 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.1.9` or a reviewed commit.
 
 Ready for:
 

package/docs/capability-packs.md

@@ -240,7 +240,7 @@ Thư mục nguồn phải chứa `packs/`, nằm trong project, và không chứ
 piagent-capabilities vendor --profile .pi/piagent-profile.json
 ```
 
-Lệnh này ghi vào `.pi/capability-vendor/<name>/` và in digest để review trước khi commit. Đây là chỗ duy nhất chạm network. Resolve và guard chỉ đọc thứ đã có trên đĩa, nên pack không đổi được giữa lúc review và lúc chạy. Nguồn khai mà chưa vendor thì resolve fail — không im lặng chạy với ít pack hơn profile yêu cầu.
+Lệnh này ghi vào `.pi/capability-vendor/<name>/` và in digest để review trước khi commit. Đây là chỗ duy nhất trong đường capability chạm network — update check là đường riêng, xem `docs/security-threat-model.md`. Resolve và guard chỉ đọc thứ đã có trên đĩa, nên pack không đổi được giữa lúc review và lúc chạy. Nguồn khai mà chưa vendor thì resolve fail — không im lặng chạy với ít pack hơn profile yêu cầu.
 
 ### Vẫn deny by default
 

package/docs/command-reference-vietnamese.md

@@ -419,12 +419,13 @@ 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@0.82.0` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts @piagent/platform@1.1.7` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.1.7` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.1.9` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.1.9` | 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 một lệnh: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. Thêm `--project <path>` để chạy doctor sau. |
 | `piagent-update --version X.Y.Z` | Update tới đúng một release thay vì latest; dùng cho rollout theo lô hoặc rollback. |
+| `PIAGENT_NO_UPDATE_CHECK=1` | Tắt notice "có bản mới" ở đầu session Pi. Mặc định bật, hỏi registry nhiều nhất một lần mỗi 24 giờ ở tiến trình nền. |
 | Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Sequence thủ công tương đương. Thứ tự bắt buộc: `piagent-install` fail nếu Pi host lệch bản pin và không tự cài host. Version pin của từng release nằm 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á dependency risk của host cũ trước khi hạ version. |
 | `piagent-install --stable --dry-run` | Preview Pi package matching với helper hiện tại; stable resolve tag → commit SHA. |

package/docs/distribution-standard.md

@@ -14,9 +14,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.1.7` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.1.9` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.1.7` |
+| Registry distribution | `npm:@piagent/platform@1.1.9` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -26,7 +26,7 @@ Latest tiện cho máy cá nhân muốn nhận cập nhật nhanh. Pin tag/commi
 
 | Channel | Command | Target | Policy |
 |---|---|---|---|
-| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.1.7` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.1.9` | Install the Pi package matching the helper. |
 | `exact` | `bash scripts/install-global.sh --version vX.Y.Z --resolve-tag` | Requested tag resolved to commit SHA | Pi-package-only rollout, rollback, and incident recovery. |
 | `dev` | `bash scripts/install-global.sh --dev` | Moving Git source | Personal/sandbox only; do not commit into project settings. |
 | `local` | `bash scripts/install-global.sh --local` | Current checkout path | Platform development only. |
@@ -53,7 +53,7 @@ Root `package.json` có `pi` manifest trỏ tới:
 Do đó team có thể:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.1.7
+pi install git:github.com/Vt-mmm/piagent@v1.1.9
 ```
 
 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.
@@ -65,12 +65,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@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.7
+npm install -g --ignore-scripts @piagent/platform@1.1.9
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.1.7` 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.1.7`.
+`pi install git:github.com/Vt-mmm/piagent@v1.1.9` 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.1.9`.
 
 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).
 
@@ -103,7 +103,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.1.7 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.1.9 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/operator-manual-vietnamese.md

@@ -18,12 +18,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@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.7
+npm install -g --ignore-scripts @piagent/platform@1.1.9
 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.1.7`. 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.1.9`. 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:
 
@@ -99,7 +99,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.7
+npm install -g --ignore-scripts @piagent/platform@1.1.9
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -281,7 +281,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.1.7 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.1.9 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -854,8 +854,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.1.7` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.1.7` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.1.9` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.1.9` | 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. |
@@ -952,7 +952,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.1.7
+npm install -g --ignore-scripts @piagent/platform@1.1.9
 command -v piagent-install
 ```
 

package/docs/publishing-for-teams.md

@@ -50,6 +50,8 @@ pi install /path/to/piagent
 - `1.1.5`: thêm `piagent-update` — một lệnh update cả Pi host, terminal helper và Pi package đúng thứ tự.
 - `1.1.6`: `be-readonly-fe` giữ được backend read-only trong monorepo, detect FE/BE đọc cả workspace, và rule detect gộp về một chỗ.
 - `1.1.7`: update global không còn chặn project đang chạy — lock chỉ block khi grant thật sự đổi, và profile dạng `extends` nhận policy từ platform đang cài thay vì giữ bản copy lúc onboard.
+- `1.1.8`: Pi báo ngay ở đầu session khi có release mới, kèm lệnh chạy update.
+- `1.1.9`: notice update hiện đúng trên bản cài bằng `pi install git:` — bản cài nhận diện theo vị trí thư mục, không theo `.git`.
 
 ## Không publish
 

package/docs/release-install-policy.md

@@ -10,7 +10,7 @@ This file is the canonical install, update, rollback, and release checklist. Oth
 
 All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.82.0`. The Pi host is installed as a Node CLI; Pi Agent Platform still defines its own release matrix because the terminal helpers and shell policy rely on Bash/POSIX behavior.
 
-| Surface | Status for v1.1.7 | Rollout guidance |
+| Surface | Status for v1.1.9 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -33,7 +33,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.1.7` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.1.9` | Fixed after resolution | Default for team rollout. |
 | `exact` | Tag, reviewed commit, or a tag resolved with `--resolve-tag` | Fixed when using a commit SHA | Pi-package-only roll forward, rollback, or reproduction. |
 | `dev` | `git:github.com/Vt-mmm/piagent` | Moving | Personal machine or sandbox only. |
 | `local` | `/path/to/piagent` | Local workspace | Platform development and dry-run validation. |
@@ -53,7 +53,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@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.7
+npm install -g --ignore-scripts @piagent/platform@1.1.9
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -61,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.1.7 (helper package version)
-tag: v1.1.7
+currentRelease: v1.1.9 (helper package version)
+tag: v1.1.9
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -79,7 +79,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.1.7
+pi install git:github.com/Vt-mmm/piagent@v1.1.9
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.

package/docs/security-threat-model.md

@@ -21,7 +21,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
 - Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
 - A human remains available to approve destructive and external-provider actions.
-- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.1.7, and WSL2 is experimental/unverified.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.1.9, and WSL2 is experimental/unverified.
 - Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
 
 ## Threat actors and failure modes
@@ -55,6 +55,16 @@ The final category is outside the containment capability of the Piagent guard. I
 
 `read-only`, `workspace-write`, and `trusted-full-access` change the allowed working scope; they do not disable protected paths, secret redaction, capability integrity, destructive confirmation, or external-provider confirmation. `trusted-full-access` is intended for an already trusted repository in an externally safe environment. It is not a bypass or sandbox mode.
 
+## Outbound network from a session
+
+A Pi session makes one outbound request of its own: at most once every 24 hours it leaves a detached `npm view @piagent/platform version` behind to learn whether a newer release exists. This is the only network traffic the guard originates.
+
+What it sends is an npm registry request for a public package and nothing else — no project path, no repository name, no profile, no telemetry. The registry reply reaches the terminal only if it matches `MAJOR.MINOR.PATCH` exactly; anything else is discarded rather than displayed, so a hostile or compromised registry response cannot become a line of attacker-chosen text in the operator's terminal. The answer is cached at `~/.pi/piagent-update-check.json`, an ordinary user-writable file whose worst case is suppressing the notice.
+
+The session never waits on it: the request runs in a detached process with no inherited stdio, and the notice appears on the session after the one that refreshed the cache. A checkout is never told to update.
+
+Set `PIAGENT_NO_UPDATE_CHECK=1` to switch it off. Nothing else changes.
+
 ## Security verification
 
 Release gates include policy regression tests, TypeScript checking, runtime smoke tests, redaction benchmarks, package-content inspection, release-identity checks, installer tests, exact Pi host/add-on dependency audit, and CI on Linux x64 plus the current macOS runner. CodeQL covers JavaScript/TypeScript and GitHub Actions.

package/docs/team-onboarding.md

@@ -9,7 +9,7 @@ Một thành viên mới không cần biết local path của maintainer. Luồn
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.7
+npm install -g --ignore-scripts @piagent/platform@1.1.9
 piagent-install --stable
 cd /path/to/project
 pi
@@ -42,7 +42,7 @@ Mặc định team dùng stable helper:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.7
+npm install -g --ignore-scripts @piagent/platform@1.1.9
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -70,7 +70,15 @@ piagent-update --check
 piagent-update --project /path/to/project
 ```
 
-`--check` chỉ báo version, không đụng gì. Lên đúng một bản cụ thể thì `piagent-update --version 1.1.7`.
+`--check` chỉ báo version, không đụng gì. Lên đúng một bản cụ thể thì `piagent-update --version 1.1.9`.
+
+Không cần ai nhớ đi kiểm tra: khi có release mới, Pi tự báo ngay ở dòng notice lúc mở session, kèm luôn lệnh chạy.
+
+```text
+Piagent update available: 1.1.7 -> 1.1.8. Run `piagent-update` to move this machine to it.
+```
+
+Version mới nhất được hỏi npm registry nhiều nhất một lần mỗi 24 giờ, ở tiến trình nền tách rời, nên session không chờ gì cả — lần mở đầu tiên sau khi có bản mới có thể chưa thấy notice, lần sau sẽ thấy. Checkout của maintainer không bao giờ được báo. Tắt bằng `PIAGENT_NO_UPDATE_CHECK=1`; chi tiết ở `docs/security-threat-model.md`.
 
 Sequence thủ công vẫn dùng được, và bắt buộc theo thứ tự này — `piagent-install` **fail** nếu Pi host lệch bản pin, nó không tự nâng host:
 

package/docs-site/index.html

@@ -798,7 +798,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.1.7 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.1.9 docs</span>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
@@ -934,7 +934,7 @@
               <article class="step">
                 <div>
                   <h3>Cài — hai lệnh</h3>
-                  <p>Cần Node.js 22.19.0 trở lên. Không cần cài Pi Coding Agent trước: <span class="inline-code">piagent-setup</span> tự cài đúng bản <span class="inline-code">0.82.0</span> mà release <span class="inline-code">v1.1.7</span> đang pin. Chạy nó ngay trong thư mục project — nó cài Pi package, khởi tạo <span class="inline-code">.pi/</span>, cài MCP baseline cùng subagents, rồi chạy doctor. Thêm <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span>, <span class="inline-code">--no-herdr</span> hoặc <span class="inline-code">--global-only</span> để bỏ bớt.</p>
+                  <p>Cần Node.js 22.19.0 trở lên. Không cần cài Pi Coding Agent trước: <span class="inline-code">piagent-setup</span> tự cài đúng bản <span class="inline-code">0.82.0</span> mà release <span class="inline-code">v1.1.9</span> đang pin. Chạy nó ngay trong thư mục project — nó cài Pi package, khởi tạo <span class="inline-code">.pi/</span>, cài MCP baseline cùng subagents, rồi chạy doctor. Thêm <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span>, <span class="inline-code">--no-herdr</span> hoặc <span class="inline-code">--global-only</span> để bỏ bớt.</p>
                   <div class="table-wrap compact-table">
                     <table>
                       <thead>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -103,7 +103,7 @@
   ],
   "scripts": {
     "verify": "bash scripts/verify-local.sh",
-    "test": "node --test tests/*.test.mjs",
+    "test": "PIAGENT_NO_UPDATE_CHECK=1 node --test tests/*.test.mjs",
     "test:policy": "node --test tests/policy-core.test.mjs",
     "test:golden": "node --test tests/golden-enforcement.test.mjs",
     "typecheck": "tsc --noEmit",

package/packages/piagent-core/capabilities/capability-core.js

@@ -803,7 +803,12 @@ function buildCoreIntegrity(root) {
     // project-shape.js picks the profile a project is offered, and the profile is
     // the document that carries protectedPaths and readOnlyPaths. Steering the
     // recommendation is a way to choose what the guard will end up enforcing.
-    "packages/piagent-core/extensions/project-shape.js"
+    "packages/piagent-core/extensions/project-shape.js",
+    // update-check.js is the one file here that enforces nothing. It is pinned
+    // for a different reason: it starts a process on session start and puts a
+    // line in the operator's terminal, so tampering with it buys code execution
+    // and a message the operator has been trained to trust.
+    "packages/piagent-core/extensions/update-check.js"
   ];
   return files.map((relativePath) => {
     const resolved = resolveRegularFile(root, relativePath, MAX_ARTIFACT_BYTES);

package/packages/piagent-core/extensions/piagent-guard.ts

@@ -40,6 +40,7 @@ import {
   redactSensitiveText
 } from "./redaction-core.js";
 import { detectProfileName } from "./project-shape.js";
+import { evaluateUpdateCheck, isInstalledPlatform, readUpdateCache, startUpdateProbe } from "./update-check.js";
 import { buildExtendingProfile, resolveProjectProfileDocument } from "../capabilities/project-profile.js";
 import {
   resolveCapabilityProfileDocument,
@@ -422,6 +423,23 @@ const DEFAULT_POLICY: BasePolicy = {
 // Which platform supplies the adapters is fixed by where this file is installed,
 // so it is resolved once here rather than threaded through every profile load.
 const PLATFORM_ROOT = findPlatformRoot(path.dirname(fileURLToPath(import.meta.url)));
+const UPDATE_CHECK_MODULE = fileURLToPath(new URL("./update-check.js", import.meta.url));
+
+// The installed version, read from the package this file ships in. A maintainer
+// working in the repository is not running a release and has nothing to update
+// to, so only a tree Pi or npm placed is given a version to compare.
+function installedPlatformVersion(): string | undefined {
+  if (!isInstalledPlatform(PLATFORM_ROOT)) return undefined;
+  return readJsonFile<{ version?: string }>(path.join(PLATFORM_ROOT, "package.json"))?.version;
+}
+
+function updateAvailabilityNotice(): string | undefined {
+  const installed = installedPlatformVersion();
+  if (!installed) return undefined;
+  const decision = evaluateUpdateCheck({ installed, cache: readUpdateCache(), now: Date.now() });
+  if (decision.probe) startUpdateProbe(UPDATE_CHECK_MODULE);
+  return decision.notice;
+}
 
 function loadPolicy(extensionDir: string): BasePolicy {
   const root = findPackageRoot(extensionDir);
@@ -3733,6 +3751,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
     if (permissionProfile.mode === "trusted-full-access") {
       ctx.ui.notify("Piagent permission profile trusted-full-access is active; protected paths, secret redaction, and destructive/external confirmations remain enforced.", "warning");
     }
+    // Last, so a release announcement never pushes a security warning out of
+    // the first thing the operator reads.
+    const updateNotice = updateAvailabilityNotice();
+    if (updateNotice) ctx.ui.notify(updateNotice, "info");
   });
 
   pi.on("input", async (event, ctx) => {

package/packages/piagent-core/extensions/update-check.js

@@ -0,0 +1,211 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+// Telling someone a new release exists is only useful if it costs them nothing.
+// A session start that waits on the registry pays a network round trip every
+// time Pi opens, for information that changes a few times a month, so the check
+// never runs in the session's path: the session reads a cache file and, when
+// that cache is old, leaves a detached process behind to refresh it. The notice
+// lands on this session if the cache already knew, and on the next one if it did
+// not.
+//
+// Everything read here comes from outside the process — a registry response and
+// a file any local process can write — so the only value that ever reaches the
+// terminal is a version string that matched RELEASE_VERSION. A registry that
+// answers with a sentence, or a cache someone edited to carry one, produces no
+// notice rather than a line of attacker-chosen text in the operator's terminal.
+
+const HELPER_PACKAGE = "@piagent/platform";
+const CACHE_FILE = "piagent-update-check.json";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const PROBE_TIMEOUT_MS = 10_000;
+const MAX_CACHE_BYTES = 4096;
+const RELEASE_VERSION = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+
+/**
+ * Whether this platform tree is an install rather than somebody's working copy.
+ *
+ * Identified by where it sits, not by what it contains. `pi install git:...`
+ * clones the repository, so an install made the ordinary way carries a `.git`
+ * directory and every other file a maintainer's checkout carries — there is no
+ * mark inside the tree that separates them. What does separate them is that Pi
+ * puts packages it installed under its own agent directory, and npm puts the
+ * global helper under node_modules. A tree anywhere else is a working copy, and
+ * telling its owner to install over it is worse than saying nothing.
+ *
+ * @param {string} platformRoot
+ * @param {{home?: string, env?: Record<string, string|undefined>}} [options]
+ * @returns {boolean}
+ */
+export function isInstalledPlatform(platformRoot, options = {}) {
+  if (typeof platformRoot !== "string" || platformRoot.length === 0) return false;
+  if (platformRoot.split(path.sep).includes("node_modules")) return true;
+  const env = options.env ?? process.env;
+  const configured = env.PI_CODING_AGENT_DIR?.trim();
+  const base = options.home ?? os.homedir();
+  const agentDir = configured || (typeof base === "string" && base.length > 0 ? path.join(base, ".pi", "agent") : undefined);
+  if (!agentDir) return false;
+  // Both sides are resolved before comparing. A home reached through a symlink
+  // is ordinary — macOS reaches /var that way — and comparing one real path
+  // against one symlinked path makes an install look like it is somewhere else.
+  const relative = path.relative(realPath(agentDir), realPath(platformRoot));
+  // Empty means the same directory, which is not a package inside it; a leading
+  // `..` or an absolute result means the tree is somewhere else entirely.
+  return relative.length > 0 && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+/** @param {string} value @returns {string} */
+function realPath(value) {
+  try {
+    return fs.realpathSync(value);
+  } catch {
+    return value;
+  }
+}
+
+/** @param {string} [home] @returns {string|undefined} */
+export function updateCacheFile(home) {
+  const base = home ?? os.homedir();
+  if (typeof base !== "string" || base.length === 0) return undefined;
+  return path.join(base, ".pi", CACHE_FILE);
+}
+
+/**
+ * A release version and nothing else. Prereleases and build metadata are
+ * rejected rather than parsed: this decides what to tell someone to install, and
+ * nudging an operator onto a prerelease is not what the notice is for.
+ * @param {unknown} value @returns {string|undefined}
+ */
+export function releaseVersion(value) {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return RELEASE_VERSION.test(trimmed) ? trimmed : undefined;
+}
+
+/**
+ * Compare two release versions numerically. `1.1.10` is after `1.1.9`, which
+ * string ordering gets backwards.
+ * @param {string} left @param {string} right @returns {number}
+ */
+export function compareReleaseVersions(left, right) {
+  const leftParts = left.split(".").map(Number);
+  const rightParts = right.split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] < rightParts[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+/** @param {string} [home] @returns {{latest?: string, checkedAt?: number}} */
+export function readUpdateCache(home) {
+  const file = updateCacheFile(home);
+  if (!file) return {};
+  try {
+    // A cache larger than this is not something this code wrote.
+    if (fs.statSync(file).size > MAX_CACHE_BYTES) return {};
+    const document = JSON.parse(fs.readFileSync(file, "utf8"));
+    const checkedAt = Date.parse(document?.checkedAt);
+    return {
+      latest: releaseVersion(document?.latest),
+      checkedAt: Number.isFinite(checkedAt) ? checkedAt : undefined
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** @param {string|undefined} home @param {string} latest @param {number} now @returns {boolean} */
+export function writeUpdateCache(home, latest, now) {
+  const file = updateCacheFile(home);
+  const version = releaseVersion(latest);
+  if (!file || !version) return false;
+  const document = {
+    schemaVersion: 1,
+    package: HELPER_PACKAGE,
+    latest: version,
+    checkedAt: new Date(now).toISOString()
+  };
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`);
+    fs.renameSync(temporary, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * What the session should do about updates, decided from state alone so it can
+ * be tested without a registry or a clock.
+ * @param {{installed?: string, cache?: {latest?: string, checkedAt?: number}, now: number, env?: Record<string, string|undefined>}} options
+ * @returns {{notice?: string, probe: boolean}}
+ */
+export function evaluateUpdateCheck(options) {
+  const env = options.env ?? process.env;
+  if (env.PIAGENT_NO_UPDATE_CHECK?.trim()) return { probe: false };
+
+  const installed = releaseVersion(options.installed);
+  const cache = options.cache ?? {};
+  const latest = releaseVersion(cache.latest);
+  const probe = !(typeof cache.checkedAt === "number" && options.now - cache.checkedAt < CACHE_TTL_MS);
+
+  if (!installed || !latest || compareReleaseVersions(latest, installed) <= 0) return { probe };
+  return {
+    probe,
+    notice: `Piagent update available: ${installed} -> ${latest}. Run \`piagent-update\` to move this machine to it.`
+  };
+}
+
+/**
+ * Leave the refresh behind and return. The child is detached with no inherited
+ * stdio, so nothing it does can hold the session open or write into the
+ * terminal.
+ * @param {string} moduleFile @param {{spawn?: typeof spawn}} [options]
+ * @returns {boolean}
+ */
+export function startUpdateProbe(moduleFile, options = {}) {
+  try {
+    const child = (options.spawn ?? spawn)(process.execPath, [moduleFile, "--probe"], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** @returns {string|undefined} */
+function fetchLatestVersion() {
+  const result = spawnSync("npm", ["view", HELPER_PACKAGE, "version", "--json"], {
+    encoding: "utf8",
+    timeout: PROBE_TIMEOUT_MS,
+    windowsHide: true
+  });
+  if (result.status !== 0 || typeof result.stdout !== "string") return undefined;
+  try {
+    return releaseVersion(JSON.parse(result.stdout));
+  } catch {
+    return undefined;
+  }
+}
+
+/** @param {{now?: number, home?: string, fetch?: () => string|undefined}} [options] @returns {boolean} */
+export function runUpdateProbe(options = {}) {
+  const latest = (options.fetch ?? fetchLatestVersion)();
+  // A registry that could not be reached leaves the cache alone, so the next
+  // session retries instead of recording "no update" as if it had been checked.
+  if (!latest) return false;
+  return writeUpdateCache(options.home, latest, options.now ?? Date.now());
+}
+
+if (process.argv[2] === "--probe" && process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runUpdateProbe();
+}

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "type": "module",
   "private": true,
   "license": "MIT",

package/scripts/install-global.sh

@@ -15,7 +15,7 @@ Package source examples:
   # Installs the stable tag after resolving it to a commit SHA.
 
   # Pin a specific release:
-  scripts/install-global.sh --version v1.1.7 --resolve-tag
+  scripts/install-global.sh --version v1.1.9 --resolve-tag
 
   # Preview the planned install/update without changing user config:
   scripts/install-global.sh --stable --dry-run
@@ -127,7 +127,7 @@ detect_runtime_surface() {
       printf 'native-windows/%s (not release-gated; terminal helpers require Bash semantics)' "$arch_name"
       ;;
     *)
-      printf '%s/%s (outside v1.1.7 release matrix)' "$os_name" "$arch_name"
+      printf '%s/%s (outside v1.1.9 release matrix)' "$os_name" "$arch_name"
       ;;
   esac
 }
@@ -135,7 +135,7 @@ detect_runtime_surface() {
 warn_runtime_surface_if_needed() {
   local surface="$1"
   case "$surface" in
-    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.1.7 release matrix"*)
+    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.1.9 release matrix"*)
       echo "WARN: runtime surface is $surface." >&2
       echo "WARN: For team rollout, run piagent-doctor plus the project smoke/verify suite on this machine before relying on it." >&2
       ;;

package/scripts/team-doctor.sh

@@ -137,7 +137,7 @@ function runtimeMatrixStatus() {
     surface: `${platform}/${arch}`,
     status: "outside-release-matrix",
     teamRolloutReady: false,
-    note: "This runtime is outside the documented v1.1.7 support matrix."
+    note: "This runtime is outside the documented v1.1.9 support matrix."
   };
 }