pi-orchestrator-config 4.21.0 → 4.22.1

package/README.md

@@ -26,7 +26,7 @@ Single extension that provides:
 | **Git status**                | Live git status in status line with colored icons — updates after every tool call. Shows clickable `#N` when the branch has an open PR. Last-activity clock `⏱ HH:MM (Xm/Xh ago)` shows time since last response                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | **Desktop notifications**     | Notifies via `notify-send` on task completion, waiting for input, and action required                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | **File preview**              | Serves generated HTML/frontend files via HTTP for browser preview from container                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| **Graft integration**         | When `graft_enable=true`, main agents and subagents query the local Graft graph before raw project navigation on substantive prompts. Children only consume graphs. Stale graphs remain usable, retrieval failures fall back to raw tools, and main processes coordinate rebuilds with a cross-process lock.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| **Trail-code integration**    | On by default when the `trail` binary is installed. Main agents and subagents query the local code map before raw project navigation: the first project navigation per turn is gated behind a `trail_*` call, guidance is map-first (`trail_find_code` first, `trail_repo_map` once per session), and injected hits carry source. Worktrees resolve the map under `graft/` or `.trail/cache/`, inherit enablement from the main checkout, and seed from it instead of cold-building. Stale maps stay usable and failures fall open. |
 | **Pidash dashboard**          | Live web dashboard — multi-session monitoring, browser messaging, model switching, live session name updates, reasoning token display                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | **Pidiff viewer**             | Per-project diff viewer with review comments — branch diffs, file tree, inline comments, git-based ignore rules                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | **Dreaming**                  | Background memory consolidation — extracts memories from sessions, deduplicates, maintains topic-based memory                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
@@ -179,7 +179,7 @@ The installer covers:
 
 - **Pi Packages** — pi-config, pi-vertex-claude, pi-web-access, myk-pi-tools, bun
 - **Python Tools** — prek
-- **npm Packages** — acpx, agent-browser, graft
+- **npm Packages** — acpx, agent-browser, trail-code (`@trailhq/trail-code`)
 - **Browser Automation** — playwright + chromium
 - **Environment Setup** — gitignore configuration
 
@@ -425,28 +425,74 @@ Set `image_model` in `pi-config-settings.json` or use `PI_IMAGE_MODEL` env var.
 
 In containers, images are auto-served via HTTP for browser preview.
 
-### Graft repository graph (optional)
+### Trail-code code map (on by default)
 
-Set `graft_enable` to `true` in `.pi/pi-config-settings.json` (or set
-`PI_GRAFT_ENABLE=true`) to enable local Graft repository graph context:
+Trail-code is the local code map behind the `trail_*` tools. It is **on by
+default** whenever the `trail` binary is on `PATH` — no setting required. In a
+trusted git worktree, pi indexes the project and gives main agents and
+subagents a queryable map, so the first project navigation of every substantive
+turn is a `trail_*` query instead of a blind `grep`.
+
+Install or upgrade the CLI:
+
+```bash
+DO_NOT_TRACK=1 npm install -g @trailhq/trail-code@latest
+uv run scripts/install.py   # audited install used by the container
+```
+
+The installer downloads `@trailhq/trail-code@latest` with scripts disabled into a
+dedicated npm prefix, audits that isolated dependency tree for lifecycle scripts,
+and strictly rebuilds it with only those packages approved. The completed prefix
+is published under the global npm prefix and its `trail` binary linked globally,
+so unrelated global packages are never evaluated. It verifies `trail --version`;
+`DO_NOT_TRACK=1` disables Trail telemetry. Requirements: Node.js 22+, npm 12+,
+and the node-gyp prerequisites (Python 3, `make`, G++). If the binary is missing
+or the install fails, pi continues without the map and the `trail_*` tools are
+simply absent.
+
+**Kill switch.** `trail_enable` (env `PI_TRAIL_ENABLE`) defaults to `true`. Set it
+to `false` in `.pi/pi-config-settings.json`, or globally in
+`~/.pi/pi-config-settings.json`, to keep the integration fully inactive:
 
 ```json
 {
-  "graft_enable": true
+  "trail_enable": false
 }
 ```
 
