@galaxy-stack/ai-coder-core 0.1.0 → 0.3.0-alpha.7

package/CHANGELOG.d/2026-09-19-advisory-guard-policy.md

@@ -0,0 +1,25 @@
+# Advisory guard policy cho observation (2026-09-19 00:15 +07:00)
+
+### Added
+
+- `AiCoderRunBudget.noProgressPolicy`: `advisory` (mặc định) và `strict`.
+- `AiCoderRunBudget.observationNudgeThresholds` (mặc định `[3, 5, 8]`, theo
+  tư tưởng repeat-tool-reminder của DeepSeek Harness): các mốc nhắc advisory
+  cho observation đọc-only; block chỉ xảy ra sau mốc cuối.
+- Checkpoint lưu `noProgress.policy` và `noProgress.observationNudgeThresholds`;
+  resume với cấu hình khác bị từ chối `CHECKPOINT_INCOMPATIBLE`, checkpoint cũ
+  không có trường này vẫn resume được (legacy).
+- Trace `policy_decision` cho `observation_nudge` và `observation_blocked`.
+
+### Changed
+
+- Nudge advisory không còn tăng `noProgressEpisodes`; quyết định pause chỉ đến
+  từ block thật hoặc guard mutation/validation/cycle. Chế độ `strict` giữ nguyên
+  hành vi cũ (nudge đầu tiên đếm episode, block theo `maxRepeatedToolRequests`).
+- Bộ đếm observation family đếm mọi lượt dispatch (kể cả thất bại), khớp hợp
+  đồng "requested" trong ARCHITECTURE.md.
+
+### Tests
+
+- 3 test runtime mới: advisory thresholds + block sau mốc cuối; advisory không
+  đếm episode; cấu hình fail-loud + checkpoint-bound trên resume.

package/CHANGELOG.d/2026-09-19-research-citation-parsing.md

@@ -0,0 +1,16 @@
+# Sửa parser citation bị nhiễu Markdown (2026-09-19 11:55 +07:00)
+
+### Fixed
+
+- `researchCitations` strip đuôi emphasis/punctuation lặp (`**`, `*`, `_`,
+  backtick, `:`, `;`) trước khi canonicalize, nên URL được model viết kiểu
+  `**https://example.com/a**:` khớp với URL đã fetch. Trước đó report
+  durable-research bị oracle từ chối sai hai citation hợp lệ
+  (INC-001 trong `galaxy-code/docs/TEST_FAILURE_ANALYSIS.md`).
+- Giữ nguyên xử lý ngoặc cân bằng; URL chỉ-search (model tự ghi "not fetched")
+  vẫn bị từ chối đúng.
+
+### Tests
+
+- Test mới: bold/italic/backtick/colon, dedupe, và trường hợp URL thật kết thúc
+  bằng `*` (được strip — trade-off đã ghi trong incident register).

package/CHANGELOG.d/2026-09-19-research-rejection-evidence.md

@@ -0,0 +1,15 @@
+# Lưu evidence khi citation bị từ chối (2026-09-19 23:15 +07:00)
+
+### Added
+
+- Event `completion_rejected` lưu nguyên candidate và ba tập URL: fetch thành
+  công, chỉ xuất hiện ở search, và citation không có fetch evidence; source
+  ledger giữ `toolCallId` và `contentHash` để ghép lại tool result.
+- Feedback cho model liệt kê nguồn đã fetch để model sửa report thay vì lặp
+  nguyên candidate hoặc tự đoán URL khác. Đây là phần core của INC-010 trong
+  `galaxy-code/docs/TEST_FAILURE_ANALYSIS.md`.
+
+### Tests
+
+- Regression runtime tạo search-only + fetched source, từ chối candidate đầu,
+  kiểm tra event/feedback có đủ ledger, rồi hoàn thành bằng citation đã fetch.

package/CHANGELOG.d/2026-09-19-test-journal-reporter.md

@@ -0,0 +1,8 @@
+# Node test reporter ghi nhật ký (2026-09-18 23:45 +07:00)
+
+### Added
+
+- Reporter Node development-only (`scripts/test-journal-reporter.mjs`): `npm test`
+  ghi `TEST_ERROR_LOG.md` và `.galaxy/tests/<run>/` (events.jsonl, summary.json,
+  summary.md) với timestamp từng assertion, stack lỗi, số đếm test, commit và
+  source fingerprint. Không thêm dependency runtime, không đổi public exports.

