[binliu-udacity]

Plugin type (required) / 插件类型（必填）

• UI Plugin / 是 UI 插件
• Standard plugin / 普通插件（非 UI）
• Not applicable / 不适用

Affected plugin: zcode-herdr-status. Category: developer-tools.

What

Adds an explicitly enabled Linux bridge from ZCode lifecycle Hooks to the current inherited Herdr pane. An operator can observe activity/permission waits without giving the bridge permission to approve tools, inject prompts, or control other sessions. This is a community plugin under external_plugins/, version 0.2.1, with equivalent English/Chinese READMEs, Apache-2.0 license and matching marketplace registration.

Related interface proposal: #128. Please keep this draft pending maintainer guidance on the experimental status interface and outstanding validation below.

• Default Hooks-only mode never treats Stop as proven completion. It reports completion unverified, and expires activity hints after 30 seconds without a new Hook. Consequently long legitimate generation/permission waits can also become unknown; this is documented, not hidden behind an optimistic green status.
• Optional --experimental-db-status is explicitly selected and pinned to ZCode 3.16.3 / CLI 0.17.0. It reads only exact-session/current-parent lifecycle projections from a same-user SQLite database. It does not read message text, reasoning, tool parameters/outputs or credentials. This private-schema dependency needs maintainers' approval or replacement with a stable lifecycle API.
• Initial supported scope: Linux, Python 3.10+ (tests ran on Python 3.12), Herdr 0.9.5, ZCode 3.16.3. Unsupported runtime versions fail before launch. No Ovis patch or MCP App is included.
• The explicit launcher preserves user-selected native arguments. Bindings use inherited pane/socket, socket inode/owner, process start-time/UID lineage and a per-pane lock. Stop/disable releases only the observer's source and leaves native ZCode alive. Unknown transport outcomes remain unconfirmed.

Validation

• python3 -B -m unittest discover -s external_plugins/zcode-herdr-status/tests -v: 39 passed. Covers session/parent isolation, stale events, permission rejection/cancellation classifications, hook-hint expiry, process exit, plugin disable, observer stop, deadline, socket replacement, transport failure, unsupported versions, private state and unbound Hooks.
• python3 scripts/validate.py: 52 plugins validated.
• git diff --check: passed.
• Focused official build_dist.build_zip on this plugin: built twice with identical bytes; SHA256 dbd8f895ab132d638e61eff746d4de2c055368a72c5c81293fee949dd6ccb5f7.
• pnpm install --frozen-lockfile: completed. This environment has Node 22.22.0, below the repository's Node >=24 requirement.
• pnpm build: blocked, at unrelated photocraft source build: rustup is required to compile Craft Web snapshots.
• python3 scripts/build_dist.py: blocked by that existing UI plugin's incomplete build. No catalogue entries were removed and no upstream build checks were weakened to claim success.
• Portable package installed from a dedicated local marketplace in an isolated account/session; installation/cache version checked before testing. Actual project_token_login_failed was reproduced. Hooks-only activity correctly expired to unknown rather than staying working forever; explicit observer stop was acknowledged and left the native process alive. A separate untouched shell pane retained its identity.
• Experimental metadata mode identified the same real authentication failure as idle / failed (not successful completion), with acknowledged Herdr reason metadata.
• Disabling this plugin through the native plugin manager was detected; its observer exited with plugin-disabled, acknowledged source release, and left native ZCode alive. The test pane was then closed and the candidate uninstalled; previous plugin installations were retained.
• Successful model completion, permission denial and cancellation on this portable candidate still require revalidation after authentication is restored. Earlier internal-prototype trials exercised those flows, but are not counted as proof for this version. Authentication root cause is unresolved; no credential files or private runtime evidence are published.

Side effects and provenance

Python standard library only. Writes private metadata/lock/receipt files; optionally opens the same user's metadata DB read-only; executes local ZCode/Herdr argv commands and a bounded observer. No observer network requests, telemetry, model calls, runtime downloads or service installation. Native ZCode retains its normal account/network/usage behavior. Logs may contain local paths/session IDs and must remain private. Source is derived from an internal observational prototype under Apache-2.0; no third-party runtimes or UI assets are bundled.

Self-check

• Unique kebab-case plugin under external_plugins/
• Category independent of ownership
• Standard plugin type and name declared
• Version 0.2.1 matches manifest and marketplace
• Equivalent English/Chinese README and localized descriptions
• No credentials, customer materials, machine-specific paths, caches or binaries committed
• Dependencies, permissions, writes, execution and network behavior documented
• Full repository validate.py and build_dist.py pass (validator passes; whole distribution build blocked as above)
• Maintainer acceptance of lifecycle API / experimental private-schema boundary
• Portable candidate's successful authenticated lifecycle verification