# Cập nhật AI Collab Bridge 0.3.29

Bản ổn định nội bộ cho macOS 14 trở lên, chip Apple Silicon. Địa chỉ mặc định: https://ai-collab-workspace.guvico.com. Bridge giữ cùng bundle identifier và namespace dữ liệu; thành viên dùng tài khoản và quyền của mình.

## Tải bộ cài

- [AI-Collab-Bridge-0.3.29-arm64.dmg](/downloads/AI-Collab-Bridge-0.3.29-arm64.dmg)
- [Mã SHA-256 để đối chiếu](/downloads/AI-Collab-Bridge-0.3.29-arm64.dmg.sha256)

Mã SHA-256 xác minh tính toàn vẹn khi tải. Kết quả chữ ký và phạm vi nghiệm thu được ghi trong manifest phát hành; chữ ký Apple Team nội bộ khác với Developer ID/notarization cho phân phối công khai.

## Chữ ký và công chứng Apple

Bộ cài dùng cùng Apple Team `583Q9859J2` và bundle identifier `vn.ai-collab.bridge.native` với bản đã phát hành. Kiểm chữ ký và nhận dạng qua cập nhật đã đạt.

Bản này chưa được notarize. Phép kiểm Gatekeeper trên máy build chưa chấp nhận tự động; đây là bản phân phối nội bộ, không phải bộ cài đã được Apple công chứng. Nếu macOS chặn mở, thành viên liên hệ người quản trị để xác minh bộ cài.

## Nâng cấp từ bản đang dùng

1. Lưu công việc và thoát Bridge cũ.
2. Cài bộ mới từ mục **Tải cầu nối**; thay ứng dụng tại `/Applications/AI Collab Bridge.app` bằng `Install.command` hoặc kéo vào Applications.
3. Giữ dữ liệu cấu hình và Keychain. Mở Bridge, kiểm danh sách workspace đã lưu. Nếu ứng dụng yêu cầu đăng nhập, dùng tài khoản của chính bạn; không dùng tài khoản hoặc token của owner.
4. Trong mỗi workspace, kiểm `AGENTS.md`. Nếu còn URL Railway cũ, sao lưu file rồi chỉ thay hai dòng URL dưới đây, giữ nguyên `projectKey`, `bridgeEndpoint` và mọi hướng dẫn riêng:

```text
- authorityOrigin: https://ai-collab-workspace.guvico.com
- bootstrapEndpoint: https://ai-collab-workspace.guvico.com/api/authority
```

Workspace mới có thể tải AGENTS.md từ đúng dự án trên Web theo quyền của thành viên. Không lấy AGENTS.md của dự án khác làm mẫu quyền.

5. Bấm **Làm mới**. AI client gọi lại `bridge_list_workspaces` và `authority_bootstrap` qua MCP local `http://127.0.0.1:47621/mcp`.

URL cũ từng được cấu hình riêng bằng `AI_COLLAB_BRIDGE_AUTHORITY` hoặc `--authority` vẫn có độ ưu tiên cao hơn mặc định; người vận hành cần đổi cấu hình đó sang URL mới. Bản cập nhật không âm thầm ghi đè cấu hình chủ động.

## Cài mới cho thành viên

Cài ứng dụng, đăng nhập tài khoản của mình, chọn workspace có AGENTS.md đúng dự án và URL mới. Danh sách project và khả năng thao tác do Authority quyết định. Lỗi membership 403 cần người quản lý kiểm quyền; đổi URL không tự mở quyền.

## Cách kiểm tra sau khi cập nhật

AI node cần gọi lại `tools/list`. Kết quả hợp lệ phải có:

```text
bridge_list_workspaces
authority_call_operation
authority_sync_skills
authority_log_work_event
```

AI node gọi `bridge_list_workspaces` để lấy `workspaceId` và `projectKey` đã được user đăng ký. Khi gọi operation cho một dự án, AI node truyền một trong hai giá trị này. AI node không có tool để tự thêm hoặc xóa workspace.

Khi task có skill, bridge mới sẽ sync skill về:

```text
.agents/skills
.agents/skills/<skillId>
```

Nếu vẫn thiếu `bridge_list_workspaces` hoặc `authority_sync_skills`, chưa dùng đúng bridge mới hoặc app Bridge chưa được khởi động lại.

## Nhật ký nhân quả của AI node

