axstack 0.20.2 → 0.20.4

package/README.md

@@ -1,142 +1,129 @@
 # Axstack
 
-Axstack is a standalone toolkit for finishing agreed engineering work with less
-supervision while retaining independent review. Chat drives execution; a Bun
-CLI installs owned skills and role data and checks capabilities. Axstack has no
-daemon, scheduler, runtime database, or workflow state machine.
-
-Orca is the only supported active runtime. Its installed, version-matched
-`orchestration` and `orca-cli` guides own worktrees, sessions, supervised
-dispatch, messages, settlement, and handoff mechanics. Axstack owns scope,
-role choices, evidence, review policy, and one private derived run record.
-
-## How a run works
-
-Invoke the needed phase directly: `axstack-align`, `axstack-spec`,
-`axstack-tickets`, `axstack-implement`, `axstack-review`, and `axstack-watch`.
-Direct `axstack-research`, `axstack-explain`,
-`axstack-improve`, and `axstack-debug` routes need no spec ceremony. `axstack-relay` remains an
-optional inline route for explicit messages and authorized notifications; an
-unavailable or legacy-runtime-only relay falls back to the current conversation
-without changing authority.
-
-1. Classify new engineering work as substantial, small, or unclear with a brief
-   reason. Small, bounded one-PR work uses the current request or selected issue
-   as a snapshotted small-change intent;
-   substantial or stacked work needs an approved spec and matching ticket map.
-   Substantial work uses Linear by default, or explicitly selected GitHub Issues
-   or repository Markdown, as its authoritative spec and capability tracker.
-2. The current chat drives on whatever model runs it; there is no driver
-   profile. Bind each ready task to the selected role snapshot and an authoritative Orca
-   Run, Task, and Dispatch. Exactly one writer owns a candidate at a time. All
-   subagent and delegated worker dispatches go through Orca orchestration rather than
-   harness-native subagent tools.
-3. Peer PRs receive both configured independent reviewer roles. Authored PRs
-   receive one eligible reviewer from the selected preset's explicit mapping
-   and actual author provenance. Every review binds the exact head and base.
-   Stable IDs are `axstack-reviewer-primary` and `axstack-reviewer-secondary`.
-4. Accepted repairs return to the same author where its session and evidence
-   remain valid. The human merges by default, bottom-up for a stack.
-5. Full handoff requires explicit recipient acceptance of the exact scope and
-   authority before ownership changes. Ordinary resume reconciles the current
-   owner instead of replacing it.
-
-Active PR fanout is dependency- and capacity-driven; there is no fixed count.
-Each PR has one theme and a measured size under the shared
-[PR-shape policy](skills/axstack/references/pr-shape.md). Routine shape and
-fanout choices remain autonomous inside approved scope. Material scope,
-serious-risk, unavailable-model, and human-merge holds remain explicit.
-The autonomous driver records the rationale band's cohesion rationale; the exception band needs a
-reasonable split attempt and full exception record. Size alone never requires
-user approval.
-
-## Install from source
-
-Requirements: Bun >=1.3.14, Git, `gh`, the `gh stack` extension, and a running
-Orca with its runtime-owned guides. Filesystem access uses Bun's implementation
-of `node:fs` and `node:fs/promises`; there are no runtime dependencies.
+Engineering workflows for AI agents, from an idea to a reviewed pull request.
+
+Axstack is a set of skills for engineers who want agents to carry work forward
+with less supervision, without giving up clear scope, independent review, or
+control over what ships. Use it to plan a feature, implement an agreed task,
+review a teammate's PR, or maintain your own PRs as feedback arrives.
+
+Your chat stays in charge. Orca provides the worktrees, agent sessions, and
+coordination; Axstack supplies the workflow and review rules. A small Bun CLI
+installs the skills and checks prerequisites. There is no Axstack daemon,
+scheduler, or runtime database to operate. Orca is the only supported runtime.
+
+## What you can do
+
+| Need | Skill |
+| --- | --- |
+| Explore an idea and settle scope | `axstack-align` |
+| Turn agreed scope into a specification | `axstack-spec` |
+| Break a specification into executable tickets | `axstack-tickets` |
+| Build an approved task with tests and independent review | `axstack-implement` |
+| Review a pull request | `axstack-review` |
+| Monitor or maintain an existing PR | `axstack-watch` |
+| Diagnose a bug and establish a failing check | `axstack-debug` |
+| Answer a bounded question with sources | `axstack-research` |
+| Explain a system or identify improvements | `axstack-explain`, `axstack-improve` |
+| Measure a run's outcomes and gaps | `axstack-audit` |
+| Send an explicit message or authorized notification | `axstack-relay` |
+
+Start at the phase you need. Small, bounded changes can begin with your request
+or an existing issue; substantial work needs an approved spec and matching
+tickets before implementation. Research, explanation, and peer review do not
+require a new specification.
+
+For a larger feature, the usual path is:
+
+```text
+align → spec → tickets → implement → review → watch
+```
+
+The implementation workflow includes the author–review–repair loop. You do not
+need to manually coordinate every agent or repeat an approval that is still valid.
+
+## Quick start
+
+You need Bun >=1.3.14, Git, the GitHub CLI (`gh`), the `gh stack` extension,
+and a running Orca with its `orca-cli` and `orchestration` guides available.
+The agents selected by your preset must also be available in Orca.
+
+Install the CLI and skills for your harness. For example, for Codex:
 
 ```sh
-bun bin/axstack.js check --bundle . [--harness claude|codex|opencode|antigravity]
-bun bin/axstack.js install --bundle . --skills-dir <dir> --instructions <file> --preset mixed [--yes]
-bun bin/axstack.js install --bundle . --skills-dir <dir> --preset mixed
-bun bin/axstack.js uninstall --skills-dir <dir> --instructions <file>
+bun add --global axstack
+axstack check --harness codex
+axstack install --harness codex --preset mixed --yes
+```
+
+Codex skills default to the shared `~/.agents/skills` root while its owned
+`AGENTS.md` block stays under `$CODEX_HOME` (default `~/.codex`). A default
+install safely retires only unchanged manifest-owned legacy Axstack skills;
+use `--skills-dir` for an explicit target without automatic migration.
+
+Then open an Orca chat and ask for the relevant skill:
+
+```text
+$axstack-align Help me scope account recovery.
+$axstack-implement Build the task we agreed on.
+$axstack-review Review this pull request: <PR URL>
+$axstack-watch Monitor this PR without making changes: <PR URL>
 ```
 
-Use `--harness claude|codex|opencode|antigravity` only for a verified default
-skill directory and rules file. `--claude-settings` and `--no-claude-settings` manage the existing
-Claude Code subagent default transaction; they do not configure Orca roles.
-See [installation details](docs/installation.md).
-
-`--instructions` manages one versioned Axstack block in `AGENTS.md`,
-`CLAUDE.md`, or `GEMINI.md`. Harness defaults resolve those files automatically. The block
-requires direct matching phase-skill invocation and requires every subagent, delegated
-worker, reviewer, and cross-harness dispatch to use visible Orca orchestration via the `orca` CLI
-rather than a harness-native subagent tool (e.g. Claude/Codex native subagents). OpenCode
-and Antigravity subagents run as Orca-supervised workers. Text and file
-mode outside the markers are preserved; edited, malformed, unowned, or unsafe
-targets are reported without normal-path adoption. Install exits nonzero when
-an instruction conflict is preserved, while clean and idempotent installs exit
-successfully.
-
-The public bundle preserves three canonical 24-role inputs:
+Use `--harness claude`, `opencode`, or `antigravity` for another supported
+installation target, or provide explicit skill and instruction paths.
+Installation adds an owned instruction block and preserves unrelated content;
+it does not enable automations or prove that every configured model is available.
+See [installation](docs/installation.md) for source installs, custom paths,
+upgrades, conflicts, and uninstalling.
+
+## How work stays controlled
+
+- **One accountable driver, one writer per candidate.** Your current chat
+  coordinates work; separate worktrees keep PR jobs isolated.
+- **Independent review.** Peer PRs receive two independent reviews; authored
+  changes receive a reviewer selected from the actual author's configured
+  pairing. Reviews apply to an exact revision, not just a branch name.
+- **Visible agent work.** Delegation uses visible Orca orchestration via the `orca` CLI,
+  not harness-native subagent tools.
+- **Explicit boundaries.** Agents work within agreed scope. Missing authority,
+  unavailable models, and serious risks are surfaced rather than silently
+  bypassed. The human merges by default.
+- **Resumable progress.** Work retains ownership, decisions, and evidence so a
+  later session can reconcile what happened before continuing.
+
+Choose an explicit role preset:
 [mixed](profiles/presets/mixed.json),
-[codex-only](profiles/presets/codex-only.json), and
-[claude-only](profiles/presets/claude-only.json). Each is exactly
-`{ "version": 1, "roles": [...] }`. Installation writes the selected snapshot
-to `<skills-dir>/axstack/roles.json` as
-`{ "version": 1, "preset": "<name>", "roles": [...] }` under normal ownership
-hashes. An edited installed role file is preserved.
-
-Mixed configures independent Astra and Fable advisers at high. Single-provider
-presets preserve both adviser IDs and mark the unavailable one with `model:
-null` inside that preset's provider bounds; installation remains ready, while
-Align and Spec hold because both receipts are required. The mixed
-`axstack-checker` and `axstack-research-web-google` roles launch Antigravity by
-agent ID with explicit `model: null`; the run records the model reported by the
-TUI. The single-provider presets configure the checker and record the Google
-research branch as intentionally absent. Preset changes affect new runs only. Stored model, effort, and permission
-fields are declared intent until actual Orca launch receipts establish effective
-behavior; installation never proves provider availability or permission parity.
-Subscription availability and quota never select a fallback model.
-End-to-end compatibility remains unverified without matching runtime receipts.
-
-## Runtime evidence and holds
-
-Native Orca exercises have returned Codex, Claude, and OpenCode Muse Spark
-worker completions, same-terminal follow-up, separate worktree placement, settlement
-cleanup, `user_takeover` retention, and recovery from `consumer_fenced`. These are
-bounded runtime facts, not proof that every role or harness is compatible.
-
-Input acceptance is not agent readiness. A trust prompt was observed after an
-accepted launch, so startup recovery must inspect the existing attempt, never
-answer trust or permission prompts on the worker's behalf, and never create a
-duplicate writer. A `worker_done` advances work only when its Task and Dispatch
-match the active attempt and its revision evidence verifies.
-
-Two logical native PR-manager lanes run on staggered 15-minute schedules. Each
-pass uses a fresh finite session in a new isolated workspace. Review
-and watch each admit at most five bounded PR jobs;
-waiting PRs stay covered without reserving slots. Axstack adds no custom
-scheduler, queue engine, or decision interpreter. Sessions reconcile before
-admission across the whole lane, save durable continuity and decisions outside
-disposable workspaces, and retire only their verified pass workspace as the
-final action. Manual review/watch never inherits this cleanup lifecycle.
-Native fresh-session, overlapping-pass, recovery, and VPS resource behavior
-require a canary before activation.
-
-Mobile completion/reply behavior remains unverified. Structural checks and
-qualitative scenario evaluation are not live runtime proof.
-
-## Historical migration boundary
-
-Older releases used Paseo for orchestration and could leave profile ownership
-provenance or retired skills behind. That state is historical and inert in the
-Orca runtime. Migration preserves user-edited and unknown assets and records
-legacy ownership without reading, writing, or deleting live host configuration.
-Use the explicit migration guidance in [installation](docs/installation.md);
-release installation, host cutover, and old-timer cleanup need separate
-authorization.
+[codex-only](profiles/presets/codex-only.json), or
+[claude-only](profiles/presets/claude-only.json).
+Mixed supports the cross-provider implementation workflow. Single-provider
+presets have workflow limitations; they are not automatic fallbacks when a
+model is unavailable. See [workflow and routing details](docs/workflows.md).
+
+## Optional PR automation
+
+Manual review and watch work independently of scheduled automation.
+For recurring use, Axstack defines two native Orca manager lanes: one discovers
+eligible peer-review requests, and the other monitors your open PRs and handles
+authorized repair events.
+
+The lanes use staggered 15-minute schedules. Each pass uses a fresh finite
+session in an isolated workspace and admits at most five executing PR jobs per
+lane, fewer under resource pressure. Waiting PRs remain tracked without consuming
+execution slots, so a large open-PR backlog does not require an idle agent per PR.
+Completed passes save continuity and retire their own verified resources.
+
+Scheduling is opt-in and requires host-specific runtime validation before
+activation. Installing Axstack does not turn it on. Repairs are limited to
+explicitly allowed repositories; automation never merges for you.
+See [PR-manager setup and safety](skills/axstack/references/automations.md).
+
+## Documentation
+
+- [Installation and configuration](docs/installation.md)
+- [Workflows, review policy, and model routing](docs/workflows.md)
+- [PR scope and sizing](skills/axstack/references/pr-shape.md)
+- [Releases](https://github.com/axatbhardwaj/axstack/releases)
 
 ## License
 

package/bin/axstack.js

@@ -8,6 +8,8 @@ import { join, resolve } from '../src/posixpath.js';
 import {
   checkInstructionBinding,
   installBundle,
+  readLegacySkillsManifest,
+  retireLegacySkills,
   uninstallBundle,
   validateBundle,
 } from '../src/installer.js';
@@ -57,7 +59,8 @@ Flags:
                       profiles/presets/*.json role data. Defaults to the package root.
   --preset <name>     Required routing preset: mixed, codex-only, or claude-only.
                       Aliases: codex = codex-only; claude = claude-only.
-  --skills-dir <dir>  Explicit install target (required). Overrides --harness.
+  --skills-dir <dir>  Explicit install target. Overrides harness skill defaults
+                      and automatic legacy Codex skill retirement.
   --instructions <file>
                       Instruction file to receive the owned routing block.
                       Harness defaults: ~/.claude/CLAUDE.md for Claude,
@@ -71,6 +74,8 @@ Flags:
                       Skip Claude Code user-settings management.
   --harness <name>    Known harness (${harnessLocations().map((h) => h.harness).join(', ')}).
                       Grok has no verified auto-discovery: --skills-dir is required.
+                      Codex skills default to ~/.agents/skills; CODEX_HOME
+                      continues to select its AGENTS.md configuration home.
   --force             Overwrite/remove user-edited owned assets and take
                       ownership of unknown files. Off by default.
   --yes               Confirm writes inside your home directory. Temp dirs
@@ -203,13 +208,20 @@ function resolveHarnessTarget(harness) {
     );
   }
   if (entry.harness === 'codex') {
-    // User skills live under $CODEX_HOME/skills; CODEX_HOME defaults to ~/.codex.
-    const home = Bun.env.CODEX_HOME ? expandHome(Bun.env.CODEX_HOME) : join(homeDir(), '.codex');
-    return join(home, 'skills');
+    // Axstack uses Codex's shared user-skill root. CODEX_HOME remains the
+    // configuration home for AGENTS.md, not an Axstack skill destination.
+    return join(homeDir(), '.agents', 'skills');
   }
   return expandHome(entry.skillsDir);
 }
 
+function legacyCodexSkillsTarget() {
+  const codexHome = Bun.env.CODEX_HOME
+    ? expandHome(Bun.env.CODEX_HOME)
+    : join(homeDir(), '.codex');
+  return join(codexHome, 'skills');
+}
+
 function resolveHarnessInstructions(harness) {
   if (harness === 'claude') return join(homeDir(), '.claude', 'CLAUDE.md');
   if (harness === 'codex') {
@@ -278,18 +290,45 @@ async function main() {
         : flags.harness
           ? resolveHarnessInstructions(flags.harness)
           : null;
+      const usesCodexDefault = flags.harness === 'codex' && !flags['skills-dir'];
+      const legacyCodexDir = usesCodexDefault ? legacyCodexSkillsTarget() : null;
+      const legacyCodexManifest = legacyCodexDir
+        ? await readLegacySkillsManifest(legacyCodexDir)
+        : null;
       const summary = await installBundle({
         bundleDir: flags.bundle ? resolve(flags.bundle) : PACKAGE_ROOT,
         skillsDir,
         preset: flags.preset,
         instructionsPath,
+        inheritedInstructions: legacyCodexManifest?.instructions,
         force: !!flags.force,
         yes: !!flags.yes,
         claude: resolveClaudeOption(flags, 'install'),
         log: (m) => { if (m !== 'plan complete') console.log(m); },
       });
+      const migrationReady = summary.instructions?.status !== 'conflict' &&
+        summary.roles?.ready !== false && summary.ownershipComplete;
+      if (usesCodexDefault && migrationReady) {
+        try {
+          summary.legacyCodex = await retireLegacySkills({
+            canonicalSkillsDir: skillsDir,
+            legacySkillsDir: legacyCodexDir,
+            acceptedInstructionTransfer: summary.acceptedInstructionTransfer,
+            yes: !!flags.yes,
+          });
+        } catch (err) {
+          summary.legacyCodex = {
+            removed: [], preserved: [], missing: [], skipped: false,
+            failed: true,
+            reason: `legacy Codex skills not retired: ${err.message}`,
+          };
+        }
+      } else if (usesCodexDefault) {
+        summary.legacyCodex = { removed: [], preserved: [], missing: [], held: true };
+      }
       const changed =
         summary.added.length + summary.updated.length + summary.removed.length +
+        (summary.legacyCodex?.removed.length ?? 0) +
         (['created', 'updated'].includes(summary.instructions?.status) ? 1 : 0);
       if (changed === 0) {
         console.log('Install complete: no changes (idempotent, everything unchanged).');
@@ -303,6 +342,31 @@ async function main() {
         console.log(`preserved user edits (use --force to overwrite): ${summary.preserved.join(', ')}`);
       }
       if (summary.stale.length) console.log(`stale owned files left on disk: ${summary.stale.join(', ')}`);
+      if (summary.legacyCodex && !summary.legacyCodex.skipped) {
+        if (summary.legacyCodex.held) {
+          console.log(
+            `legacy Codex skills preserved (retirement held): ${summary.legacyCodex.reason ?? 'canonical install has an unresolved conflict'}`,
+          );
+          if (summary.legacyCodex.failure) process.exitCode = 1;
+        }
+        if (summary.legacyCodex.failed) {
+          console.log(
+            `canonical install completed; legacy retirement failed: ${summary.legacyCodex.reason}`,
+          );
+          process.exitCode = 1;
+        }
+        if (summary.legacyCodex.removed.length) {
+          console.log(`legacy Codex skills retired: ${summary.legacyCodex.removed.join(', ')}`);
+        }
+        if (summary.legacyCodex.preserved.length) {
+          console.log(
+            `legacy Codex skills preserved (modified; resolve manually): ${summary.legacyCodex.preserved.join(', ')}`,
+          );
+        }
+        if (summary.legacyCodex.missing.length) {
+          console.log(`legacy Codex manifest entries already missing: ${summary.legacyCodex.missing.join(', ')}`);
+        }
+      }
       if (summary.instructions) {
         const i = summary.instructions;
         if (i.status === 'conflict') {

package/docs/installation.md

@@ -24,6 +24,8 @@ axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-
 - `--bundle` defaults to the package root and contains `skills/` plus
   `profiles/presets/*.json`.
 - `--skills-dir` is required unless a verified harness default resolves it.
+  Codex defaults to the shared `~/.agents/skills` root; an explicit override
+  remains authoritative and disables automatic legacy Codex-root retirement.
 - `--instructions` selects the instruction file that receives Axstack's owned
   marker block. `--harness claude` defaults to `~/.claude/CLAUDE.md`;
   `--harness codex` defaults to `$CODEX_HOME/AGENTS.md` or `~/.codex/AGENTS.md`;
@@ -34,6 +36,23 @@ axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-
   reads `~/.claude/skills`, so its own directory is only needed for the owned
   routing block; Antigravity (IDE and `agy` CLI) reads `~/.gemini/config/skills`
   only.
+
+For a default Codex install, Axstack first installs and verifies the canonical
+`~/.agents/skills` copy. It then retires only unchanged files owned by the
+legacy `$CODEX_HOME/skills/.axstack-manifest.json`. Modified, missing, unowned,
+or symlinked content is preserved or refused and reported; an instruction
+conflict preserves the complete legacy install. An unchanged owned Codex
+`AGENTS.md` binding is transferred to the canonical manifest without changing
+the instruction bytes. Other harness ownership, settings, and inert profile
+provenance remain untouched. Repeated installs verify the same canonical
+preset and converge without duplicate skill entries.
+
+If retirement leaves only the legacy manifest's Claude-settings ownership,
+first confirm its `files` map is empty and it has no instruction or profile
+conflict. Then finish that owner with
+`axstack uninstall --skills-dir "${CODEX_HOME:-$HOME/.codex}/skills" --yes`;
+the settings sidecar preserves the value while any other install still owns it.
+
 - `--claude-settings` and `--no-claude-settings` control the existing Claude
   Code subagent-default transaction. They do not configure Orca roles.
 - `--force` may replace an edited owned asset; it never adopts or removes
@@ -197,7 +216,7 @@ survives.
 | Harness | Default directory | Status |
 | --- | --- | --- |
 | Claude | `~/.claude/skills` | documented upstream |
-| Codex | `$CODEX_HOME/skills` (default `~/.codex/skills`) | documented upstream |
+| Codex | `~/.agents/skills` | documented upstream |
 | OpenCode | `~/.config/opencode/skills` | documented upstream |
 | Antigravity | `~/.gemini/config/skills` | documented upstream |
 | Grok | explicit `--skills-dir` only | auto-discovery unverified |

package/docs/workflows.md

@@ -228,6 +228,8 @@ Predeclared scenario evaluation is qualitative behavior evidence, not determinis
 compatibility requires actual guide discovery, role/session evidence, worktree
 and Dispatch receipts, completion delivery, and cleanup as applicable. Mobile
 completion and reply behavior remain unverified.
+End-to-end compatibility remains unverified for any route without matching
+runtime receipts; evidence from one route does not establish support for all roles.
 
 ## Historical migration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.20.2",
+  "version": "0.20.4",
   "description": "Axstack installer and setup CLI: installs owned chat skills and role data, configures supported harness settings, and checks Orca capabilities.",
   "keywords": [
     "claude-code",

package/skills/axstack/references/automations.md

@@ -66,7 +66,17 @@ intent alone is insufficient. Conversely a completed run row does not prove exit
 If these facts remain unknown, report the hold at the durable decision location;
 do not silently stand down forever or replace a potentially live owner.
 
-Before PR admission, reconcile old pass resources. If three or more unreclaimed
+Before PR admission, reconcile old pass resources and reclaim every safely
+removable earlier pass workspace under the retirement guards below. This is
+routine cleanup on every admitted pass; do not wait for the three-workspace
+threshold to start cleanup. Save confirmed exit and ownership-release receipts
+before removing each workspace. Preserve dirty, unpushed, evidence-bearing,
+user-owned, active, or uncertain resources; the threshold never relaxes these guards.
+Explicitly classified evidence may cease to block cleanup only after the
+[private evidence archive](evidence-archive.md) is verified and its receipt is
+read back from durable continuity. This never makes other dirt disposable.
+After cleanup, re-list and count only the earlier pass workspaces still remaining.
+If three or more unreclaimed
 earlier pass workspaces remain, disable only this automation through the native
 CLI, verify the disabled setting, save/report the cleanup hold, and admit no new
 PR jobs. Also pause on a confirmed cleanup failure or unresolved lane ownership.
@@ -146,12 +156,14 @@ publication receipt, hold, and next action. GitHub remains authoritative for
 open state, revisions, reviews, checks, and merge state.
 
 When the current event is handled, settle and release owned native resources.
-Preserve dirty worktrees, unpushed candidates, review evidence, pending
+Preserve dirty worktrees, unpushed candidates, unarchived review evidence, pending
 external results, and user-owned work until durability and ownership are
 proven. Unknown liveness, `user_takeover`, and ambiguous publication likewise
 forbid cleanup. Here a pending external result means an unconfirmed publication
 or send outcome, not pending CI. Waiting state belongs in GitHub and the compact
 record, never in an idle model, per-PR timer, or polling loop.
+Follow the [private evidence archive](evidence-archive.md) when evidence is the
+only local state to preserve; archive success does not relax any other guard.
 
 ## Review and repair authority
 
@@ -216,8 +228,11 @@ self-close. Waiting PRs still occupy zero slots once their owned trees settle.
 
 Cleanup of PR-job setup shells stays scoped to positively identified owned unused
 setup shells: use the native exact-terminal close operation for each only.
-Preserve dirty worktrees, unpushed candidates, review evidence, user-owned
+Preserve dirty worktrees, unpushed candidates, unarchived review evidence, user-owned
 terminals, unknown liveness, `user_takeover`, and ambiguous publication state.
+Never classify all dirt as evidence. If explicitly classified evidence is the
+last retention reason, apply and verify the [private evidence archive](evidence-archive.md),
+update durable continuity, and read it back before native retirement.
 
 For the manager pass only, verify native run/workspace identity, exclusive
 automation ownership, no unsettled descendants, and a fresh terminal inventory
@@ -235,9 +250,12 @@ A failed or uncertain close is not proof of retirement. The next admitted pass
 reconciles prior retirement from native state before trusting saved intent.
 Retire only positively identified completed pass resources; do not kill another
 live or unknown manager. Remove an old pass worktree only with native cleanup
-after terminal retirement is confirmed and its Git state is clean, with no
-unpushed commits, retained evidence, children, or user-owned work. Never use
-recursive shell deletion. Failed cleanup remains recorded, not silently forgotten.
+after terminal retirement is confirmed and it has no unpushed commits,
+unarchived evidence, children, user-owned work, unknown files, or unexplained
+dirty source. A verified evidence archive does not require otherwise clean Git
+state, but every remaining change must still be positively classified and safe;
+unknown dirt blocks removal. Never use recursive shell deletion. Failed cleanup
+remains recorded, not silently forgotten.
 
 The activation canary must additionally prove distinct workspace IDs per pass,
 cross-workspace lane admission, self-retirement and absence after client reconnect,

package/skills/axstack/references/evidence-archive.md

@@ -0,0 +1,68 @@
+# Private evidence archive
+
+Use this only when local review or coordinator evidence is the last reason a
+finished automation-owned worktree cannot be retired. It archives evidence; it
+never decides that a terminal or worktree is safe to remove and never performs
+native cleanup.
+
+## Eligibility
+
+First prove the exact repository, PR, 40-character head SHA, Task/Dispatch,
+workspace, terminal incarnation, automation ownership, descendant settlement,
+and liveness from current native state. A manual chat, `user_takeover`, an
+active or unknown task terminal, an unsettled descendant, unpushed commits,
+dirty source, ambiguous publication, or an unknown file remains protected.
+
+Classify each evidence file explicitly. Do not equate a dirty worktree with
+disposable evidence, archive a whole worktree, or copy source changes as a way
+to authorize deletion. Evidence may be archived while unrelated protected state
+continues to block cleanup.
+
+## Archive and verify
+
+Choose a configured absolute private archive root outside every disposable
+worktree and outside public Orca artifacts. The root must be owned for this
+purpose and inaccessible to group/other users. From the installed `axstack`
+skill directory, run:
+
+```sh
+bun scripts/archive-evidence.js \
+  --source-root <absolute-worktree-or-evidence-root> \
+  --archive-root <absolute-private-archive-root> \
+  --repo <owner/repository> --pr <number> --head <40-character-sha> \
+  --dispatch <exact-dispatch-id> \
+  --file <classified-relative-file> [--file <classified-relative-file> ...]
+```
+
+The helper refuses path escapes, symlinks, non-private archive directories,
+identity changes, and existing content that does not verify. It copies only the
+listed regular files, writes them with private permissions, hashes their exact
+bytes, and emits a JSON receipt containing the archive directory, manifest path,
+manifest hash, and file count. Repeating the same command verifies the immutable
+archive and returns the same receipt; it does not overwrite it.
+
+Record the receipt plus the exact repo/PR/head/Task/Dispatch/workspace/terminal
+identities in durable lane continuity, then read the continuity and archive
+manifest back before cleanup. If either readback differs or is unavailable,
+preserve the worktree.
+
+## Native retirement
+
+Retire descendants before their parent. For each positively identified unused
+setup shell, use the native exact-terminal close operation, then re-list native
+state and require exit proof for that exact terminal incarnation. A task
+terminal, manual chat, unexpected terminal, failed close, or uncertain exit
+remains protected.
+
+After receipt and continuity readback, if the only remaining Git dirt is the
+verified archived untracked evidence, compare its current bytes with the
+manifest again and unlink only those exact regular evidence files individually.
+Never remove tracked or unknown files, directories, or any path whose hash now
+differs. Re-read Git and native state; any remaining or uncertain dirt holds
+retirement.
+
+Only then use the version-matched Orca guide's native worktree cleanup operation
+with the exact workspace identity. Never use shell recursive deletion and never
+treat archive success as ownership, settlement, exit, or cleanup proof. Record
+and verify native absence before advancing continuity; failure or uncertainty
+preserves the resource.

package/skills/axstack/scripts/archive-evidence.js

@@ -0,0 +1,298 @@
+#!/usr/bin/env bun
+import {
+  chmod,
+  lstat,
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
+
+function isAbsolute(path) {
+  return path.startsWith('/');
+}
+
+function normalize(path) {
+  const absolute = isAbsolute(path);
+  const parts = [];
+  for (const part of path.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') {
+      if (parts.length > 0) parts.pop();
+    } else parts.push(part);
+  }
+  const normalized = `${absolute ? '/' : ''}${parts.join('/')}`;
+  return normalized || (absolute ? '/' : '.');
+}
+
+function join(...parts) {
+  return normalize(parts.filter(Boolean).join('/'));
+}
+
+function resolve(...parts) {
+  let path = '';
+  for (let i = parts.length - 1; i >= 0; i -= 1) {
+    path = `${parts[i]}${path ? `/${path}` : ''}`;
+    if (isAbsolute(parts[i])) return normalize(path);
+  }
+  return normalize(`${process.cwd()}/${path}`);
+}
+
+function dirname(path) {
+  const normalized = normalize(path);
+  if (normalized === '/') return '/';
+  const index = normalized.lastIndexOf('/');
+  if (index < 0) return '.';
+  return index === 0 ? '/' : normalized.slice(0, index);
+}
+
+function relative(from, to) {
+  const fromParts = resolve(from).split('/').filter(Boolean);
+  const toParts = resolve(to).split('/').filter(Boolean);
+  let common = 0;
+  while (fromParts[common] === toParts[common] && common < fromParts.length) common += 1;
+  return [...Array(fromParts.length - common).fill('..'), ...toParts.slice(common)].join('/');
+}
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function parseArgs(argv) {
+  const values = { files: [] };
+  for (let i = 0; i < argv.length; i += 2) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    if (!flag?.startsWith('--') || value === undefined) fail(`invalid argument near ${flag ?? '(end)'}`);
+    const key = flag.slice(2);
+    if (key === 'file') values.files.push(value);
+    else if (['source-root', 'archive-root', 'repo', 'pr', 'head', 'dispatch'].includes(key)) {
+      if (values[key] !== undefined) fail(`duplicate --${key}`);
+      values[key] = value;
+    } else fail(`unknown argument: ${flag}`);
+  }
+  for (const key of ['source-root', 'archive-root', 'repo', 'pr', 'head', 'dispatch']) {
+    if (!values[key]) fail(`missing --${key}`);
+  }
+  if (values.files.length === 0) fail('at least one --file is required');
+  if (!isAbsolute(values['source-root']) || !isAbsolute(values['archive-root'])) {
+    fail('source and archive roots must be absolute');
+  }
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(values.repo)) fail('repo must be owner/name');
+  if (!/^[1-9][0-9]*$/.test(values.pr)) fail('pr must be a positive integer');
+  if (!/^[0-9a-f]{40}$/.test(values.head)) fail('head must be an exact 40-character lowercase SHA');
+  if (!/^[A-Za-z0-9_-]+$/.test(values.dispatch)) fail('dispatch contains unsafe characters');
+  values.files = [...new Set(values.files)].sort();
+  for (const file of values.files) {
+    const parts = file.split('/');
+    if (!file || isAbsolute(file) || parts.some((part) => !part || part === '.' || part === '..') || file.includes('\0')) {
+      fail(`unsafe evidence path: ${file || '(empty)'}`);
+    }
+  }
+  return values;
+}
+
+async function assertRealPath(path, expectedType) {
+  const st = await lstat(path).catch((err) => {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (!st) fail(`missing ${expectedType}: ${path}`);
+  if (st.isSymbolicLink()) fail(`refusing symlink: ${path}`);
+  if (expectedType === 'directory' && !st.isDirectory()) fail(`not a directory: ${path}`);
+  if (expectedType === 'file' && !st.isFile()) fail(`not a regular file: ${path}`);
+  return st;
+}
+
+async function assertNoSymlinkComponents(root, rel) {
+  let current = root;
+  for (const part of rel.split('/')) {
+    current = join(current, part);
+    const st = await assertRealPath(current, current === join(root, rel) ? 'file' : 'directory');
+    if (st.isSymbolicLink()) fail(`refusing symlink: ${current}`);
+  }
+}
+
+async function assertSafeAncestors(path) {
+  const absolute = resolve(path);
+  let current = '/';
+  for (const part of absolute.split('/').filter(Boolean)) {
+    current = join(current, part);
+    const st = await lstat(current).catch((err) => {
+      if (err?.code === 'ENOENT') return null;
+      throw err;
+    });
+    if (!st) break;
+    if (st.isSymbolicLink()) fail(`refusing symlink path component: ${current}`);
+  }
+}
+
+async function ensurePrivateDir(path) {
+  const st = await lstat(path).catch((err) => {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (st) {
+    if (st.isSymbolicLink() || !st.isDirectory()) fail(`unsafe archive directory: ${path}`);
+    if ((st.mode & 0o077) !== 0) fail(`archive directory must have private 0700 permissions: ${path}`);
+    return;
+  }
+  await mkdir(path, { mode: 0o700 });
+  await chmod(path, 0o700);
+}
+
+function sha256(bytes) {
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(bytes);
+  return hasher.digest('hex');
+}
+
+async function collectSource(sourceRoot, files) {
+  await assertRealPath(sourceRoot, 'directory');
+  const collected = {};
+  for (const rel of files) {
+    await assertNoSymlinkComponents(sourceRoot, rel);
+    const bytes = await readFile(join(sourceRoot, rel));
+    collected[rel] = { bytes, sha256: sha256(bytes), size: bytes.length };
+  }
+  return collected;
+}
+
+function manifestBytes(identity, collected) {
+  const files = {};
+  for (const rel of Object.keys(collected).sort()) {
+    files[rel] = { sha256: collected[rel].sha256, size: collected[rel].size };
+  }
+  return Buffer.from(JSON.stringify({ version: 1, identity, files }, null, 2) + '\n');
+}
+
+async function verifyArchive(archiveDir, identity, collected) {
+  const archiveStat = await assertRealPath(archiveDir, 'directory');
+  if ((archiveStat.mode & 0o077) !== 0) fail(`archive permissions are not private: ${archiveDir}`);
+  const filesRoot = join(archiveDir, 'files');
+  const filesStat = await assertRealPath(filesRoot, 'directory');
+  if ((filesStat.mode & 0o077) !== 0) fail(`archive permissions are not private: ${filesRoot}`);
+  const manifestPath = join(archiveDir, 'manifest.json');
+  const expectedManifest = manifestBytes(identity, collected);
+  const actualManifest = await readFile(manifestPath);
+  if (!actualManifest.equals(expectedManifest)) fail(`archive manifest mismatch: ${manifestPath}`);
+  if (((await assertRealPath(manifestPath, 'file')).mode & 0o077) !== 0) {
+    fail(`archive manifest permissions are not private: ${manifestPath}`);
+  }
+  for (const [rel, expected] of Object.entries(collected)) {
+    const archived = join(archiveDir, 'files', rel);
+    await assertNoSymlinkComponents(filesRoot, rel);
+    const st = await assertRealPath(archived, 'file');
+    if ((st.mode & 0o077) !== 0) fail(`archived evidence permissions are not private: ${archived}`);
+    if (sha256(await readFile(archived)) !== expected.sha256) fail(`archived evidence hash mismatch: ${rel}`);
+  }
+  const actualFiles = await listArchiveFiles(archiveDir);
+  const expectedFiles = ['manifest.json', ...Object.keys(collected).map((rel) => `files/${rel}`)].sort();
+  if (JSON.stringify(actualFiles) !== JSON.stringify(expectedFiles)) {
+    fail(`archive contains unexpected or missing files: ${archiveDir}`);
+  }
+  return {
+    archiveDir,
+    manifestPath,
+    manifestHash: sha256(actualManifest),
+    files: Object.keys(collected).length,
+  };
+}
+
+async function listArchiveFiles(root, prefix = '') {
+  const files = [];
+  const entries = await readdir(join(root, prefix), { withFileTypes: true });
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    const st = await lstat(join(root, rel));
+    if (st.isSymbolicLink()) fail(`refusing symlink in archive: ${rel}`);
+    if (st.isDirectory()) files.push(...await listArchiveFiles(root, rel));
+    else if (st.isFile()) files.push(rel);
+    else fail(`unexpected archive entry: ${rel}`);
+  }
+  return files.sort();
+}
+
+async function main() {
+  const args = parseArgs(Bun.argv.slice(2));
+  const sourceRoot = resolve(args['source-root']);
+  const archiveRoot = resolve(args['archive-root']);
+  const sourceToArchive = relative(sourceRoot, archiveRoot);
+  const archiveToSource = relative(archiveRoot, sourceRoot);
+  if (
+    sourceToArchive === '' || (!sourceToArchive.startsWith('..') && !isAbsolute(sourceToArchive)) ||
+    archiveToSource === '' || (!archiveToSource.startsWith('..') && !isAbsolute(archiveToSource))
+  ) fail('source and archive roots must not contain each other');
+
+  const collected = await collectSource(sourceRoot, args.files);
+  const identity = {
+    repo: args.repo,
+    pr: Number(args.pr),
+    head: args.head,
+    dispatch: args.dispatch,
+  };
+  const repoSlug = args.repo.replace('/', '--');
+  const archiveDir = join(archiveRoot, repoSlug, `pr-${args.pr}`, args.head, args.dispatch);
+
+  await assertSafeAncestors(archiveRoot);
+  let current = archiveRoot;
+  const generated = [repoSlug, `pr-${args.pr}`, args.head];
+  await ensurePrivateDir(current);
+  for (const part of generated) {
+    current = join(current, part);
+    await ensurePrivateDir(current);
+  }
+  const existing = await lstat(archiveDir).catch((err) => {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (existing) {
+    if (existing.isSymbolicLink() || !existing.isDirectory()) fail(`unsafe existing archive: ${archiveDir}`);
+    const receipt = await verifyArchive(archiveDir, identity, collected);
+    console.log(JSON.stringify({ status: 'verified', ...receipt }));
+    return;
+  }
+
+  const tempDir = `${archiveDir}.tmp-${process.pid}`;
+  if (await lstat(tempDir).catch((err) => err?.code === 'ENOENT' ? null : Promise.reject(err))) {
+    fail(`temporary archive already exists: ${tempDir}`);
+  }
+  await mkdir(join(tempDir, 'files'), { recursive: true, mode: 0o700 });
+  await chmod(tempDir, 0o700);
+  await chmod(join(tempDir, 'files'), 0o700);
+  try {
+    for (const [rel, entry] of Object.entries(collected)) {
+      const dest = join(tempDir, 'files', rel);
+      const parent = dirname(dest);
+      await mkdir(parent, { recursive: true, mode: 0o700 });
+      let cursor = join(tempDir, 'files');
+      const parentRel = relative(cursor, parent);
+      for (const part of parentRel === '' ? [] : parentRel.split('/')) {
+        cursor = join(cursor, part);
+        await chmod(cursor, 0o700);
+      }
+      await writeFile(dest, entry.bytes, { flag: 'wx', mode: 0o600 });
+      await chmod(dest, 0o600);
+    }
+    const manifestPath = join(tempDir, 'manifest.json');
+    await writeFile(manifestPath, manifestBytes(identity, collected), { flag: 'wx', mode: 0o600 });
+    await chmod(manifestPath, 0o600);
+    await rename(tempDir, archiveDir);
+  } catch (err) {
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {});
+    throw err;
+  }
+
+  const receipt = await verifyArchive(archiveDir, identity, collected);
+  console.log(JSON.stringify({ status: 'archived', ...receipt }));
+}
+
+try {
+  await main();
+} catch (err) {
+  console.error(`archive-evidence: ${err.message}`);
+  process.exitCode = 1;
+}

package/src/installer.js

@@ -430,6 +430,21 @@ export async function checkInstructionBinding({ skillsDir, instructionsPath } =
   return { status: 'owned', path: instructionsFile };
 }
 
+export async function readLegacySkillsManifest(skillsDir) {
+  const root = resolve(skillsDir);
+  const rootStat = await lstat(root).catch((err) => {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (rootStat?.isSymbolicLink()) {
+    throw new Error(`legacy Codex skills root is a symlink at ${root}; refusing`);
+  }
+  if (rootStat && !rootStat.isDirectory()) {
+    throw new Error(`legacy Codex skills root is not a directory at ${root}; refusing`);
+  }
+  return readManifest(root);
+}
+
 async function assertFileSnapshot(dest, expected) {
   let current = null;
   try {
@@ -447,6 +462,7 @@ export async function installBundle({
   skillsDir,
   preset,
   instructionsPath = null,
+  inheritedInstructions = null,
   force = false,
   yes = false,
   claude = null,
@@ -492,7 +508,10 @@ export async function installBundle({
     ? 'legacy Paseo profile provenance retained inert; see legacy cleanup guidance in docs/installation.md'
     : null;
 
-  const boundInstructions = prevManifest.instructions ?? { path: null, hash: null };
+  const ownInstructions = prevManifest.instructions ?? { path: null, hash: null };
+  const usesInheritedInstructions = ownInstructions.path === null &&
+    inheritedInstructions?.path === instructionsFile;
+  const boundInstructions = usesInheritedInstructions ? inheritedInstructions : ownInstructions;
   let existingInstructionsRaw = null;
   let instructionPlan = null;
   let legacyInstructionNote = null;
@@ -685,6 +704,20 @@ export async function installBundle({
     }
     return {
       ...summary,
+      ownershipComplete: desired.every(({ rel, content }) =>
+        installedHashes[rel] === hashContent(content)),
+      // Retirement may retry after a prior canonical install succeeded. The
+      // accepted plan proves either fresh inheritance or existing canonical
+      // ownership of the same legacy-bound path; forced edits prove neither.
+      acceptedInstructionTransfer: inheritedInstructions?.path === instructionsFile &&
+        boundInstructions.path === instructionsFile &&
+        instructionPlan?.action !== 'conflict' && !instructionPlan?.forced
+        ? {
+            path: instructionsFile,
+            legacyHash: inheritedInstructions.hash,
+            canonicalHash: nextInstructions.hash,
+          }
+        : null,
       preset: selectedPreset,
       roles: roleReadiness,
       claudeSettings: claudePlan.report,
@@ -969,6 +1002,144 @@ export async function uninstallBundle({
   }
 }
 
+// Retire the obsolete Codex-root copy only after a canonical Axstack install
+// is present and byte-for-byte verified. This deliberately handles skill
+// payloads only: instruction files, Claude settings, and historical profile
+// ownership may belong to another harness and remain bound to the old manifest.
+export async function retireLegacySkills({
+  canonicalSkillsDir,
+  legacySkillsDir,
+  acceptedInstructionTransfer = null,
+  yes = false,
+} = {}) {
+  if (!canonicalSkillsDir || !legacySkillsDir) {
+    throw new Error('legacy retirement requires canonical and legacy skills directories');
+  }
+  const canonicalRoot = await canonicalTargetDir(resolve(canonicalSkillsDir));
+  await readLegacySkillsManifest(legacySkillsDir);
+  const legacyRoot = await canonicalTargetDir(resolve(legacySkillsDir));
+  if (canonicalRoot === legacyRoot) return { removed: [], preserved: [], missing: [], skipped: true };
+  assertOutsideHome(legacyRoot, { yes, kind: 'legacy Codex skills directory' });
+
+  const canonicalManifest = await readManifest(canonicalRoot);
+  if (!canonicalManifest || Object.keys(canonicalManifest.files).length === 0) {
+    throw new Error('legacy Codex skills not retired: canonical install has no ownership manifest');
+  }
+  for (const [rel, expectedHash] of Object.entries(canonicalManifest.files)) {
+    const { current } = await readOwnedTarget(canonicalRoot, rel);
+    if (current === null || hashContent(current) !== expectedHash) {
+      throw new Error(`legacy Codex skills not retired: canonical verification failed for ${rel}`);
+    }
+  }
+
+  const legacyManifest = await readManifest(legacyRoot);
+  if (!legacyManifest || Object.keys(legacyManifest.files).length === 0) {
+    return { removed: [], preserved: [], missing: [], skipped: true };
+  }
+
+  // Validate every owned destination before deleting the first one. In
+  // particular, one symlink refuses the entire retirement rather than being
+  // followed or leaving a partly retired legacy install.
+  const protectedGroups = new Set();
+  for (const [rel, ownedHash] of Object.entries(legacyManifest.files)) {
+    const target = await readOwnedTarget(legacyRoot, rel);
+    if (target.current !== null && hashContent(target.current) !== ownedHash) {
+      protectedGroups.add(rel.split('/')[0]);
+    }
+  }
+
+  const summary = { removed: [], preserved: [], missing: [], skipped: false };
+  const remainingFiles = { ...legacyManifest.files };
+  let remainingInstructions = legacyManifest.instructions;
+  if (legacyManifest.instructions?.path !== null) {
+    const canonicalInstructions = canonicalManifest.instructions;
+    const transferAccepted =
+      acceptedInstructionTransfer?.path === legacyManifest.instructions.path &&
+      acceptedInstructionTransfer?.legacyHash === legacyManifest.instructions.hash &&
+      acceptedInstructionTransfer?.canonicalHash === canonicalInstructions?.hash &&
+      canonicalInstructions?.path === legacyManifest.instructions.path;
+    if (!transferAccepted) {
+      return {
+        ...summary,
+        held: true,
+        failure: true,
+        reason: 'legacy instruction ownership is bound to a different instruction file or was not accepted by the canonical install',
+      };
+    }
+    const instructionsRaw = await readFile(await canonicalInstructionFile(canonicalInstructions.path), 'utf8');
+    const installedBlock = locateInstructionBlock(instructionsRaw);
+    if (
+      installedBlock === null || hashContent(installedBlock.block) !== canonicalInstructions.hash
+    ) {
+      throw new Error('legacy instruction ownership not transferred: canonical binding is not verified');
+    }
+    remainingInstructions = { path: null, hash: null };
+  }
+  const manifestFile = join(legacyRoot, '.axstack-manifest.json');
+  const manifestBefore = await readFile(manifestFile);
+  const manifestMode = (await stat(manifestFile)).mode & 0o777;
+  const deletedFiles = [];
+  try {
+    for (const [rel, ownedHash] of Object.entries(legacyManifest.files)) {
+      if (protectedGroups.has(rel.split('/')[0])) {
+        summary.preserved.push(rel);
+        continue;
+      }
+      const { dest, current, mode } = await readOwnedTarget(legacyRoot, rel);
+      if (current === null) {
+        summary.missing.push(rel);
+        delete remainingFiles[rel];
+      } else if (hashContent(current) === ownedHash) {
+        deletedFiles.push({ dest, bytes: current, mode });
+        await rm(dest);
+        await pruneEmptyParents(dest, legacyRoot);
+        delete remainingFiles[rel];
+        summary.removed.push(rel);
+      } else {
+        summary.preserved.push(rel);
+      }
+    }
+
+    const hasProfiles = Object.keys(legacyManifest.profiles?.entries ?? {}).length > 0;
+    const hasOtherOwnership = hasProfiles || legacyManifest.claudeSettings?.path !== null ||
+      remainingInstructions.path !== null;
+    if (Object.keys(remainingFiles).length === 0 && !hasOtherOwnership) {
+      await rm(manifestFile);
+    } else {
+      await writeManifest(legacyRoot, {
+        ...legacyManifest,
+        files: remainingFiles,
+        instructions: remainingInstructions,
+      });
+    }
+    return summary;
+  } catch (err) {
+    const rollbackErrors = [];
+    for (const { dest, bytes, mode } of deletedFiles.reverse()) {
+      try {
+        await writeAtomic(dest, bytes, mode === null ? {} : { mode });
+      } catch (restoreErr) {
+        rollbackErrors.push(`${dest}: ${restoreErr?.message ?? restoreErr}`);
+      }
+    }
+    try {
+      const currentManifest = await readFile(manifestFile).catch((readErr) => {
+        if (readErr?.code === 'ENOENT') return null;
+        throw readErr;
+      });
+      if (currentManifest?.equals(manifestBefore) !== true) {
+        await writeAtomic(manifestFile, manifestBefore, { mode: manifestMode });
+      }
+    } catch (restoreErr) {
+      rollbackErrors.push(`${manifestFile}: ${restoreErr?.message ?? restoreErr}`);
+    }
+    if (rollbackErrors.length > 0) {
+      err.message += ` (incomplete rollback; manual repair needed: ${rollbackErrors.join('; ')})`;
+    }
+    throw err;
+  }
+}
+
 async function pruneEmptyParents(file, stopDir) {
   let dir = dirname(file);
   while (dir !== stopDir && withinRoot(dir, stopDir)) {

package/src/locations.js

@@ -17,11 +17,11 @@ export function harnessLocations() {
     },
     {
       harness: 'codex',
-      skillsDir: '$CODEX_HOME/skills (default ~/.codex/skills)',
+      skillsDir: '~/.agents/skills',
       discovery: 'docs',
-      source: 'https://developers.openai.com/codex/skills',
+      source: 'https://learn.chatgpt.com/docs/build-skills',
       notes:
-        'User skills live under $CODEX_HOME/skills per OpenAI docs (CODEX_HOME defaults to ~/.codex). The CLI honors $CODEX_HOME when set. Pass --skills-dir to override.',
+        'Codex user skills use the shared ~/.agents/skills root. CODEX_HOME still selects AGENTS.md. Pass --skills-dir to override skill placement and skip automatic legacy migration.',
     },
     {
       harness: 'opencode',