@piagent/platform 1.1.0 → 1.1.1

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.1 - 2026-07-26
+
+Fixes for defects found reviewing v1.1.0 after it shipped.
+
+### Fixed
+
+- `piagent-setup --no-mcp` installs no MCP again. Setup only ever appended `--with-mcp` and relied on the installer defaulting MCP off; v1.1.0 changed that default to on, so the opt-out reached the installer as silence and the installer's default overrode the operator's explicit choice. It now passes `--no-mcp` through. The other install flags stay one-sided because the installer still defaults them off, which is the condition that made the pattern safe in the first place.
+- `npm run site:check` no longer hangs when a response exceeds the 4 MB body cap. Hitting the cap destroys the response, and a destroyed response emits neither `end` nor `error` — it goes to `aborted` and `close` — so the promise stayed pending forever, and the request timeout could not rescue it because the socket was already gone. A release gate that hangs is worse than one that fails, because nothing reports it. A body cut short is also now reported as cut short rather than as a page that does not mention the version, which is a different claim.
+- `npm run site:check` no longer exits `0` when it could not check an address. Unreachable addresses were printed as `UNVERIFIED` and then the run still ended in `PASS`, so a gate that verified fewer addresses than it resolved reported that it had verified them all. An unchecked address now ends the run; `--allow-unverified` accepts the gap deliberately and names it in the summary.
+- `piagent_document_read` refuses bytes that are not valid UTF-8 or UTF-16 instead of decoding them into replacement characters. The binary check was a scan for a NUL byte, which plenty of binary formats do not carry in their first bytes, and everything past it was decoded leniently — so a binary file renamed to `.txt` came back as content-shaped garbage and was handed to the model. Decoding is now strict in both encodings, which is what the surrounding code already claimed to do.
+- Two CodeQL high alerts came from building a regular expression out of a version string and escaping only `.`. Those assertions were comparing literal text, so they are substring checks now and need no escaping at all. Two further alerts were reviewed and dismissed with written reasons: extracting `&lt;script&gt;` from a document as `<script>` is the required result and the sink is a terminal tool result, not HTML; and the SHA-256 over a normalised shell command is a content identifier, not a password hash.
+
+### Changed
+
+- The release checklist now requires the **Code scanning results** check on the `main` ruleset, separately from the `analyze (...)` jobs. Requiring those jobs proves only that the analysis ran and uploaded its results — they succeed just as well when the analysis found new high-severity alerts, which is how v1.1.0 merged green with open ones.
+
 ## v1.1.0 - 2026-07-26
 
 A document downloaded outside the repository can now be read by the agent, and the two documented install commands stop disagreeing about MCP.

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.0` 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.1` or a reviewed commit.
 
 Ready for:
 

package/docs/command-reference-vietnamese.md

@@ -419,8 +419,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@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.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.1.0` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.1.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.1.1` | 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. |
 | 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, npm-global 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á dependency risk của host cũ trước khi hạ version. |

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.0` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.1.1` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.1.0` |
+| Registry distribution | `npm:@piagent/platform@1.1.1` |
 | 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.0` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.1.1` | 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.0
+pi install git:github.com/Vt-mmm/piagent@v1.1.1
 ```
 
 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.0
+npm install -g --ignore-scripts @piagent/platform@1.1.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.1.0` 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.0`.
+`pi install git:github.com/Vt-mmm/piagent@v1.1.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.1.1`.
 
 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.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.1.1 \
   --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.0
+npm install -g --ignore-scripts @piagent/platform@1.1.1
 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.0`. 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.1`. 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.0