-Graft requires Node.js 22+, npm 12+, node-gyp prerequisites (Python 3, `make`, and
-G++), and the `graft` CLI. The container includes them; native installs can use
-`uv run scripts/install.py`. The installer downloads `@nanonets/graft@latest` with
-scripts disabled into a dedicated npm prefix, audits that isolated dependency tree
-for lifecycle scripts, and strictly rebuilds it with only those packages approved.
-The completed prefix is then published under the global npm prefix and its `graft`
-binary linked globally, so unrelated global packages are never evaluated. The
-installer verifies `graft --version`; `DO_NOT_TRACK=1` disables Graft telemetry.
-When enabled, Graft reads the trusted project and writes a regenerable `./graft/`
-cache. Delete that directory or set `graft_enable` to `false` to disable it. If the
-native CLI is unavailable or its installation fails, pi continues without Graft.
+**Where the map lives.** Upstream owns the path: `./graft/` on older repos and
+`.trail/cache/` once a repo is on trail (upstream renames a legacy map itself).
+Both are regenerable and gitignored, and pi reads whichever is present. Never
+commit them.
+
+**Worktrees.** The map is resolved from the worktree root, and enablement is
+inherited from the main checkout when the worktree has no `.pi` settings file
+(`.pi/` is gitignored, so a fresh worktree would otherwise look disabled). A
+fresh worktree seeds its own cache from the main checkout on the first query — a
+copy plus branch-diff repair, never a cold rebuild — and never writes to the main
+checkout's map. Expect roughly 48 MB per worktree in this repo.
+
+**Layers.** This is not memory. Pi memory (`.pi/memory/`, dreaming, enforced
+entries) is what pi carries between sessions. Trail's own layer —
+`.trail/learnings/`, `trail note`, the pre-ship `trail check` — is upstream's and
+**we do not use it**. We only read the code map.
+
+### Migrating from Graft
+
+The integration was renamed from Graft to Trail-code. The break is intentional:
+
+- Only `@trailhq/trail-code` is installed and only `trail` is invoked. The `graft`
+  binary is no longer installed and there is no fallback — if you only have
+  `@nanonets/graft`, install trail to get the map tools back.
+- `graft_enable` / `PI_GRAFT_ENABLE` are gone, with no alias and no migration. An
+  existing `graft_enable: true` is a dead key, which is harmless: the feature is
+  default-on when the binary exists.
+- Tools are `trail_find_code`, `trail_find_all`, `trail_file_api`,
+  `trail_trace_calls`, `trail_repo_map`, `trail_refresh`, `trail_blast_radius`.
+- `log_graft` becomes `log_trail` (env `PI_LOG_TRAIL`); the old `~/.pi/logs/graft`
+  directory is neither read nor migrated.
+- `graft/` survives as a _path_ until upstream renames it: it is the map
+  directory, not the product.
 
 ### Cache Miss Notices
 
@@ -469,20 +515,20 @@ Run pi inside a disposable container for **filesystem isolation** — the agent
 - **Consistent tooling** — All required tools pre-installed in a single image
 - **Disposable** — Container is destroyed after each session (`--rm`)
 
-**Graft (optional `graft_enable`):** The image installs the latest
-`@nanonets/graft` with `DO_NOT_TRACK=1`. It downloads with scripts disabled, derives
+**Trail-code (`trail_enable`, on by default):** The image installs the latest
+`@trailhq/trail-code` with `DO_NOT_TRACK=1`. It downloads with scripts disabled, derives
 an exact script allowlist by auditing the installed package's reachable dependency
 metadata in a dedicated npm prefix, then strictly rebuilds that isolated tree with
 those approvals. Only after the rebuild succeeds is the completed prefix moved under
-the global npm prefix and its `graft` binary linked globally. This prevents unrelated
+the global npm prefix and its `trail` binary linked globally. This prevents unrelated
 global packages from entering npm's strict preflight. The allowlist is command-scoped
 and changes with `@latest`; other npm commands keep npm 12's install-script
 protections. The image includes Python 3,
-`make`, and the GCC/G++ toolchain required by node-gyp for Graft and other native
+`make`, and the GCC/G++ toolchain required by node-gyp for Trail-code and other native
 npm packages; these remain available for reliable package rebuilds. The build then
-verifies `graft --version`. Enable Graft in trusted project or global pi-config
-settings; it reads the project locally and stores its regenerable graph in `./graft/`. Set
-`graft_enable` to `false` and delete that directory to disable and remove the cache.
+verifies `trail --version`. The map is written to the mounted project's `./graft/` or
+`.trail/cache/` directory; set `trail_enable` to `false` and delete that directory to
+disable and remove the cache.
 Native installations require Node.js 22+, npm 12+, Python 3, `make`, and G++; the
 installer uses the same audited strict installation and failure remains non-fatal.
 
