@scotthuang/agent-knock-knock 0.16.6 → 0.16.7

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.16.7 / Pi 0.1.0-poc.15 / DeepSeek Harness 0.1.0-rc.19 — 2026-10-29
+
+- Reduce repeated discovery work within one CLI command: share in-flight Claude reader and terminal probes, isolate the memo between commands, inspect known Claude targets directly, and bound parallel process checks. Execution identity and input fences remain fresh and are never cached as authority.
+- Make default List a lightweight inventory. Detailed approval/composer/task scans are deferred to Status, explicit `--approval-scan` / `noApprovalScan: false`, and execution preflight. Deferred or unknown observations are not proof that a session is input-ready. Keep unavailable or unresolved operations explicit.
+- Preserve the existing default-list treatment of verified unstarted Codex candidates. Only ambiguous same-home/workspace groups receive additional snapshot verification; unavailable evidence keeps candidates visible, and task bodies are excluded from the inventory.
+- Keep detailed Claude List confidence consistent with the exact native identity resolved during that same command. This presentation update does not grant cached input authority or promote unavailable identity evidence.
+- Publish coordinated Pi and DSH connector updates with exact core **0.16.7** dependencies and synchronized Skill guidance. Existing Host compatibility ranges, callback ownership, persistent recovery and prerelease `next` tags remain unchanged.
+- Preserve the PR #484 measurement record as development evidence. Its environment-specific read-only timing samples are not universal latency guarantees; complete Status includes additional safety checks and can remain slower than direct inspection.
+
+## DeepSeek Harness 0.1.0-rc.18 — 2026-10-29
+
+- Add DSH connector author/keywords and a clearer installation/discovery entry. Keep `next` for the prerelease connector and exact core **0.16.6**; no core or Pi release or runtime compatibility expansion.
+- Publish an AKK-maintained format-1 market index using exact published npm versions and reviewed DSH peer ranges, avoiding the old bare-package `latest` selection. It is an opt-in third-party source, not a default official market or endorsement.
+- Repair npm README cross-directory links and clarify POSIX resident-Web, prerelease, clean-restart, approval and callback boundaries. Reuse the existing AKK demo with its actual controller environment identified.
+
 ## 0.16.6 / Pi 0.1.0-poc.14 / DeepSeek Harness 0.1.0-rc.17 — 2026-10-28
 
 - Align Claude List offers with managed Send and native thread-lifecycle admission. Check the applicable transcript-boundary and exact idle-reader requirements, retain bounded readiness diagnostics in compact List, and provide actionable recovery guidance. Execution still captures fresh evidence; List observations do not grant cached input authority.

package/README.md

@@ -75,7 +75,7 @@ That is the terminal first-task flow. For terminal setup and multiple panes, see
 ## Install for Pi
 
 Pi can be the controller Host without OpenClaw. The connector supports Pi `1.2.0`
-and retains `0.84.4` compatibility. It includes AKK `0.14.7`, with direct CLI and
+and retains `0.84.4` compatibility. It includes AKK `0.16.7`, with direct CLI and
 Desktop capabilities governed by the same target-specific boundaries above.
 
 ```bash
@@ -88,16 +88,24 @@ Pi should show `AKK ready`. With a supported coding-agent conversation open, ent
 
 ## Install for DeepSeek Harness
 
-The connector targets DeepSeek Harness Web `0.2.0-rc.2` (upstream `latest`,
-**still a release candidate**). It includes AKK `0.14.7`. See the connector guide
-for the separate alpha and older-version validation boundaries.
+Let DeepSeek Harness delegate to your existing Codex CLI, Codex Desktop and
+Claude Code sessions. Use a resident POSIX **DSH Web 0.2.1-rc.2** Host (the
+reviewed baseline), Node.js `>=22.19.0`, and `pnpm`. The connector pins AKK
+**0.16.7**; newer unlisted DSH versions are not automatically compatible.
 
 ```bash
 dsh plugin --profile web add @scotthuang/agent-knock-knock-deepseek-harness@next
