Add marker-gated skill targets (gatedTools) and the Meta Muse format

[TeoSlayer]

What

Adds Meta Muse as a skill-injection target through a new optional manifest key, gatedTools, without changing what released daemons do.

• gatedTools rows are active only while their requireMarker file exists inside ~/.pilot and names the row's target (see "The marker names the target" below). The Muse installer writes ~/.pilot/targets/muse. Without a matching marker, nothing under rootDir is read, written or removed, by a tick or by Uninstall.
• Rotating proxy credentials. With no Config.HTTPClient (how the daemon registers skillinject), fetches now re-read the proxy credentials with the daemon's refresh command, so ticks keep working after the Muse proxy rotates them (see "Egress proxies that rotate their credentials" below).
• skillFormat: "muse" rewrites the entrypoint SKILL.md frontmatter to name: "<entrypoint with - replaced by _>" and a one-line quoted description. The body is unchanged.
• The Muse row that pilot-skills will ship:

  "gatedTools": [{ "name": "muse", "rootDir": "~/workspace/skills", "skillsDir": "~/workspace/skills",
                   "requireMarker": "~/.pilot/targets/muse", "skillFormat": "muse" }]

Why a new key and not a tools row

Every release reads the manifest with plain json.Unmarshal into a struct that has no gatedTools field, so the key is dropped. That covers v0.2.2, v0.2.3, v0.2.4, v0.2.5-beta.1, and the 902f745 build that pilot v1.13.2 through v1.13.10-rc.1 ship.

As a tools row, the same entry would be installed by every one of those releases on any host that has ~/workspace/skills:

• the unconverted SKILL.md is written into ~/workspace/skills/pilotctl/, with no marker check;
• disable all then deletes that file.

The pilot-skills PR proves both: it runs the released modules against the new manifest, plus a negative control with muse moved into tools.

A correction to the brief: validateManifestPaths / defaultWriteRoots (which rejects a whole manifest if any tools path is outside the allowlisted roots) exists only on the unmerged wip/preserve-2026-08-02 branch (a72ae88), not in any release. TestGatedManifest_ValidUnderReleasedRules checks two things:

• the manifest passes the parse and checks every release actually runs;
• every tools path still passes that pending allowlist, so landing the hardening later will not reject this manifest. The muse rootDir is outside it, which is one more reason the row must stay out of tools.

The marker names the target

