Feat/issue 12 agents skills installer

[aam9063]

Linked issue

Closes #12

Summary

Add a deterministic installer that copies the canonical skill into the shared .agents/skills locations used by Codex, OpenCode, and Gemini CLI.

• npm bin entry (mobile-agent-orchestrator) with an install command: repeatable --target codex|opencode|gemini (shared destination deduplicated into one copy and one manifest), required --scope user|project, and --dry-run that prints the exact plan and writes nothing.
• Pure plan/execute engine (lib/hosts.mjs, lib/installer.mjs, zero dependencies): copies the canonical SKILL.md and every bundled reference (recursive discovery matching the validator's published inventory), records installer version and sha256 checksums in .mobile-agent-orchestrator.manifest.json beside the skill directory, and is an idempotent no-op when managed content already matches.
• Managed-file safety model: installs abort with a conflict list and zero writes when the destination contains locally modified, unmanaged, or symlinked content, a corrupt manifest, or a non-directory skill path; replace is only granted to content backed by a recorded manifest checksum. I/O failures mid-install report clearly that the destination may be inconsistent and that re-running repairs it.
• scripts/validate-package.mjs: allowlist and tarball inventory extended to bin/ and lib/; all other validation rules unchanged. pi.skills and Pi package discovery are untouched.

Intentionally out of scope (issue non-goals): Claude Code target, interactive detection, status/uninstall, npm publication.

Review boundary note: current PR diff is 1231 lines (1223 additions, 8 deletions). The follow-up review fix commit adds 490 diff lines; the maintainer explicitly authorized keeping the four fixes together and retaining all regression coverage. The plan/execute module seam remains buildPlan/executePlan; no unrelated P3 work was added.

Follow-up review fixes (e15dc4e)

• Execute the CLI correctly through npm's .bin symlink, including nonzero exit codes for invalid commands.
• Reject valid/dangling manifest symlinks and non-regular manifests before any writes.
• Reconcile removed/renamed package files only when their content matches the previous manifest; preserve locally modified, unmanaged, and symlinked entries. Dry runs expose removals without applying them.
• Publish managed files and the manifest through exclusive temporary files and atomic rename; preserve the previous manifest on write failure and allow a subsequent retry.

Review the installer safety/reconciliation changes and regression tests first. Pi discovery, targets/scopes, dependencies, and the original non-goals are unchanged.

Verification

Latest verification — e15dc4e

Platform: Linux/WSL2, Node v24.20.0, npm 12.0.2.

• npm test: 44 passed, 0 failed, 0 skipped, including package validation.
• npm run pack:check: exit 0, the same 11-entry publication inventory.
• node --check on all four changed .mjs files: passed.
• Real npm pack + installation in a temporary prefix: npm shim help/invalid-command exit codes, installation for three deduplicated targets, and idempotent reinstall passed; installer destinations and HOME were isolated in temporary directories.
• Regression checks cover manifest symlinks, safe removals/renames, zero-write conflicts/dry runs, and a real Linux EFBIG failure preserving the old manifest with successful retry. Crafted manifest paths cannot delete files outside the skill directory.
• Independent read-only verification: all four findings resolved, no new blockers.
• GitHub Validate package check for this head: passed.

Limitations: Windows/macOS were not rerun for these fixes. The case-insensitive and unavailable-inode fallback branches were not executed on this Linux filesystem; the case-sensitive rename branch was exercised.

Original Windows verification — before the follow-up fixes

The author's original platform evidence is retained below; it is not a rerun against the updated head.

Platform: Windows 11, Git Bash, Node v24.18.0 (CI verifies on Linux/Node 22).

• npm run pack:check: exit 0; tarball contains the expected 11 entries (skill + bin/ + lib/).
• node --test: 30 tests — 27 pass, 1 skipped, 2 fail. The skip is the broken-symlink test (symlinkSync requires privileges on Windows; by design, Linux CI exercises it). The 2 failures are the pre-existing Windows-only detect-release spawn failures documented in odd/tasks/issue-12-installer.md; they reproduce on unmodified main.
• node --test tests/installer.test.mjs: 15 tests — 14 pass, 1 skipped (symlink), 0 fail.
• node scripts/validate-package.mjs: every check passes except the tarball-comparison spawn, which fails with spawnSync npm ENOENT , the pre-existing Windows limitation also documented in the task file.
• The three issue dry-run commands all exit 0 and write nothing:
  • node bin/mobile-agent-orchestrator.mjs install --target codex --scope user --dry-run
  • node bin/mobile-agent-orchestrator.mjs install --target opencode --scope project --dry-run
  • node bin/mobile-agent-orchestrator.mjs install --target gemini --scope user --dry-run
• Live behavior checks: duplicate --target deduplicates to one destination; modified destination content aborts with exit 1 and no writes; corrupt manifest and file-as-destination abort cleanly.

Task/evidence document (decisions, review rounds, rejected findings): odd/tasks/issue-12-installer.md.

Checklist

• The issue reference is correct: Closes #12 (completed work).
• The scope is focused and preserves the skill's safety contracts.
• Verification results and any limitations are recorded above.
• Documentation is updated where applicable (README installer subsection).

[egdev6]

Thanks @aam9063 for the installer and the thorough test coverage! The plan/execute split provides a solid foundation for safe, repeatable installs.

Really appreciate the contribution.