-dsh web
 ```
 
-Open a Web conversation and enter `/akk list`. The connector gives every conversation `/akk`, the same capability-handshake-verified semantic tool catalog, the bundled `agent-knock-knock` skill, and callbacks to the exact Harness Agent that initiated the work. See the [DeepSeek Harness connector guide](connectors/deepseek-harness/README.md).
+Use `@next` or an explicit reviewed RC, not the bare package name. Finish
+existing work, cleanly restart the Web Host after installation, then enter
+`/akk list` in a Web conversation. Do not start a second Host to reload it.
+
+Prefer the DSH plugin UI? Add the [AKK-maintained index](https://raw.githubusercontent.com/scotthuang/agent-knock-knock/main/market/dsh/index.json)
+to **Plugins → Discover**; it installs a pinned published version. This is a
+third-party source, not a default official market. The
+[DSH connector guide](connectors/deepseek-harness/README.md) covers the exact
+setup, compatibility matrix, callbacks, approvals and demo.
 
 ## See It in Action
 
@@ -206,8 +214,8 @@ can use a supported terminal route. Claude Code direct control is available unde
 | Claude Code direct connection | macOS, compatible native peer protocol `1`, and Python 3 available to AKK. Live observations include `2.1.295` and `2.1.296`; these are not minimum versions. Standard `claude` and configured wrappers use the same adapter. See the [direct guide](docs/claude-cli-direct.md) for task and interaction boundaries. |
 | Terminal coding agents | Reviewed Codex profiles include `0.160.0`, `0.162.1`, `0.164.0` and `0.165.0`; Claude fixtures include `2.1.285`, with live observations on `2.1.295`/`2.1.296`. An otherwise eligible, complete `x.y.z` Claude version may attempt supported controls through runtime validation even without an exact regression profile. Actual identity, protocol and UI evidence determine availability; unknown dialogs are not guessed. |
 | OpenClaw | `2026.6.5`+; plugin API and Gateway `2026.5.12`+ |
-| Pi connector | Pi `1.2.0` and `0.84.4`; connector `0.1.0-poc.14` (`next`), pinned AKK `0.16.6` |
-| DeepSeek Harness connector | Web `0.2.1-rc.2` (RC); connector `0.1.0-rc.17` (`next`), pinned AKK `0.16.6`. See its guide for previous RC, alpha and legacy coverage. |
+| Pi connector | Pi `1.2.0` and `0.84.4`; connector `0.1.0-poc.15` (`next`), pinned AKK `0.16.7` |
+| DeepSeek Harness connector | Web `0.2.1-rc.2` (RC); connector `0.1.0-rc.19` (`next`), pinned AKK `0.16.7`. See its guide for previous RC, alpha and legacy coverage. |
 | Runtime | Node.js `22.19.0`+ on macOS or Linux |
 
 The adjacent OpenClaw boundary `2026.5.10-beta.2` is intentionally unsupported. Herdr versions are observations, not an allowlist: discovery verifies live identity and read capabilities, while input requires a matching CLI schema declaration or verified baseline behavior. An untested server without input evidence exposes only verified read capabilities. Desktop controls validate the live native contract. Desktop catalog presence alone does not prove the conversation is open or controllable. See each connector guide, the [Pi/DSH validation matrix](docs/pi-dsh-compatibility.md), and the Desktop guide for tested boundaries and limitations.

package/connectors/deepseek-harness/README.md

@@ -1,5 +1,11 @@
 # Agent Knock Knock for DeepSeek Harness
 
+Let your DeepSeek Harness agent delegate to **Codex CLI, Codex Desktop and
+Claude Code**, follow progress and receive results in the same DSH conversation.
+
+[Install](#five-minute-quick-start) · [DSH Discover](#find-akk-in-dsh-discover) ·
+[Demo](#demo) · [Support](https://github.com/scotthuang/agent-knock-knock/blob/main/SUPPORT.md)
+
 This package is the native DeepSeek Harness Web connector for Agent Knock
 Knock (AKK). When the Web Host mounts the bundle, it adds `/akk`, the AKK
 semantic tools supplied by its pinned runtime, and the bundled
@@ -13,7 +19,7 @@ tests, lockfile, bundle manifest, and connector-specific release tag.
 
 ## Compatibility
 
-Connector **0.1.0-rc.17** pins AKK **0.16.6** in its package and lockfile,
+Connector **0.1.0-rc.19** pins AKK **0.16.7** in its package and lockfile,
 including scoped persistent callback recovery and verified running-process
 Codex version discovery, with the 0.165.0 adaptation and accurate Claude
 pane-observation diagnostics. It exposes that runtime's 27 semantic tools,
@@ -24,13 +30,25 @@ monitoring records (24 hours by default), plus active or unresolved records.
 A newer root checkout does not silently replace this pinned dependency. This
 prerelease uses the `next` dist-tag.
 
-The development baseline is DeepSeek Harness **0.2.1-rc.2** with Cordis
-**4.0.5**. This is a release candidate, not a stable release; as checked on
-2026-10-17, npm `next` points here while `latest` still points to
-**0.2.0-rc.2**. Do not downgrade a newer installed RC just to follow `latest`.
-Previously reviewed Hosts `0.1.1-rc.2`, `0.1.2-alpha.1`, `0.1.5-rc.2`,
-`0.2.0-rc.2`, and preview `0.2.1-alpha.2` remain accepted. Use a resident POSIX Web Host
-and Node.js `>=22.19.0`.
+The reviewed baseline is **DeepSeek Harness Web 0.2.1-rc.2** and **Cordis
+4.0.5**. These are prerelease compatibility claims, not a stable-version
+endorsement. On 2026-10-29, upstream DSH `latest` is `0.2.1-rc.2`, while
+`next` is `0.2.1-rc.4` and `alpha` is `0.2.2-alpha.2`; the latter two are **not
+validated or accepted by this connector**. Do not replace an existing Host
+with a different release merely to follow a tag.
+
+| Scope | Declared / validated boundary |
+| --- | --- |
+| Current Web baseline | DSH `0.2.1-rc.2`, Cordis `4.0.5` |
+| Previously reviewed DSH RCs | `0.1.1-rc.2`, `0.1.5-rc.2`, `0.2.0-rc.2` |
+| Separate preview coverage | `0.1.2-alpha.1`, `0.2.1-alpha.2` |
+| Accepted Cordis peers | `4.0.1`, `4.0.2`, `4.0.4`, `4.0.5-alpha.1`, `4.0.5` (not a continuous range) |
+| Platform / runtime | Resident POSIX Web Host, Node.js `>=22.19.0`, `pnpm` on `PATH` |
+| Outside validated scope | DSH Desktop embedded launcher, headless/one-shot Host, Windows named pipes; newer unlisted DSH releases |
+
+The versioned validation notes below distinguish live Host checks from fixtures
+and earlier compatibility runs. This metadata/documentation release does not
+add a new Host compatibility claim.
 
 Activation locates the real `@deepseek-ai/dsh` launcher and requires the
 launcher, `dsh-base`, `dsh-agent`, `dsh-commands`, `dsh-llm`, `dsh-skill`, and
@@ -53,10 +71,46 @@ Headless/one-shot Harness processes, Windows named pipes, and DSH Desktop's
 embedded launcher are outside this connector's validated scope. Existing Codex CLI backend and Desktop connections need no
 terminal container when their advertised capability is available. Claude Code
 and terminal-specific operations retain their documented transport conditions;
-see [core compatibility](../../README.md#compatibility) and the
-[Pi/DSH validation matrix](../../docs/pi-dsh-compatibility.md). This connector does
+see [core compatibility](https://github.com/scotthuang/agent-knock-knock/blob/v0.16.7/README.md#compatibility) and the
+[Pi/DSH validation matrix](https://github.com/scotthuang/agent-knock-knock/blob/v0.16.7/docs/pi-dsh-compatibility.md). This connector does
 not launch replacement coding processes or create terminal panes.
 
+## Demo
+
+Existing AKK demo by [@scotthuang](https://github.com/scotthuang):
+OpenClaw/WeChat delegates a task to Codex Desktop, handles an explicitly
+authorized approval, and brings the result back to chat. This edited clip shows
+AKK core capabilities, **not the DSH interface**.
+
+https://github.com/user-attachments/assets/cc20a609-7907-4996-977e-0b88d8ba6388
+
+## Find AKK in DSH Discover
+
+This is an **AKK-maintained third-party index**, not a default DSH market or an
+official endorsement. DSH does not ship with built-in index sources.
+
+1. In a supported DSH Web profile, open **Plugins → Experimental plugins →
+   Custom plugin market** and enable it.
+2. Open **Discover → Add index source** and paste this HTTPS URL:
+
+   ```text
+   https://raw.githubusercontent.com/scotthuang/agent-knock-knock/main/market/dsh/index.json
+   ```
+
+3. Search for **Agent Knock Knock**. Check the confirmation shows the package
+   `@scotthuang/agent-knock-knock-deepseek-harness`, an explicit reviewed RC
+   version and the npm registry. Confirm only that expected package/version.
+4. Finish existing work and cleanly restart the Web Host after installation;
+   this connector is not hot-loaded. Then run `/akk list` in a Web conversation.
+
+The index pins a published version, so market installation does not resolve the
+old bare-package `latest` tag. All listed connector versions are prereleases;
+DSH can recommend a compatible prerelease when the entry has no stable version.
+The source URL is stable, but its selected version can change after future
+verified releases. CLI users can use `@next` or the exact version shown in
+this README. See the [official market guide](https://deepseek-harness.github.io/deepseek-harness/guide/plugin-market)
+and the [index maintenance notes](https://github.com/scotthuang/agent-knock-knock/tree/main/market/dsh).
+
 ## Five-minute quick start
 
 ### 1. Check the prerequisites
@@ -82,7 +136,7 @@ can select an older `latest` build.
 DSH `0.2.1-rc.2` requires connector `0.1.0-rc.6` or a later release that
 explicitly supports that Host. Connector `0.1.0-rc.5` does not support this RC.
 Use `next`, or pin
-`@scotthuang/agent-knock-knock-deepseek-harness@0.1.0-rc.17`.
+`@scotthuang/agent-knock-knock-deepseek-harness@0.1.0-rc.19`.
 
 ```sh
 dsh plugin --profile web add @scotthuang/agent-knock-knock-deepseek-harness@next
