From c4ab175edad329e765343d3cfcc293b1379c9c6c Mon Sep 17 00:00:00 2001 From: UnbreakableMJ Date: Mon, 24 Aug 2026 13:02:38 +0300 Subject: [PATCH] fix(orca-skills): return orca-cli to revision 37 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Orca's update dialog listed all three vendored skills as `Skipped — the copy here doesn't match the official version — it may be modified, or a different skill with the same name`. Two of the three were not modified and did not differ. Hashing each vendored `SKILL.md` against the installed app's own `resources/skills/snapshot-registry.json` — which carries every historical revision, not just the current one — identifies exactly what each copy holds: computer-use revision 8 == latest 8 orchestration revision 28 == latest 28 orca-cli revision 36 < latest 37 So nothing was hand-edited. `computer-use` and `orchestration` were already byte-identical to the manifest, and `orca-cli` was one release behind — the deliberate pin from a46c108. That pin has expired. It was taken on 2026-08-19 because revision 37 advertised `share skills` while the installed binary's `orca skills` offered only `list`, `get`, `install` and `update`, so the skill described a command that did not exist. The app has since been rebuilt (AppImage dated 2026-08-22): its manifest now lists `orca-cli` at revision 37, and `orca skills` has grown the `share` subcommand. Both halves of the 2026-08-19 reasoning have reversed, and staying at 36 is now the position that produces the warning and the inaccuracy. Revision 37 differs from 36 by exactly two lines — `skill sharing` and `share skills` added to the description — and the rendered description is 813 characters, inside the §5.6 cap. Vendored verbatim and hash-verified against the manifest's `exactSha256` (`cdd5d9c8…`, 3944 bytes), so the tree stays a verbatim vendoring rather than an adaptation (§4.2). Also corrects a claim in CREDITS.md that this update disproved. It said a hash match "means Orca will leave the tree alone"; it does not. `computer-use` and `orchestration` matched exactly and were skipped anyway. The cause is the install location, not the bytes: `orca skills installed` attributes all three to Codex home — `~/.agents/skills`, a symlink into `/nix/store`, a read-only filesystem Orca never wrote to and cannot write to. Orca skips what it does not own and reports it with the only message it has. The dialog's advice to remove the copy is not actionable and must not be followed — nothing can be removed from a store path, and a Home-Manager switch would restore it. This tree will therefore report `Skipped` on every Orca update, permanently, by design — the accepted cost of the vendoring rationale in `flake.nix` (Orca resolves skills by exact leaf name, so they must sit wherever agents read skills from). CREDITS.md now says so, and points at the hash check as the thing to run instead of trusting the dialog. Verified: `nix build .#skills` produces a tree whose `computer-use`, `orca-cli` and `orchestration` all match the installed app's manifest. reuse lint, check-license-files and generate-steelbore-scm --check pass; validate-configs passes with pyyaml present. check-skill-refs fails identically with and without this change (seven pre-existing findings, all in `chat/*.texi`). Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_017hj64PwFDDJsNdAJoEuYpB --- orca-skills/CREDITS.md | 46 ++++++++++++++++++++++++++++++----- orca-skills/orca-cli/SKILL.md | 4 +-- 2 files changed, 42 insertions(+), 8 deletions(-) diff --git a/orca-skills/CREDITS.md b/orca-skills/CREDITS.md index 3b626df..e82b160 100644 --- a/orca-skills/CREDITS.md +++ b/orca-skills/CREDITS.md @@ -17,10 +17,13 @@ machine-readable `MIT` metadata declared for `orca-skills/**` in the repo-root | Source URL | | | Scope | The three skills below, vendored verbatim — each `SKILL.md` byte-for-byte identical to upstream, including Orca's own frontmatter. No content was edited, relicensed, or adapted. | -**Upstream provenance:** `computer-use` and `orchestration` from commit -`fe95698b95e7687857d2421549366b8771c71e36` (2026-08-18); `orca-cli` pinned one -revision behind that (see "Which revision to vendor" below). Vendored -2026-08-18, `orca-cli` re-pinned 2026-08-19. +**Upstream provenance:** `computer-use` (release revision 8) and +`orchestration` (revision 28) from commit +`fe95698b95e7687857d2421549366b8771c71e36` (2026-08-18); `orca-cli` at revision +37. Vendored 2026-08-18; `orca-cli` pinned back to revision 36 on 2026-08-19 +and returned to revision 37 on 2026-08-24, when the installed Orca caught up +(see "Which revision to vendor" below). All three now match the installed +app's manifest exactly. ## Vendored skills (3) @@ -59,6 +62,15 @@ advertised `share skills` and `skill sharing`, while the installed Orca's skill described a command the binary did not have. Pinning to revision 36 (3913 bytes) fixed both the warning and the inaccuracy. +The pin is a **hold, not a destination** — it is released the moment the app +catches up. On 2026-08-24 the installed Orca had been rebuilt (AppImage dated +2026-08-22), its manifest listed `orca-cli` at revision 37, and `orca skills` +had grown the `share` subcommand the skill describes. The two lines that +revision 37 adds — `skill sharing` and `share skills` in the description — are +now accurate against the binary, so the tree returned to 37. Both halves of the +2026-08-19 reasoning had reversed: the warning and the inaccuracy would come +from *staying* at 36. + To re-vendor after updating the Orca app, read the manifest for the revision it now expects and verify each file against its `exactSha256`: @@ -68,8 +80,30 @@ jq '.skills[] | select(.name=="orca-cli") | {releaseRevision, files}' "$D/curren sha256sum orca-skills/orca-cli/SKILL.md ``` -A mismatch here is the signal to re-vendor; a match means Orca will leave the -tree alone. +`snapshot-registry.json`, beside that manifest, lists every historical revision +with the same per-file hashes. Hashing a vendored file against it identifies the +exact revision the copy holds, which separates "one release behind" from "someone +edited it" — a distinction the Orca dialog does not draw. + +A mismatch here is the signal to re-vendor. **A match is not a promise of +silence**, and the 2026-08-24 update proved it: `computer-use` and +`orchestration` were byte-identical to the app's own manifest and Orca still +listed all three as `Skipped — the copy here doesn't match the official +version`. That wording is generic, and for those two it was simply untrue. + +The reason is the install location, not the bytes. `orca skills installed` +attributes all three to **Codex home** — `~/.agents/skills`, a symlink into +`/nix/store`, which is a read-only filesystem Orca never wrote to and cannot +write to. Orca skips what it does not own, and reports that with the only +message it has. The dialog's advice — "Remove it if you want Orca to update this +skill" — is not actionable here and must not be followed: nothing can be removed +from a store path, and a Home-Manager switch would restore it regardless. + +So this tree will report `Skipped` **on every Orca update, permanently, by +design**. That is the accepted cost of vendoring (see the `flake.nix` rationale: +Orca resolves skills by exact leaf name, so they must sit wherever agents read +skills from). Treat the dialog as a prompt to run the hash check above, not as +evidence of damage. ## Leaf-name note diff --git a/orca-skills/orca-cli/SKILL.md b/orca-skills/orca-cli/SKILL.md index 39ecf6d..b2a3b83 100644 --- a/orca-skills/orca-cli/SKILL.md +++ b/orca-skills/orca-cli/SKILL.md @@ -2,12 +2,12 @@ name: orca-cli description: >- Use the public `orca` CLI to operate Orca-managed worktrees, folder contexts, - terminals, repos, automations, artifacts, worktree comments, and the browser + terminals, repos, automations, artifacts, skill sharing, worktree comments, and the browser embedded inside the Orca app. Use when the user says "$orca-cli", "use orca cli", "Orca worktree", "child worktree", "cardStatus", "spawn codex/claude in a worktree", "read/wait/send Orca terminal", "terminal send", "full handoff", "handover", "give this to another agent", "another worktree", "Orca browser", "orca artifacts", - "share HTML/Markdown", "public artifact link", or "control the browser inside + "share HTML/Markdown", "public artifact link", "share skills", or "control the browser inside Orca". Prefer this over raw `git worktree`, ad hoc PTYs, Playwright, or Computer Use when the task touches Orca-managed state. Use Computer Use for browser windows, webviews, or desktop UI outside Orca's