package/CHANGELOG.d/2026-09-21-evidence-missing-remediation.md

@@ -0,0 +1,15 @@
+# Remediation cho RESEARCH_EVIDENCE_MISSING (2026-09-21 02:20 +07:00)
+
+### Changed
+
+- Completion rejection giờ có dòng remediation riêng cho `RESEARCH_EVIDENCE_MISSING`,
+  nêu tên tool (`search_web` cho discovery, `fetch_url` cho đọc nguồn) và nói rõ
+  fetch-only không thỏa search requirement. Trước đây issue chỉ nêu số lượng
+  ("search calls 0/1") nên model dưới compaction cao không có hướng hành động
+  (run [OycseO](../../galaxy-code/.galaxy/audit/2026-09-20T18-36-41-606Z-OycseO/summary.json)
+  durable repeat-3: 0 search, 3 fetch, 2 rejection, NO_PROGRESS).
+
+### Tests
+
+- Core 108/108 pass, thêm regression: model fetch-only bị từ chối, nhận feedback
+  nêu tên tool, gọi `search_web` sau rejection rồi hoàn thành.

package/CHANGELOG.d/2026-09-21-observation-nudge-context.md

@@ -0,0 +1,12 @@
+# Nudge nhận diện bằng arguments hash (2026-09-21 00:55 +07:00)
+
+### Changed
+
+- Advisory observation nudge giờ kèm `arguments_hash` để model thấy chính xác
+  lệnh nào đang lặp, thay vì chỉ biết có sự lặp. Đây là phiên bản tiết kiệm
+  budget của tư tưởng deepseek-harness "giữ full canonical arguments để nhận
+  diện": nhận diện vẫn dùng toàn bộ arguments, lời nhắc chỉ mang hash.
+
+### Tests
+
+- Core 107/107 pass (`npm test`), không có test assert nội dung nudge cũ bị phá.

package/CHANGELOG.d/2026-09-22-model-retry-budget.md

@@ -0,0 +1,18 @@
+# Retry delay theo scenario budget + deadline-aware skip (2026-09-22 07:25 +07:00)
+
+### Changed
+
+- Bảng backoff giữa các model request retry trở thành budget knob
+  `modelRetryDelaysMs` (1-8 số nguyên dương, tối đa 600 000 ms mỗi entry) thay
+  vì `MODEL_RETRY_DELAYS` hardcode. Schedule được dùng theo thứ tự attempt và
+  báo trong sự kiện `model_retry`.
+- Retry deadline-aware: trước khi sleep, runtime kiểm tra budget còn lại; nếu
+  `deadline - now <= delay + thời gian attempt vừa fail` thì bỏ attempt, fail
+  loud với message nêu rõ còn bao nhiêu budget, backoff bao nhiêu và attempt
+  trước kéo dài bao nhiêu, thay vì dispatch một request chắc chắn chết.
+
+### Tests
+
+- Core 111/111 pass: budget schedule được dùng đúng thứ tự và report qua
+  `onEvent`; retry không đủ budget bị skip trước khi sleep; 6 case schedule
+  invalid fail loud tại validation.

package/CHANGELOG.d/2026-09-22-no-progress-recovery-turn.md

@@ -0,0 +1,19 @@
+# Recovery turn trước no-progress pause (2026-09-22 01:07 +07:00)
+
+### Changed
+
+- Khi `noProgressEpisodes` chạm ngưỡng pause lần đầu, runtime không pause ngay
+  mà chèn một feedback turn `[GALAXY NO-PROGRESS RECOVERY]` liệt kê failed
+  tools của round kèm remediation (re-read vùng đúng, whole-file write, đổi
+  nguồn), rồi cho model đúng một round nữa. Nếu round đó vẫn không tiến triển
+  thì pause như cũ. Đây là phiên bản two-strike của Gemini CLI
+  loopDetectionService cho Galaxy: giữ nguyên ngưỡng 2/2/2, không bỏ pause,
+  chỉ thêm đúng một cơ hội phục hồi có kiểm soát.
+- Trace runtime ghi `policy_decision` với `action:
+  "no_progress_recovery_turn"` để audit phân biệt lượt recovery với lượt pause.
+
+### Tests
+
+- Core 108/108 pass. Hash-cycle, resume-cycle, observation recovery, validation
+  recovery có fixture xác minh: recovery round được cấp đúng một lần; round
+  phục hồi thành công (đổi chiến lược) thì complete; round vẫn lặp thì pause.

