Experimental canvas: support `--global` install to `~/.copilot/extensions/` (user scope)

[sergio-sisternes-epam]

Summary

The experimental Copilot canvas primitive (shipped in #1689) is deliberately project-scope-only — apm install deploys a canvas to <git-root>/.github/extensions/<name>/. This issue tracks adding --global / user-scope support so a canvas can be deployed to ~/.copilot/extensions/<name>/ and become available in every Copilot session, not just the one repo.

Confirmation: Copilot DOES scan the global folder

Verified against the GitHub Copilot CLI runtime contract (bundled with the installed app):

Source	Evidence
RPC schema — copilot-sdk/generated/rpc.d.ts	ExtensionSource = "project" | "user"; "Extension discovered from the user's ~/.copilot/extensions directory."
Bundled SDK docs — copilot-sdk/docs/extensions.md	"The CLI scans .github/extensions/ (project) and the user's copilot config extensions directory"
create-canvas skill	Discovery scans immediate subdirs of .github/extensions/ (git root) and $COPILOT_HOME/extensions/ (default ~/.copilot).

So global install is technically supportable and useful.

What's already in place

APM's user-scope machinery already maps the copilot TargetProfile (user_root_dir=".copilot", anchored at Path.home()) + the canvas PrimitiveMapping(subdir="extensions") to ~/.copilot/extensions/ — the exact path Copilot discovers. Canvas is blocked at user scope only by:

• unsupported_user_primitives=("canvas",) on the copilot profile (src/apm_cli/integration/targets.py:480), and
• a belt-and-braces guard in the integrator: if scope is InstallScope.USER: return empty (src/apm_cli/integration/canvas_integrator.py:173-177).

Blocking implementation work (not just a flag flip)

A safe implementation must address these, because a canvas is arbitrary executable Node.js loaded into every future session:

1. User-scope local-file tracking gap (critical). post_deps_local.py skips user scope (if ctx.scope is not InstallScope.PROJECT: return, lines 23-25 / 48-50). A first-party canvas deployed globally would not be recorded in local_deployed_files, so apm uninstall -g / stale-sync would not prune it — install works but uninstall leaks executable code globally. Fixing this touches the user-scope local-file tracking chokepoint for all user-scope primitives.
2. $COPILOT_HOME is unhandled. It is read nowhere in APM (grep COPILOT_HOME src/ → none); APM hardcodes .copilot under Path.home(). If a user sets $COPILOT_HOME outside home, APM would deploy to the wrong place relative to where Copilot scans. Honouring it correctly interacts with the lockfile URI scheme — _deployed_path_entry (src/apm_cli/install/services.py:90-96) would mis-encode a dynamic Copilot root as cowork://.
3. Cleanup divergence. cleanup.py:170-177 resolves deployed files against the current root. If $COPILOT_HOME differs between install and uninstall, the original global executable could be orphaned. Needs install-root identity persisted in the lockfile.
4. CanvasIntegrator computes paths manually (canvas_integrator.py:192-195) instead of via TargetProfile.deploy_path(...), so it won't honour a dynamic resolver without rework.
5. Local/offline bundle path (services.py:712-741) filters canvas paths itself with hardcoded .github/extensions/ messaging — needs scope-aware deploy root + diagnostics.

Security recommendation: scope-aware trust gate

Today first-party canvases deploy freely (flag only); dependency canvases need --trust-canvas-extensions. At global scope the blast radius is the whole user account (runs in every session), so:

• project first-party canvas → flag only (unchanged)
• global first-party canvas → require --trust-canvas-extensions (new)
• dependency canvas → require trust in both scopes (unchanged)

npm/pip precedent (global binaries without a trust flag) is weak here — a global Copilot extension is a persistent plugin, not a PATH binary. Update the flag help (install.py:924-927) which currently says "provided by dependencies".

Other notes

• Shadowing: a project .github/extensions/<name>/ shadows a user ~/.copilot/extensions/<name>/ at Copilot discovery time. On global install, if the current repo has a same-named project canvas, emit an informational warning.
• Removing canvas from unsupported_user_primitives should not affect apm compile (driven by compile_family), but add a narrow regression test.

Acceptance criteria

• apm install --global deploys a first-party canvas to $COPILOT_HOME/extensions/ (default ~/.copilot/extensions/), gated on the experimental flag and --trust-canvas-extensions.
• apm uninstall -g (and stale-sync) reliably removes the global canvas — no orphaned executable files, including the $COPILOT_HOME-changed case (or a loud warning if unremovable).
• $COPILOT_HOME honoured for both deploy and cleanup.
• Scope-aware trust gate + updated diagnostics/help.
• Tests (integrator user-scope deploy + trust gate; tracking/cleanup incl. out-of-home $COPILOT_HOME; compile-unchanged regression), docs (docs/src/content/docs canvas page + packages/apm-guide/.apm/skills/apm-usage/), CHANGELOG.

Discovered while validating #1689 end-to-end. Evidence and design critique captured in that work.

[sergio-sisternes-epam]

PR #1689 now closes this issue. It delivers a bounded, leak-safe slice of the acceptance criteria rather than the full first-party-global surface, because the blocking work this issue itself identified (item 1, the user-scope local-file tracking gap in post_deps_local.py) makes unrestricted first-party global deploy unsafe.

Delivered:

• apm install --global deploys a dependency-provided canvas to ~/.copilot/extensions/, gated on the experimental flag and --trust-canvas-extensions (scope-aware trust: user scope always requires trust).
• apm uninstall -g / stale-sync reliably prunes the global canvas (reuses the existing user-scope sync_for_target + lockfile path encoding; no orphaned executable files).
• Scope-aware trust gate + updated --trust-canvas-extensions help/diagnostics.
• Tests (user-scope deploy + trust gate + first-party block + non-default $COPILOT_HOME block + uninstall prune), docs, CHANGELOG.

Deliberately deferred (fail-closed, not silently broken):

• First-party root .apm/extensions/ at user scope is blocked with a diagnostic. The user-scope lockfile pipeline (post_deps_local.py, PROJECT-scope-only) does not track first-party local files, so deploying one globally would leak an executable bundle on uninstall. Supporting it safely requires fixing that shared chokepoint for all user-scope primitives — too broad to fold in here.
• A non-default $COPILOT_HOME is refused with a diagnostic (APM only honours the default ~/.copilot, which keeps the lockfile path home-relative and prunable). Full $COPILOT_HOME support interacts with the lockfile URI scheme and is left as follow-up.

Both deferrals are enforced refusals with clear diagnostics, so there is no leak path. The dependency-provided slice is the real "package + install --global" UX and is fully validated end-to-end.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/security
area/distribution
area/docs-site
type/feature
status/needs-design

Milestone

null -- needs-design issues do not receive milestone assignments.

Suggested next action

Draft the lockfile identity schema for COPILOT_HOME: specify how apm.lock.yaml encodes the Copilot extensions root used at install time so that cleanup and uninstall remain correct when $COPILOT_HOME changes between sessions; link the design back to this issue before implementation begins.

Suggested issue comment

Excellent analysis, @sergio-sisternes-epam. The feature direction is sound -- user-scope
canvas install maps naturally to `--global` and the Copilot CLI discovery contract is
well-evidenced in the RPC schema and bundled SDK docs you cited.

The panel agrees with all 5 blocking items and flags item 3 as a design-required gate
before any code can land safely. The problem: if a user installs a global canvas with
`COPILOT_HOME=X` and later runs `apm uninstall -g` with `COPILOT_HOME=Y`, the
uninstall cannot locate the original deployed files and leaks a persistent executable
into what may become an unused directory. Fixing this requires encoding the Copilot
home root used at install time in `apm.lock.yaml` -- a lockfile schema change that
needs a design document covering the URI scheme, backward compatibility, and migration
path before any implementation begins.

The specific design question to resolve:

> How should `apm.lock.yaml` encode the COPILOT_HOME-relative deploy root so that
> (a) uninstall can recover the original path even after an environment change, and
> (b) the existing `(redacted) lockfile URI scheme remains valid for the static-home
> case?

Items 1, 2, 4, and 5 from your blocking list are well-scoped implementation work that
can proceed in sequence once this schema question is answered. The author analysis in
this issue is a strong starting point for the design doc -- linking it back here when
ready will let a maintainer approve and unblock the implementation sprint.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

User-scope (--global) install is a familiar pattern from npm, pip, and cargo. The
request maps directly to an existing CLI flag and a documented Copilot discovery path.
The trust-gate proposal -- requiring --trust-canvas-extensions for global canvas in
addition to the experimental flag -- is ergonomically sensible: a persistent plugin
running in every Copilot session has a larger blast radius than a project-scoped one,
so an explicit opt-in is the right default. The acceptance criteria are well-structured
and include the CLI help text update. The uninstall correctness gap (item 1) is the
primary UX risk: a global canvas that cannot be cleanly removed is worse than one
that cannot be installed.

Supply Chain Security Expert -- Risk-Surface Reviewer

Global canvas deployment is the highest-blast-radius install surface in APM: arbitrary
Node.js code runs in every future Copilot session. The trust gate is the correct
mitigation and is consistent with the security model documented in enterprise/security.md.
Item 1 (post_deps_local.py user-scope tracking gap) is independently a security
concern: a globally deployed canvas not tracked in local_deployed_files cannot be
reliably removed, creating an orphaned executable. Item 2 ($COPILOT_HOME unhandled)
is also a trust-boundary issue: deploying to a path that Copilot does not actually
scan means the canvas either silently fails or shadows an unexpected directory
depending on resolution order. theme/security is required. area/distribution
(global deploy surface) and area/docs-site (acceptance criteria explicitly name docs)
are the correct sub-theme labels. area/content-security is also applicable given
the trust gate on arbitrary executable content, but is omitted to stay within the
6-label cap; a maintainer may add it if desired.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- sergio-sisternes-epam has author_association=COLLABORATOR with
many prior contributions visible in recent release notes; standard technical tone is
appropriate and the reply does not need first-timer warmth tuning.

Python Architect -- Architecture Reviewer

The 5 blocking items are correctly identified and the feasibility analysis is thorough.
Item 3 (cleanup divergence when $COPILOT_HOME changes) is the blocking design problem:
it requires encoding the Copilot home path used at install time in the lockfile. The
_deployed_path_entry logic in services.py (lines 90-96) encodes deploy paths
under the static (redacted) scheme; a dynamic COPILOT_HOME root would require a new encoding or a resolver that can reconstruct the original path from stored metadata. This is a lockfile schema change with backward-compat and migration implications. Items 1, 2, 4, and 5 are implementation-only work that can follow from the schema decision. Recommend status/needs-design` with the design question scoped to exactly
this schema choice; all other items can proceed once the schema is settled.

Doc Writer -- Documentation Reviewer

The acceptance criteria explicitly name two documentation deliverables: the canvas
page in docs/src/content/docs and the packages/apm-guide/.apm/skills/apm-usage/
resources. The implementing PR will need to add --global install usage to the canvas
reference, update the trust-gate flag description, and sync the apm-usage skill
resource (per repo Rule 4). area/docs-site is included as a required secondary label
to ensure the implementing PR does not skip the docs work. The suggested comment is
grounded in the technical vocabulary used in this issue and does not introduce new
jargon.

APM CEO -- Triage Arbiter

The feature direction is correct and aligns with APM's positioning as the package
manager for AI-native development: user-scope primitives that work globally are a
natural next step. However, the Python Architect correctly identifies that the
$COPILOT_HOME lockfile schema must be settled before code can safely land. Shipping
global canvas install without a reliable uninstall path would be a community trust
problem: a persistent executable orphan in every Copilot session is a worse outcome
than a two-week delay for a design document. Decision ratified: needs-design, scoped
narrowly to the lockfile identity schema for COPILOT_HOME. No milestone assigned.
The author's analysis is the natural starting point for the design doc; once approved
by a maintainer, the implementation can proceed in the ordered sequence the author
already outlined.

{
  "decision": "needs-design",
  "decision_detail": "Lockfile identity schema for COPILOT_HOME: how apm.lock.yaml encodes the Copilot extensions root at install time so uninstall and cleanup remain correct when $COPILOT_HOME changes between sessions.",
  "theme": "theme/security",
  "areas": ["area/distribution", "area/docs-site"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Draft the lockfile COPILOT_HOME identity schema and link it back to this issue before implementation begins.",
  "comment_markdown": "Excellent analysis, @sergio-sisternes-epam. The feature direction is sound. The panel flags item 3 (COPILOT_HOME identity persistence) as a design-required gate: it requires a lockfile schema change specifying how apm.lock.yaml encodes the Copilot home root so uninstall can recover the original path even after an environment change. Design doc first, then implementation."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · sonnet46 4.1M · ◷