Từ `0.3.11`, AI node dùng `authority_log_work_event` để ghi các mốc có thể kiểm chứng như mục tiêu, quyết định, evidence, blocker và kết quả. Không ghi chain-of-thought (chuỗi suy luận nội bộ), token, mật khẩu, raw prompt hoặc source code.

Khi authority tạm mất kết nối, Bridge chỉ xếp hàng các lỗi mạng, `408`, `425`, `429` hoặc `5xx` vào `.agents/runtime/ai-work-event-spool.v1.json`. Dữ liệu được redaction trước khi ghi đĩa, giới hạn tối đa 200 event và tự gửi lại theo batch khi kết nối phục hồi. Lỗi đăng nhập hoặc sai schema không được xếp hàng để tránh che lỗi cần user hoặc AI node xử lý.

Trên Foundation v2, dùng biểu mẫu `activity-logs/append` và thao tác hiện hành của máy chủ để ghi nhật ký. Mỗi bản ghi phải gắn với người chịu trách nhiệm; AI node chỉ bổ sung quyết định, bằng chứng hoặc vấn đề mà máy chủ không thể tự ghi nhận. Không quay về thao tác legacy (hệ thống cũ) nếu công cụ đó không có trong danh sách hiện hành.

## Chế Độ Kiểm Chứng Hiện Hành

Kiểm tra phản hồi bootstrap có:

```text
operationCatalog.version = foundation-v2
bridgeCompatibility.validationExecutorRequired = false
foundation.validation.create
foundation.validation.report
```

Nếu thiếu cấu hình hoặc thao tác kiểm chứng, Bridge báo lỗi rõ ràng; không tự khởi động hàng đợi để thay thế. Không cần đăng ký executor (bộ chạy kiểm chứng nền), claim (nhận việc từ hàng đợi) hay lease (quyền nhận việc có thời hạn) của hệ thống cũ.

## Ghi Chú Lịch Sử

Các mục bên dưới mô tả các bản sửa trước Foundation v2 và chỉ dùng để đối chiếu. Những quy định về executor, queue (hàng đợi), lease và API cũ không phải yêu cầu của Foundation v2; luôn ưu tiên cấu hình khởi tạo hiện hành ở trên.

## Unix socket Nx trong validation job

Nx dùng Unix socket cục bộ cho daemon và tiến trình plugin. Đường dẫn workspace cô lập có thể vượt giới hạn socket của macOS dù source code và package script đều đúng.

Bridge `0.3.22` cấp `NX_SOCKET_DIR` ngắn, riêng biệt cho từng job. Sandbox chỉ cho bind, nhận và kết nối Unix socket bên trong đúng thư mục này; TCP và các đường dẫn ngoài policy vẫn bị chặn. Thư mục được dọn sạch sau khi job kết thúc để không để lại socket hoặc lock cũ cho lần chạy sau.

## Lỗi package script không khởi động khi mở Bridge từ Finder

Trước `0.3.19`, app đã đóng gói Node nhưng validation executor vẫn phụ thuộc vào `npm` trong `PATH` của terminal. Khi app được mở từ Finder, macOS không nạp cấu hình NVM/Homebrew nên lệnh build hoặc test có thể trả trạng thái rỗng dù source code hợp lệ.

Từ `0.3.19`, Bridge đóng gói cùng một bộ Node/npm, truyền `PATH` cố định cho executor và kiểm tra bộ công cụ ngay trong smoke test của app. Báo cáo thất bại đồng thời giữ mã lỗi và tên script có cấu trúc, không còn chỉ lưu 4.000 ký tự cuối làm mất nguyên nhân gốc.

## Lỗi brownfield trong isolated workspace

Bridge `0.3.9` có thể trả `BROWNFIELD_BASELINE_COMMIT_NOT_FOUND` vì workspace cô lập không chứa Git metadata. Nếu chỉ gắn lại history nhưng vẫn dùng `node_modules` symlink, validator tiếp tục trả `PROJECT_PACKAGE_DEPENDENCY_ROOT_UNTRUSTED`.

Bridge `0.3.10` tạo Git snapshot tối thiểu chứa baseline, HEAD và các object cần cho changed-path diff; dependency roots được materialize thành thư mục thật bằng APFS copy-on-write khi hệ thống hỗ trợ. Vì vậy validator có thể kiểm `git cat-file`, `merge-base`, baseline diff và executable package path ngay trong isolated project root.