package/CHANGELOG.d/2026-09-23-agent-platform.md

@@ -0,0 +1,5 @@
+# Agent platform foundation
+
+Add general agent profiles, optional MCP/skill/SQLite adapters and move the private live/replay lab into testing.
+
+Package and repository names are unchanged. See README and architecture/migration docs for current limitations and the release order.

package/CHANGELOG.d/2026-09-23-conservative-output-reserve.md

@@ -0,0 +1,16 @@
+## 0.3.0-alpha.7 — 2026-09-23 07:00 +07:00
+
+### Conservative profile output reserve bump (Mode B fix)
+
+**Lỗi:** `INVALID_MODEL_STREAM "length"` — model dùng hết output tokens (conservative profile chỉ reserve 24 000) chỉ để sinh thinking + tool-call JSON, chưa kịp write file nào (0 writes trên 14 chat requests).
+
+**Hệ thống khác xử lý:**
+- Codex CLI: tách budget riêng cho thinking và tool-call JSON, không chia sẻ cùng một output cap.
+- Claude Code: mỗi tool call có output budget riêng, không trộn với thinking.
+- Gemini CLI: dùng `thinking_config` để cấp thinking budget riêng khỏi output budget.
+
+**Fix Galaxy:** nâng `outputReserveTokens` của profile `conservative` từ 24 000 lên 32 768 (khớp balanced/extended). Không đổi toolDefinitionBudget hay softInputTokens. `AI_CODER_CONTEXT_PROFILE_CONFIG_VERSION` bump thành `"1.1.0"`.
+
+**File sửa:** `src/context/context-profile.ts`.
+
+**Test:** 112/112 core offline (chạy sau build). Không cần unit test mới — profile không được assert trực tiếp trong unit suite.

package/CHANGELOG.d/2026-09-24-approval-workspace-review.md

@@ -0,0 +1,7 @@
+# Request-scoped approvals and scratch workspace review
+
+Abort host approval prompts when their request expires or resolves; reject late approvals without canceling the parent run. Allow NodeToolExecutor hosts to choose their approval timeout.
+
+Add the optional NodeWorkspaceReviewExecutor for stable, bounded before/after text review without Git. It attests real diff-review evidence without weakening validation requirements. Update the prompt to use this tool when available.
+
+Validation: core verify (121 tests), 16 lab executor regressions and CLI end-to-end scratch-project completion, including a live provider run.

package/CHANGELOG.d/2026-09-24-incremental-ollama.md

@@ -0,0 +1,5 @@
+# Incremental Ollama streaming
+
+Decode NDJSON as bytes arrive instead of buffering the complete HTTP response. Share the stateful normalizer with replay, retain byte limits and UTF-8 correctness, and cancel body readers when requests or consumers stop. Late errors do not emit a duplicate started event.
+
+Validation: core verify, 13 transport tests, 7 normalizer tests and recorded replay; delayed HTTP→CLI rendering verifies deltas before EOF.

package/CHANGELOG.d/README.md

@@ -0,0 +1,16 @@
+# CHANGELOG.d
+
+Mỗi bản sửa đáng chú ý (behavior/API/tooling) được ghi thành một fragment trong
+thư mục này ngay khi hoàn thành, đặt tên `YYYY-MM-DD-ten-ngan.md`. Khi cắt một
+version, gom các fragment thành một mục trong [CHANGELOG.md](../CHANGELOG.md)
+với version, ngày, giờ (+07:00), rồi chuyển trạng thái fragment sang đã phát
+hành. Không sửa nội dung fragment đã gom; chỉ xóa khi mục tương ứng đã nằm
+trong CHANGELOG.md.
+
+Nội dung fragment phải ghi: vùng thay đổi (runtime/prompt/tools/docs/dev), hành
+vi trước và sau, yêu cầu test hồi quy hoặc link incident tương ứng trong
+`galaxy-code/docs/TEST_FAILURE_ANALYSIS.md` khi bản sửa xuất phát từ một lỗi
+live.
+
+CHANGELOG.md (file công khai trên npm/GitHub) viết tiếng Anh; fragment ở đây là
+ghi chú làm việc nội bộ, viết tiếng Việt cũng được.

