agentwheel 0.21.0 → 0.21.3

package/README.md

@@ -98,6 +98,7 @@ Fragments are Agentwheel composition inputs, not runtime file-drop targets.
 |---|---|
 | `agentwheel search <query>` | Search configured registries and the public enriched/Vercel catalogue; supports stable JSON output for agent reranking. |
 | `agentwheel add <source>` | Validate and save a package entry in `.agentwheel/config.json`; does not touch runtimes. |
+| `agentwheel pin <alias> <commit>` | Change an existing pinned alias's exact commit, preserving its configuration; does not resolve sources or touch runtimes. |
 | `agentwheel plan [name-or-source]` | Preview what `install` would reconcile without writing; supports `--profile <name>` and `--json`. |
 | `agentwheel install` | Reconcile configured packages into the current target or selected fleet. Uses the graph lock as input by default. |
 | `agentwheel install <name-or-source>` | Ensure semantics: configured name/source scopes the install; a new source is added and installed. |
@@ -496,15 +497,27 @@ the same path with the same artifact identity move; the rest stay in the source
 listed. The current graph groups packages as install does, by installation type and adapter
 configuration, and the command refuses when they resolve to more than one install state or when
 `--installation-type`, `--adapter-config`, or `--adapter-module` differs from what install resolves.
-Runtime bytes must match the recorded hash unless `--carry-drift` keeps that hash, so the next
-install reports drift instead of overwriting local changes. A path another owner still claims blocks the
+For plain entries, runtime bytes must match the recorded hash unless `--carry-drift` keeps that
+hash, so the next install reports drift instead of overwriting local changes. A path another owner still claims blocks the
 plan. A duplicate claim by the same previous owner is listed only when it sits under another legacy
 key of that root with the same proof and the same recorded artifact and hashes; run the command
 again with that key to retire it. Any other duplicate, including one in that root's current state,
 blocks the plan. Apply only the emitted command. It writes the stable manifest first and the legacy
-manifest second, and changes nothing else. A pending apply journal blocks the command. If an apply
-stops after the stable manifest was written, run the dry-run again: paths already in the stable
-state are then retired from the legacy key.
+manifest second without rewriting runtime artifacts. A pending apply journal blocks the command:
+recover the journal before planning again. Once the stable phase has completed, a new reviewed
+dry-run retires the exact source copy left under the legacy key.
+
+Coherent managed instruction blocks are also supported. There must be one complete selected
+marker pair with matching selector, marker digest and recorded body hash; duplicate, overlapping,
+missing or drifted markers are refused. `--carry-drift` is forbidden when a managed block is selected.
+The reviewed plan records the original body hash separately from the whole-file runtime hash,
+prefix/suffix/block digests and byte/mode snapshot. The native phase journals bind these values and
+the whole install-manifest inventory. Initial apply and interrupted recovery require exact reviewed
+before/after state, preserving concurrent edits rather than overwriting them. Additional overlapping
+claims are refused; only an exact source/destination copy from the two-phase transition may remain.
+The runtime file, its prefix, suffix, block and permissions stay unchanged. Adoption preserves the
+recorded source metadata; it does not establish historical Git availability or evaluate a later source
+update. Run ordinary install planning separately for that decision.
 
 ## Core Ideas
 
@@ -571,6 +584,44 @@ agentwheel plan
 agentwheel install
 ```
 
+Use `add --runtimes codex` to restrict a saved package to matching runtime adapters. The option
+accepts comma-separated names and can be repeated. When replacing an existing package alias,
+pass its runtime restrictions and selection again; `add` replaces the saved entry.
+
+To change only an existing pinned alias's revision, use its exact configured name and a full
+40-hex commit SHA:
+
+```bash
+agentwheel pin shared-pack 0123456789abcdef0123456789abcdef01234567 --fleet delivery --reason "Pin the reviewed source revision"
+```
+
+`pin` preserves the source URL, driver, adapter, runtime restrictions, installation type (including
+its absence), package order and other fields. It accepts the normal workspace selectors
+`--fleet`, `--local`, `--user`, or `--target-root`, and uses the same mutation policy, durable
+receipts and revision provider as other source mutations. Missing or duplicate aliases, tracking
+packages and abbreviated or symbolic revisions are refused. No sources are fetched or rendered;
+use the normal plan/dry-run before installing the new revision.
+
+Omitting `--select` preserves the complete existing selection. Supplying repeatable or
+comma-separated `--select type/name` replaces the complete selection, including any legacy
+`skills` or imported `selection` field. An explicit empty selection is refused.
+
+For one source mutation with several aliases, use `pin --pins-file reviewed-pins.json --fleet
+delivery --reason "Pin the reviewed source set"`. The JSON file is a nonempty array of objects
+containing only `alias`, `commit` and optional `select`:
+
+```json
+[
+  { "alias": "shared-pack", "commit": "0123456789abcdef0123456789abcdef01234567" },
+  { "alias": "companion-pack", "commit": "abcdef0123456789abcdef0123456789abcdef01", "select": ["skills/companion"] }
+]
+```
+
+The batch cannot be combined with positional pins or `--select`. Every entry is validated before
+the config write; duplicate aliases and extra fields are refused. An omitted `select` preserves
+that package's selection; an explicit list replaces only that package's complete selection. The
+batch shares one durable receipt and revision-provider transaction.
+
 Package authors can mark artifacts as required. Required artifacts are always installed and cannot
 be deselected: