gentle-pi 2.3.0 → 2.5.0

package/scripts/verify-package-files.mjs

@@ -46,6 +46,7 @@ const requiredPaths = [
   "assets/support/sdd-status-contract.md",
   "assets/support/strict-tdd.md",
   "assets/support/strict-tdd-verify.md",
+  "docs/delegated-verification.md",
   "docs/native-authority-architecture.md",
   "docs/skill-style-guide.md",
   "docs/review-integration.md",
@@ -59,10 +60,13 @@ const requiredPaths = [
   "lib/review-integration-v2.ts",
   "lib/review-relay-contract.ts",
   "lib/sdd-preflight.ts",
+  "lib/telemetry-trigger.ts",
 	"runtime/gentle-ai-binary.mjs",
 	"runtime/native-review-cli.mjs",
 	"runtime/review-integration-v2.mjs",
+	"runtime/review-risk-assessment.mjs",
 	"runtime/review-relay-contract.mjs",
+	"runtime/telemetry-trigger.mjs",
   "scripts/check-provider-contract.mjs",
   "scripts/gentle-ai-installer.mjs",
   "scripts/install-gentle-ai.mjs",
@@ -80,16 +84,17 @@ const requiredPaths = [
   // exact bytes are pinned by the lock-driven scripts/check-provider-contract.mjs
   // drift check, which runs in the same pnpm test flow.
   "contracts/review-provider-contract-mirror/provider-contract.lock.json",
-  "contracts/review-provider-contract-mirror/v1.1.0/bundle/README.md",
-  "contracts/review-provider-contract-mirror/v1.1.0/bundle/manifest.json",
-  "contracts/review-provider-contract-mirror/v1.1.0/bundle/schemas/lens.schema.json",
-  "contracts/review-provider-contract-mirror/v1.1.0/bundle/schemas/refuter.schema.json",
-  "contracts/review-provider-contract-mirror/v1.1.0/bundle/schemas/targeted-validator.schema.json",
-  "contracts/review-provider-contract-mirror/v1.1.0/bundle/vectors/lens.json",
-  "contracts/review-provider-contract-mirror/v1.1.0/bundle/vectors/refuter.json",
-  "contracts/review-provider-contract-mirror/v1.1.0/bundle/vectors/targeted-validator.json",
-  "contracts/review-provider-contract-mirror/v1.1.0/generated/provider-capabilities.baseline.json",
-  "contracts/review-provider-contract-mirror/v1.1.0/generated/provider-roles.baseline.json",
+  "contracts/review-provider-contract-mirror/v1.2.0/bundle/README.md",
+  "contracts/review-provider-contract-mirror/v1.2.0/bundle/manifest.json",
+  "contracts/review-provider-contract-mirror/v1.2.0/bundle/orchestration/pi.md",
+  "contracts/review-provider-contract-mirror/v1.2.0/bundle/schemas/lens.schema.json",
+  "contracts/review-provider-contract-mirror/v1.2.0/bundle/schemas/refuter.schema.json",
+  "contracts/review-provider-contract-mirror/v1.2.0/bundle/schemas/targeted-validator.schema.json",
+  "contracts/review-provider-contract-mirror/v1.2.0/bundle/vectors/lens.json",
+  "contracts/review-provider-contract-mirror/v1.2.0/bundle/vectors/refuter.json",
+  "contracts/review-provider-contract-mirror/v1.2.0/bundle/vectors/targeted-validator.json",
+  "contracts/review-provider-contract-mirror/v1.2.0/generated/provider-capabilities.baseline.json",
+  "contracts/review-provider-contract-mirror/v1.2.0/generated/provider-roles.baseline.json",
   "prompts/skill-creation.md",
   "skills/_shared/review-ledger-contract.md",
   "skills/branch-pr/SKILL.md",
@@ -175,7 +180,7 @@ const contractHashes = {
   "contracts/review-integration/v2/schemas/repair.schema.json": "98a85fd45a8ae7f6211ffeeb3f9c478fa1dd1c17f385751f15f2111e6c3ab167",
   "contracts/review-integration/v2/schemas/start.schema.json": "2991e3fcca672d9257d61b6a336fb34e58b15a8e03f8a09a7adf892cae6a8085",
   "contracts/review-integration/v2/schemas/status.schema.json": "c4dcc736cfc6300560a3c4262d2d982368529d5c49d58d499552a3b0beef9212",
-  "docs/review-integration.md": "0a2a415e8bd24be61f5c6090bd0efccde0ed1b4561261be11bba197aa081f336",
+  "docs/review-integration.md": "95a3df92785bc4d9f3b99e702aaf817ae0440bd16c83218d2c3f2aca67c280fb",
 };
 
 requiredPaths.push(...Object.keys(contractHashes));
@@ -333,7 +338,7 @@ async function main() {
   });
 
   if (driftedContracts.length > 0) {
-    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v2.5.0 runtime's vendored Gentle AI contract artifacts:");
+    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v2.7.0 runtime's vendored Gentle AI contract artifacts:");
     for (const drift of driftedContracts) console.error(`- ${drift.relativePath}: expected ${drift.expected}, got ${drift.actual}`);
     process.exit(1);
   }
@@ -378,7 +383,7 @@ async function main() {
     process.exit(1);
   }
 
-  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v2.5.0 runtime).`);
+  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v2.7.0 runtime).`);
 }
 
 const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;

