[Feature]: Support user-global Pi extension installation

[hua03]

Preflight

• I searched existing issues, discussions, and contributor tasks for this request.
• This request and its attachments contain no credentials or private/internal material.

Request origin

Observed need in a real workflow.

Problem or unmet outcome

The Pi host installer currently supports only a project-local extension target:

loopx slash-commands --install --surface pi --pi-project <project>

This writes:

<project>/.pi/extensions/loopx-goal.ts
<project>/.pi/extensions/pi-goal-loop-runtime.mjs

Pi also has a user-global extension discovery location, ~/.pi/agent/extensions/, which is the normal target when an extension should be available in every Pi project. LoopX has no managed install option for that scope today.

As a result, a user asking to "install LoopX for Pi" can reasonably expect a global Pi extension but receive a project-local installation instead. The manual workaround is to copy the adapter and runtime into ~/.pi/agent/extensions/loopx/, but that copy is outside LoopX's upgrade, ownership-marker, readback, and uninstall lifecycle.

Use case

1. Install or update LoopX.
2. Enable the LoopX Pi adapter once for the current user.
3. Start Pi in different trusted projects.
4. Use /loopx without installing duplicate adapter files into every repository.
5. Upgrade or uninstall LoopX-managed global adapter files through the same CLI lifecycle.

Project bindings can continue to live under each current project's .loopx/pi/; only the Pi extension code needs user-global discovery.

Proposed outcome

Add an explicit user-global Pi installation scope while preserving the current project-local behavior for compatibility. The exact CLI spelling is open, for example:

loopx slash-commands --install --surface pi --pi-scope user
loopx slash-commands --uninstall --surface pi --pi-scope user

Observable behavior:

• The user-global install writes a Pi-discoverable directory entry such as ~/.pi/agent/extensions/loopx/index.ts plus the sibling runtime module.
• The project install remains available through --pi-project and keeps its existing behavior.
• Install and upgrade replace only files carrying the LoopX managed marker.
• Uninstall preserves modified or user-owned same-name files and fails closed, matching the current project installer policy.
• Dry-run output identifies the selected scope and exact target paths.
• loopx doctor or an equivalent readback reports whether the Pi adapter is absent, project-local, user-global, stale, or current.
• Documentation distinguishes user-global extension code from project-local .loopx/pi/ binding state and notes the required Pi /reload or restart.

LoopX area

Host or runtime integration; build, packaging, and installer lifecycle.

Alternatives considered

• Keep installing separately into every project's .pi/extensions/. This works but duplicates managed code and does not match a user-global installation request.
• Manually copy the release files into ~/.pi/agent/extensions/loopx/. This loads successfully, but later loopx update does not refresh the copy and LoopX cannot safely uninstall or diagnose it.
• Register a fixed release-snapshot path in Pi settings. This becomes stale when the active LoopX release pointer changes.

Scope and non-goals

In scope:

• Managed user-global Pi adapter install, dry-run, upgrade/readback, and uninstall.
• Clear scope selection and documentation.
• Preservation of the current project-local install path.

Out of scope:

• Moving project goal bindings or runtime state out of .loopx/pi/.
• Granting repository, network, credential, or external-system authority.
• Changing quota, continuation, or terminal-state semantics.

Contribution

• I may be able to help validate this request.

[huangruiteng]

Thanks for the detailed request. This is a maintainer triage response; no implementation has been started.

Current behavior confirmed. loopx slash-commands --install --surface pi --pi-project <project> writes <project>/.pi/extensions/loopx-goal.ts and pi-goal-loop-runtime.mjs as one atomic unit. Install/upgrade only replaces files carrying the LoopX managed marker, same-name user-owned files are skipped, and uninstall is fail-closed (user-owned files are preserved). Dry-run reports the exact target paths. The issue's description of today's project-local-only behavior is accurate.

Scope fit and recommended shape. The request is compatible with the existing installer lifecycle and is a reasonable extension rather than a rewrite:

• Add an explicit user scope while keeping project as the default for compatibility (e.g. --pi-scope {project,user}; exact spelling open).
• The user scope must target the directory Pi actually discovers for user-global extensions (~/.pi/agent/extensions/loopx/ per this issue). The implementation must verify discovery and module aliasing (typebox, @earendil-works/*) against the supported Pi release before merging.
• The adapter and its loop runtime must stay one atomic delivery unit: preflight both targets and fail closed with zero writes if either is user-owned.
• The managed marker, dry-run, upgrade, uninstall fail-closed, and loopx doctor readback (absent / project-local / user-global / stale / current) should ship with the change, not as follow-ups.
• Project bindings stay under <project>/.loopx/pi/; only the extension code becomes user-global. No repo/network/credential authority changes. Docs should note the required Pi /reload or restart.

Admission decision. I'm admitting this as a tracked enhancement (triage + enhancement labels). Implementation needs a maintainer assignment and should follow the standard worktree + PR flow with focused smokes for ownership-marker preservation, atomic install/uninstall, user-owned conflict fail-closed, and doctor readback.

Two clarifications for the implementer: confirm Pi's user-global discovery path and subdirectory support in the supported Pi release, and confirm the desired default for the new scope flag (I recommend keeping project as the default for compatibility).

[LIHUA919]

I'd like to take this issue. I completed a current-main implementation preflight and confirmed that no assignee or implementation PR currently owns this slice.

Proposed bounded scope:

• add an explicit --pi-scope {project,user} while keeping project as the compatibility default;
• install the user scope as <Pi agent dir>/extensions/loopx/index.ts with the existing runtime module beside it, honoring PI_CODING_AGENT_DIR instead of hard-coding the default home;
• reuse the existing managed-marker ownership and two-file fail-closed preflight for install, update, dry-run, and uninstall;
• keep project bindings under <project>/.loopx/pi/ and make no quota, permission, or authority changes;
• add Pi installation readback covering project/user locations, current/stale/partial ownership, and the dual-scope duplicate-load warning;
• update the Pi guide plus focused unit and smoke coverage.

I verified the user-global path and one-level index.ts subdirectory discovery against the current Pi documentation and source. The final validation would include the focused installer/doctor tests, the slash-command install smoke, py_compile, loopx check, the risk-based premerge canary, and a real Pi v0.83.0 install, /reload, update, and uninstall readback.

Please assign this issue to me if this scope is acceptable. I will wait for the assignment before starting implementation.

[huangruiteng]

Thanks for the current-main preflight. The proposed boundary matches the maintainer's admitted shape: keep project as the compatibility default, make user-global adapter delivery explicit and atomic, preserve managed-marker and user-owned conflict behavior, keep project bindings local, and include doctor/readback plus focused lifecycle validation.

I also rechecked the intake state: there is no linked implementation PR, and the earlier maintainer triage response already records the admission decision. The remaining gate is the explicit maintainer assignment requested in your comment. This intake lane is reply-only and will not assign the issue or mutate its labels/state, so please wait for that explicit assignment before starting implementation.