@@ -392,7 +446,7 @@ exact reviewed version:
 
 ```sh
 dsh plugin --profile web add @scotthuang/agent-knock-knock-deepseek-harness@next
-dsh plugin --profile web add @scotthuang/agent-knock-knock-deepseek-harness@0.1.0-rc.17
+dsh plugin --profile web add @scotthuang/agent-knock-knock-deepseek-harness@0.1.0-rc.19
 ```
 
 Restart the Web Host after either operation. The connector pins the exact AKK
@@ -420,10 +474,10 @@ dsh plugin --profile web add "file:$(pwd -P)/connectors/deepseek-harness"
 ```
 
 Restart `dsh web` after installation. The child package currently installs and
-tests against its pinned AKK runtime `0.16.6`; building the current repository
+tests against its pinned AKK runtime `0.16.7`; building the current repository
 root does not silently replace that dependency. Before core publication, test
 the candidate core tarball in isolation as described in the
-[coordinated release policy](../../CONTRIBUTING.md#coordinated-package-releases);
+[coordinated release policy](https://github.com/scotthuang/agent-knock-knock/blob/v0.16.7/CONTRIBUTING.md#coordinated-package-releases);
 the registry-based `npm ci` above requires that exact core to be published.
 Testing connector changes against another AKK runtime requires an explicit
 dependency change and
@@ -431,6 +485,24 @@ compatibility review rather than an implicit local link.
 
 ## Tests and release status
 
+Connector **`0.1.0-rc.19`** pins AKK **`0.16.7`** and its synchronized Skill.
+It carries [PR #484](https://github.com/scotthuang/agent-knock-knock/pull/484):
+command-scoped discovery reuse and targeted inspection reduce repeated reader
+and terminal probes. Default List defers detailed approval/composer scans;
+unscanned state is not approval or Send authority, and Status and mutating
+operations keep fresh identity and input checks. DSH Host versions, persistent
+callback ownership and the prerelease `next` policy are unchanged. The
+[performance record](https://github.com/scotthuang/agent-knock-knock/blob/v0.16.7/docs/command-discovery-performance.md)
+covers the PR's development measurements, not universal latency guarantees or
+a new DSH live-model/channel acceptance run.
+
+Connector **`0.1.0-rc.18`** keeps exact core **`0.16.6`** and the existing
+runtime/Host compatibility behavior. This release adds npm discovery metadata,
+a clearer DSH entry and explicit-version market installation guidance, and
+replaces cross-directory README links with public URLs that work on npm.
+The curated index uses published registry metadata and the official format-1
+contract; adding an index or publishing a community post is not official approval.
+
 Connector **`0.1.0-rc.17`** pins AKK **`0.16.6`** and its synchronized Skill.
 It carries [PR #478](https://github.com/scotthuang/agent-knock-knock/pull/478):
 Claude List and execution share each operation's reader and idle checks;
@@ -457,7 +529,7 @@ coordinated dependency refresh adds no new DSH live-model or external-channel
 delivery claim and remains on npm `next`.
 
 Connector **`0.1.0-rc.15`** pins AKK **`0.16.4`** and its synchronized Skill.
-It carries the [Codex CLI 0.165.0 compatibility update](../../docs/codex-0.165.0-compatibility.md):
+It carries the [Codex CLI 0.165.0 compatibility update](https://github.com/scotthuang/agent-knock-knock/blob/v0.16.6/docs/codex-0.165.0-compatibility.md):
 exact frontend/backend version reporting, native terminal profiles, Terra model
 label handling, and manual folder-trust blocking. Existing task identities,
 monitor deadlines and callback receipts are preserved. Host version ranges and
@@ -530,13 +602,13 @@ remains available when no controllable terminal counterpart exists. Codex stays
 backend-first. Existing task routes, interaction authority, the DSH Host/peer
 policy, independent Store and callback ownership remain unchanged. This
 dependency update does not claim a new DSH live-model or external-channel
-delivery test. See the [Claude direct-control guide](../../docs/claude-cli-direct.md)
+delivery test. See the [Claude direct-control guide](https://github.com/scotthuang/agent-knock-knock/blob/v0.16.6/docs/claude-cli-direct.md)
 for prerequisites and operation-specific limits. The connector remains on `next`.
 
 Connector **`0.1.0-rc.9`** pins AKK **`0.14.17`** and carries its Codex CLI
 `0.164.0` compatibility changes and reviewed Skill. The DSH Host/peer version
 policy, independent Store, typed interactions and callback ownership are
-unchanged. The core [compatibility matrix](../../docs/codex-0.164.0-compatibility.md)
+unchanged. The core [compatibility matrix](https://github.com/scotthuang/agent-knock-knock/blob/v0.16.6/docs/codex-0.164.0-compatibility.md)
 separates native backend task/approval/question checks from terminal capture
 regressions and retained limits. This dependency refresh does not claim a new
 DSH live-model or external-channel delivery run. It remains on npm `next`.
@@ -565,7 +637,7 @@ npm run pack:check
 
 These commands typecheck the connector, run its fast wiring/profile/IPC/schema
 tests, and inspect the package tarball. They do not publish anything. The
-`0.1.0-rc.17` lockfile uses the published DeepSeek Harness `0.2.1-rc.2`
+`0.1.0-rc.19` lockfile uses the published DeepSeek Harness `0.2.1-rc.2`
 SDK packages and Cordis `4.0.5`. Its real ToolRuntime regression checks
 canonical result rendering, exact Agent ownership, typed questionnaire payloads,
 and rejection before dispatch when targets are ambiguous or stale. This is
@@ -610,7 +682,7 @@ gate to both connectors. Their package versions are validated independently.
 Publishing additionally requires both explicit flags:
 
 ```sh
