Summary
When an installed extension fails to activate because a module cannot be resolved, pm reports "Unknown command" and offers typo-hunting remediation. The real cause is detected and printed — but last, after the recovery bundle, under a bare heading with no remediation attached. Every actionable part of the output points away from the fix.
Reproduce
cd "$(mktemp -d)"
pm init diag --yes --author t --agent-guidance skip
pm install /path/to/some-extension --project # works: `pm <cmd>` resolves
rm -rf .agents/pm/extensions/<name>/node_modules # what a copy/clone/rsync of a project produces
pm <cmd>
Output:
Error: Unknown command vcs
What happened:
pm does not expose command path "vcs" in current runtime configuration.
What is required:
Use a valid command name or subcommand path.
Why:
Command registry includes core commands plus active extension command handlers.
Examples:
- pm --help
- pm activity --help
...
Next steps:
- Run "pm --help" to list commands available in this runtime, including active extensions.
- Use one of the suggested command paths above with --help to inspect valid flags and usage.
Recovery bundle:
attempted_command: pm vcs status
normalized_args: vcs status
Extension activation failures:
- project:pm-vcs: Cannot find package '@unbrained/pm-cli' imported from /tmp/…/.agents/pm/extensions/pm-vcs/dist/engine/record-format.js
Why this is worth fixing
The command is not unknown. It is installed, declared in the extension's manifest, and would register normally — it failed to activate. Three things then compound:
- The headline diagnosis is false. "pm does not expose command path
vcs in current runtime configuration" describes a command that was never installed. An agent reads this as "wrong name".
- The remediation actively confirms the false reading. "Run
pm --help to list commands" — and pm --help will not list vcs either, because the extension still fails to activate. The agent now has independent-looking confirmation that it used a bad command name, and starts guessing variations.
- The true cause carries no remediation.
Cannot find package '@unbrained/pm-cli' imported from … appears after the recovery bundle, under a heading with no "next steps". The fix — reinstall the extension's dependencies — is never stated, though the host has everything it needs to state it: it knows the extension id, its directory, and that the failure was a module resolution error.
This is not hypothetical. It is the default outcome of copying a project directory without node_modules, which is exactly what a VCS clone, an rsync, a Docker COPY, or a CI checkout of a committed .agents/pm/extensions/ tree produces. The recovery is one npm install in the extension directory; the output costs an agent several turns before it can find that.
Suggested behaviour
When a command path is unresolved and an activation failure was recorded for an extension that declares it, lead with the activation failure:
Error: Extension "pm-vcs" failed to activate, so "vcs status" is unavailable
What happened:
project:pm-vcs could not be loaded: Cannot find package '@unbrained/pm-cli'
imported from .agents/pm/extensions/pm-vcs/dist/engine/record-format.js
Next steps:
- Install the extension's dependencies:
npm install --prefix .agents/pm/extensions/pm-vcs
- Then re-run: pm vcs status
- Inspect activation state: pm extension --manage
Even without matching the failure to the specific command, two smaller changes would remove most of the cost: move the activation-failure block above the recovery bundle, and suppress the "you used a wrong name, run pm --help" remediation whenever any activation failure is present — that advice is known-wrong in exactly that case.
Relationship to #772
#772 covers a rejected registration (a host-owned flag collision) silently dropping a command and its later siblings. This is the neighbouring case: activation failed at import time, the host did detect and report it, and the reporting is ordered and worded so that the detection does not reach the reader. Fixing #772 would not fix this, and vice versa — but they likely share the code path that decides what an unresolved command path means.
Environment
pm-cli 2026.8.3, Node 26.5.0, Linux. Reproduced with a project-scoped extension install; nothing about the extension is unusual — any extension importing @unbrained/pm-cli behaves the same way once its node_modules is absent.
Summary
When an installed extension fails to activate because a module cannot be resolved,
pmreports "Unknown command" and offers typo-hunting remediation. The real cause is detected and printed — but last, after the recovery bundle, under a bare heading with no remediation attached. Every actionable part of the output points away from the fix.Reproduce
Output:
Why this is worth fixing
The command is not unknown. It is installed, declared in the extension's manifest, and would register normally — it failed to activate. Three things then compound:
vcsin current runtime configuration" describes a command that was never installed. An agent reads this as "wrong name".pm --helpto list commands" — andpm --helpwill not listvcseither, because the extension still fails to activate. The agent now has independent-looking confirmation that it used a bad command name, and starts guessing variations.Cannot find package '@unbrained/pm-cli' imported from …appears after the recovery bundle, under a heading with no "next steps". The fix — reinstall the extension's dependencies — is never stated, though the host has everything it needs to state it: it knows the extension id, its directory, and that the failure was a module resolution error.This is not hypothetical. It is the default outcome of copying a project directory without
node_modules, which is exactly what a VCS clone, anrsync, a DockerCOPY, or a CI checkout of a committed.agents/pm/extensions/tree produces. The recovery is onenpm installin the extension directory; the output costs an agent several turns before it can find that.Suggested behaviour
When a command path is unresolved and an activation failure was recorded for an extension that declares it, lead with the activation failure:
Even without matching the failure to the specific command, two smaller changes would remove most of the cost: move the activation-failure block above the recovery bundle, and suppress the "you used a wrong name, run
pm --help" remediation whenever any activation failure is present — that advice is known-wrong in exactly that case.Relationship to #772
#772 covers a rejected registration (a host-owned flag collision) silently dropping a command and its later siblings. This is the neighbouring case: activation failed at import time, the host did detect and report it, and the reporting is ordered and worded so that the detection does not reach the reader. Fixing #772 would not fix this, and vice versa — but they likely share the code path that decides what an unresolved command path means.
Environment
pm-cli 2026.8.3, Node 26.5.0, Linux. Reproduced with a project-scoped extension install; nothing about the extension is unusual — any extension importing
@unbrained/pm-clibehaves the same way once itsnode_modulesis absent.