package/CHANGELOG.md

@@ -0,0 +1,166 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Times are recorded in Asia/Ho_Chi_Minh (+07:00). Per-fix fragments are filed in
+[CHANGELOG.d](CHANGELOG.d/README.md) and compiled here at release time.
+
+## [0.3.0-alpha.7] - 2026-09-23 07:00 +07:00
+
+### Fixed
+
+- Conservative context profile `outputReserveTokens` raised from 24 000 to
+  32 768 (matching balanced/extended) to prevent `INVALID_MODEL_STREAM
+  "length"` failures when the model spends the full reserve on thinking plus
+  tool-call JSON before writing any file. Profile config version bumped to
+  `1.1.0`. See
+  [CHANGELOG.d fragment](CHANGELOG.d/2026-09-23-conservative-output-reserve.md).
+
+## [0.3.0-alpha.6] - 2026-09-22 07:25 +07:00
+
+### Changed
+
+- Model retry backoff is now a budget knob (`modelRetryDelaysMs`, 1-8 entries,
+  up to 600 000 ms each) consumed in order by retry attempt and reported in
+  `model_retry` events, replacing the hardcoded delay table. Retries are also
+  deadline-aware: when the remaining run budget cannot cover the backoff plus
+  the failed attempt's duration, the runtime skips the attempt and fails loud
+  with the full budget math. See
+  [CHANGELOG.d fragment](CHANGELOG.d/2026-09-22-model-retry-budget.md).
+
+## [0.3.0-alpha.5] - 2026-09-22 01:07 +07:00
+
+### Changed
+
+- No-progress pause now grants exactly one recovery feedback round before
+  pausing: the runtime injects `[GALAXY NO-PROGRESS RECOVERY]` listing the
+  round's failed tools with their remediation and expects a materially
+  different strategy. Thresholds (2/2/2), pause semantics, and
+  fail-loud-after-budget behavior are unchanged; a trace
+  `policy_decision(action: "no_progress_recovery_turn")` marks the granted
+  round. Inspired by Gemini CLI's two-strike loop detection; see
+  [CHANGELOG.d fragment](CHANGELOG.d/2026-09-22-no-progress-recovery-turn.md).
+
+## [0.3.0-alpha.4] - 2026-09-21 02:20 +07:00
+
+### Changed
+
+- `RESEARCH_EVIDENCE_MISSING` completion rejections now carry actionable
+  remediation naming `search_web` (discovery) and `fetch_url` (reading), and
+  state that fetch-only runs do not satisfy a search requirement.
+
+## [0.3.0-alpha.3] - 2026-09-21 00:55 +07:00
+
+### Changed
+
+- Advisory observation nudges include the repeated call's `arguments_hash` so
+  the model can identify exactly which call is repeating while the guard keeps
+  recognition on the full canonical arguments.
+
+## [0.3.0-alpha.2] - 2026-09-19 23:15 +07:00
+
+### Added
+
+- `completion_rejected` runtime events now retain the rejected candidate and a
+  structured research ledger: successfully fetched URLs, search-only URLs,
+  unsupported citations, and source tool-call correlation. Hosts can persist
+  enough evidence to diagnose a repeated citation failure without
+  reconstructing model output from prose.
+- README installation, lifecycle usage, public API, adapter ownership, and
+  alpha-upgrade guidance.
+
+### Changed
+
+- Research citation rejection feedback lists the successfully fetched sources
+  available to the model and tells it to fetch or remove unsupported URLs.
+  Search snippets and plausible URLs remain insufficient completion evidence.
+
+## [0.3.0-alpha.1] - 2026-09-19 12:17 +07:00 (published; first alpha-tagged release)
+
+The first release after `0.1.0` is alpha-tagged because the no-progress guard
+policy changes the default runtime behavior. All changes since `0.1.0` ship in
+this version; the internal working versions `0.2.0`–`0.2.2` were never published.
+
+### Added
+
+- Configurable observation guard policy:
+  - `AiCoderRunBudget.noProgressPolicy`: `advisory` (default) and `strict`.
+  - `AiCoderRunBudget.observationNudgeThresholds` (default `[3, 5, 8]`,
+    following the DeepSeek Harness `repeat-tool-reminder` design): escalating
+    trusted nudges for repeated read-only observations; blocking only after the
+    final threshold. Advisory nudges no longer count toward
+    `maxNoProgressEpisodes`; the `strict` policy preserves the older
+    first-incident accounting.
+- Checkpoints persist `noProgress.policy` and
+  `noProgress.observationNudgeThresholds`; resuming with a different guard
+  configuration fails with `CHECKPOINT_INCOMPATIBLE` (legacy checkpoints
+  without these fields still resume).
+- `policy_decision` trace events for `observation_nudge` and
+  `observation_blocked`.
+- Development-only Node test reporter: `npm test` writes a timestamped journal
+  (`TEST_ERROR_LOG.md`, `.galaxy/tests/<run>/`) with assertion results,
+  failure stacks, test counts, commit, and source fingerprint. Excluded from
+  the published bundle.
+
+### Changed
+
+- Observation-family counters now count every dispatched identical observation
+  attempt, including failed results, matching the documented "requested"
+  contract.
+
+### Fixed
+
+- Research citation parsing: trailing Markdown emphasis and punctuation
+  (`**url**:`, `*url*`, backtick-quoted URLs, trailing `:`/`;`) are
+  stripped before canonicalization, so citations of successfully fetched
+  sources are no longer rejected when the model decorates them. Search-only
+  URLs cited as unfetched are still rejected. See
+  [2026-09-19-research-citation-parsing.md](CHANGELOG.d/2026-09-19-research-citation-parsing.md).
+
+## [0.2.2] - 2026-09-19 11:54 +07:00 (internal working version)
+
+- Working version carrying the citation parsing fix; superseded by
+  `0.3.0-alpha.1` before publishing.
+
+## [0.2.1] - 2026-09-19 00:00 +07:00 (internal working version)
+
+- Working version for the advisory guard policy and the test journal reporter;
+  the first two live audits on the advisory guard ran with this version.
+
+## [0.2.0] - 2026-09-18 02:00 +07:00 (internal working version)
+
+### Added
+
+- Prompt version `ai-coder-single/2.6.0` ships two new static modules:
+  - `code-minimalism-policy`: ordered resolution ladder before writing new code
+    (unnecessary behavior → repository → standard library → platform →
+    installed dependency → focused one-line change), and forbids weakening
+    validation, security handling, accessibility, or error reporting to reduce
+    code size.
+  - `evidence-provenance-policy`: requires `EXTRACTED`, `INFERRED`, or
+    `AMBIGUOUS` labels for non-obvious internal code claims.
+- Completion gate now rejects `RESEARCH_CITATION_UNSUPPORTED`: every cited
+  research URL must carry successful fetch evidence before completion.
+- Optional MCP port definition checklist in `docs/HOST_CONFORMANCE.md`
+  (Definition / Effect policy / Provider / Consumer / Conformance scenarios).
+- Optional fast pre-push gate via `git config core.hooksPath .githooks`.
+
+### Changed
+
+- Project is the core exception of the Galaxy Stack plan: npm scope stays
+  `@galaxy-stack/ai-coder-core`, GitHub repository moves to the
+  [galaxy-blackhole](https://github.com/galaxy-blackhole) organization.
+
+## [0.1.0] - 2026-09-17 14:46 +07:00 (published on npm and GitHub)
+
+### Added
+
+- Initial npm release of the platform-neutral single-agent runtime for
+  Galaxy AI Coder.
+- Deterministic run controller, context manager with tamper-evident
+  checkpoints, prompt assembler, tool registry, approval policy, lexical
+  retrieval, completion gate, and trace protocol.
+- 100 deterministic tests covering runtime, registry, approval, retrieval,
+  and checkpoint behavior.

package/README.md

@@ -17,9 +17,96 @@ completion gate are implemented and covered by deterministic tests.
 not copy runtime logic; they should implement the same ports and pass the same
 host conformance fixtures first.
 
-This package is still pre-integration (`0.1.0`, private). Optional MCP,
-semantic retrieval, background terminal sessions, and subagents are outside
-the current runtime baseline.
+This package is still pre-integration: only `galaxy-code` passes the full
+conformance gate today. Optional MCP, semantic retrieval, background terminal
+sessions, and subagents are outside the current runtime baseline.
+
+## Versioning and release policy
+
+All releases before `1.0.0` are development quality. Every release carries an
+explicit semver pre-release tag (`x.y.z-alpha.N`) while the host conformance
+gate is still running; stable-looking `x.y.z` numbers are reserved for
+post-`1.0.0` releases. Publish pre-releases with a dist tag
+(`npm publish --tag alpha`) so `npm install @galaxy-stack/ai-coder-core@latest`
+never upgrades a consumer to an unverified alpha.
+
+Every behavior- or API-level fix lands in [CHANGELOG.d](CHANGELOG.d/README.md)
+as a dated fragment (date, time, area, before/after, regression requirement)
+and is compiled into [CHANGELOG.md](CHANGELOG.md) at release time. When reading
+any audit or live run, compare the recorded `packageVersion` against
+[CHANGELOG.md](CHANGELOG.md) before concluding that a fixed defect recurred.
+
+Publishing is automated through npm trusted publishing (OIDC, no stored npm
+token): every push to `main` runs the conformance gate and
+[.github/workflows/publish.yml](.github/workflows/publish.yml) publishes the
+package only when `package.json` carries a version that npm does not have yet.
+Pre-release versions publish under the `alpha` dist tag, so
+`npm install @galaxy-stack/ai-coder-core@latest` never jumps to an unverified
+alpha.
+
+## Installation
+
+Install the current development line explicitly; `latest` intentionally stays
+on the last non-alpha release:
+
+```sh
+npm install @galaxy-stack/ai-coder-core@alpha
+```
+
+The package is ESM-only and requires Node.js 20 or newer. It does not bundle a
+model provider, filesystem adapter, command runner, credential store, or UI.
+Each host supplies those capabilities through typed ports.
+
+## Basic usage
+
+`AiCoderRunController` owns each run lifecycle; one controller may host
+multiple distinct run IDs, while every run still has exactly one AI. A host
+constructs the adapter set once, passes a complete request to `start`, observes
+typed runtime events, and awaits the handle result. The same request fields
+plus a trusted durable checkpoint are used by `resume`.
+
+```ts
+import {
+  AiCoderRunController,
+  type AiCoderRunDependencies,
+  type AiCoderRunRequest,
+} from "@galaxy-stack/ai-coder-core";
+
+export async function runCoder(
+  dependencies: AiCoderRunDependencies,
+  request: AiCoderRunRequest,
+) {
+  const controller = new AiCoderRunController(dependencies);
+  const handle = controller.start(request);
+
+  // A UI may call handle.pause(), handle.cancel(), or
+  // handle.resolveApproval(requestId, decision) while result is pending.
+  return await handle.result;
+}
+```
+
+Required dependencies are a `CodingModelAdapter` and an
+`AiCoderRuntimeToolExecutor`. Production hosts should also provide a trusted
+run store, trace port, workspace verifier, and output-spill adapter when their
+completion requirements enable those guarantees. `galaxy-code` is the
+reference implementation and conformance test host.
+
+## Public API
+
+| Export | Purpose |
+| --- | --- |
+| `AiCoderRunController` | Start, resume, pause, cancel, and resolve approvals for a run. |
+| `AiCoderRunRequest` / `AiCoderRunResult` | Typed task input, budgets, completion requirements, and terminal result. |
+| `AiCoderRunDependencies` | Model, tools, persistence, trace, workspace verification, clock, and event adapters. |
+| `AiCoderRuntimeEvent` | Model, tool, checkpoint, retry, context-pressure, state, and completion-rejection telemetry. |
+| `evaluateAiCoderCompletion` | Pure completion-evidence evaluation for tests and host diagnostics. |
+| `createAiCoderRunCheckpoint` / `assertAiCoderRunCheckpoint` | Durable checkpoint creation and validation. |
+| `AiCoderToolRegistry` | Canonical tool registration and model-facing registry snapshots. |
+
+Focused subpath exports are available at `/ports`, `/tools`, `/context`,
+`/prompt`, `/approval`, `/retrieval`, and `/runtime`. The API is pre-1.0:
+pin an exact alpha version in production-like hosts and review
+[CHANGELOG.md](CHANGELOG.md) before upgrading.
 
 ## Non-negotiable invariants
 
@@ -59,7 +146,10 @@ the current runtime baseline.
     fingerprint, and returning content hashes are bounded. Semantically
     identical validation, diff, and criterion evidence does not manufacture a
     new state transition; unresolved no-progress episodes pause with a
-    checkpoint.
+    checkpoint. Read-only observations follow the configured `noProgressPolicy`
+    (`advisory` by default: escalating nudges at `observationNudgeThresholds`,
+    blocked only after the final threshold; `strict` preserves the older
+    first-incident accounting).
 13. Provider-reported context overflow checkpoints, compacts, and recounts
     before another model request. Mandatory state is never silently dropped to
     force a round through.
@@ -112,20 +202,41 @@ src/
 
 ## Development
 
-Requires Node.js 20 or newer.
+The platform-neutral root supports Node.js 20+. Full development checks and optional SQLite adapters require Node.js 22.13+ (CI covers Node 22 and 24).
 
 ```bash
 npm install
 npm run verify
 ```
 
+Optional fast pre-push gate:
+
+```bash
+git config core.hooksPath .githooks
+```
+
 `npm run verify` runs strict TypeScript checks, all source tests, a clean build,
 and a public `dist` smoke test. `npm pack --dry-run` should also be checked
 before publishing or consuming the package from another repository.
 
-The deterministic end-to-end host gate lives in `galaxy-code`:
+`npm test` writes [TEST_ERROR_LOG.md](TEST_ERROR_LOG.md) and per-run evidence under
+`.galaxy/tests/`: timestamped assertion results, failure stacks, test counts,
+commit and source fingerprint. The reporter is development-only and runs without
+a galaxy-code checkout. Raw `tsx --test` invocations bypass this reporter.
+
+The deterministic/live/replay host gate lives in the private `testing/` workspace:
 
 ```bash
-cd ../../galaxy-code
-npm run check
+cd testing
+npm ci
+npm run test:local
 ```
+
+
+## Agent platform and optional adapters
+
+The runtime also supports `prompt.agentProfile: "assistant" | "research"` alongside the default coding profile. `contextData` is bounded, snapshotted and wrapped as untrusted context; it never changes approval or validation evidence.
+
+`@galaxy-stack/ai-coder-core/agent` exports `AgentMemoryPort`, `AgentSkillsPort`, `AgentToolExecutor`, `CompositeToolExecutor`, memory/skill tool factories and profile types. Optional `.../adapters/node/*` exports provide the shared Ollama/Node tools, MCP SDK client, directory skill loader and SQLite memory. They are not imported through the platform-neutral root. The SQLite adapter requires Node >=22.13.
+
+The executable lab moved into [testing/](testing/README.md); it is private and excluded from the npm package. Production CLI/TUI lives in the sibling `galaxy-code` repository. See [docs/AGENT_PLATFORM.md](docs/AGENT_PLATFORM.md) for APIs, current scope, commands and rollout boundaries.

package/dist/adapters/node/config/manual-provider-config.d.ts

@@ -0,0 +1,19 @@
+export type CredentialSource = "environment" | "manual-config" | "none";
+export interface ResolvedOllamaConnection {
+    readonly apiKey?: string;
+    readonly baseUrl: string;
+    readonly configPath: string;
+    readonly credentialSource: CredentialSource;
+    readonly model: string;
+}
+export interface ResolveOllamaConnectionOptions {
+    readonly baseUrl?: string;
+    readonly configPath?: string;
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    readonly model?: string;
+}
+export declare function resolveOllamaConnection(options?: ResolveOllamaConnectionOptions): Promise<ResolvedOllamaConnection>;
+export declare function publicOllamaConnection(connection: ResolvedOllamaConnection): Omit<ResolvedOllamaConnection, "apiKey" | "configPath"> & Readonly<{
+    configPath: string;
+}>;
+//# sourceMappingURL=manual-provider-config.d.ts.map

package/dist/adapters/node/config/manual-provider-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manual-provider-config.d.ts","sourceRoot":"","sources":["../../../../src/adapters/node/config/manual-provider-config.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,eAAe,GAAG,MAAM,CAAC;AAExE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAkDD,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,wBAAwB,CAAC,CA2BnC;AAED,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,wBAAwB,GACnC,IAAI,CAAC,wBAAwB,EAAE,QAAQ,GAAG,YAAY,CAAC,GAAG,QAAQ,CAAC;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAO5F"}

package/dist/adapters/node/config/manual-provider-config.js

@@ -0,0 +1,91 @@
+import { DEFAULT_AI_CODER_CORE_SETTINGS } from "../../../index.js";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function optionalNonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function safeProviderBaseUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error("Ollama base URL must be an absolute HTTP(S) URL.");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Ollama base URL must use HTTP or HTTPS.");
+    }
+    if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+        throw new Error("Ollama base URL must not contain credentials, query parameters, or a fragment.");
+    }
+    return parsed.href.replace(/\/+$/, "");
+}
+async function readManualAgent(configPath) {
+    let raw;
+    try {
+        raw = await readFile(configPath, "utf8");
+    }
+    catch (error) {
+        if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")
+            return null;
+        throw new Error(`Unable to read Galaxy manual config: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (Buffer.byteLength(raw, "utf8") > 1024 * 1024)
+        throw new Error("Galaxy manual config exceeds 1 MiB.");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Galaxy manual config is not valid JSON.");
+    }
+    if (!isObject(parsed) || !Array.isArray(parsed.agent)) {
+        throw new Error("Galaxy manual config must contain an agent array.");
+    }
+    const manual = parsed.agent.find((entry) => isObject(entry) && entry.type === "manual");
+    if (manual === undefined)
+        return null;
+    if (!isObject(manual))
+        throw new Error("Galaxy manual provider entry is invalid.");
+    return manual;
+}
+export async function resolveOllamaConnection(options = {}) {
+    const configPath = options.configPath ?? join(homedir(), ".galaxy", "config.json");
+    const manual = await readManualAgent(configPath);
+    const manualApiKey = optionalNonEmpty(manual?.apiKey);
+    const environmentApiKey = optionalNonEmpty((options.environment ?? process.env).OLLAMA_API_KEY);
+    const apiKey = manualApiKey ?? environmentApiKey;
+    const credentialSource = manualApiKey !== undefined
+        ? "manual-config"
+        : environmentApiKey !== undefined
+            ? "environment"
+            : "none";
+    const baseUrl = safeProviderBaseUrl(options.baseUrl
+        ?? optionalNonEmpty(manual?.baseUrl)
+        ?? DEFAULT_AI_CODER_CORE_SETTINGS.singleAgent.baseUrl);
+    const model = options.model
+        ?? optionalNonEmpty(manual?.model)
+        ?? DEFAULT_AI_CODER_CORE_SETTINGS.singleAgent.model;
+    if (model.trim().length === 0)
+        throw new Error("Ollama model must be non-empty.");
+    return Object.freeze({
+        ...(apiKey === undefined ? {} : { apiKey }),
+        baseUrl,
+        configPath,
+        credentialSource,
+        model: model.trim(),
+    });
+}
+export function publicOllamaConnection(connection) {
+    return Object.freeze({
+        baseUrl: connection.baseUrl,
+        configPath: connection.configPath.replace(homedir(), "~"),
+        credentialSource: connection.credentialSource,
+        model: connection.model,
+    });
+}
+//# sourceMappingURL=manual-provider-config.js.map

package/dist/adapters/node/config/manual-provider-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manual-provider-config.js","sourceRoot":"","sources":["../../../../src/adapters/node/config/manual-provider-config.ts"],"names":[],"mappings":"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"}