@@ -789,7 +835,7 @@ PI_PIDIFF_ENABLE=false pi
 | `acpx`              | Agent proxy for remote models                                                                                                                                                                                                                                                                                                  |
 | `kubectl` / `oc`    | Kubernetes and OpenShift CLI                                                                                                                                                                                                                                                                                                   |
 | `agent-browser`     | Browser automation CLI (navigate, click, screenshot, forms)                                                                                                                                                                                                                                                                    |
-| `graft`             | Local repository code graph for opt-in `graft_enable`; graph cache is stored in the mounted project’s `./graft/` directory                                                                                                                                                                                                        |
+| `trail`             | Local code map for `trail_enable` (on by default); the regenerable cache lives in the mounted project's `./graft/` or `.trail/cache/` directory |
 | `procps`            | Process utilities (ps, top, pgrep, pkill)                                                                                                                                                                                                                                                                                      |
 | `passwd`            | `usermod`/`groupmod` — init remaps user `node` to `PI_HOST_UID`/`PI_HOST_GID`                                                                                                                                                                                                                                                  |
 | `docker` / `podman` | Container CLIs (used via `docker-safe` read-only wrapper)                                                                                                                                                                                                                                                                      |
@@ -814,7 +860,7 @@ PI_PIDIFF_ENABLE=false pi
 | `myk-pi-tools pr claude-md`            | Fetch `CLAUDE.md` and `AGENTS.md` content for a PR's repository                                                                                |
 | `myk-pi-tools release create`          | Create a GitHub release with changelog                                                                                                         |
 | `myk-pi-tools release plan`            | Scoped-release plan: which packages changed since their last publish (per-package registry-anchored diff windows). Detection only — no proposed versions. Read-only; requires `release-map.toml` at the repo root — without it, reports lockstep mode and changes nothing (issue #965) |
-| `myk-pi-tools release bump-scoped`     | Bump ONLY the affected packages' version files. Versions are ALWAYS explicit: `--set NAME=VERSION` per affected package (the versions the LLM/user decided in the `/release` flow) or a global `--version X.Y.Z` — the plan never proposes versions. Each package versions from its own registry history (no global repo-tag guard — no forced jumps for long-skipped packages); tags are per-package `<name>@<version>`. Versions are validated (strict x.y.z, no leading zeros, strictly greater than the registry-published version). Errored packages, undetected version files, or partially-updatable manifests abort before or at the first bad write. Requires `release-map.toml` — without it, exit 1 (use `bump-version` for lockstep) (issue #965) |
+| `myk-pi-tools release bump-scoped`     | Bump ONLY the affected packages' version files. Versions are ALWAYS explicit: `--set NAME=VERSION` per affected package (the versions the LLM/user decided in the `/release` flow) or a global `--version X.Y.Z` — the plan never proposes versions. Each package versions from its own registry history (no global repo-tag guard — no forced jumps for long-skipped packages); tags are per-package `<name>@<version>`. Versions are validated (strict x.y.z, no leading zeros, strictly greater than the registry-published version). Errored packages, undetected version files, or partially-updatable manifests abort before or at the first bad write. Requires `release-map.toml` — without it, exit 1 (use `bump-version` for lockstep) (issue #965). When the repo has a `uv.lock` the bump refreshes it with `uv lock` and reports it under its own `lockfile` key — `updated[]` keeps only version files; a missing or failing `uv` reports `refreshed: false` instead of failing the release. |
 | `myk-pi-tools db`                      | Review database query commands                                                                                                                 |
 | `myk-pi-tools reviews`                 | Review handling commands (fetch, poll, address, post, store, store-session)                                                                   |
 | `myk-pi-tools reviews poll`            | Poll a PR for review comments until approved or actionable — `--source qodo` reads findings through the `qodo` CLI (structured, with spans and authoritative open/closed status) when the binary is installed and authenticated, and falls back to the GitHub sticky-comment scrape otherwise. Read-only: replies are always posted as GitHub comments via `reviews address` |
@@ -968,7 +1014,8 @@ Control your pi sessions from your phone via Discord DMs.
    - Go to "Bot" section → click "Reset Token" → copy the token
    - Enable "Message Content Intent" under "Privileged Gateway Intents"
    - Go to "OAuth2 > URL Generator" → select scope `bot` → select permissions:
-     `Send Messages`, `Read Message History`, `Add Reactions`, `View Channels`
+     `Send Messages`, `Read Message History`, `Add Reactions`, `View Channels`,
+     and for per-session threads: `Create Public Threads`, `Send Messages in Threads`
    - Open the generated URL → add bot to your server
 
 2. **Configure:**
@@ -978,11 +1025,21 @@ Control your pi sessions from your phone via Discord DMs.
    cat > ~/.pi/discord.env << EOF
    DISCORD_BOT_TOKEN=your-token-here
    DISCORD_ALLOWED_USERS=your-discord-user-id
+   # Optional: open access without an allowlist (off by default)
+   # DISCORD_ALLOW_ALL=true
+   # Optional: how long a pending agent question waits (default 10m, min 30s)
+   # DISCORD_PROMPT_TTL_MS=600000
+   # Optional: forum channel id for /board (one post per session)
+   # DISCORD_FORUM_CHANNEL_ID=
    EOF
    ```
 
    Find your Discord user ID: Settings > Advanced > Developer Mode ON, then right-click yourself > Copy User ID.
 
+   > The bot refuses to start without `DISCORD_ALLOWED_USERS` — a token alone must
+   > not mean "anyone who DMs the bot drives your agent". Set
+   > `DISCORD_ALLOW_ALL=true` only if you really want open access.
+
 3. **Restart pidash:**
    The Discord bot runs inside the pidash server daemon. Restart it to pick up the config:
 
@@ -992,15 +1049,30 @@ Control your pi sessions from your phone via Discord DMs.
 
 ### Discord Commands
 
-| Command     | Description                         |
-| ----------- | ----------------------------------- |
-| `!sessions` | List active pi sessions             |
-| `!watch N`  | Watch/switch to session N           |
-| `!status`   | Show current session info           |
-| `!abort`    | Abort current operation             |
-| `!help`     | Show commands                       |
-| Any text    | Send as prompt to watched session   |
-| `/command`  | Forward slash command to pi session |
+| Command              | Description                                        |
+| -------------------- | -------------------------------------------------- |
+| `/sessions`          | Paginated, ephemeral list with watch buttons       |
+| `/watch session:<n>` | Watch a session by name (autocomplete)             |
+| `/status`            | Watched session: model, branch, state, cwd         |
+| `/stop`              | Interrupt the running turn                         |
+| `/compact`           | Compact the watched session's context              |
+| `/model [value]`     | Show or switch the model                           |
+| `/thinking [value]`  | Show or set the thinking level                     |
+| `/tasks` `/coms` `/memory` `/mcp` `/diff` | Inspect the watched session       |
+| `/file path:<rel>`   | Send a file from the session cwd (8MB max)         |
+| `/notify on\|off`     | DM when a turn finishes in an unwatched session    |
+| Any text (DM/thread) | Send as a prompt to the watched session            |
+| `/cancel`            | Dismiss a pending agent question                   |
+
+Agent questions arrive with **Approve/Deny** buttons or a dropdown; you can also
+reply `yes`/`no`, an option number, or the option text. In a server, watching a
+session opens a **thread** for it (DMs are used as a fallback).
+
+The bot fails closed: without `DISCORD_ALLOWED_USERS` it refuses to start unless
+you set `DISCORD_ALLOW_ALL=true`. Commands, reaction shortcuts (⏹ 🔁 🗑), the
+forum session board and every environment variable are documented in
+[docs/discord-bot.md](docs/discord-bot.md)
+for the full surface.
 
 ### How It Works
 
@@ -1021,7 +1093,7 @@ it also runs as a pre-commit hook when TypeScript files change.
 
 ## Prerequisites
 
-- [pi](https://github.com/badlogic/pi-mono) (minimum version: **0.99.0**). Pidash uses Pi's `ui_prompt_start` and `ui_prompt_end` events to show prompt wait separately from agent work.
+- [pi](https://github.com/badlogic/pi-mono) (minimum version: **1.4.0**). Pidash uses Pi's `ui_prompt_start` and `ui_prompt_end` events to show prompt wait separately from agent work.
 - `gh` CLI (for GitHub operations)
 - `uv` (for Python execution)
 - `myk-pi-tools` (optional, for `/pr-review` and `/release`)

package/extensions/orchestrator/async-agents.ts

@@ -17,7 +17,7 @@ const require = createRequire(import.meta.url);
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig, AgentDiscoveryResult } from "./agents.js";
 import { resolveAgentModelProvider } from "./resolve-agent-model.js";
-import { withGraftTools } from "./graft.js";
+import { trailToolsArgs } from "./trail.js";
 import { getPiInvocation, getProjectTmpDir, parseProcStartTime, djb2Hash } from "./utils.js";
 import { addReviewerPending, recordReviewerResult, countFindings, readReviewState } from "./pi-config-review-state.js";
 import {
@@ -1097,8 +1097,7 @@ export function registerAsyncAgents(
     piArgs.push("--session-id", deterministicSessionId);
     if (effectiveModel) piArgs.push("--model", effectiveModel);
     if (effectiveProvider) piArgs.push("--provider", effectiveProvider);
-    const tools = withGraftTools(agent.tools, getSetting(cwd, "graft_enable"));
-    if (tools?.length) piArgs.push("--tools", tools.join(","));
+    piArgs.push(...trailToolsArgs(agent.tools, cwd));
 
     if (agent.systemPrompt?.trim()) {
       const promptPath = path.join(workerDir, "system-prompt.md");

package/extensions/orchestrator/index.ts

@@ -37,7 +37,7 @@ import { registerSettingsTui } from "./settings-tui.js";
 import { buildSituationReport } from "./situation-report.js";
 import { listTopics } from "./memory-tree.js";
 import { registerMarkdownTransformer } from "./markdown-transformer.js";
-import { registerGraft } from "./graft.js";
+import { registerTrail } from "./trail.js";
 import { registerReviewLearning } from "./review-learning.js";
 import { ensureGitSshTimeout, isRunningInContainer, terminalNotify } from "./utils.js";
 import { createLogger } from "../shared/logger.js";
@@ -129,7 +129,7 @@ export default function (pi: ExtensionAPI) {
   const { spawnAsyncAgent, killAsyncAgent, getAsyncJobs } = registerAsyncAgents(pi, terminalNotify);
   registerSubagentTool(pi, spawnAsyncAgent, killAsyncAgent);
   registerProjectSettings(pi);
-  registerGraft(pi);
+  registerTrail(pi);
   registerEnforcement(pi, IN_CONTAINER);
   registerReviewUI(pi);
   registerRules(pi, getAsyncJobs);

package/extensions/orchestrator/project-settings.ts

@@ -46,8 +46,8 @@ interface ProjectSettings {
   cli_agents?: string | string[];
   pidash_enable?: boolean;
   pidiff_enable?: boolean;
-  /** Enable local Graft repository graph integration. Default: false. */
-  graft_enable?: boolean;
+  /** Enable local Trail code map integration. Default: true. */
+  trail_enable?: boolean;
   pidash_port?: number;
   task_auto_clear_enabled?: boolean;
   task_auto_clear_minutes?: number;
@@ -123,7 +123,7 @@ const PROJECT_SETTINGS_KEYS: (keyof ProjectSettings)[] = [
   "cli_agents",
   "pidash_enable",
   "pidiff_enable",
-  "graft_enable",
+  "trail_enable",
   "pidash_port",
   "task_auto_clear_enabled",
   "task_auto_clear_minutes",
@@ -185,7 +185,7 @@ export function parseSettingsFile(filePath: string): ProjectSettings {
     if (typeof raw.orchestrator_edit_write_block === "boolean") result.orchestrator_edit_write_block = raw.orchestrator_edit_write_block;
     if (typeof raw.pidash_enable === "boolean") result.pidash_enable = raw.pidash_enable;
     if (typeof raw.pidiff_enable === "boolean") result.pidiff_enable = raw.pidiff_enable;
-    if (typeof raw.graft_enable === "boolean") result.graft_enable = raw.graft_enable;
+    if (typeof raw.trail_enable === "boolean") result.trail_enable = raw.trail_enable;
     if (typeof raw.pidash_port === "number" && Number.isInteger(raw.pidash_port) && raw.pidash_port > 0 && raw.pidash_port <= 65535) {
       result.pidash_port = raw.pidash_port;
     }
@@ -238,7 +238,7 @@ export function parseSettingsFile(filePath: string): ProjectSettings {
     const SPECIAL_CASE_KEYS = new Set<string>([
       "commit_trailer", "allow_push_to_protected_branches", "use_worktrees",
       "dream_interval_hours", "dco", "comment_signature", "review_loop_enforcement",
-      "orchestrator_edit_write_block", "pidash_enable", "pidiff_enable", "graft_enable", "pidash_port",
+      "orchestrator_edit_write_block", "pidash_enable", "pidiff_enable", "trail_enable", "pidash_port",
       "image_model", "internal_operations_provider", "internal_operations_model",
       "review_loop_max_cycles", "acpx_agents", "cli_agents", "agent_provider",
       "agent_model", "agent_overrides",
@@ -485,7 +485,7 @@ export function getSetting(cwd: string, key: "acpx_agents"): string[];
 export function getSetting(cwd: string, key: "cli_agents"): string[];
 export function getSetting(cwd: string, key: "pidash_enable"): boolean;
 export function getSetting(cwd: string, key: "pidiff_enable"): boolean;
-export function getSetting(cwd: string, key: "graft_enable"): boolean;
+export function getSetting(cwd: string, key: "trail_enable"): boolean;
 export function getSetting(cwd: string, key: "pidash_port"): number;
 export function getSetting(cwd: string, key: "task_auto_clear_enabled"): boolean;
 export function getSetting(cwd: string, key: "task_auto_clear_minutes"): number;

package/extensions/orchestrator/review-learning.ts

@@ -1391,12 +1391,12 @@ export function createReviewLearning(options: ReviewLearningOptions = {}) {
       }
     });
 
-    // Surface 1 — before_agent_start injection (graft-gate pattern).
+    // Surface 1 — before_agent_start injection (trail-gate pattern).
     // Purely mechanical path extraction (prompt tokens + branch diff), sync
     // DB/git with timeouts, no model calls. Diff paths are repo-relative —
     // normalized against the worktree ROOT so nested sessions still match
     // the DB's repo-relative paths. Must be fast and never throw — other
-    // before_agent_start handlers (graft gate, rules) must not stall.
+    // before_agent_start handlers (trail gate, rules) must not stall.
     pi.on("before_agent_start", (event: any, ctx: any) => {
       try {
         const cwd = ctx?.cwd;
@@ -1415,7 +1415,7 @@ export function createReviewLearning(options: ReviewLearningOptions = {}) {
         recall.fullBlockInjected = true;
         log.info("recall_injected_prompt", { paths: findings.length, chars: block.length });
         // Prefer a custom prompt section (rules.ts pattern — preserves cached
-        // prompt prefixes); fall back to the graft return shape when a prior
+        // prompt prefixes); fall back to a replacement prompt when a prior
         // handler forced the whole prompt or sections are unavailable.
         const opts = event?.systemPromptOptions;
         const sections = opts?.sections;
@@ -1430,7 +1430,7 @@ export function createReviewLearning(options: ReviewLearningOptions = {}) {
       }
     });
 
-    // Surface 2 — first-write tool_result hint (graft blastHint pattern):
+    // Surface 2 — first-write tool_result hint (trail blastHint pattern):
     // catches paths discovered mid-run that prompt extraction missed. Appends
     // once per path per session; a path is checked once per session whether
     // or not it has findings (a no-findings path must not re-query the DB on

package/extensions/orchestrator/rules.ts

@@ -236,19 +236,23 @@ export function registerRules(
       }
     }
 
+    // 1.4.0's BeforeAgentStartEvent is a union: `prompt` exists only on the user
+    // variant, so narrow once here and use this for every downstream lookup.
+    const prompt = event.messageType === "user" ? event.prompt : undefined;
+
     // Project memories — situation report (scored, token-budgeted) injected BEFORE rules
     // systemPrompt.length is chars; estimateMemoryBudget converts internally
     const budget = estimateMemoryBudget(event.systemPrompt?.length ?? 0, undefined, ctx.cwd);
     const queryClass =
-      !isSubagent && event.prompt && !isSocialCloser(event.prompt)
-        ? classifyQueryClass(event.prompt)
+      !isSubagent && prompt && !isSocialCloser(prompt)
+        ? classifyQueryClass(prompt)
         : "general";
     const memories = loadMemoriesWithScoring(ctx.cwd, isSubagent, budget, queryClass);
 
     // Auto-inject contextually relevant memories via vector search (~2.5ms, in-process)
     // Session-scoped/expired entries are filtered out first (Qodo #19, PR #916)
     // — a session rule must not leak into a later session's context.
-    const shouldSearch = !isSubagent && !!event.prompt && !isSocialCloser(event.prompt);
+    const shouldSearch = !isSubagent && !!prompt && !isSocialCloser(prompt);
     let contextMemories = "";
     if (shouldSearch) {
       try {
@@ -271,7 +275,7 @@ export function registerRules(
                   ...entries.filter((e) => !boostCats.has(e.category)),
                 ]
               : entries;
-          const results = await vectorSearch(ctx.cwd, event.prompt, searchPool, topK);
+          const results = await vectorSearch(ctx.cwd, prompt, searchPool, topK);
           const injectThreshold = Number(getSetting(ctx.cwd, "memory_inject_similarity")) || 0.65;
           const relevant = results.filter(r => r.similarity > injectThreshold);
           if (relevant.length > 0) {
@@ -281,7 +285,7 @@ export function registerRules(
               relevant.map(r => `- [${r.category}] ${r.text} (similarity: ${r.similarity.toFixed(3)})`).join("\n") +
               "\n\n";
             // Retrieval telemetry — track what was injected
-            logMemoryInjection(ctx.cwd, event.prompt, relevant, queryClass);
+            logMemoryInjection(ctx.cwd, prompt, relevant, queryClass);
             lastInjectedMemories = relevant;
             log.info("memory_injected", relevant.length);
           }
@@ -294,7 +298,7 @@ export function registerRules(
     if (shouldSearch) {
       try {
         const { searchSessions } = await import("./session-search.js");
-        const sessionResults = searchSessions(ctx.cwd, event.prompt, 3);
+        const sessionResults = searchSessions(ctx.cwd, prompt, 3);
         if (sessionResults.length > 0) {
           log.info("context_injected", "session_history");
           sessionContext = "\n# Relevant Past Sessions\n\n" +
@@ -307,7 +311,7 @@ export function registerRules(
           try {
             getTelemetryLog(ctx.cwd).append({
               event: "session-inject",
-              prompt: event.prompt.slice(0, 200),
+              prompt: prompt?.slice(0, 200),
               sessionCount: sessionResults.length,
             });
           } catch (e: any) { log.debug("session telemetry write failed:", e?.message?.slice(0, 100)); }

package/extensions/orchestrator/status-bar.ts

@@ -9,7 +9,7 @@
  *
  * Stale-ctx safety (reload crash postmortem, PR #950): ctx.ui getters call
  * assertActive() and THROW after a runtime reload/replacement — an async
- * continuation (e.g. a graft build resolving across a reload) or a
+ * continuation (e.g. a trail build resolving across a reload) or a
  * session_shutdown handler touching a captured ctx must never crash the
  * process over a footer update. Guarded with isLiveExtensionCtx + try/catch.
  */
@@ -26,7 +26,7 @@ const SLOTS = {
   crons:  "3-crons",
   dream:  "3b-dream",
   git:    "4-git",
-  graft:  "4b-graft",
+  trail:  "4b-trail",
   review: "5-review",
 } as const;
 

package/extensions/orchestrator/subagent-tool.ts

@@ -47,7 +47,7 @@ import { getSetting } from "./project-settings.js";
 import { checkSyncLimit } from "./sync-limit.js";
 import { substituteSettingsPlaceholders } from "./rule-placeholders.js";
 import { resolveAgentModelProvider } from "./resolve-agent-model.js";
-import { withGraftTools } from "./graft.js";
+import { trailToolsArgs } from "./trail.js";
 import { parseModelOverride, mergeModelOverride } from "./parse-model-override.js";
 import { clockHHMM, getPiInvocation, getProjectTmpDir, djb2Hash } from "./utils.js";
 
@@ -424,8 +424,7 @@ export async function runSingleAgent(
   const { model: effectiveModel, provider: effectiveProvider } = resolveAgentModelProvider(agentName, agent, parentModelId, parentProvider, cwd, explicit);
   if (effectiveModel) args.push("--model", effectiveModel);
   if (effectiveProvider) args.push("--provider", effectiveProvider);
-  const tools = withGraftTools(agent.tools, getSetting(cwd, "graft_enable"));
-  if (tools?.length) args.push("--tools", tools.join(","));
+  args.push(...trailToolsArgs(agent.tools, cwd));
 
   let tmpDir: string | null = null;
   let tmpFile: string | null = null;