-npm run release:check -- --publish --confirm-version 0.1.0-rc.17
+npm run release:check -- --publish --confirm-version 0.1.0-rc.19
 ```
 
 Prereleases use npm tag `next`; stable versions use `latest`. Repository tags

package/connectors/pi/README.md

@@ -12,7 +12,7 @@ socket.
 
 ## Status and compatibility
 
-Connector **0.1.0-poc.14** pins AKK **0.16.6**, including CLI direct
+Connector **0.1.0-poc.15** pins AKK **0.16.7**, including CLI direct
 connections, Codex Desktop, Recovery, state-derived List guidance and verified
 running-process Codex version discovery, with the 0.165.0 adaptation and accurate
 Claude pane-observation diagnostics. Its generated Skill and registered tools
@@ -35,7 +35,7 @@ The current compatibility contract is intentionally exact:
   supported older runtime, installed from the official
   `@earendil-works/pi-coding-agent` package.
 - Node.js `22.19.0` or newer.
-- AKK `0.16.6`, pinned by this connector's package and lockfile. A different
+- AKK `0.16.7`, pinned by this connector's package and lockfile. A different
   version at the repository root is not substituted automatically. Before core
   publication, test its candidate tarball in isolation under the
   [coordinated release policy](../../CONTRIBUTING.md#coordinated-package-releases).
@@ -87,8 +87,8 @@ pi list
 ```
 
 Using `next` follows compatible Pi connector prereleases. To pin this exact