package/skills/_shared/review-ledger-contract.md

@@ -20,10 +20,18 @@ Risk routing is deterministic:
 
 Generated files matching `testdata/golden/**` remain in snapshot identity but do not count as authored risk lines. Ordinary tests, fixtures, and snapshots are never broadly excluded. The correction budget is frozen as `min(200, ceil(original_changed_lines / 2))`.
 
-Before status/START, consult effective review mode. `off` creates no authority or authorization and yields organic `disabled/unmanaged`, never approval. Ordinary START declares `--consent relay`; low risk stays silent. A medium/high `consent/v2` result always returns the complete raw provider envelope plus an opaque in-memory candidate binding to the parent, then stops without UI or provider follow-up. The parent localizes and presents it losslessly while preserving tokens, commands, target IDs, and invocations. One explicit `answer-consent` call accepts only that binding and `granted|declined`, consumes it before provider mutation, and rechecks repository/target/projection/lineage/answer binding. Ambiguity reconciles through STATUS, never replay. Grant is exact-candidate-only. Decline creates no lineage, authority, actor/candidate binding, latch, or pending authorization; the next candidate asks again. Old Pi clone latch files are inert.
+Before status/START, consult effective review mode. `off` creates no authority or authorization and yields organic `disabled/unmanaged`, never approval. Ordinary START declares `--consent relay`; low risk stays silent. A medium/high `consent/v3` result carries the complete raw two-choice provider envelope plus an opaque in-memory candidate binding. In an eligible interactive parent Pi session, the host displays both provider labels and effects unchanged plus one clearly separate host-owned action: **Run this review and allow reviews for this Pi session**. The first two actions stay candidate-only. Direct human selection of the third action executes that fresh envelope's exact existing `granted` invocation through `answer-consent`, then grants only future fresh validated envelopes for the same live SessionManager object, exact nonempty session ID, and canonical Git worktree root. Every envelope is consumed once before provider mutation and rechecks repository, target, projection, lineage, answer binding, and live session identity; ambiguity reconciles through STATUS and never replays.
+
+The host grant lives only in a schema-checked `globalThis[Symbol.for(...)]` WeakMap registry. Reload preserves the SessionManager and reconnects the grant; quit, new, resume, fork, explicit revoke, or process restart removes it. `/tree` retains it. Child-agent processes, headless/RPC/unsupported UI, explicit cross-repository `workspaceRoot`, model prose, and tool arguments cannot offer, create, or consume it. It grants no provider mode, verdict, cost forecast, acknowledgement, maintenance, delivery, or cross-repository authority. If host UI is cancelled, fails, or cannot prove current Git/session identity, the original unresolved provider envelope is returned unchanged. If that envelope reaches the parent, localize and present its original two choices losslessly; never append the host action to the decoded provider contract. Decline creates no lineage, authority, standing grant, latch, or pending authorization; the next candidate asks again. Old Pi clone latch files are inert, and Pi writes no asked latch.
 
 Reviewer, refuter, and validator verdicts are admitted natively, never Pi-authored. `finalize` follows the provider's negotiated `next_transition` and supplies only the negotiated collection answers: a lens `review.capture-result` collect input rendered with `--agent=pi --materialize=true` is satisfied by the gentle-pi host relay, which prints the exact Go-materialized opaque prompt, launches a fresh locked-down print-mode `pi` subprocess in an empty scratch directory with every discovery surface disabled, and submits the untouched raw output bytes through the provider-owned submission form. The adversarial roles do not go through that relay: `review.capture-refuter` and `review.capture-validation` collect inputs render as self-contained authority-advancing vectors (binding tokens plus `--agent=pi --execute=true`, no submission descriptor); executing the exact rendered invocation makes Go materialize the role prompt, spawn its own locked-down `pi` process, and admit the raw verdict. Native Go owns validation, canonicalization, missing lens/finding ID assignment, persistence, and hashing, and performs only the legal transition from the current compact state. The five states are `reviewing`, `correction_required`, `validating`, `approved`, and `escalated`.
 
+### Concurrent Reviewer Group (MANDATORY)
+
+When one fresh `collect.inputs` set contains multiple distinct independent `review.capture-result` reviewer slots, call `gentle_review_capture_group` once with the complete ordered provider bindings and its forecast acknowledgement. Before any materialization it validates the whole current group, its common binding fields, unique slot identities, and every provider submission descriptor; then it starts all reviewers before waiting. For canonical 4R, preserve `review-risk`, `review-resilience`, `review-readability`, `review-reliability` order.
+
+Each grouped launch runs only its own provider-issued `review.capture-result` binding, and admission remains in provider order. A typed terminal or nonterminal closure returns directly; a later stop after earlier admission reports bounded partial progress and never claims no mutation. If every submission returns without closure, reconcile fresh bound STATUS and return its declared action rather than inferring group success. On `correction_required`, continue only through exact bound STATUS and the provider-issued `review.capture-correction-plan` binding.
+
 `validate` is informational and runs with zero actors. It never mutates compact authority or controls delivery.
 
 ## Causal findings

package/skills/issue-creation/SKILL.md

@@ -4,18 +4,14 @@ description: "Create and triage GitHub issues from repository evidence. Trigger:
 license: Apache-2.0
 metadata:
   author: gentleman-programming
-  version: "1.2"
+  version: "1.3"
 ---
 
 # Issue Creation
 
-## When To Use
-
-Use this skill when creating, drafting, triaging, or approving an issue in the current GitHub repository.
-
 ## Core Rule
 
-Discover the repository's actual contribution workflow before proposing or publishing an issue. Templates, labels, approval gates, and Discussions support are repository policy, not universal GitHub behavior.
+Discover the target repository's contribution workflow before proposing or publishing. YAML Issue Forms are the format authority for the default automated path: materialize reviewed answers into a private `BODY_FILE` and publish with `--body-file`.
 
 ## Safe Discovery
 
@@ -27,123 +23,87 @@ REPO="$(gh repo view --json nameWithOwner -q .nameWithOwner)"
 REPO_URL="$(gh repo view --json url -q .url)"
 HOST="${REPO_URL#*://}"
 HOST="${HOST%%/*}"
+TARGET="$HOST/$REPO"
 gh repo view --json nameWithOwner,url,hasDiscussionsEnabled,hasIssuesEnabled,isBlankIssuesEnabled
-git ls-files CONTRIBUTING.md CONTRIBUTING.* .github/CONTRIBUTING.md .github/ISSUE_TEMPLATE
+git ls-files README.md CONTRIBUTING.md CONTRIBUTING.* .github/CONTRIBUTING.md .github/ISSUE_TEMPLATE .github/ISSUE_TEMPLATE/config.yml
 gh api --hostname "$HOST" --paginate "repos/$REPO/labels?per_page=100" --jq '.[].name'
 ```
 
-Also inspect:
-
-- repository instructions such as `CONTRIBUTING.md` and `README.md`;
-- files under `.github/ISSUE_TEMPLATE`;
-- `.github/ISSUE_TEMPLATE/config.yml` when present;
-- issue forms, required fields, and labels declared by each template;
-- existing open and closed issues for duplicates and established wording.
+Inspect `README.md`, contribution instructions, `.github/ISSUE_TEMPLATE/config.yml` contact links, forms, labels, and open and closed issues. For questions/support, follow repository-prescribed Discussions/contact routing when available; otherwise ask or stop. Complete target verification for `REPO`, `HOST`, and `TARGET`. Fail closed before mutation when authentication, target verification, issue availability, policy, form selection, or required metadata is missing or ambiguous. A blank fallback is allowed only when `isBlankIssuesEnabled` is explicitly true.
 
-Stop and ask for repository context if authentication, repository resolution, verification that REPO and HOST are non-empty, required metadata is unavailable, hasIssuesEnabled is false, or policy discovery fails. Never continue from failed discovery into issue publication.
-
-A no-template fallback is allowed only when isBlankIssuesEnabled is explicitly true. Otherwise follow discovered contact links or stop and ask; never publish.
-
-After discovery and review, build optional label arguments using only labels that exist and repository policy permits the actor to apply:
+Build `LABEL_ARGS` only from reviewed labels that exist and policy permits the actor to apply:
 
 ```bash
 LABEL_ARGS=()
-# Repeat for each reviewed, permitted discovered label.
-LABEL_ARGS+=(--label "$LABEL")
+LABEL_ARGS+=(--label "$LABEL") # Repeat only for each permitted discovered label.
 ```
 
-An empty array applies no label; do not invent labels.
-
-## Workflow
+## Duplicate And Form Decision
 
-1. Describe the problem or request in one sentence and derive a short search query.
-2. Search open and closed issues:
+1. Describe the report in one sentence, derive `QUERY`, then complete one duplicate search across open and closed issues:
 
    ```bash
-   gh issue list --repo "$HOST/$REPO" --state all --search "$QUERY" --limit 1000
+   gh issue list --repo "$TARGET" --state all --search "$QUERY" --limit 1000
    ```
 
-   If 1000 results are returned or completeness remains uncertain, narrow the search, use read-only API discovery, or stop and ask before publishing.
-
-3. If an issue already covers the same behavior, comment there instead of creating a duplicate.
-4. Choose a repository-provided template only when its purpose matches the report.
-5. Fill every required template field from known evidence. Ask for missing facts rather than inventing them.
-6. Apply labels only when they exist and repository guidance establishes who should apply them.
-7. Publish only after the title, body, target repository, and selected template or fallback have been reviewed, and the pre-submission privacy review below has passed.
-
-## Pre-submission Privacy Review
-
-Pre-submission privacy review is mandatory. Scan every issue body immediately before `gh issue create`. The scan replaces — never deletes — environment-specific data with explicit placeholders so the reproduction still teaches:
-
-| Category | Replace with | Example (before → after) |
-|----------|---------------|---------------------------|
-| Private project names | `<project-name>` | `my-private-project-b` → `<project-name>` |
-| Usernames | `<user>` | `C:\Users\my-real-username\go\bin` → `C:\Users\<user>\go\bin` |
-| Hostnames | `<hostname>` | `devbox-macbook.local` → `<hostname>` |
-| Home paths | `/home/<user>` or `C:\Users\<user>` | (covered above) |
-| API keys, tokens, passwords | `<token>` / `<password>` | `ghp_abc123...` → `<token>` |
-| Internal ports / hostnames | `<host>:<port>` | `10.0.0.42:5432` → `<host>:<port>` |
-
-Do NOT redact intentionally public identifiers: tool names (`gentle-ai`, `engram`, `go`, `node`, `python`), package names, public documentation URLs, generic example domains (`example.com`, `localhost`). Keep reproduction structure with placeholders — never redact an example into nothingness.
-
-**Rule of thumb:** if the reader can run the reproduction step after you replace every identifier with its placeholder, the sanitization is correct. If a step becomes impossible (because the placeholder consumed a needed value), that step needs the value — and you should mark it `<value-required>` and explain in the body what the user should fill in.
+   If results are saturated or completeness is uncertain, narrow the read-only search or stop. Comment on a confirmed duplicate instead of creating one. Before commenting on a confirmed duplicate, perform the same privacy scan/redaction on the exact comment body as for publication.
+2. Select one repository-provided form only when its declared purpose matches. If multiple forms match and policy does not distinguish them, stop and request that decision.
+3. For a YAML form, read its schema and establish controls in declared order. Support only `input`, `textarea`, `dropdown`, and `checkboxes`. Markdown controls are non-answer guidance: honor their visible instructions when collecting and materializing adjacent answers, but do not render them as response sections. Fail closed before mutation on malformed, unsupported, missing, or ambiguous required structure or answers. A malformed schema, or missing or ambiguous required answers, fail closed: do not open a browser or mutate. A browser handoff is available only when the user explicitly requests browser completion or a syntactically valid selected form cannot safely/faithfully be represented by the automated path; otherwise report why automation is unsafe and stop.
 
-## Template Paths
+| Control | Required handling |
+| --- | --- |
+| `input` / `textarea` | Preserve the visible label. Require an answer when `validations.required` is true; otherwise render `_No response_`. |
+| `dropdown` | Preserve visible labels and options. Require exact selected option text; single-select has one selection, and multi-select preserves selections in declared options order. A required dropdown needs at least one valid selection; an optional dropdown with no selection renders `_No response_`. |
+| `checkboxes` | Preserve the visible label and every option as `- [x]` or `- [ ]` in declared order. Enforce individually required checkboxes and require explicit first-person affirmation for first-person option text. |
 
-Do not guess a template filename. If multiple templates could apply and repository guidance does not distinguish them, stop and ask which one to use.
+For each answer, render `### <visible label>` followed by its materialized value. For `textarea.attributes.render`, fence the answer with the declared language and a fence long enough for its content. Never invent answers, selections, confirmations, or labels.
 
-- .yml and .yaml files are GitHub Issue Forms. Do not parse or render their schema. Open the web issue chooser and stop for human completion:
+A Markdown template may be completed only from known evidence into the same private `BODY_FILE`. If no matching template exists, use the reviewed structured blank fallback only when blank issues are explicitly enabled; otherwise stop without publishing.
 
-  ```bash
-  gh issue create --repo "$HOST/$REPO" --web "${LABEL_ARGS[@]}"
-  ```
+## Review And Publication
 
-- .md files are Markdown templates. Read the matching template, complete it from known evidence into a reviewed BODY_FILE, then publish it:
+Before the single create attempt, review the target, title, selected form or permitted fallback, exact body, and permitted labels. Perform a privacy scan immediately before publication: replace private project names, usernames, hostnames, home paths, credentials, and private network addresses with useful placeholders without removing reproduction structure.
 
-  ```bash
-  gh issue create --repo "$HOST/$REPO" --title "$TITLE" --body-file "$BODY_FILE" "${LABEL_ARGS[@]}"
-  ```
-
-## No-Template Fallback
-
-When the repository permits issue creation, provides no matching template, and isBlankIssuesEnabled is explicitly true, prepare a structured body with these sections:
-
-- problem or requested outcome;
-- reproduction or motivating example;
-- expected behavior;
-- actual behavior or current limitation;
-- environment and relevant evidence;
-- alternatives or workarounds, when applicable.
-
-Publish the reviewed fallback explicitly:
+Create one owner-only temporary directory outside the repository for both private files; restrict it to the current user and clean up both files on every exit/outcome:
 
 ```bash
-gh issue create --repo "$HOST/$REPO" --title "$TITLE" --body "$BODY" "${LABEL_ARGS[@]}"
+umask 077
+REPO_ROOT="$(git rev-parse --show-toplevel)" || exit 1
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd -P)" || exit 1
+if [ "$REPO_ROOT" = "/" ]; then
+  printf '%s\n' "Temporary directory is inside the repository" >&2; exit 1
+fi
+TMP_DIR="$(TMPDIR=/tmp mktemp -d /tmp/gentle-ai-issue.XXXXXXXX)" || exit 1
+trap 'rm -rf -- "$TMP_DIR"' EXIT
+TMP_DIR_REAL="$(cd "$TMP_DIR" && pwd -P)" || exit 1
+case "$TMP_DIR_REAL/" in
+  "$REPO_ROOT/"*) printf '%s\n' "Temporary directory is inside the repository" >&2; exit 1 ;;
+esac
+chmod 700 "$TMP_DIR_REAL"
+BODY_FILE="$TMP_DIR_REAL/body.md"
+READBACK_FILE="$TMP_DIR_REAL/readback.json"
 ```
 
-If blank issues are not explicitly enabled, follow discovered contact links or stop and ask. Never publish a no-template fallback.
-
-## Labels And Approval
+Make one mutation attempt through the automated path and publish exactly once:
 
-Treat labels and approval gates as conditional:
+```bash
+gh issue create --repo "$TARGET" --title "$TITLE" --body-file "$BODY_FILE" "${LABEL_ARGS[@]}"
+```
 
-- use only labels returned by repository discovery;
-- follow contribution guidance for who may apply each label;
-- wait when repository policy requires maintainer approval before implementation;
-- do not invent a status or priority taxonomy when none is documented.
+When browser completion is available under the form decision above, an optional, separate browser handoff may open the repository form. It is never proof of publication and is never a response to malformed schemas or missing/ambiguous required answers:
 
-## Questions And Discussions
+```bash
+gh issue create --repo "$TARGET" --web
+```
 
-Use Discussions only when `hasDiscussionsEnabled` is true and repository guidance routes the question there. Otherwise follow documented support/contact links or ask the user where the question belongs. Never link to another repository's Discussions page.
+Do not retry a timeout, network failure, missing identity, or other uncertain result. Capture the returned issue number, then read it back from the verified target host before reporting success:
 
-## Triage Decision
+```bash
+gh issue view "$NUMBER" --repo "$TARGET" --json number,url,title,body,state,labels >"$READBACK_FILE"
+```
 
-Before approving or closing an issue, verify:
+Confirm that read-back identifies the target-host issue and that title and body match after only CRLF-to-LF and trailing-final-newline normalization. Report `confirmed` only after this target-host read-back. Otherwise report `no_write` when an authoritative rejection proves no issue was created, or `unknown` and stop all later mutations.
 
-- it describes a concrete bug or scoped improvement rather than an unsupported question;
-- it is not a duplicate;
-- the report contains enough evidence for an implementation decision;
-- the requested behavior is in repository scope;
-- labels and status changes follow the current repository's policy.
+## Triage
 
-If any point is uncertain, keep the issue in the repository's review state and request the smallest missing evidence.
+Before approving or closing an issue, verify it is concrete, non-duplicate, sufficiently evidenced, in scope, and consistent with repository label/status policy. If any point is uncertain, retain the repository review state and request the smallest missing evidence.

package/tests/agents-config.test.ts

