Files

Tom Boucher 27aa40f65e fix(#3023 ): stage pi's shared hook bundle outside pi's reserved hooks/ directory (#3175 )

* test(#3023): failing-first guard — pi must not stage hooks in its reserved dir

pi reserves <configDir>/hooks as its deprecated extension location and warns
on every startup when it exists. Assert a pi install stages the shared hook
bundle under gsd-hooks/ instead, manifests it there, and never creates hooks/.

Also adds pi to the local-scope dir table in install-shared.cjs: pi was in
RUNTIME_META but not LOCAL_DIR_NAME, so scope:'local' resolved
path.join(root, undefined) and no local pi install could be exercised.

Fails before the fix. Verified via the remote runner.

* fix(#3023): stage pi's shared hook bundle outside pi's reserved hooks/ dir

pi reserves <configDir>/hooks as its now-deprecated extension location and
warns on every startup when that directory merely exists — checkDeprecatedExtensionDirs()
guards the warning with a bare existsSync(), unlike its tools/ sibling. GSD staged
its shared hook bundle exactly there, and pi's advised remediation (move it to
extensions/) would break the adapter's paths and expose GSD's .js helpers to pi's
extension auto-discovery.

The bundle directory name is now runtime-descriptor-driven: hostBehaviors
.sharedHooksDirName, defaulting to 'hooks' so all 18 other runtimes are
byte-identical. pi sets 'gsd-hooks'. The name is validated as a single path
segment — separators, dot-only segments, trailing dots, absolute paths, NUL,
and Windows reserved device names all fall back to the default, because the
value is joined onto a user's config root and written to.

Renamed in place rather than relocated: hook scripts resolve siblings via
__dirname/.., so a depth change would silently break them.

- install / uninstall / manifest sites all read the resolved name
- pi/gsd.cjs probes gsd-hooks then hooks, so dev checkouts and half-upgraded
  trees still resolve; the never-throws contract is preserved
- new migration 009 retires the legacy pi hooks/ dir on upgrade, using a new
  non-recursive remove-empty-dir engine primitive (rmdirSync only,
  symlink-refusing, containment-guarded); ADR-0008 amended accordingly
- fixes two latent name-dependencies the rename exposed: the stale-hook scan
  and the injection scanner's self-exclusion both hardcoded 'hooks'

Verified on the remote runner.

Closes #3023

* fix(#3023): close review findings and align emitted provenance with the rename

Adversarial review found two defects, and the remote runner found four
failure clusters. All fixed here.

Review BLOCKER — detect-custom-files was blind to the renamed bundle.
GSD_PREFIX_MANAGED_DIRS in gsd-tools.cjs hardcoded 'hooks', so for pi the
whole gsd-hooks/ tree was invisible to the custom-file scan and user-added
files there were never backed up before the next update's clean-install wipe.
The dir set now resolves via the .gsd-runtime marker plus the shipped
capability registry (never bin/install.js, which is not shipped into installed
trees), and falls back to scanning every known candidate when the runtime
cannot be determined — over-scanning is safe, under-scanning is the data loss.

Review MAJOR — the pi adapter bound to an empty bundle. resolveSharedHooksDir
accepted any directory, so an interrupted install left gsd-hooks/ winning over
a fully-staged legacy hooks/ and every hook silently no-opped. A candidate now
qualifies only if it is non-empty.

Remote-runner clusters:
- emitted-provenance had no rule for the gsd-hooks/ family; added two pi-scoped
  rules pointing at the same sources the existing hooks/ rules use. The table is
  total, so an unattributed family is a hard failure by design.
- pi tests in install-minimal-hooks and the install integration suite asserted
  the old layout; updated to derive the dir name from the descriptor rather than
  hardcoding either name.
- 19 unrelated-looking failures on node22 only were a leaked fs mock: t.after()
  runs in registration order, cleanup was registered before mock.restoreAll(),
  and node22's JS rimraf calls the public fs.rmdirSync while node24's native
  path does not — so the EACCES stub leaked process-wide on one lane. Restore
  now runs first.

Verified on the remote runner.

* fix(#3023): honor PI_CODING_AGENT_DIR, ack the rename ripple, fix expandTilde

pi resolves its agent dir as PI_CODING_AGENT_DIR ?? ~/<CONFIG_DIR_NAME>/agent
(packages/coding-agent/src/config.ts). GSD's pi descriptor declared an empty
configHome.env, so a user with that variable set had GSD installed where pi
never looks. Added the env name; the dot-home-nested resolver already handled
the override, so no resolver logic changed.

Also fixes expandTilde in the shared runtime-homes resolver, found while adding
that: it hardcoded os.homedir() and ignored the opts.home every caller threads,
so EVERY runtime's tilde-valued env override (claude, antigravity, windsurf, pi)
silently resolved against the real home. That is a correctness bug and a
test-escape hazard — a sandboxed test asserting on a tilde override reached the
developer's actual home directory. Now threaded through every branch; behavior
with no injected home is unchanged.

Adds the emitted-drift ack fragment for the 58 pi paths whose emitted location
moved with the rename. The provenance rules satisfy the totality gate; the
differential gate needs the ack because the hook sources are byte-unchanged —
only the installer's target directory moved. The two hook files this branch
genuinely edits stay attributed and are not double-acked.

Note on piConfig.configDir: it is read from pi's OWN installed package.json
(getPackageDir walks up from pi's __dirname), alongside piConfig.name — a
white-label setting for a redistributed pi fork, not a per-project user setting.
Documented accordingly rather than treated as an unsupported override.

Verified on the remote runner.

* fix(#3023): reject blank env overrides, pin adapter/descriptor parity

Three review findings, all fixed.

A whitespace-only config-dir override was accepted verbatim: the guard was
`if (val)`, falsy only for the empty string, so PI_CODING_AGENT_DIR='   '
resolved to a literal three-space directory name instead of falling back to the
descriptor default. Fixed across every env-consuming branch — dot-home,
dot-home-nested, all three xdg steps, and generic-agents-root — not just pi's.
Non-blank values are still never trimmed, so '~/My Agent Dir' keeps working.

pi/gsd.cjs's probe list and the descriptor were two independent sources of truth
for the bundle directory name; a future rename would have desynced them silently
and left every pi hook quiet with no error. The probe list stays deliberate — it
must resolve in a dev checkout and a half-upgraded tree, where the registry's
answer would be wrong — so this adds the parity assertion the repo's
generative-fix-divergence rule calls for: the descriptor value must be the FIRST
candidate, and the default must remain present.

Changeset body rewritten to cover the two later user-facing fixes it had not
caught up with.

Verified on the remote runner.

* chore(#3023): backfill changeset PR number

* fix(#3023): anchor injection-scan patterns and fix a macOS detection hole

CI's security job flagged CONTEXT.md:124 — pre-existing prose reading 'not the
same fact as a genuinely empty or absent one'. The match was the 'act as a'
INSIDE 'f-act as a': the pattern had no left word boundary, so any word ending
in act tripped it (fact, impact, contract, artifact, interact, redact,
abstract). My four-line CONTEXT.md edit dragged the latent false positive into
this PR because the scan is diff-scoped by file but reads whole files. Anchored
with (^|[^[:alnum:]]) rather than rewording maintainer-owned prose, which would
have left the class alive for the next PR touching any file saying 'fact as a'.

Auditing the rest of the list for the same class surfaced a real detection hole:
the eval/exec/Function patterns matched a quote via \x27, a GNU-grep-only hex
escape. BSD/macOS grep reads it as four literal characters, so single-quoted
eval('...')/exec('...') payloads were NEVER detected there while passing on
GNU-grep CI. Replaced with a literal apostrophe class.

Boundaries were added only where a real word-suffix collision exists; exec,
jailbreak, developer mode and the role-manipulation family were audited and
deliberately left unanchored. 22 new cases cover both directions — the false
positives now scan clean, and every real payload still fires, including the
quote/punctuation/start-of-line boundary forms.

Also builds this branch's injection test fixture at runtime instead of carrying
the literal phrase, so the payload keeps its teeth without tripping the scan.

Verified on the remote runner.

---------

Co-authored-by: sim <sim@local>

2026-08-07 13:41:21 -04:00

5.7 KiB

Raw Blame History

Installer Migration Module owns install-time upgrade safety

Status: Accepted
Date: 2026-05-11

We decided to introduce an explicit Installer Migration Module for install-time file moves, removals, config rewrites, and user-data preservation. Installer upgrade behavior must be represented as versioned migration records that produce a dry-run plan before applying changes.

Decision

Add an Installer Migration Module as the owner for upgrade migrations.
Keep the existing installer materialization pipeline, but move cleanup and feature-retirement behavior into migration records over time.
Track applied migrations in an install-state file next to the existing file manifest.
Treat the existing file manifest as the managed-file ownership baseline.
Treat user-owned artifacts as a single shared policy consumed by preservation and manifest writing.
Require migrations to plan first, then apply through a shared executor that owns backup, rollback, and reporting.
Default ambiguous or unknown files to preserve; destructive changes need managed-file evidence or explicit user choice.
Support dry-run output using the same planner used by apply mode.
Include a first-time baseline scanner for legacy installs that need classification before destructive migrations can be trusted.
Treat the runtime configuration contract registry in docs/installer-migrations.md as the source of truth for migrations that touch host runtime config.

Runtime Contract Decision

Every migration that rewrites runtime config, moves an invocation surface, or retires a generated runtime artifact must cite the registry row in docs/installer-migrations.md. If the migration changes where a runtime loads commands, skills, agents, hooks, or rules, the PR must update both the registry and docs/ARCHITECTURE.md.

The registry records what GSD installs, where it installs it, when migrations may touch it, who owns the surrounding config, and why the shape matches the host runtime. When upstream docs do not publish an API or docs version, the checked date is the drift sentinel. A later upstream docs or CLI release that changes command, skill, agent, hook, or rule loading requires a new registry snapshot before migration work proceeds.

Consequences

Retiring features requires an explicit migration instead of a hidden cleanup block.
The installer can remove stale GSD-owned artifacts without guessing about user files.
Locally modified managed files get a consistent backup path before removal or replacement.
Future rollback work can become runtime-neutral instead of Codex-specific.
Migration authors must define ownership evidence, conflict behavior, runtime scope, and non-interactive behavior.
Migration authors must also define which runtime contract they are relying on and whether the upstream documentation is versioned.
The installer gains another state file, so tests must cover missing, legacy, and checksum-mismatch state.

Scope

The first implementation should extract manifest/user-owned helpers, add install-state persistence, add migration planning, and port one existing orphan cleanup into the migration runner. It should not rewrite every runtime installer branch in the first pass.

The detailed module contract lives in docs/installer-migrations.md.

Amendment (2026-05-11): Authoring guard enforcement

The Installer Migration Authoring Guard Module validates migration records and planned actions before planning can proceed. Records must declare title, description, introduction version, explicit install scopes, destructive status, and a plan function. Destructive or config-rewrite actions must include ownership evidence, and runtime config rewrites must cite the runtime configuration contract registry.

Amendment (2026-08-07): Non-recursive empty-directory removal primitive

Migration 003's docblock records, as an intentional consequence of this ADR, that the framework has no recursive directory-removal primitive: every action targets a single file by relPath, and an emptied directory shell is left behind for the user (or a future migration) to clean up. #3023 exposed a case where that is not enough: pi reserves the directory NAME hooks/ for its own deprecated-extension check, which warns on the path's mere existence regardless of contents. Leaving an emptied hooks/ shell behind would keep the warning firing forever, defeating the retirement.

We added remove-empty-dir, a new action type, rather than relaxing the "never remove directories" posture generally:

It calls fs.rmdirSync only — never fs.rmSync, { recursive: true }, or { force: true }. A non-empty directory fails the underlying syscall and is treated as a successful no-op (skipped-not-empty), not swept.
Emptiness is re-checked immediately before the call, not trusted from planning time, so a file that survived an earlier action in the same run (a failed removal, or a legitimately preserved unknown file) keeps the directory alive.
The target must not be a symlink, and its realpath must resolve strictly inside — and never equal — the config directory's own realpath.
Any unexpected failure degrades to left-in-place, matching every sibling action type's non-throwing posture.

Recursive directory removal remains deliberately absent. This primitive only retires a directory NODE once every file inside it has already been individually classified and actioned by other, ordinary file-level actions in the same migration — it is not a shortcut for sweeping a subtree in one step, and a migration author who wants that should still enumerate files individually per migration 003's and 009's pattern.

See docs/installer-migrations.md#action-types (remove-empty-dir) and src/installer-migrations/009-pi-retire-reserved-hooks-dir.cts.

5.7 KiB Raw Blame History