-core `0.16.6` connector, install
-`npm:@scotthuang/agent-knock-knock-pi@0.1.0-poc.14`; exact versions are pinned
+core `0.16.7` connector, install
+`npm:@scotthuang/agent-knock-knock-pi@0.1.0-poc.15`; exact versions are pinned
 and are not advanced by Pi's bulk update command.
 
 ### 4. Start Pi
@@ -453,7 +453,7 @@ Harness independently; it does not require their package versions to match.
 Publishing Pi additionally requires explicit version confirmation:
 
 ```sh
-npm run release:check -- --publish --confirm-version 0.1.0-poc.14
+npm run release:check -- --publish --confirm-version 0.1.0-poc.15
 ```
 
 Prereleases use npm tag `next`; stable versions use `latest`. Tags and GitHub
@@ -503,6 +503,17 @@ a presentation change, not evidence that a candidate is disconnected, and it
 does not change Send routing or callback ownership. Sole empty conversations
 and exact frontend associations remain visible.
 
+Connector **`0.1.0-poc.15`** pins AKK **`0.16.7`** and its synchronized Skill.
+It carries [PR #484](https://github.com/scotthuang/agent-knock-knock/pull/484):
+command-scoped discovery reuse and targeted inspection reduce repeated reader
+and terminal probes. Default List defers detailed approval/composer scans;
+unscanned state is not approval or Send authority, and Status and mutating
+operations keep fresh identity and input checks. Pi Host versions, callback
+ownership and the prerelease `next` policy are unchanged. Performance samples
+in the [core record](../../docs/command-discovery-performance.md) are observations
+from the PR's development verification, not universal latency guarantees or a
+new Pi live-model/channel acceptance run.
+
 Connector **`0.1.0-poc.14`** pins AKK **`0.16.6`** and its synchronized Skill.
 It carries [PR #478](https://github.com/scotthuang/agent-knock-knock/pull/478):
 Claude List and execution share each operation's reader and idle checks;
@@ -601,8 +612,8 @@ or external-channel delivery run.
 
 These are POC acceptance results, not a promise of compatibility with every
 future Pi, Codex, Claude Code, tmux, or Herdr release. Version
-`0.1.0-poc.14` is an npm prerelease distributed through the `next` dist-tag;
-its publication is coordinated with core `0.16.6` and the DSH connector.
+`0.1.0-poc.15` is an npm prerelease distributed through the `next` dist-tag;
+its publication is coordinated with core `0.16.7` and the DSH connector.
 ClawHub publication remains a separate channel.
 
 ## Deliberate POC limits

package/dist/src/claude-agent-discovery-cache.d.ts

@@ -0,0 +1,6 @@
+type Reader = (file: string, args: string[], env?: NodeJS.ProcessEnv) => Promise<string>;
+/** Share the expensive reader only for discovery; registry/process/socket checks remain separate. */
+export declare function readClaudeAgentDiscovery(configDir: string, reader: string, run?: Reader): Promise<string>;
+/** Read-only List enrichment may consume its completed discovery; execution preflights never use this. */
+export declare function completedClaudeAgentDiscovery(configDir: string, reader: string): string | undefined;
+export {};

package/dist/src/claude-agent-discovery-cache.js

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { cliEnv, cliExecutionMemo } from "./cli-runtime-context.js";
+import { resolveOptionalExecutable } from "./cli-command-runtime.js";
+const runReader = (file, args, env) => new Promise((resolve, reject) => {
+    execFile(file, args, { env, timeout: 10_000, maxBuffer: 10 * 1024 * 1024, encoding: "utf8" }, (error, stdout) => error ? reject(error) : resolve(stdout));
+});
+function canonical(value) {
+    try {
+        return fs.realpathSync(value);
+    }
+    catch {
+        return path.resolve(value);
+    }
+}
+function snapshot(configDir, reader, run) {
+    const readers = cliExecutionMemo("claude-agent-discovery", run, () => new Map());
+    const key = JSON.stringify([canonical(configDir), reader]);
+    let entry = readers.get(key);
+    if (!entry)
+        readers.set(key, entry = {});
+    return entry;
+}
+/** Share the expensive reader only for discovery; registry/process/socket checks remain separate. */
+export function readClaudeAgentDiscovery(configDir, reader, run = runReader) {
+    // The production cache key and launched executable must agree, including HOME/PATH fallback.
+    const executable = run === runReader ? resolveOptionalExecutable(reader) : reader;
+    const entry = snapshot(configDir, executable, run);
+    if (entry.output !== undefined)
+        return Promise.resolve(entry.output);
+    return entry.pending ??= Promise.resolve().then(() => run(executable, ["agents", "--json", "--all"], { ...cliEnv(), CLAUDE_CONFIG_DIR: configDir })).then(output => {
+        entry.output = output;
+        return output;
+    }).finally(() => { entry.pending = undefined; });
+}
+/** Read-only List enrichment may consume its completed discovery; execution preflights never use this. */
+export function completedClaudeAgentDiscovery(configDir, reader) {
+    return snapshot(configDir, resolveOptionalExecutable(reader), runReader).output;
+}
+//# sourceMappingURL=claude-agent-discovery-cache.js.map

package/dist/src/claude-agent-discovery-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-agent-discovery-cache.js","sourceRoot":"","sources":["../../src/claude-agent-discovery-cache.ts"],"names":[],"mappings":"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"}

package/dist/src/claude-native-discovery.d.ts

@@ -15,6 +15,7 @@ export interface ClaudeNativeDiscoveryResult {
 }
 export declare function runClaudeNativeCommand(file: string, args: string[], env?: NodeJS.ProcessEnv): Promise<string>;
 export declare function readClaudeNativeRegistry(configDir: string, pid: number): Promise<Record<string, unknown>>;
+/** The agent-list row and owned registry must describe the same supported inbox. */
 export declare function validateClaudeNativeRegistry(configDir: string, row: Record<string, unknown>, options?: ClaudeNativeDiscoveryOptions): Promise<ClaudeNativeCatalogEntry>;
 export declare function discoverClaudeNativeSessions(options?: ClaudeNativeDiscoveryOptions): Promise<ClaudeNativeDiscoveryResult>;
 export declare function inspectClaudeNativeSession(identity: ClaudeNativeIdentity, options?: ClaudeNativeDiscoveryOptions): Promise<ClaudeNativeCatalogEntry>;

package/dist/src/claude-native-discovery.js

@@ -3,6 +3,8 @@ import { lstat, readFile, realpath } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { readClaudeAgentDiscovery } from "./claude-agent-discovery-cache.js";
+import { cliExecutionMemoAsync } from "./cli-runtime-context.js";
 import { ClaudeNativeError, createClaudeNativeConversationId, validateClaudeNativeIdentity } from "./claude-native-identity.js";
 const execFile = promisify(execFileCallback);
 export async function runClaudeNativeCommand(file, args, env) {
@@ -11,9 +13,11 @@ export async function runClaudeNativeCommand(file, args, env) {
 }
 /** Only an executable launch failure establishes that the configured reader is unavailable. */
 async function readClaudeNativeAgentOutput(configDir, options) {
-    const run = options.run ?? runClaudeNativeCommand;
     try {
-        return await run(options.claudePath ?? "claude", ["agents", "--json", "--all"], { ...process.env, CLAUDE_CONFIG_DIR: configDir });
+        const output = await readClaudeAgentDiscovery(configDir, options.claudePath ?? "claude", options.run);
+        if (Buffer.byteLength(output) > 2 * 1024 * 1024)
+            throw new Error("Claude native discovery exceeds its output limit");
+        return output;
     }
     catch (error) {
         if (error?.code === "ENOENT" || error?.code === "EACCES") {
@@ -48,76 +52,132 @@ export async function readClaudeNativeRegistry(configDir, pid) {
         throw new ClaudeNativeError("invalid_registry", "Native registry entry exceeds limit");
     return record(JSON.parse(await readFile(file, "utf8")));
 }
-/** The agent-list row and owned registry must describe the same supported inbox. */
-function catalogFields(m, row, identity) {
-    if (m.pid !== identity.pid || row.pid !== identity.pid || row.sessionId !== identity.sessionId || row.kind !== "interactive"
-        || !absolute(m.cwd) || row.cwd !== m.cwd || typeof m.version !== "string" || !/^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/u.test(m.version)
+function registryIdentity(configDir, m, pid) {
+    const processStart = typeof m.procStart === "string" ? m.procStart.trim().replace(/\s+/gu, " ") : "";
+    return validateClaudeNativeIdentity({ configDir, sessionId: String(m.sessionId), pid, processStart });
+}
+function registryFields(m, identity) {
+    if (m.pid !== identity.pid || !absolute(m.cwd)
+        || typeof m.version !== "string" || !/^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/u.test(m.version)
         || m.peerProtocol !== 1 || !Array.isArray(m.peerFeatures) || !m.peerFeatures.every(x => typeof x === "string")
         || !absolute(m.messagingSocketPath) || path.basename(m.messagingSocketPath) !== `${identity.pid}.sock`) {
-        throw new ClaudeNativeError("unsupported_contract", "Claude native registry and agent list do not prove a supported live identity");
+        throw new ClaudeNativeError("unsupported_contract", "Claude native registry does not prove a supported live identity");
     }
     return { cwd: m.cwd, version: m.version, socketPath: m.messagingSocketPath,
         peerProtocol: 1, peerFeatures: m.peerFeatures };
 }
-export async function validateClaudeNativeRegistry(configDir, row, options = {}) {
-    const pid = Number(row.pid), m = await readClaudeNativeRegistry(configDir, pid);
-    const processStart = typeof m.procStart === "string" ? m.procStart.trim().replace(/\s+/gu, " ") : "";
-    const identity = validateClaudeNativeIdentity({ configDir, sessionId: String(m.sessionId), pid, processStart });
-    const fields = catalogFields(m, row, identity);
+/** Never cache execution fences: every targeted inspection observes the current process and socket. */
+async function assertLiveNativeRegistry(identity, fields, options) {
     const run = options.run ?? runClaudeNativeCommand;
-    const processInfo = (await run("/bin/ps", ["-p", String(pid), "-o", "uid=", "-o", "lstart="], { ...process.env, LC_ALL: "C", TZ: "UTC" })).trim().replace(/\s+/gu, " ");
-    if (processInfo !== `${process.getuid?.()} ${processStart}`)
+    const processInfo = (await run("/bin/ps", ["-p", String(identity.pid), "-o", "uid=", "-o", "lstart="], { ...process.env, LC_ALL: "C", TZ: "UTC" })).trim().replace(/\s+/gu, " ");
+    if (processInfo !== `${process.getuid?.()} ${identity.processStart}`)
         throw new ClaudeNativeError("process_changed", "Claude process identity changed");
-    const socketPath = fields.socketPath;
-    await owned(await realpath(path.dirname(socketPath)), "directory");
-    await owned(socketPath, "socket");
+    await owned(await realpath(path.dirname(fields.socketPath)), "directory");
+    await owned(fields.socketPath, "socket");
+}
+function catalogEntry(identity, fields, row, status) {
     const statusMap = { idle: "idle", busy: "working", waiting: "waiting" };
-    // Both sources must agree. Unknown or racing state remains observable, never sendable.
-    const status = m.status === row.status && typeof m.status === "string"
-        ? statusMap[m.status] ?? "unknown" : "unknown";
     return { ...identity, ...fields, nativeId: createClaudeNativeConversationId(identity),
-        ...(typeof row.name === "string" ? { name: row.name.slice(0, 512) } : {}), status,
+        ...(typeof row.name === "string" ? { name: row.name.slice(0, 512) } : {}),
+        status: typeof status === "string" ? statusMap[status] ?? "unknown" : "unknown",
         ...(typeof row.waitingFor === "string" ? { waitingFor: row.waitingFor.slice(0, 256) } : {}), observedAt: new Date().toISOString() };
 }
-export async function discoverClaudeNativeSessions(options = {}) {
+/** The agent-list row and owned registry must describe the same supported inbox. */
+export async function validateClaudeNativeRegistry(configDir, row, options = {}) {
+    const pid = Number(row.pid), m = await readClaudeNativeRegistry(configDir, pid);
+    const identity = registryIdentity(configDir, m, pid), fields = registryFields(m, identity);
+    if (row.pid !== identity.pid || row.sessionId !== identity.sessionId || row.kind !== "interactive" || row.cwd !== m.cwd) {
+        throw new ClaudeNativeError("unsupported_contract", "Claude native registry and agent list do not prove a supported live identity");
+    }
+    await assertLiveNativeRegistry(identity, fields, options);
+    // Both sources must agree. Unknown or racing state remains observable, never sendable.
+    return catalogEntry(identity, fields, row, m.status === row.status ? m.status : undefined);
+}
+async function discoverConfigDirectory(configured, options) {
     const errors = [], sessions = [];
-    const configDirs = [...new Set(options.configDirs ?? [process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude")])];
-    if ((options.platform ?? process.platform) !== "darwin")
-        return { sessions, errors: [{ configDir: "", code: "unsupported_platform" }] };
-    for (const configured of configDirs.slice(0, 16)) {
-        let configDir = path.resolve(configured);
-        try {
-            configDir = await realpath(configDir);
-            const raw = JSON.parse(await readClaudeNativeAgentOutput(configDir, options));
-            if (!Array.isArray(raw) || raw.length > 4096)
-                throw new ClaudeNativeError("invalid_agent_list", "Invalid Claude agents list");
-            for (const value of raw) {
-                const row = record(value);
-                if (row.kind !== "interactive")
-                    continue;
+    let configDir = path.resolve(configured);
+    try {
+        configDir = await realpath(configDir);
+        const raw = JSON.parse(await readClaudeNativeAgentOutput(configDir, options));
+        if (!Array.isArray(raw) || raw.length > 4096)
+            throw new ClaudeNativeError("invalid_agent_list", "Invalid Claude agents list");
+        // Bounded parallel PID checks retain input ordering without spawning one process per row at once.
+        for (let index = 0; index < raw.length; index += 8) {
+            const pending = [];
+            let malformed;
+            for (const value of raw.slice(index, index + 8)) {
+                let row;
                 try {
-                    const entry = await validateClaudeNativeRegistry(configDir, row, options);
-                    if (sessions.some(s => s.nativeId === entry.nativeId))
-                        throw new ClaudeNativeError("duplicate_identity", "Duplicate native agent identity");
-                    sessions.push(entry);
+                    row = record(value);
                 }
                 catch (error) {
-                    errors.push({ configDir, code: error instanceof ClaudeNativeError ? error.code : "registry_unavailable" });
+                    malformed = error;
+                    break;
                 }
+                if (row.kind !== "interactive")
+                    continue;
+                pending.push(validateClaudeNativeRegistry(configDir, row, options).catch(error => ({ configDir,
+                    code: error instanceof ClaudeNativeError ? error.code : "registry_unavailable" })));
             }
+            for (const value of await Promise.all(pending)) {
+                if ("nativeId" in value)
+                    sessions.push(value);
+                else
+                    errors.push(value);
+            }
+            if (malformed)
+                throw malformed;
         }
-        catch (error) {
-            errors.push({ configDir, code: error instanceof ClaudeNativeError ? error.code : "discovery_unavailable" });
+    }
+    catch (error) {
+        errors.push({ configDir, code: error instanceof ClaudeNativeError ? error.code : "discovery_unavailable" });
+    }
+    return { sessions, errors };
+}
+async function discoverConfiguredSessions(configDirs, options) {
+    const errors = [], sessions = [], seen = new Set();
+    for (let index = 0; index < configDirs.length; index += 4) {
+        const results = await Promise.all(configDirs.slice(index, index + 4).map(dir => discoverConfigDirectory(dir, options)));
+        for (const result of results) {
+            errors.push(...result.errors);
+            for (const entry of result.sessions) {
+                if (seen.has(entry.nativeId))
+                    errors.push({ configDir: entry.configDir, code: "duplicate_identity" });
+                else {
+                    seen.add(entry.nativeId);
+                    sessions.push(entry);
+                }
+            }
         }
     }
     return { sessions, errors };
 }
+export async function discoverClaudeNativeSessions(options = {}) {
+    const configDirs = [...new Set(options.configDirs ?? [process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude")])].slice(0, 16);
+    const platform = options.platform ?? process.platform;
+    if (platform !== "darwin")
+        return { sessions: [], errors: [{ configDir: "", code: "unsupported_platform" }] };
+    const namespace = `claude-native-discovery:${JSON.stringify([configDirs, options.claudePath ?? "claude", platform])}`;
+    const snapshot = await cliExecutionMemoAsync(namespace, options.run ?? runClaudeNativeCommand, () => discoverConfiguredSessions(configDirs, options));
+    return structuredClone(snapshot);
+}
 export async function inspectClaudeNativeSession(identity, options = {}) {
     const wanted = validateClaudeNativeIdentity(identity);
-    const result = await discoverClaudeNativeSessions({ ...options, configDirs: [wanted.configDir] });
-    const found = result.sessions.find(s => s.nativeId === createClaudeNativeConversationId(wanted));
-    if (!found)
+    if ((options.platform ?? process.platform) !== "darwin")
+        throw new ClaudeNativeError("unsupported_platform", "Claude native inspection is currently validated on macOS only");
+    const configDir = await realpath(wanted.configDir), m = await readClaudeNativeRegistry(configDir, wanted.pid);
+    const current = registryIdentity(configDir, m, wanted.pid);
+    if (createClaudeNativeConversationId(current) !== createClaudeNativeConversationId(wanted)) {
         throw new ClaudeNativeError("identity_unavailable", "Exact Claude CLI process/session is no longer available");
-    return found;
+    }
+    // Interactive registry ownership is the targeted counterpart of the agents-row filter.
+    // A parked foreground process displays a background job; it is not that job's inbox.
+    if (m.kind !== "interactive" || m.parkedJobId !== undefined
+        || m.pidDomain !== undefined && m.pidDomain !== (options.platform ?? process.platform)) {
+        throw new ClaudeNativeError("unsupported_contract", "Claude target is not an ordinary interactive session");
+    }
+    const fields = registryFields(m, current);
+    await assertLiveNativeRegistry(current, fields, options);
+    return catalogEntry(current, fields, m, m.status);
 }
 //# sourceMappingURL=claude-native-discovery.js.map