@@ -0,0 +1,143 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { after } from "node:test";
+import {
+	AGENT_MODE,
+	agentDirectories,
+	discoverAgents,
+	loadAgentsConfig,
+	parseAgentDefinition,
+	parseAgentsConfig,
+	parseFrontmatter,
+	parseModelRef,
+	resolveAgentProfile,
+} from "../lib/agents-config.ts";
+
+// Gentle Agents configuration: markdown agent definitions (the same files
+// gentle-ai installs) and subagents.json, both parsed without touching pi.
+
+const root = mkdtempSync(join(tmpdir(), "gentle-agents-config-"));
+after(() => rmSync(root, { recursive: true, force: true }));
+
+const EXPLORER = `---
+name: gentle-ai-explore
+description: Read-only exploration and mapping.
+model: openai-codex/gpt-5.6-terra
+thinking: high
+tools:
+  - read
+  - grep
+  - codegraph
+---
+
+You are the read-only explorer.
+Map files and return a compressed handoff.
+`;
+
+test("parseFrontmatter reads scalars, inline lists, and block lists, and keeps the body", () => {
+	const { data, body } = parseFrontmatter("---\nname: a\ntools: [read, grep]\nlist:\n  - one\n  - two\nquoted: \"x: y\"\n---\nBody here\n");
+	assert.deepEqual(data, { name: "a", tools: ["read", "grep"], list: ["one", "two"], quoted: "x: y" });
+	assert.equal(body, "Body here");
+	assert.deepEqual(parseFrontmatter("no frontmatter"), { data: {}, body: "no frontmatter" });
+});
+
+test("parseModelRef splits provider/id and accepts a bare id", () => {
+	assert.deepEqual(parseModelRef("openai-codex/gpt-5.6-terra"), { provider: "openai-codex", id: "gpt-5.6-terra" });
+	assert.deepEqual(parseModelRef("sonnet"), { provider: undefined, id: "sonnet" });
+	assert.equal(parseModelRef("   "), undefined);
+});
+
+test("parseAgentDefinition builds a definition from the gentle-ai agent format", () => {
+	const agent = parseAgentDefinition(EXPLORER, "/home/x/.pi/agent/agents/gentle-ai-explore.md", "global");
+	assert.ok(!("error" in agent));
+	assert.equal(agent.name, "gentle-ai-explore");
+	assert.equal(agent.description, "Read-only exploration and mapping.");
+	assert.deepEqual(agent.model, { provider: "openai-codex", id: "gpt-5.6-terra" });
+	assert.equal(agent.thinking, "high");
+	assert.deepEqual(agent.tools, ["read", "grep", "codegraph"]);
+	assert.equal(agent.mode, undefined);
+	assert.equal(agent.scope, "global");
+	assert.match(agent.instructions, /^You are the read-only explorer\./);
+});
+
+test("parseAgentDefinition accepts effort and subagent_mode aliases, csv tools, and names from the file", () => {
+	const agent = parseAgentDefinition("---\ndescription: d\neffort: low\nsubagent_mode: background\ntools: read, bash\n---\nbody", "/p/.pi/agents/worker.md", "project");
+	assert.ok(!("error" in agent));
+	assert.equal(agent.name, "worker");
+	assert.equal(agent.thinking, "low");
+	assert.equal(agent.mode, AGENT_MODE.BACKGROUND);
+	assert.deepEqual(agent.tools, ["read", "bash"]);
+});
+
+test("parseAgentDefinition rejects unknown thinking levels, modes, and empty bodies", () => {
+	assert.match((parseAgentDefinition("---\nname: a\nthinking: extreme\n---\nbody", "/a.md", "global") as { error: string }).error, /thinking "extreme"/);
+	assert.match((parseAgentDefinition("---\nname: a\nsubagent_mode: forever\n---\nbody", "/a.md", "global") as { error: string }).error, /mode "forever"/);
+	assert.match((parseAgentDefinition("---\nname: a\n---\n   \n", "/a.md", "global") as { error: string }).error, /no instructions/);
+});
+
+test("discoverAgents merges the four directories with project over global and subagents over agents", () => {
+	const home = join(root, "home");
+	const cwd = join(root, "project");
+	for (const dir of [".pi/agent/agents", ".pi/agent/subagents"]) mkdirSync(join(home, dir), { recursive: true });
+	for (const dir of [".pi/agents", ".pi/subagents"]) mkdirSync(join(cwd, dir), { recursive: true });
+	writeFileSync(join(home, ".pi/agent/agents/explore.md"), EXPLORER);
+	writeFileSync(join(home, ".pi/agent/agents/shared.md"), "---\ndescription: global agents\n---\nglobal");
+	writeFileSync(join(home, ".pi/agent/subagents/shared.md"), "---\ndescription: global subagents\n---\nglobal sub");
+	writeFileSync(join(cwd, ".pi/agents/shared.md"), "---\ndescription: project agents\n---\nproject");
+	writeFileSync(join(cwd, ".pi/agents/broken.md"), "---\nthinking: nope\n---\nx");
+	writeFileSync(join(cwd, ".pi/agents/notes.txt"), "ignored");
+	const { agents, errors } = discoverAgents({ cwd, home });
+	assert.deepEqual(agents.map((agent) => `${agent.name}:${agent.description}:${agent.scope}`), ["gentle-ai-explore:Read-only exploration and mapping.:global", "shared:project agents:project"]);
+	assert.equal(errors.length, 1);
+	assert.match(errors[0], /broken\.md/);
+	assert.deepEqual(discoverAgents({ cwd: join(root, "empty"), home: join(root, "nohome") }), { agents: [], errors: [] });
+});
+
+test("profile agent roots isolate global definitions and subagents.json while explicit homes keep their fallback", () => {
+	const cwd = join(root, "profile-project");
+	const principal = join(root, "pi-principal", "agent");
+	const lab = join(root, "pi-lab", "agent");
+	for (const [agentHome, name, model] of [[principal, "principal", "openai/principal"], [lab, "lab", "openai/lab"]] as const) {
+		mkdirSync(join(agentHome, "agents"), { recursive: true });
+		writeFileSync(join(agentHome, "agents", `${name}.md`), `---\ndescription: ${name}\n---\n${name}`);
+		writeFileSync(join(agentHome, "subagents.json"), JSON.stringify({ default_model: model }));
+	}
+	assert.deepEqual(agentDirectories({ cwd, home: join(root, "legacy-home"), agentHome: principal }).slice(0, 2).map(({ dir }) => dir), [join(principal, "agents"), join(principal, "subagents")]);
+	assert.deepEqual(discoverAgents({ cwd, home: join(root, "legacy-home"), agentHome: principal }).agents.map((agent) => agent.name), ["principal"]);
+	assert.deepEqual(discoverAgents({ cwd, home: join(root, "legacy-home"), agentHome: lab }).agents.map((agent) => agent.name), ["lab"]);
+	assert.equal(loadAgentsConfig({ cwd, home: join(root, "legacy-home"), agentHome: principal }).defaultModel?.id, "principal");
+	assert.equal(loadAgentsConfig({ cwd, home: join(root, "legacy-home"), agentHome: lab }).defaultModel?.id, "lab");
+	assert.equal(agentDirectories({ cwd, home: join(root, "legacy-home") })[0].dir, join(root, "legacy-home", ".pi", "agent", "agents"));
+});
+
+test("parseAgentsConfig applies defaults, validates values, and silently ignores the retired total-timeout key", () => {
+	const config = parseAgentsConfig({ default_model: "openai-codex/gpt-6-astra", default_effort: "medium", max_concurrency: 3, timeout_ms: 1000, stall_timeout_ms: 12_000, model_profiles: { explore: { model: "openai-codex/gpt-5.6-terra", effort: "high" } } }, { max_concurrency: 2, timeout_ms: 500, model_profiles: { explore: { effort: "low" }, worker: { model: "anthropic/claude-sonnet-5" } } });
+	assert.deepEqual(config.defaultModel, { provider: "openai-codex", id: "gpt-6-astra" });
+	assert.equal(config.defaultThinking, "medium");
+	assert.equal(config.maxConcurrency, 2);
+	assert.equal(config.stallTimeoutMs, 12_000);
+	assert.equal("timeoutMs" in config, false, "legacy timeout_ms must not become an active runtime setting");
+	assert.deepEqual(config.modelProfiles.explore, { model: { provider: "openai-codex", id: "gpt-5.6-terra" }, thinking: "low" });
+	assert.deepEqual(config.modelProfiles.worker, { model: { provider: "anthropic", id: "claude-sonnet-5" }, thinking: undefined });
+	const defaults = parseAgentsConfig(undefined, undefined);
+	assert.equal(defaults.maxConcurrency, 5);
+	assert.equal("timeoutMs" in defaults, false);
+	assert.equal(defaults.stallTimeoutMs, 4 * 60_000);
+	assert.equal(defaults.defaultMode, AGENT_MODE.TASK);
+	assert.equal(defaults.historyMaxTasks, 200);
+	assert.equal(parseAgentsConfig({ max_concurrency: "many", default_effort: "wild", default_mode: "background" }, undefined).maxConcurrency, 5);
+	assert.equal(parseAgentsConfig({ default_mode: "background" }, undefined).defaultMode, AGENT_MODE.BACKGROUND);
+});
+
+test("resolveAgentProfile prefers the profile, then the definition, then the defaults", () => {
+	const config = parseAgentsConfig({ default_model: "openai-codex/gpt-6-astra", default_effort: "medium", model_profiles: { "gentle-ai-explore": { effort: "high" } } }, undefined);
+	const explore = parseAgentDefinition(EXPLORER, "/x/explore.md", "global");
+	assert.ok(!("error" in explore));
+	assert.deepEqual(resolveAgentProfile(explore, config), { model: { provider: "openai-codex", id: "gpt-5.6-terra" }, thinking: "high", source: { model: "definition", thinking: "profile" } });
+	const bare = parseAgentDefinition("---\nname: bare\n---\nbody", "/x/bare.md", "global");
+	assert.ok(!("error" in bare));
+	assert.deepEqual(resolveAgentProfile(bare, config), { model: { provider: "openai-codex", id: "gpt-6-astra" }, thinking: "medium", source: { model: "default", thinking: "default" } });
+	assert.deepEqual(resolveAgentProfile(bare, parseAgentsConfig(undefined, undefined)).source, { model: "unresolved", thinking: "unresolved" });
+});