+npm install -g --ignore-scripts @piagent/platform@1.1.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -269,7 +269,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.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.1.1 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -842,8 +842,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.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.1.0` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.1.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.1.1` | 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. |
@@ -940,7 +940,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.0
+npm install -g --ignore-scripts @piagent/platform@1.1.1
 command -v piagent-install
 ```
 

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.0 | Rollout guidance |
+| Surface | Status for v1.1.1 | 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.0` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.1.1` | 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.0
+npm install -g --ignore-scripts @piagent/platform@1.1.1
 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.0 (helper package version)
-tag: v1.1.0
+currentRelease: v1.1.1 (helper package version)
+tag: v1.1.1
 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.0
+pi install git:github.com/Vt-mmm/piagent@v1.1.1
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.
@@ -192,9 +192,12 @@ Before broad team access, a repository administrator must enable these external
 3. Enable Dependency graph, Dependabot alerts, and Dependabot security updates. Keep `.github/dependabot.yml` enabled for scheduled npm and GitHub Actions update pull requests.
 4. Enable GitHub private vulnerability reporting so the form linked by `SECURITY.md` works before public rollout.
 5. Keep secret scanning and push protection enabled. Review CodeQL results after the workflow's first successful run.
+6. Add the **Code scanning results** check to the `main` branch ruleset and set its alert threshold so that a new high-severity CodeQL alert blocks the merge. The `analyze (...)` jobs required above only prove the analysis ran and uploaded its SARIF; they succeed just as well when the analysis found new high-severity alerts. Without this separate check, a pull request merges green with open high alerts, which is what happened on `v1.1.1`. Requiring the `analyze` jobs is still necessary — it catches an analysis that failed to run — but it is not the results gate and must not be mistaken for one.
 
 Verify these settings in GitHub **Settings → Rules** and **Settings → Code security and analysis**. Treat any missing control as an explicit rollout blocker, not as a passing source-code gate. Repository rules also close the remaining mutability risk of bootstrap-by-tag; tag-to-SHA resolution inside `piagent-install` alone cannot protect the helper package before it starts.
 
+Alerts dismissed as false positives carry their reason in the dismissal comment, and the reason belongs in the source as well when the flagged shape is deliberate. An alert dismissed without a written reason is indistinguishable from an alert nobody read.
+
 ### Required npm publishing controls
 
 The publish workflow authenticates with the `NPM_TOKEN` repository secret. That token needs three things, and read-and-write access alone is not enough:
@@ -270,7 +273,9 @@ Re-running the workflow from a branch instead skips publishing, because the publ
    npm run site:check
    ```
 
-   Opening the site in a browser does not answer this. The domain has several address records, so one can be dead or looping while every manual look lands on a healthy one. This resolves both hosts, asks each address directly with the right `Host` header and SNI, and requires each to return the released version. A redirect from an address back to its own host is reported as a loop rather than followed. An address the machine has no route to is reported as unverified, not as a pass.
+   Opening the site in a browser does not answer this. The domain has several address records, so one can be dead or looping while every manual look lands on a healthy one. This resolves both hosts, asks each address directly with the right `Host` header and SNI, and requires each to return the released version. A redirect from an address back to its own host is reported as a loop rather than followed.
+
+   An address the machine has no route to ends the run. It is reported separately from a site failure, because the machine is what is missing rather than the site, but it is not a pass either — the release gate must not report that it verified every address in a run where it verified fewer. Run the check from a machine with routes to every address family the domain publishes. `--allow-unverified` accepts the gap deliberately and names it in the summary; use it only when the missing route is understood and the remaining addresses were verified.
 9. Publish the already-reviewed draft only after production verification passes:
 
    ```bash

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.0, 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.1, 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

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.0
+npm install -g --ignore-scripts @piagent/platform@1.1.1
 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.0
+npm install -g --ignore-scripts @piagent/platform@1.1.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```

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.0 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.1.1 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.0</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.1</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.0",
+  "version": "1.1.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public",

package/packages/piagent-core/extensions/document-intake.ts

@@ -288,6 +288,17 @@ function decodeXmlEntities(value: string): string {
     .replace(/&/g, "&");
 }
 