Bridge `0.3.14` định nghĩa `.agents/` là namespace runtime do Bridge sở hữu. Khi dựng isolated snapshot, Bridge không copy runtime cũ từ source, thêm `.agents/` vào exclude cục bộ của snapshot rồi mới materialize skill đang chạy. Việc này không sửa `.gitignore` hoặc `.git/info/exclude` của repo thật; validator vẫn thấy đầy đủ mọi file source thay đổi, nhưng không còn đưa `.agents/skills/**` vào `missingFromSelection`.

Nếu tên folder repo local không trùng `repoKey` của authority, khai báo đường dẫn trong `.agents/validation-workspaces.json`:

```json
{
  "repositories": {
    "guvico-api": "source/guvico-api"
  }
}
```

Bridge `0.3.21` đọc lại file này trước khi claim mỗi batch job, nên user không cần thoát app sau khi thêm hoặc sửa mapping. Với repo có application root nằm trong thư mục con, khai báo rõ `projectSubpath`:

```json
{
  "repositories": {
    "goha-shipper": {
      "path": "source/Goha_shipper",
      "projectSubpath": "GohaApp"
    }
  }
}
```

Nếu không khai báo `projectSubpath`, Bridge chỉ tự suy ra khi repo có đúng một `package.json` ứng viên trong ba cấp thư mục. Nhiều ứng viên sẽ bị chặn với mã lỗi rõ ràng để tránh kiểm nhầm ứng dụng.

## Runtime Node và dependency của workspace cô lập

Bridge `0.3.21` đóng gói Node `18.18.0`, `20.11.0` và `20.17.0`, sau đó chọn bản cao nhất thỏa `package.json > engines.node`. Nếu project yêu cầu khoảng phiên bản ngoài catalog, executor trả `BRIDGE_PROJECT_NODE_RUNTIME_UNAVAILABLE` thay vì âm thầm chạy bằng Node của máy user.

`npm`, `Yarn` và `pnpm` trong app luôn dùng chính Node đã chọn. Vì vậy project yêu cầu `20.x` không còn bị Yarn từ chối do app Bridge đang chạy bằng Node 24.

Khi task worktree không có `node_modules`, Bridge chỉ được mượn dependency từ repo nguồn đã cấu hình nếu phần dependency trong `package.json` và toàn bộ lockfile trùng chính xác. Script build/test có thể khác giữa hai branch mà không tạo false blocker; thay đổi dependency hoặc lockfile sẽ fail-closed. Dependency được copy thành thư mục thật trong workspace cô lập, không dùng symlink ra ngoài sandbox.

## Phiên đăng nhập dài hạn và lỗi Unauthorized

Bản `0.3.18` không lưu một access token tĩnh 30 ngày. Access token có thời hạn 24 giờ và được tự gia hạn trước khi còn 15 phút; refresh credential có thời hạn tuyệt đối 30 ngày, được rotate sau mỗi lần dùng và chỉ lưu trong Keychain Session V3. Web khóa refresh giữa nhiều tab; Bridge đọc lại Keychain trước khi refresh và nhận kết quả của tiến trình đã rotate trước. Project-agent token cũng có thời hạn tối đa 24 giờ và luôn bị ràng buộc với session của user chịu trách nhiệm.

Session V3 được tạo mới bởi app có Apple Team ID và bundle identifier ổn định. Bridge chỉ đọc mục V2 để migrate khi macOS vẫn cho phép; nếu mục cũ mang ACL từ bản ad-hoc và không đọc được, user đăng nhập một lần trên `0.3.18` để tạo V3. Từ lần đó, quit/open app không yêu cầu đăng nhập lại khi session còn hạn.

Session bị thu hồi ngay khi user logout, đổi mật khẩu, bị vô hiệu hóa hoặc thay đổi quyền. Nếu refresh credential hết hạn, bị thu hồi hoặc không đọc được, Bridge mới quay về màn hình đăng nhập. Cơ chế này giữ phiên đủ lâu để làm việc nhưng không biến một token bị lộ thành credential sống 30 ngày.

Gói `0.3.10` tiếp tục dùng danh tính Apple và `designated requirement` (điều kiện nhận dạng ứng dụng) ổn định đã thiết lập từ `0.3.8`. Vì vậy, cập nhật từ `0.3.9` sang `0.3.10` giữ cùng danh tính để Keychain nhận ra đây vẫn là cùng một ứng dụng.

## Skill bị tự hạ version sau khi task đã rebind

Bản `0.3.10` coi `task.skills` là binding canonical. Các trường `requiredSkills`, `supportSkills`, `optionalSkills` chỉ được dùng cho task legacy chưa có binding canonical; `skillOutputs` chỉ là fallback cuối cùng, không được phép ghi đè version/hash đang được task bind. Bridge đồng thời:

1. Từ chối hai binding canonical cùng độ ưu tiên nhưng khác version hoặc hash.
2. Kiểm tra package tải về có đúng `skillId`, `version` và `contentHash` trước khi thay package local.
3. Lưu revision task cao nhất trong `.skill-lock.json` và bỏ qua response cũ đến muộn.
4. Xếp hàng toàn bộ quá trình đọc, tải, ghi package và lock theo từng workspace.

## Đọc task không được thay skill đang hoạt động

Từ `0.3.8`, việc lấy task, manifest hoặc dữ liệu project là thao tác chỉ đọc và không ghi vào `.agents/skills`. Bridge chỉ thay package đang hoạt động trong ba trường hợp:

1. AI node claim task bằng operation `progress.native.claim`.
2. AI node gọi `authority_sync_skills` cho task hoặc danh sách skill cụ thể.
3. AI node chủ động truyền `autoSyncSkills=true` vào `authority_call_operation`.

Vì vậy, đọc task project cha để lấy business contract không còn được phép hạ version của skill support đang hoạt động cho task repo con.

## Lỗi validation executor `409` sau khi Bridge chạy lâu

Bản `0.3.14` giữ nguyên contract hoàn tất report theo causal identity của `0.3.12`:

1. Khi app thoát, Bridge chờ validation executor dừng và cưỡng chế dừng nếu tiến trình không phản hồi.
2. Executor theo dõi tiến trình app cha; nếu app crash hoặc được thay phiên bản, executor cũ tự kết thúc.
3. Nếu hai worker vẫn gặp cùng một job trong lúc chuyển giao, `VALIDATION_JOB_LEASE_ACTIVE` được xem là job đã có worker khác nhận, không làm cả workspace chuyển sang trạng thái lỗi.
4. Bridge gia hạn lease lần cuối khi cần, chờ heartbeat đang chạy hoàn tất, sau đó đóng heartbeat trước khi upload report.
5. Server xác nhận quyền hoàn tất bằng `validationRunId + attemptId + leaseId + skill/package/input`, không dùng revision heartbeat làm danh tính report.
6. Nếu heartbeat đã tăng revision ngay trước report, server giữ heartbeat mới nhất, chuyển job sang `reported` đúng một lần và không đưa job về queue để reclaim lại.

## Lỗi `VALIDATION_JOB_AI_BRIDGE_REQUIRED`

Lỗi này trên bản `0.3.0` xảy ra khi AI node gọi tạo validation job qua `authority_call_operation`, nhưng Bridge gửi web session thay vì project-agent token có `nodeId`. Từ bản `0.3.1`, Bridge đọc `authMode` từ operation catalog và tự dùng đúng project-agent token của workspace. Sau khi cài lại, thoát hẳn Bridge cũ, mở Bridge mới, bấm `Làm mới` và gọi lại operation; không cần đăng ký lại workspace.

## Danh sách workspace và workspace mặc định dùng để làm gì

Danh sách workspace cho Bridge biết từng nơi cần đọc `AGENTS.md`, sync `.agents/skills` và chạy validation executor. Workspace mặc định chỉ là fallback khi operation không chỉ rõ `workspaceId` hoặc `projectKey`; nó không giới hạn quyền filesystem tổng quát của ứng dụng AI. Mỗi workspace phải có `Authority Pointer` hợp lệ và tài khoản phải có membership trong project tương ứng. AI node chỉ được chọn workspace đã có trong registry, không được âm thầm thay cấu hình user.

Một member có thể đăng ký đồng thời Guvico, Goha và AI Collab Workspace. Bridge vẫn dùng một endpoint MCP, nhưng tách skill, token project và validation theo từng project. Một executor lỗi không làm dừng executor của workspace khác.

## Lỗi `Failed to connect to 127.0.0.1 port 47621`

Lỗi này nghĩa là AI node đang gọi đúng port bridge mặc định, nhưng AI Collab Bridge local chưa listen tại port đó. Cách xử lý:

1. Thoát bridge cũ.
2. Cài `AI-Collab-Bridge-0.3.23-arm64.dmg`.
3. Mở lại AI Collab Bridge và đăng nhập.
4. Kiểm tra trạng thái trong app phải thấy `Bridge đang chạy tại http://127.0.0.1:47621/mcp`.
5. Chạy lại AI node sau khi bridge đã chạy.