package/tests/agents-fake-child.ts

@@ -0,0 +1,52 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import type { ChildLike } from "../lib/agents-runner.ts";
+
+// A fake `pi --mode rpc` child: answers every command with a success
+// response, records what the host wrote, and lets tests emit events.
+
+export interface FakeChild {
+	child: ChildLike;
+	written: Array<Record<string, unknown>>;
+	emit(event: Record<string, unknown>): void;
+	exit(code: number): void;
+	fail(message: string): void;
+	killed: string[];
+}
+
+export function fakeChild(options: { exitOnKill?: boolean; pid?: number } = {}): FakeChild {
+	const emitter = new EventEmitter();
+	const stdin = new PassThrough();
+	const stdout = new PassThrough();
+	const written: Array<Record<string, unknown>> = [];
+	const killed: string[] = [];
+	let buffer = "";
+	stdin.on("data", (chunk: Buffer) => {
+		buffer += chunk.toString();
+		const lines = buffer.split("\n");
+		buffer = lines.pop() ?? "";
+		for (const line of lines) {
+			const command = JSON.parse(line) as Record<string, unknown>;
+			written.push(command);
+			if (command.type === "extension_ui_response") continue;
+			const data = command.type === "get_state" ? { sessionFile: "/sessions/child.jsonl" } : undefined;
+			stdout.write(`${JSON.stringify({ type: "response", id: command.id, command: command.type, success: true, data })}\n`);
+		}
+	});
+	const child: ChildLike = {
+		pid: options.pid,
+		stdin,
+		stdout,
+		stderr: new PassThrough(),
+		kill: (signal) => {
+			killed.push(String(signal ?? "SIGTERM"));
+			if (options.exitOnKill !== false) queueMicrotask(() => emitter.emit("exit", 0, signal ?? "SIGTERM"));
+			return true;
+		},
+		on: (event, listener) => {
+			emitter.on(event, listener);
+			return child;
+		},
+	};
+	return { child, written, killed, emit: (event) => stdout.write(`${JSON.stringify(event)}\n`), exit: (code) => emitter.emit("exit", code, null), fail: (message) => emitter.emit("error", new Error(message)) };
+}