+// Stripping markup and then decoding entities is the shape of an incomplete
+// sanitizer, and static analysis flags it as one: a document containing the
+// literal text `&lt;script&gt;` comes out as `<script>`. That is not a defect
+// here, it is the required result — the document shows those characters to a
+// reader, so extraction has to reproduce them. What makes it safe is the sink.
+// This text becomes a Pi tool result, `{ type: "text" }`, rendered in a
+// terminal; the shipped package contains no HTML sink at all. Untrusted
+// document content is separately redacted and wrapped in a region delimited by
+// a marker the document cannot predict. If any renderer that interprets markup
+// is ever added downstream, escaping belongs at that boundary, not here, where
+// it would corrupt the extracted text for every existing caller.
 export function extractDocxText(buffer: Buffer): DocumentExtraction {
   const document = readZipEntry(buffer, "word/document.xml");
   if (document.status === "error") return document;
@@ -337,6 +348,20 @@ function finish(text: string, kind: "text" | "docx" | "pdf"): DocumentExtraction
 // UTF-16 is half NUL bytes by design, so the binary check has to know about it
 // before it runs, and a byte-order mark is the only signal available without
 // guessing. Everything without a mark is treated as UTF-8.
+//
+// Decoding is strict in both encodings. Buffer.toString substitutes U+FFFD for
+// anything it cannot decode, which turns a binary file renamed to .txt into
+// "text" made of replacement characters — the exact outcome the extension gate
+// exists to prevent. A NUL scan does not catch it either: plenty of binary
+// formats carry no NUL in their first bytes.
+function decodeStrict(bytes: Buffer, encoding: "utf-8" | "utf-16le"): string | undefined {
+  try {
+    return new TextDecoder(encoding, { fatal: true }).decode(bytes);
+  } catch {
+    return undefined;
+  }
+}
+
 function decodeTextBuffer(buffer: Buffer): string | undefined {
   if (buffer.length >= 4 && buffer[0] === 0xff && buffer[1] === 0xfe && buffer[2] === 0x00 && buffer[3] === 0x00) {
     return undefined;
@@ -346,13 +371,13 @@ function decodeTextBuffer(buffer: Buffer): string | undefined {
   if (utf16Little || utf16Big) {
     const body = buffer.subarray(2);
     if (body.length % 2 !== 0) return undefined;
-    return utf16Big ? Buffer.from(body).swap16().toString("utf16le") : body.toString("utf16le");
+    return decodeStrict(utf16Big ? Buffer.from(body).swap16() : body, "utf-16le");
   }
   if (buffer.includes(0)) return undefined;
   if (buffer.length >= 3 && buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf) {
-    return buffer.subarray(3).toString("utf8");
+    return decodeStrict(buffer.subarray(3), "utf-8");
   }
-  return buffer.toString("utf8");
+  return decodeStrict(buffer, "utf-8");
 }
 
 export function extractTextDocument(buffer: Buffer): DocumentExtraction {
@@ -360,7 +385,10 @@ export function extractTextDocument(buffer: Buffer): DocumentExtraction {
   // otherwise rather than emit replacement characters that read like content.
   const decoded = decodeTextBuffer(buffer);
   if (decoded === undefined) {
-    return { status: "error", reason: "file has a text extension but contains binary data" };
+    return {
+      status: "error",
+      reason: "file has a text extension but its bytes are not valid UTF-8 or UTF-16 text; it is binary or in some other encoding"
+    };
   }
   return finish(decoded.replace(/\r\n?/g, "\n"), "text");
 }

package/packages/piagent-core/package.json

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

package/scripts/check-published-site.mjs

@@ -30,15 +30,20 @@ function fail(message) {
 }
 
 function parseArguments(values) {
-  const options = { hosts: [], expect: null };
+  const options = { hosts: [], expect: null, allowUnverified: false };
   for (let index = 0; index < values.length; index += 1) {
     const option = values[index];
     if (option === "-h" || option === "--help") {
-      process.stdout.write("Usage: node scripts/check-published-site.mjs [--host <name>]... [--expect <text>]\n");
+      process.stdout.write("Usage: node scripts/check-published-site.mjs [--host <name>]... [--expect <text>] [--allow-unverified]\n");
       process.stdout.write("Verify every resolved address of the docs site serves the released version.\n");
       process.stdout.write("Defaults to piagent.io.vn and www.piagent.io.vn, expecting the root package version.\n");
+      process.stdout.write("--allow-unverified downgrades addresses this machine cannot route to from a failure to a note.\n");
       process.exit(0);
     }
+    if (option === "--allow-unverified") {
+      options.allowUnverified = true;
+      continue;
+    }
     const value = values[index + 1];
     if (option === "--host") {
       if (!value || value.startsWith("--")) fail("--host requires a value");
@@ -76,14 +81,30 @@ async function resolveAddresses(host) {
   return addresses;
 }
 
-function request(host, { address, family }) {
+// `port` and `tlsOptions` exist so the body-cap path can be driven against a
+// local server in a test. Nothing on the command line reaches them, and the
+// defaults are what every real run uses: port 443 and Node's own trust store.
+export function request(host, { address, family, port = 443 }, tlsOptions = {}) {
   return new Promise((resolve) => {
+    // Every path out of here has to settle exactly once. Capping the body
+    // destroys the response, and a destroyed response emits neither `end` nor
+    // `error` — it goes straight to `aborted` and `close`. Without a `close`
+    // handler the promise stays pending forever, and the request timeout cannot
+    // rescue it because the socket is already gone. That is a hung release gate,
+    // not a failed one.
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
     const call = https.request(
       {
+        ...tlsOptions,
         host: address,
         family,
         servername: host,
-        port: 443,
+        port,
         path: "/",
         method: "GET",
         headers: { Host: host, "User-Agent": "piagent-site-check" },
@@ -92,24 +113,31 @@ function request(host, { address, family }) {
       (response) => {
         let body = "";
         let bytes = 0;
+        let truncated = false;
         response.setEncoding("utf8");
         response.on("data", (chunk) => {
           bytes += Buffer.byteLength(chunk, "utf8");
           if (bytes > MAX_BODY_BYTES) {
+            truncated = true;
             response.destroy();
             return;
           }
           body += chunk;
         });
-        response.on("end", () => resolve({ status: response.statusCode, location: response.headers.location, body }));
-        response.on("error", (error) => resolve({ error: error.message, code: error.code }));
+        response.on("end", () =>
+          settle({ status: response.statusCode, location: response.headers.location, body, truncated })
+        );
+        response.on("error", (error) => settle({ error: error.message, code: error.code }));
+        response.on("close", () =>
+          settle({ status: response.statusCode, location: response.headers.location, body, truncated })
+        );
       }
     );
     call.on("timeout", () => {
       call.destroy();
-      resolve({ error: `no response within ${REQUEST_TIMEOUT_MS}ms` });
+      settle({ error: `no response within ${REQUEST_TIMEOUT_MS}ms` });
     });
-    call.on("error", (error) => resolve({ error: error.message, code: error.code }));
+    call.on("error", (error) => settle({ error: error.message, code: error.code }));
     call.end();
   });
 }
@@ -137,8 +165,13 @@ export function judge(host, hosts, expect, result, family) {
     return null;
   }
   if (result.status !== 200) return `HTTP ${result.status}`;
-  if (!result.body.includes(expect)) return `HTTP 200 but the page does not mention ${expect}`;
-  return null;
+  if (result.body.includes(expect)) return null;
+  // Not finding the version in a body that was cut short is not the same claim
+  // as not finding it in the page.
+  if (result.truncated) {
+    return `HTTP 200 but the response exceeded ${MAX_BODY_BYTES} bytes and the part read does not mention ${expect}`;
+  }
+  return `HTTP 200 but the page does not mention ${expect}`;
 }
 
 async function main() {
@@ -170,18 +203,38 @@ async function main() {
     }
   }
 
-  for (const entry of unverified) process.stdout.write(`UNVERIFIED: ${entry}\n`);
+  const summary = summarize({ checked, failures, unverified, expect: options.expect, allowUnverified: options.allowUnverified });
+  process.stdout.write(summary.out);
+  process.stderr.write(summary.err);
+  process.exit(summary.code);
+}
+
+// An address nobody checked is not an address that passed. Reporting it as
+// unverified and then exiting 0 makes the gate say "verified every address"
+// about a run that did not, so an unchecked address ends the run unless the
+// operator accepts the gap deliberately.
+export function summarize({ checked, failures, unverified, expect, allowUnverified }) {
+  let out = "";
+  for (const entry of unverified) out += `UNVERIFIED: ${entry}\n`;
 
   if (failures.length > 0) {
-    process.stderr.write(`FAIL: ${failures.length} of ${checked} addresses do not serve ${options.expect}\n`);
-    for (const failure of failures) process.stderr.write(`  ${failure}\n`);
-    process.stderr.write("Each address is a real path users take. Fix the DNS records or the deployment behind them.\n");
-    process.exit(1);
+    let err = `FAIL: ${failures.length} of ${checked} addresses do not serve ${expect}\n`;
+    for (const failure of failures) err += `  ${failure}\n`;
+    err += "Each address is a real path users take. Fix the DNS records or the deployment behind them.\n";
+    return { code: 1, out, err };
+  }
+
+  if (unverified.length > 0 && !allowUnverified) {
+    let err = `FAIL: ${unverified.length} of ${checked} addresses could not be checked from this machine\n`;
+    for (const entry of unverified) err += `  ${entry}\n`;
+    err += "Run the check from a machine with a route to them, or pass --allow-unverified to accept the gap.\n";
+    return { code: 1, out, err };
   }
 
   const verified = checked - unverified.length;
-  const note = unverified.length > 0 ? ` (${unverified.length} not reachable from this machine)` : "";
-  process.stdout.write(`PASS: ${verified} of ${checked} addresses serve ${options.expect}${note}\n`);
+  const note = unverified.length > 0 ? ` (${unverified.length} accepted as not reachable from this machine)` : "";
+  out += `PASS: ${verified} of ${checked} addresses serve ${expect}${note}\n`;
+  return { code: 0, out, err: "" };
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

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.0 --resolve-tag
+  scripts/install-global.sh --version v1.1.1 --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.0 release matrix)' "$os_name" "$arch_name"
+      printf '%s/%s (outside v1.1.1 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.0 release matrix"*)
+    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.1.1 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/setup.sh

@@ -378,8 +378,13 @@ echo
 if [[ "$DO_GLOBAL" == true ]]; then
   ensure_pi_cli
   install_args=("$PLATFORM_ROOT/scripts/install-global.sh" "--package-source" "$PACKAGE_SOURCE")
+  # The opt-out has to be passed explicitly. The installer defaults MCP on, so
+  # saying nothing here would install it against the operator's choice; the
+  # flags below can stay one-sided only because the installer defaults them off.
   if [[ "$WITH_MCP" == true ]]; then
     install_args+=("--with-mcp" "--mcp-preset" "$MCP_PRESET")
+  else
+    install_args+=("--no-mcp")
   fi
   if [[ "$WITH_SUBAGENTS" == true ]]; then
     install_args+=("--with-subagents" "--subagents-preset" "$SUBAGENTS_PRESET" "--subagents-model-scope" "$SUBAGENTS_MODEL_SCOPE")

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.0 support matrix."
+    note: "This runtime is outside the documented v1.1.1 support matrix."
   };
 }