A marker that only exists proves that some installer ran. muse/install.sh (pilot-skills#34) can install into any folder (MUSE_SKILLS_DIR) or keep the canonical frontmatter (PILOT_MUSE_FRONTMATTER=0), and at #34's 71789ad it touches the marker in every case. Review found two results: the daemon created ~/workspace/skills/pilotctl/SKILL.md in an unrelated ~/workspace/skills after an install into ~/.agentx/skills, and after a PILOT_MUSE_FRONTMATTER=0 install the daemon and the installer rewrote each other's copy on every run.

The marker now has to say what it is for, one key=value per line:

skills_dir=/root/workspace/skills
skill_format=muse

• The row is active only when skills_dir is its skillsDir, compared after resolving symlinks (~/ is accepted), and skill_format is its skillFormat (canonical for a row that copies SKILL.md unchanged).
• These turn nothing on: an empty marker (a bare touch), a marker for another folder or format, a symlink or directory, a file over 4 KiB, a line without =, or a key set twice. Tick, Plan and Uninstall then leave the directory alone. Blank lines, # comments and unknown keys are ignored.
• The row itself is still validated first, so a broken row is an error row on every marked host, whatever the marker says.

#34 writes this marker since a366fe8 (with the folder it actually installed to, so an install elsewhere names that folder and this row stays off). The block tested earlier with the real 71789ad installer:

  if [ "$(cd "$dest" && pwd -P)" = "$(cd "$HOME/workspace/skills" 2> /dev/null && pwd -P)" ]; then
    mkdir -p "$pilot_dir/targets"
    printf '# written by pilot-skills muse/install.sh\nskills_dir=%s\nskill_format=%s\n' \
      "$HOME/workspace/skills" "$([ "$frontmatter" = "0" ] && echo canonical || echo muse)" \
      > "$pilot_dir/targets/muse"
    echo "marked this host as a Muse target ($pilot_dir/targets/muse)"
  fi

Egress proxies that rotate their credentials

The daemon registers skillinject with skillinject.Config{}. Fetches therefore went through http.DefaultTransport with the proxy credentials from the daemon's launch environment. The Muse proxy rotates them every few minutes, so every tick after the first rotation failed with 407 Proxy Authentication Required, and SKILL.md updates only reached Muse when the installer was rerun.

• When Config.HTTPClient is nil, the client is a netproxy.RefreshingTransport (common v0.5.15). Its refresh command is the new Config.ProxyCommand, else $PILOT_PROXY_CMD, else "proxy_cmd" in ~/.pilot/config.json. These are the settings pilot-daemon reads. On Muse-like hosts every Pilot entry point now supplies one the zero Config sees: the official installer (release#49 c36ad9b) saves proxy_cmd, pilotctl daemon start (pilotprotocol#470) and pilot-sandbox's pilot-up.sh (pilot-skills#34 a366fe8, which used to pass only the -proxy-cmd flag) hand the daemon $PILOT_PROXY_CMD, and pilot-mcp#23 does the same. The command is bash -c 'case $https_proxy in *@*) printf %s "$https_proxy";; *) printf %s "${HTTPS_PROXY:-$https_proxy}";; esac'.
• The command runs at the start of each tick, once a minute while it runs, and on a 407, and the refused request is retried once. Its output is never logged or put in an error.
• PILOT_PROXY or config.json "proxy" set to off, none, no, false or direct turns it off.
• With no command the client is the plain one it always was. A 407 reported as a *netproxy.ConnectError is retried once; that is what pilot-daemon's http.DefaultTransport returns (pilotprotocol#470) after refreshing its own credentials. A garbled rejection (malformed HTTP status code, Meta Muse's form) never reaches that transport's CONNECT hook, so nothing refreshed on it: it is now retried once after 2s, which succeeds when the transport's resolver re-read the credentials in the background meanwhile (netproxy starts that from the failing lookup once its 60s interval has passed). This fallback only matters for a daemon started by hand with the -proxy-cmd flag alone; every Pilot entry point hands the command over where skillinject sees it.
• The base transport is a copy of DefaultTransport without its CONNECT hook, so the daemon's hook cannot hide the 407 from the retry.

Safety rules for gated tools (gated.go)

• requireMarker must be inside ~/.pilot, rootDir inside home (and not home itself), and skillsDir inside rootDir. The entrypoint must be a plain name. A row that breaks any of these is an error row, and the other tools are unaffected.
• Every file operation goes through an os.Root opened on rootDir, so a symlink cannot take a read, write or removal outside it. A symlink at the skill file, or at any directory between rootDir and it, is refused, even one that points inside rootDir.
• Writes go to an O_EXCL temp file with a random name and are then renamed. A link planted at the old predictable SKILL.md.tmp name is never followed. This matters because the Muse daemon runs as root and ~/workspace/skills is writable by the agent.
• A gated row that resolves to a regular tool's skill copy is refused, so the two never rewrite each other on every tick.
• Only the skill copy is installed. There is no heartbeat and no plugin.
• Uninstall deletes the file, and the <entrypoint>/ dir when that leaves it empty, only while a matching marker exists. It works offline from the cached manifest, which now keeps gatedTools.

Byte parity with the Muse installer

museSkillMD is a port of muse_frontmatter in pilot-skills muse/install.sh (#34). It has to produce identical bytes; otherwise the daemon rewrites the installer's copy once and the installer puts its own back on every rerun.

• TestMuseSkillMD_MatchesInstaller sources the installer's function (vendored in testdata/muse_frontmatter.sh) and compares both on 24 edge cases: folded, literal, quoted and plain scalars, comments, CRLF, control characters, the 1024-byte cap, UTF-8, and missing or unclosed frontmatter.
• With PILOT_SKILLS_CORPUS=<pilot-skills checkout> it also compares every skills/*/SKILL.md. All 157 match locally (macOS bash 3.2 + BSD awk). CI runs the edge cases on ubuntu (bash 5).

Evidence

• go test -race ./... passes. Coverage is 92.0% total; skillformat.go is at 100% and the gated reconcile at 97%. proxyCommand and the fetcher's get/do/close are at 100%.

• Marker tests: 14 rejected marker shapes, 8 accepted spellings (including paths through symlinks), the canonical/muse/canonical opt-out sequence, and a broken row under a foreign marker. The new marker tests fail on 4a56849.

• Proxy tests use a Muse-like CONNECT-only proxy with Basic auth and rotating passwords. They cover: ticks across rotations with local-edit repair; a rotation mid-tick (407, then a retry with the new credentials); the command taken from $PILOT_PROXY_CMD and from config.json; a failing command falling back to the environment, with no secret in any error; exactly one retry for a host transport's 407; and the precedence rules.

• Rotation E2E. The reviewer's scenario runs against real raw.githubusercontent.com (pilot-skills d957c6d) through a local proxy that rotates the password every 6s: skillinject.Run with Config{} and a 10s interval, and config.json proxy_cmd set to the Muse command. A fresh bash sees the current credentials through BASH_ENV.

  • 4a56849: tick 1 creates, then DENY 407 and skillinject tick failed ... Proxy Authentication Required at every later tick.
  • This head: ALLOW gen=1, gen=2, gen=4, gen=5, and every tick succeeds. The t=8s local edit is repaired (rewrites=1), and the final file has name: "pilotctl".

• Installer E2E with the real deps: bump common to v0.5.10 (auto-cascade v0.2.4-beta.2) #34 installer (71789ad, skills from a d957c6d archive) and this build's Tick/Plan/Uninstall:

  • MUSE_SKILLS_DIR=~/.agentx/skills: muse skipped; ~/workspace still holds only their-skill.
  • PILOT_MUSE_FRONTMATTER=0: muse skipped; sha a17e8c766257 unchanged across ticks.
  • With the declaring block above:
    • default install: plan/tick identical/noop (sha 379de679fca5), and a local edit is drifted/rewrite back to it;
    • FRONTMATTER=0 gives skill_format=canonical and muse is skipped;
    • a default rerun gives noop, and a FRONTMATTER=0 rerun gives skipped again, with no flip-flop;
    • MUSE_SKILLS_DIR elsewhere writes no marker.

• Earlier local E2E, at 4a56849, where an empty marker was enough. I ran the real installer's skill step (PILOT_SKILLS_ONLY=1, HOME pointed at a temp dir, skills from main), then that build against the new pilot-skills manifest:

  • plan and three ticks all reported muse identical/noop (sha 379de679fca5 unchanged);
  • Uninstall reported deleted and removed the empty pilotctl/ dir;
  • a re-tick reported create with the same bytes;
  • with the marker removed, muse was skipped and nothing was written.

  The installer E2E above repeats the noop result with the declaring marker.

Round 3 (908afcc)

• si42-muse-rotation-fix-inert-without-release49 (medium): resolved in the deploy chain, not in code here. Nothing set PILOT_PROXY_CMD/proxy_cmd on a host set up by the live installer plus pilot-up. Now release#49 saves proxy_cmd, pilotctl#470 and pilot-mcp#23 hand $PILOT_PROXY_CMD to the daemon, and pilot-skills#34 a366fe8 hands it $PILOT_PROXY_CMD too (instead of the flag only). A daemon with this skillinject can only ship after #470 (it is bumped in pilotprotocol after this tags), so every node that gets it also gets one of those entry points. The deploy order below lists release#49 and #470 first.
• si42-proxycmd-flag-only-unparseable-rejection-no-retry (low): garbled rejections on a transport skillinject does not own are retried once after unreadableReplyRetryDelay (2s). TestFetch_RetriesUnreadableProxyReplyOnce: with a background refresh the tick succeeds after one rejection; with none it fails after exactly two (no loop). It fails with the retry disabled. The rotating test proxy can garble its rejections.
• go test -race ./... ok; go vet clean. (Two files not touched here, service.go and zz_skillinject_test.go, are not gofmt-clean on the branch base either.)

E2E, round 3 Muse sim (rotating-credential CONNECT-443-only proxy, root, no systemd): a harness calling skillinject.Tick at this head (908afcc) with the daemon's zero Config except ManifestURL (pilot-skills#35's inject-manifest.json served on loopback), on a node set up by the pilot-skills#34 one-shot (a366fe8): the marker #34 now writes (skills_dir=/root/workspace/skills, skill_format=muse, plus a # comment line) activates the row — muse … state=drifted action=rewrite, then after rm state=absent action=create, with name: "pilotctl" and a one-line description. (The drifted is catalog skew between the two unmerged branches' copies of skills/pilotctl/SKILL.md.)

Also

• canonicalPath now resolves a not-yet-existing path through its nearest existing ancestor (before, it only tried the parent). The gated/regular collision check works on the first tick, and the shared-heartbeat dedup benefits too.
• The CHANGELOG [Unreleased] section that shipped as v0.2.4 is relabelled [v0.2.4] - 2026-09-23, and the new entries go in a fresh [Unreleased].

Deploy order (all six PRs)

1. installer: transport auto/compat, HTTPS-proxy sandboxes, root without systemd release#49 merge → notify-install-sh-sync dispatches to pilot-protocol/website → sync-install-sh.yml puts install.sh into R2 pilot-release-assets/install.sh (the pilot-release Worker reads R2 per request; no Worker deploy). Check: curl -fsSL https://pilotprotocol.network/install.sh | shasum -a 256 → 4384f0cb2890177cb87a2e2bc49e1b814d2850434d24c54d1730c9955fbbb671 (up to 5 min cache).
2. install.sh: sync the Pages fallback with pilot-protocol/release#49 website#263 merge (Pages fallback public/install.sh, same bytes) → the sync workflow's drift step goes green.
3. feat: native HTTPS-proxy support and -transport=auto (Meta Muse / proxy-only sandboxes) pilotprotocol#470: re-run install.sh matches pilot-protocol/release, merge.
4. Tag pilotprotocol v1.13.11 on main (release workflow: binaries, checksums.txt, signed latest.json). v1.13.10 shipped without #470, so until this tag every install gets a daemon without -proxy. Check pilot-daemon -h lists -proxy and -proxy-cmd.
5. feat(muse): one-shot Pilot-in-Muse installer and pilot-up.sh TeoSlayer/pilot-skills#34 merge → CI regenerates skills.json/setups.json and skills/pilotctl/SKILL.md, dispatches the website deploy; the Muse one-shot (raw.githubusercontent.com/TeoSlayer/pilot-skills/main/muse/install.sh) is live at merge.
6. feat(setup): install and start Pilot behind an HTTPS egress proxy (Meta Muse) pilot-mcp#23 merge → release 0.3.0 (behaviour change; last published 0.2.13): bump package.json, package-lock.json, server.json (both fields), .well-known/mcp/server-card.json, src/version.js, src/openclaw-plugin/openclaw.plugin.json, src/openclaw-plugin/evaluate.js and the pinned pilotprotocol-mcp@0.2.13 strings in test/{hermes-setup,openclaw-plugin,native-harness-setup,harness-config-contracts}.test.js (test/release-contract.test.js locks them), move [Unreleased] to [0.3.0], push tag v0.3.0 → publish.yml (tag must equal v+version; lint + tests; npm via OIDC, MCP Registry server.json, ghcr.io/pilot-protocol/pilot-mcp).
7. Add marker-gated skill targets (gatedTools) and the Meta Muse format #42 merge → tag v0.2.5 → pilotprotocol follow-up PR go get github.com/pilot-protocol/skillinject@v0.2.5 && go mod tidy (GOWORK=off) → next daemon release (v1.13.12; or fold the bump in before tagging v1.13.11).
8. inject-manifest: gate Meta Muse under a new gatedTools key TeoSlayer/pilot-skills#35 merge (manifest gatedTools muse row). Released daemons drop the key (CI released-skillinject v0.2.2–v0.2.4). No manifest signing step: DefaultManifestPublicKeyHex is empty; only hosts that installed ~/.pilot/skillinject.pub verify inject-manifest.json.sig.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!