@hasna/skills 0.10.48 → 0.10.50

package/README.md

@@ -559,7 +559,8 @@ The plan proves the preserved original matches every witness being replaced,
 permits only the documented non-discovery differences, and labels the replacement
 witness (the JSON receipt lists them under `replacedWitnesses`). `--apply`
 preserves and reads back the original policy before writing, and never writes the
-native configuration. Claude upgrades to `claude-settings-v3`; Codex uses
+native configuration. Claude upgrades to `claude-settings-v3`, or to
+`claude-settings-v4` with `--claude-witness-version 4`; Codex uses
 `codex-settings-v2`, which also replaces the narrower automatic
 `plugins`/`marketplaces`/`skills` projection of the same file once the preserved
 original is proved to explain it. That projection is order-sensitive, so it keeps
@@ -1270,6 +1271,55 @@ reinstall or change your PATH.
 copyfile runtime, preserves configuration and launcher preimages, and keeps the
 previous runtime available for receipt-bound rollback.
 
+Every launcher the updater switches (`skills`, `skills-mcp`, `skills-serve`,
+`skills-server`, `skills-worker`, `skills-maintenance` and `skills-migrate`, in each
+PATH directory it manages, and every alias `--adopt-aliases` switches) is written as a
+pinned launcher, not a bare symlink. It is a `#!/bin/sh -p` file: the shell ignores
+exported functions and `SHELLOPTS`-style settings from your environment, and the
+updater refuses with `LAUNCHER_SHELL_UNSUPPORTED` before writing anything when
+`/bin/sh` does not accept `-p` (for example dash older than 0.5.11). The launcher
+execs the exact Bun binary that ran the update with
+`--config=/dev/null --no-env-file --no-macros --no-install --cwd=<runtime version root>`
+on the exact entry, through `env -i` with an explicit environment allowlist:
+`HOME`, `PATH`, `TMPDIR`, `USER`, `LOGNAME`, `SHELL`, `TZ`, `LANG`, terminal names
+(`TERM`, `TERM_PROGRAM`, `TERM_PROGRAM_VERSION`, `COLORTERM`, `COLUMNS`, `LINES`),
+`NO_COLOR`, `FORCE_COLOR`, `CI`, `EDITOR`, `VISUAL`, `PAGER`, `SSH_AUTH_SOCK`,
+`DATABASE_URL`, the server settings `HOST`, `PORT`, `NODE_ENV`, `AGENT_ID` and
+`ECS_CONTAINER_METADATA_URI_V4`, the agent names `TERMINAL_CWD`, `CODEX_HOME`,
+`HERMES_HOME` and `HERMES_ENABLE_PROJECT_PLUGINS`, and every name starting with
+`HASNA_`, `SKILLS_`, `SKILL_`, `MCP_`, `XDG_`, `LC_` or `AWS_`. Your `LC_ALL` passes
+through unchanged. Everything else never reaches the runtime, including `BUN_*`,
+`NODE_OPTIONS`, `DYLD_*`, `LD_*`, `NODE_EXTRA_CA_CERTS` and the proxy variables
+(`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`). A `bunfig.toml`, `.env` or `tsconfig.json`
+in the directory you run a command from is never read.
+
+Each of those entries (the CLI, the MCP server, the API server, the worker,
+maintenance and migrate) returns to your directory before anything else runs, so
+relative paths keep working, including a relative `HASNA_SKILLS_DATABASE_URL`. When
+the CLI starts another copy of itself (the hook's context lookup and its
+`SessionStart` sync), the child gets the same Bun flags, the runtime version root as
+its working directory and the same environment allowlist, and also returns to your
+directory first. The receipt records the old and new launcher shape of every path,
+the backup keeps the exact previous launcher (symlink text or pinned bytes), and
+`--rollback` restores it byte for byte. Codex hook trust, the Claude settings
+projection and `skills self-update` read a managed pinned launcher as the exact
+entry it runs and bind the launcher's own bytes as well.
+
+An updater from before pinned launchers (0.10.48 and earlier) writes bare symlinks,
+including when it installs a version that has them, and an exact-version update to
+the version already installed is refused. `skills self-update --adopt-aliases` pins
+those launchers in place: in `~/.local/bin`, `~/.bun/bin`, `/opt/homebrew/bin` and
+`/usr/local/bin`, a bare symlink that already reaches the current runtime's entry is
+adopted like an alias still pointing at an older install. The same refusals apply
+(an unsafe or unwritable directory, a launcher owned by another account, a foreign
+file, an unsupported link chain), the exact symlink is kept as
+`<launcher>.skills-alias-prev-<receipt id>`, the receipt records it as the old
+`symlink` shape, and `--rollback-aliases <receipt id>` restores it exactly. A
+launcher already pinned to the current runtime is left unchanged. Undo in reverse
+order: roll back the adoption before rolling back the runtime update that wrote
+those symlinks, because that update's `--rollback` refuses with
+`LAUNCHER_DRIFT_ROLLBACK_REFUSED` while the adopted pinned launchers are in place.
+
 To require a minimum dependency age, pass a positive integer number of days and
 repeat the exclusion option for package names or package globs:
 
@@ -2534,3 +2584,18 @@ Upgrade an existing review with `skills hook rebind-settings --agent codex
 Review the plan before adding `--apply`; the original review preimage must match
 its original mode, and unrelated changes refuse. This preserves the native
 configuration, root aliases, other witnesses and active session pins.
+
+`claude-settings-v4` is an explicit successor to `claude-settings-v3`. It
+additionally ignores only a top-level `theme` whose value is exactly one of the
+documented built-in values (`auto`, `dark`, `light`, `dark-daltonized`,
+`light-daltonized`, `dark-ansi`, `light-ansi`). Custom and plugin themes, other
+values or types, nested `theme` keys, `skipDangerousModePermissionPrompt` and
+every permission, hook, environment, helper and unknown setting stay bound.
+Existing raw/V1/V2/V3 reviews retain their original meaning.
+
+Capture with `skills hook witness --kind claude-settings-v4 --path <settings.json>`.
+Upgrade an existing review with `skills hook rebind-settings --agent claude
+--claude-witness-version 4 --reviewed-preimage <preserved-settings.json>
+--expected-policy-sha256 <policy-hash> --expected-settings-sha256 <settings-hash>`.
+Review the plan before adding `--apply`. See
+[built-in theme reviews](docs/plugin-admission.md#explicit-v4-built-in-theme-reviews).