package/tests/agents-history.test.ts

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { after } from "node:test";
+import { historyDir, loadHistory, loadStoredTask, pruneHistory, saveTask } from "../lib/agents-history.ts";
+import { applyTaskEvent, emptyThread, TASK_EVENT, TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
+
+// Gentle Agents history: JSON per task, async, lazy, pruned by count.
+
+const root = mkdtempSync(join(tmpdir(), "gentle-agents-history-"));
+after(() => rmSync(root, { recursive: true, force: true }));
+const dir = join(root, "tasks");
+
+function task(id: string, createdAt: number): TaskRecord {
+	return { id, agent: "explore", mode: "task", prompt: "p", label: "p", cwd: "/r", parentSessionId: "s", status: TASK_STATUS.COMPLETED, createdAt, startedAt: createdAt, endedAt: createdAt + 5, model: "m", thinking: undefined, sessionPath: null, error: null, result: "ok", lastStep: "done", lastActivityAt: createdAt, turns: 1, toolCalls: 0, tokens: 10, cost: 0.01 };
+}
+
+test("historyDir follows an isolated agent profile while explicit homes retain the default fallback", () => {
+	assert.equal(historyDir("/home/x", "/profiles/pi-principal/agent"), join("/profiles/pi-principal/agent", "gentle-agents", "tasks"));
+	assert.equal(historyDir("/home/x", "/profiles/pi-lab/agent"), join("/profiles/pi-lab/agent", "gentle-agents", "tasks"));
+	assert.equal(historyDir("/home/x"), join("/home/x", ".pi", "agent", "gentle-agents", "tasks"));
+});
+
+test("saveTask writes a task with its thread and loadStoredTask reads it back", async () => {
+	const thread = applyTaskEvent(emptyThread(), { type: TASK_EVENT.TEXT, text: "hello" });
+	await saveTask(dir, task("a1", 1000), thread);
+	const stored = await loadStoredTask(dir, "a1");
+	assert.equal(stored?.task.result, "ok");
+	assert.deepEqual(stored?.thread.items, [{ kind: "text", text: "hello" }]);
+	assert.equal(await loadStoredTask(dir, "missing"), undefined);
+	assert.equal(await loadStoredTask(dir, "../etc/passwd"), undefined);
+	assert.deepEqual(readdirSync(dir), ["a1.json"], "no temp file is left behind");
+});
+
+test("loadHistory skips broken files, sorts newest first, and pruneHistory keeps the newest N", async () => {
+	await saveTask(dir, task("b2", 3000), emptyThread());
+	await saveTask(dir, task("c3", 2000), emptyThread());
+	writeFileSync(join(dir, "junk.json"), "{not json");
+	writeFileSync(join(dir, "shape.json"), JSON.stringify({ task: { id: 1 } }));
+	assert.deepEqual((await loadHistory(dir)).map((entry) => entry.task.id), ["b2", "c3", "a1"]);
+	assert.equal(await pruneHistory(dir, 2), 1);
+	assert.deepEqual((await loadHistory(dir)).map((entry) => entry.task.id), ["b2", "c3"]);
+	assert.deepEqual(await loadHistory(join(root, "nowhere")), []);
+});
+
+test("TaskStore.restore adds a stored task without clobbering a live one", () => {
+	const store = new TaskStore();
+	const thread = applyTaskEvent(emptyThread(), { type: TASK_EVENT.NOTE, text: "restored" });
+	assert.equal(store.restore(task("r1", 1000), thread), true);
+	assert.equal(store.thread("r1").items.length, 1);
+	assert.equal(store.restore({ ...task("r1", 1000), result: "other" }, emptyThread()), false);
+	assert.equal(store.get("r1")?.result, "ok");
+});