Findings from the 2026-07-29 session that traced a missing `fork` tool in a
pi-devbox container to an un-registered package.
- Extension-landscape table: add the npm-installed location
(~/.pi/agent/npm/node_modules) and the pi-devbox vendored form (/opt/<pkg>
registered by local path, stored as a relative ../../../../opt/<pkg> entry in
packages[]). Warn that an empty ~/.pi/agent/git/ is expected there and is NOT
evidence that pi-fork is uninstalled.
- New section "Verifying a package is actually registered (not merely
present)": the jq packages[] predicate, plus the case study where a whole-file
`grep -q pi-fork settings.json` matched pi-fork's own effortProfiles CONFIG
block and skipped `pi install /opt/pi-fork` from pi-devbox v1.0.0 through
v1.6.3. Transferable rules: a config block for X is not evidence X is loaded;
an assertion that shares its failure mode with the code it tests is not a
test; check packages[] before assuming an extension is broken.
- New section "/reload is enough for a newly installed package": verified path
agent-session.js reload() -> settingsManager.reload() ->
resourceLoader.reload() -> packageManager.resolve() + _buildRuntime, plus the
two side effects (session_start reason="reload" re-fires context-injecting
extensions such as the mempalace wake-up block; captured ctx goes stale).
- Forensic one-liner for "did this tool ever run here" over
~/.pi/agent/sessions/*/*.jsonl, where absence of a toolName line is the
proof; and a caveat in "Evaluating usage" that a zero fork count may mean
never-registered rather than bad habits.
- Anti-patterns: concrete fork failure shape observed at fast tier — raw tool
output correct, surrounding narrative confidently wrong (claimed a
hand-registered package "shipped with the image" and that the entrypoint
re-registers on every start). Read Evidence as data, narrative as hypothesis.
Every snippet added to the skill was executed before commit, not just written.
Add skill/SKILL.md (+ skill/evaluate-extension-usage.py, referenced by the
skill via ./) so the canonical 'how to use fork/recall/ssh-controlmaster'
skill lives next to the extensions it documents — the single source of truth.
Motivation: the global AGENTS.md (pi-toolkit) tells every pi session to read
~/.agents/skills/pi-extensions/SKILL.md at session start to fix fork/recall
under-utilisation, but that skill previously lived ONLY in the private
skillset repo. In any environment without the skillset mounted (e.g. a
pi-devbox container started without it) the pointer dangled. Co-locating the
skill here gives a public, package-owned source that downstreams can vendor.
install.sh is intentionally unchanged: skill deployment on a normal
workstation stays the skillset repo's responsibility (no double-deploy).
joakimp
Joakim Persson