fix(z-agent): find the highest installed z-mode without a path

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "zstack",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Evidence-driven engineering workflows, scoped agents, and task-sized verification for Claude Code.",
   "author": {
     "name": "Zach Fuller",

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "zstack",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Evidence-driven engineering workflows, scoped agents, and task-sized verification for Codex.",
   "author": {
     "name": "Zach Fuller",

agents/claude/z-agent.md

@@ -4,7 +4,7 @@ description: Scoped engineering worker following z-mode. Start fresh for new wor
 model: inherit
 ---
 
-Read z-mode's SKILL.md from the absolute path your parent gave you. If that path is missing, relative, or unreadable on this machine, locate the installed z-mode SKILL.md yourself and report the bad path. If you cannot find it, stop and report; do not work without z-mode. Then read the relevant playbook. Resolve its relative links from that file's real location, independently of target cwd.
+Read z-mode's SKILL.md from the absolute path your parent gave you. If no path was given, or it is relative or unreadable on this machine, report that and, before other work, search for files ending in `skills/z-mode/SKILL.md`, following symlinks (for example, `find -L`). Search `plugins/` and `skills/` under `$CLAUDE_CONFIG_DIR` (default `~/.claude`), the target project's `.claude/skills/`, and any local marketplace directory recorded in that configuration root's `plugins/known_marketplaces.json`. Resolve each match to its real path, then read the version from the plugin manifest (`.claude-plugin/plugin.json` or `plugin.yaml`) beside that real path's `skills/` directory. Use the highest version, comparing MAJOR.MINOR.PATCH numerically; copies without a readable version rank last, and report any tie. z-mode is explicit-only, so a missing skill-catalog entry does not mean it is absent. If no copy exists, stop and report; do not work without z-mode. Then read the relevant playbook. Resolve its relative links from that file's real location, independently of target cwd.
 
 The parent's goal, scope, permissions, and acceptance criteria govern work. Simple tasks run directly. Do not recursively spawn another z-agent merely because the mode is active.
 

agents/codex/z-agent.toml

@@ -1,7 +1,7 @@
 name = "z-agent"
 description = "Scoped engineering worker following z-mode. Start fresh for new work; reuse only for costly agent-held state under the native host contract. Preserve concurrent work and return verifiable results."
 developer_instructions = """
-Read z-mode's SKILL.md from the absolute path your parent gave you. If that path is missing, relative, or unreadable on this machine, locate the installed z-mode SKILL.md yourself and report the bad path. If you cannot find it, stop and report; do not work without z-mode. Then read the playbook relevant to the brief. Resolve its relative links from that file's real location, not the target cwd.
+Read z-mode's SKILL.md from the absolute path your parent gave you. If no path was given, or it is relative or unreadable on this machine, report that and, before other work, search for files ending in `skills/z-mode/SKILL.md`, following symlinks (for example, `find -L`). Search `plugins/` and `skills/` under `$CODEX_HOME` (default `~/.codex`), `~/.agents/skills/`, and the target project's `.agents/skills/`. Resolve each match to its real path, then read the version from the plugin manifest (`.codex-plugin/plugin.json` or `plugin.yaml`) beside that real path's `skills/` directory. Use the highest version, comparing MAJOR.MINOR.PATCH numerically; copies without a readable version rank last, and report any tie. z-mode is explicit-only, so a missing skill-catalog entry does not mean it is absent. If no copy exists, stop and report; do not work without z-mode. Then read the playbook relevant to the brief. Resolve its relative links from that file's real location, not the target cwd.
 The parent's explicit goal, scope, permissions, and acceptance criteria govern your work. Simple tasks run directly. Do not recursively spawn another z-agent merely because this mode is active.
 You are not alone in the codebase. Preserve others' edits and write only to your assigned files or isolated worktree. Read-only briefs prohibit edits and external writes. Do not commit, push, open PRs, message people, or merge unless specifically delegated.
 Inherit the host model. Return status, files or symbols, evidence/checks, actual changes, and gaps. Verify artifacts rather than trusting self-reports.

docs/provenance.md

@@ -57,3 +57,5 @@ PR #31 review also corrected two retained example issues: valid empty-result ass
 Reviewed the October 13 pstack changes that reached manifest `0.15.23`: PRs [#595](https://github.com/cursor/plugins/pull/595), [#597](https://github.com/cursor/plugins/pull/597), [#602](https://github.com/cursor/plugins/pull/602), [#604](https://github.com/cursor/plugins/pull/604), [#606](https://github.com/cursor/plugins/pull/606), and [#609](https://github.com/cursor/plugins/pull/609). Each adopted change lands as one layer of a stacked PR series and adds its own paragraph below. Cursor manifests, the Cursor README, and `poteto-help` routing tables are excluded; each layer updates the local docs it affects.
 
 **Deep-dig signal.** [PR #604](https://github.com/cursor/plugins/pull/604), merge [36cecbf2](https://github.com/cursor/plugins/commit/36cecbf2b5089b275254d59cb4612d6f96f00fbd), adds one rule to fix-root-causes: when the deciding fact took a deep dig, propose the cheap, always-on signal that would have shown it at first look. The port adopts it verbatim and states that a proposal does not authorize adding the signal outside task scope. The principles reference example gains a matching sentence. Native manifests advance to `0.6.3` as a patch: the rule extends an existing principle's debugging guidance, while the README reserves MINOR bumps for skill, agent, invocation-policy, hook, and stored-state contract changes.
+
+**z-agent discovery.** [PR #597](https://github.com/cursor/plugins/pull/597), merge [b93e8117](https://github.com/cursor/plugins/commit/b93e8117880f695bc49ef7b1ef72c09bfcc7c1de), lets poteto-agent find poteto-mode without a supplied path and choose the highest installed version. Both native z-agent roles already fell back to a local search; the port names where to search on each host, including configured host roots and project-scoped installs, follows symlinked installs to their real paths, selects the highest numerically compared manifest version with unversioned copies last, and notes that explicit-only z-mode can be missing from the skill catalog while installed. The parent still supplies the absolute path under the delegation contract. Upstream's removal of ignored `mode` and `reminder` frontmatter needs no port: z-mode never carried those keys, and the validator rejects unsupported frontmatter. Upstream's slash-menu note is Cursor-specific; local docs already direct Codex users to the skill picker and Claude Code users to `/zstack:z-mode`. Native manifests advance to `0.6.4` as a compatible fix.

docs/validation.md

@@ -6,6 +6,16 @@ outline: [2, 3]
 
 Historical observations below retain the names used during those runs (`pstack`, `poteto-mode`, and `poteto-agent`). Current equivalents are `zstack`, `z-mode`, and `z-agent`; those earlier observations do not establish live behavior under the new names.
 
+## pstack 0.15.23: z-agent discovery — 2026-10-13 {#pstack-0-15-23-z-agent}
+
+Adapted [upstream PR #597](https://github.com/cursor/plugins/pull/597) at merge `b93e8117880f695bc49ef7b1ef72c09bfcc7c1de` as the second layer of the [pstack 0.15.23 stack](provenance.md#pstack-0-15-23). Both z-agent roles now name per-host search roots for a missing or unusable z-mode path and pick the highest declared version. Manifests declare `0.6.4`.
+
+A script following the Claude Code search rule on this macOS host found four copies: a stale `0.1.0` plugin cache, two packaged `dist` copies without a sibling Claude manifest, and the in-place checkout. It selected the checkout. That run simulated the procedure; no z-agent was launched without a path, and the Codex roots were not exercised. In a clean detached worktree of the layer commit, structural validation reported 52 skills and zero problems; all 15 Node tests and 120 Python tests passed; `git diff --check` passed.
+
+### PR #36 review repairs
+
+Review found that the fallback missed symlinked installs, configured host roots, and project-scoped installs. Its version rule also gave no way to rank a copy found through a link. The roles now search `$CLAUDE_CONFIG_DIR` or `$CODEX_HOME` and the target project's skill directory, follow symlinks, read manifests from real paths, compare versions numerically, and rank unversioned copies last. A script following the revised Claude rule picked a linked `0.10.0` checkout over a cached `0.1.0` copy in two fixtures, one with a custom `CLAUDE_CONFIG_DIR` and one with a project-scoped link. On this host it again picked the in-place checkout. Plain `find` returned nothing for a symlinked skill directory; `find -L` found it. The Codex rule and a live z-agent launch without a path remain unexercised.
+
 ## pstack 0.15.23: deep-dig signal — 2026-10-13 {#pstack-0-15-23-signal}
 
 Adapted [upstream PR #604](https://github.com/cursor/plugins/pull/604) at merge `36cecbf2b5089b275254d59cb4612d6f96f00fbd`, starting from main `caf7a1f`, as the bottom layer of the [pstack 0.15.23 stack](provenance.md#pstack-0-15-23). fix-root-causes now proposes a cheap, always-on signal when the deciding fact took a deep dig; the principles reference example matches. Manifests declare `0.6.3`.

plugin.yaml

@@ -1,5 +1,5 @@
 name: zstack
-version: 0.6.3
+version: 0.6.4
 description: Evidence-driven engineering skills and task-sized verification for Hermes Agent.
 author: Zach Fuller
 license: MIT