@proofofwork-agency/toolpin 0.2.3

package/dist/versions.js

@@ -0,0 +1,127 @@
+export function knownVersions(servers, name) {
+    const byVersion = new Map();
+    for (const server of servers) {
+        if (server.name !== name)
+            continue;
+        const existing = byVersion.get(server.version);
+        if (!existing || server.isLatest) {
+            byVersion.set(server.version, {
+                version: server.version,
+                source: server.registrySource,
+                isLatest: server.isLatest,
+            });
+        }
+    }
+    const sorted = [...byVersion.values()].sort(compareKnownVersions);
+    return sorted.map((entry, index) => ({ ...entry, isLatest: entry.isLatest || index === 0 }));
+}
+export function latestKnownVersion(servers, name) {
+    return knownVersions(servers, name)[0];
+}
+export function compareLockedToLatest(name, lockedVersion, servers) {
+    const versions = knownVersions(servers, name);
+    const latest = versions[0];
+    if (!lockedVersion || !latest) {
+        return {
+            name,
+            lockedVersion,
+            latestVersion: latest?.version,
+            status: "unknown",
+            previousVersions: versions.slice(1),
+        };
+    }
+    const delta = compareSemver(latest.version, lockedVersion);
+    return {
+        name,
+        lockedVersion,
+        latestVersion: latest.version,
+        status: delta === undefined
+            ? "unknown"
+            : delta > 0
+                ? "update-available"
+                : delta < 0
+                    ? "ahead-of-registry"
+                    : "current",
+        previousVersions: versions.filter((entry) => entry.version !== latest.version),
+    };
+}
+export function compareVersionish(a, b) {
+    return compareSemver(a, b) ?? 0;
+}
+export function compareVersionStatus(a, b) {
+    return compareSemver(a, b);
+}
+function compareKnownVersions(left, right) {
+    const semverDelta = compareSemver(right.version, left.version);
+    if (semverDelta !== undefined && semverDelta !== 0)
+        return semverDelta;
+    if (left.isLatest !== right.isLatest)
+        return left.isLatest ? -1 : 1;
+    return 0;
+}
+const SEMVER_PATTERN = new RegExp("^v?"
+    + "(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)"
+    + "(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?"
+    + "(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?"
+    + "$");
+function compareSemver(a, b) {
+    const left = parseSemver(a);
+    const right = parseSemver(b);
+    if (!left || !right)
+        return undefined;
+    const versionDelta = compareNumbers(left.major, right.major)
+        || compareNumbers(left.minor, right.minor)
+        || compareNumbers(left.patch, right.patch);
+    if (versionDelta !== 0)
+        return versionDelta;
+    return comparePrerelease(left.prerelease, right.prerelease);
+}
+function parseSemver(version) {
+    const match = SEMVER_PATTERN.exec(version);
+    if (!match)
+        return undefined;
+    return {
+        major: Number.parseInt(match[1], 10),
+        minor: Number.parseInt(match[2], 10),
+        patch: Number.parseInt(match[3], 10),
+        prerelease: match[4]?.split(".") ?? [],
+    };
+}
+function comparePrerelease(left, right) {
+    if (left.length === 0 && right.length === 0)
+        return 0;
+    if (left.length === 0)
+        return 1;
+    if (right.length === 0)
+        return -1;
+    const length = Math.max(left.length, right.length);
+    for (let i = 0; i < length; i += 1) {
+        const leftIdentifier = left[i];
+        const rightIdentifier = right[i];
+        if (leftIdentifier === undefined)
+            return -1;
+        if (rightIdentifier === undefined)
+            return 1;
+        const identifierDelta = comparePrereleaseIdentifier(leftIdentifier, rightIdentifier);
+        if (identifierDelta !== 0)
+            return identifierDelta;
+    }
+    return 0;
+}
+function comparePrereleaseIdentifier(left, right) {
+    const leftNumeric = isNumericIdentifier(left);
+    const rightNumeric = isNumericIdentifier(right);
+    if (leftNumeric && rightNumeric)
+        return compareNumbers(Number.parseInt(left, 10), Number.parseInt(right, 10));
+    if (leftNumeric)
+        return -1;
+    if (rightNumeric)
+        return 1;
+    return left === right ? 0 : left > right ? 1 : -1;
+}
+function compareNumbers(left, right) {
+    return left === right ? 0 : left > right ? 1 : -1;
+}
+function isNumericIdentifier(value) {
+    return /^(0|[1-9]\d*)$/.test(value);
+}

package/docs/assets/readme/terminal-demo.svg

@@ -0,0 +1,174 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="560" viewBox="0 0 1200 560" role="img" aria-labelledby="title desc">
+  <title id="title">Animated ToolPin terminal workflow</title>
+  <desc id="desc">A looping terminal animation showing ToolPin search, plan, install, lock, and CI drift-check commands.</desc>
+  <style>
+    :root {
+      color-scheme: dark;
+    }
+    svg {
+      background: #111;
+    }
+    .window {
+      fill: #181818;
+      stroke: #303030;
+      stroke-width: 1;
+    }
+    .topbar {
+      fill: #222;
+    }
+    .dot-red {
+      fill: #ff5f57;
+    }
+    .dot-yellow {
+      fill: #ffbd2e;
+    }
+    .dot-green {
+      fill: #28c840;
+    }
+    text {
+      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
+      font-size: 24px;
+      fill: #d8d8d8;
+    }
+    .small {
+      font-size: 19px;
+      fill: #999;
+    }
+    .prompt {
+      fill: #70e1bd;
+      font-weight: 700;
+    }
+    .cmd {
+      fill: #f5f5f5;
+    }
+    .muted {
+      fill: #9a9a9a;
+    }
+    .ok {
+      fill: #70e1bd;
+      font-weight: 700;
+    }
+    .warn {
+      fill: #ffd75f;
+      font-weight: 700;
+    }
+    .blue {
+      fill: #7cc7ff;
+      font-weight: 700;
+    }
+    .bar-ok {
+      fill: #70e1bd;
+    }
+    .bar-warn {
+      fill: #ffd75f;
+    }
+    .bar-bg {
+      fill: #3a3a3a;
+    }
+    .cursor {
+      fill: #70e1bd;
+      animation: blink 1s steps(2, start) infinite;
+    }
+    .frame {
+      opacity: 0;
+      animation: frames 12s steps(1, end) infinite;
+    }
+    .f1 {
+      animation-delay: 0s;
+    }
+    .f2 {
+      animation-delay: -9.6s;
+    }
+    .f3 {
+      animation-delay: -7.2s;
+    }
+    .f4 {
+      animation-delay: -4.8s;
+    }
+    .f5 {
+      animation-delay: -2.4s;
+    }
+    @keyframes frames {
+      0%, 19.99% {
+        opacity: 1;
+      }
+      20%, 100% {
+        opacity: 0;
+      }
+    }
+    @keyframes blink {
+      0%, 45% {
+        opacity: 1;
+      }
+      46%, 100% {
+        opacity: 0;
+      }
+    }
+  </style>
+
+  <rect class="window" x="24" y="24" width="1152" height="512" rx="14"/>
+  <rect class="topbar" x="24" y="24" width="1152" height="58" rx="14"/>
+  <rect class="topbar" x="24" y="62" width="1152" height="20"/>
+  <circle class="dot-red" cx="60" cy="53" r="9"/>
+  <circle class="dot-yellow" cx="90" cy="53" r="9"/>
+  <circle class="dot-green" cx="120" cy="53" r="9"/>
+    <text x="160" y="61" class="small">ToolPin v0.2.2 - MCP install review gate - toolpin or tpn</text>
+
+  <g class="frame f1">
+    <text x="62" y="126"><tspan class="prompt">$</tspan><tspan class="cmd"> toolpin search contextrelay --source toolpin</tspan></text>
+    <text x="62" y="174" class="muted">loaded 1 ToolPin-curated server</text>
+    <text x="62" y="222"><tspan class="ok">toolpin</tspan>  ContextRelay                  <tspan class="ok">EVIDENCE OK</tspan></text>
+    <text x="62" y="270" class="muted">@proofofwork-agency/contextrelay@3.9.2</text>
+    <text x="62" y="318" class="muted">Local coordination bridge for Codex and Claude Code agents.</text>
+    <rect class="bar-ok" x="62" y="370" width="390" height="22" rx="4"/>
+    <rect class="bar-bg" x="452" y="370" width="84" height="22" rx="4"/>
+    <text x="62" y="440"><tspan class="prompt">&gt;</tspan> select, review, then install only after the plan looks right</text>
+    <rect class="cursor" x="1070" y="418" width="14" height="28"/>
+  </g>
+
+  <g class="frame f2">
+    <text x="62" y="126"><tspan class="prompt">$</tspan><tspan class="cmd"> toolpin plan @proofofwork-agency/contextrelay --client codex --live --verify</tspan></text>
+    <text x="62" y="178"><tspan class="blue">overview</tspan> @proofofwork-agency/contextrelay@3.9.2</text>
+    <text x="62" y="226">runtime     npm     transport  stdio     secrets  <tspan class="ok">none declared</tspan></text>
+    <text x="62" y="274">evidence    <tspan class="ok">ToolPin-verified npm_integrity_verified</tspan></text>
+    <text x="62" y="322">badges      source repo, namespaced, npm, pinned version</text>
+    <text x="62" y="382">profile</text>
+    <rect class="bar-ok" x="190" y="360" width="380" height="22" rx="4"/>
+    <text x="596" y="382"><tspan class="ok">100%</tspan> metadata profile</text>
+    <text x="62" y="436">integrity</text>
+    <rect class="bar-ok" x="190" y="414" width="380" height="22" rx="4"/>
+    <text x="596" y="436"><tspan class="ok">100%</tspan> artifact evidence</text>
+  </g>
+
+  <g class="frame f3">
+    <text x="62" y="126"><tspan class="prompt">$</tspan><tspan class="cmd"> toolpin install @proofofwork-agency/contextrelay --client codex --scope global --update-lock</tspan></text>
+    <text x="62" y="184"><tspan class="blue">Install</tspan></text>
+    <text x="62" y="232">server     @proofofwork-agency/contextrelay@3.9.2</text>
+    <text x="62" y="280">client     codex        scope  global</text>
+    <text x="62" y="328">config     <tspan class="ok">updated</tspan>: ~/.codex/config.toml</text>
+    <text x="62" y="376">lock       <tspan class="ok">mcp-lock.json updated</tspan></text>
+    <text x="62" y="424" class="muted">- Requires Node.js and npm/npx on PATH.</text>
+    <text x="62" y="472"><tspan class="ok">done</tspan>       installed for codex</text>
+  </g>
+
+  <g class="frame f4">
+    <text x="62" y="126"><tspan class="prompt">$</tspan><tspan class="cmd"> toolpin audit --verify</tspan></text>
+    <text x="62" y="184"><tspan class="blue">Audit findings</tspan></text>
+    <text x="62" y="232">lockfile   mcp-lock.json</text>
+    <text x="62" y="280">checked    1 locked, 15 config file(s)</text>
+    <text x="62" y="328">doctor     <tspan class="ok">ok</tspan>  installed config matches lockfile</text>
+    <text x="62" y="376">secrets    <tspan class="ok">ok</tspan>  no plaintext secret findings</text>
+    <text x="62" y="424">evidence   <tspan class="ok">ok</tspan>  trusted artifact proof is fresh</text>
+    <text x="62" y="472"><tspan class="ok">no findings</tspan></text>
+  </g>
+
+  <g class="frame f5">
+    <text x="62" y="126"><tspan class="prompt">$</tspan><tspan class="cmd"> toolpin ci --file mcp-lock.json --live --verify</tspan></text>
+    <text x="62" y="184">resolving locked server plans...</text>
+    <text x="62" y="232">checking policy, generated config, manifest, evidence...</text>
+    <text x="62" y="280">comparing reviewed lock entries...</text>
+    <text x="62" y="348"><tspan class="ok">PASS</tspan> mcp-lock.json matches reviewed install state</text>
+    <text x="62" y="408"><tspan class="warn">commit</tspan> mcp-lock.json and run this in pull requests</text>
+    <text x="62" y="468"><tspan class="prompt">$</tspan><tspan class="cmd"> git push   </tspan><tspan class="muted"># ToolPin protects the PR</tspan></text>
+  </g>
+</svg>

package/docs/how-to/catch-drift-in-ci.md

@@ -0,0 +1,189 @@
+# Catch Drift in CI
+
+Use `toolpin ci` when `mcp-lock.json` is committed to a repository and pull
+requests should fail if registry metadata, generated client config, policy, or
+optional signatures no longer match the reviewed lockfile.
+
+`toolpin ci` is read-only. It re-resolves locked entries, rebuilds install
+plans, checks lock integrity, enforces policy unless bypassed, and exits
+non-zero on drift. It does not update `mcp-lock.json`.
+
+`toolpin ci --sarif` emits SARIF 2.1.0 JSON to stdout and still exits non-zero
+on drift:
+
+```bash
+toolpin ci --file mcp-lock.json --live --sarif > toolpin.sarif
+```
+
+Automatic GitHub code-scanning upload is not wired into the composite action in
+this pass; add an explicit upload step after reviewing the desired repository
+permissions.
+
+## Basic GitHub Action
+
+After the repository is public and tagged, call the composite action from your
+workflow. The action installs ToolPin from the action source by default, so it
+does not require npm publish:
+
+```yaml
+name: ToolPin
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  mcp-lock:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: proofofwork-agency/toolpin@v0.2.3
+        with:
+          file: mcp-lock.json
+          live: "true"
+```
+
+The action builds ToolPin from `$GITHUB_ACTION_PATH` and runs:
+
+```bash
+toolpin ci --file mcp-lock.json --source all --live --policy .toolpin/policy.json
+```
+
+When `.toolpin/policy.json` is absent, the current CLI treats policy enforcement
+as a no-op.
+
+## Direct CLI Workflow
+
+Use this form when you want the workflow to install the npm package directly
+instead of using the composite Action:
+
+```yaml
+name: ToolPin
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  mcp-lock:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm install -g @proofofwork-agency/toolpin
+      - run: toolpin ci --file mcp-lock.json --live
+```
+
+For unreleased source-checkout development, run `npm ci`, `npm test`, and
+`npm run dev -- ci --file mcp-lock.json --live`.
+
+## Digest Pin
+
+`--expect-digest` compares the whole-lock digest against a value provided by
+CI. Store the expected digest outside the pull request being checked, for
+example as a GitHub Actions variable or secret.
+
+Generate the digest after reviewing a lockfile change:
+
+```bash
+toolpin lock digest --file mcp-lock.json
+```
+
+Use it in CI:
+
+```yaml
+- uses: proofofwork-agency/toolpin@v0.2.3
+  with:
+    file: mcp-lock.json
+    live: "true"
+    expect-digest: ${{ vars.TOOLPIN_LOCK_DIGEST }}
+```
+
+Do not commit the expected digest next to `mcp-lock.json`; a PR that changes
+both files would defeat the check.
+
+## Detached Signature
+
+ToolPin can verify a detached Ed25519 signature before registry resolution:
+
+```bash
+toolpin lock sign --policy .toolpin/policy.json --key private.pem --file mcp-lock.json --signature mcp-lock.sig
+toolpin lock verify-signature --policy .toolpin/policy.json --key public.pem --file mcp-lock.json --signature mcp-lock.sig
+```
+
+Then in CI:
+
+```yaml
+- uses: proofofwork-agency/toolpin@v0.2.3
+  with:
+    file: mcp-lock.json
+    live: "true"
+    signature: mcp-lock.sig
+    public-key: public.pem
+```
+
+Commit `mcp-lock.sig` and the public key only after review. Never commit the
+private key. A signature is meaningful only when the private key and public
+trust root are controlled outside the PR path.
+
+## Policy and Live Verification
+
+To enforce a non-default policy path:
+
+```yaml
+- uses: proofofwork-agency/toolpin@v0.2.3
+  with:
+    policy: security/toolpin-policy.json
+```
+
+To make CI skip policy enforcement explicitly:
+
+```yaml
+- uses: proofofwork-agency/toolpin@v0.2.3
+  with:
+    no-policy: "true"
+```
+
+To re-run verification before comparing locked plans, use the stricter CI
+posture:
+
+```yaml
+- uses: proofofwork-agency/toolpin@v0.2.3
+  with:
+    live: "true"
+    verify: "true"
+    timeout: "15000"
+```
+
+`verify: "true"` can require network access, local runtimes, and server
+credentials for live MCP probes. Use `skip-live-verification: "true"` when you
+want artifact/metadata verification without live `tools/list` probing. Treat
+that as a conscious downgrade: it skips capability hashing and CI rejects it for
+entries that already have live capability pins.
+
+## What Fails the Build
+
+CI exits non-zero when:
+
+- `mcp-lock.json` is missing, empty, malformed, or has an unsupported version.
+- Per-entry lock integrity is missing or invalid.
+- A locked server/client no longer resolves to the reviewed install plan
+  (version, target, trust, generated config, or capability manifest drifted).
+- The whole-lock digest (`--expect-digest`) does not match.
+- Detached signature verification fails, or `signature` and `public-key` are not
+  supplied as a pair.
+- The selected policy rejects a locked entry.
+- `--verify` finds critical verification findings.
+- `--sarif` changes the output format only; it does not make failing checks
+  advisory.
+
+Use `toolpin install --update-lock` or `toolpin lock <server> --client <client>`
+only after reviewing the drift locally. CI should not update the lockfile.

package/docs/how-to/custom-registries.md

@@ -0,0 +1,156 @@
+# Custom Registries
+
+ToolPin can read built-in registries and repo-owned registry definitions from `.toolpin/registries.json`.
+
+Built-in sources:
+
+- `toolpin`: ToolPin hosted curated registry with bundled fallback, installable,
+  `curated` trust, pinned, and always enabled.
+- `official`: Official MCP Registry, installable, `canonical` trust.
+- `docker`: Docker MCP Catalog, installable, `curated` trust.
+- `pulsemcp`, `smithery`, `glama`: known directory sources, disabled by default. Enable one explicitly before it appears in `--source all`, browse, or search. `pulsemcp` is auth-gated, Smithery hosted targets require `--allow-hosted-directory-targets`, and Glama entries become installable only when ToolPin can match their repository to an Official MCP Registry entry with lockable targets.
+
+Use source preferences to turn optional built-ins on or off. The pinned
+`toolpin` source is always enabled:
+
+```sh
+toolpin registry list
+toolpin registry enable glama
+toolpin registry disable glama
+```
+
+Those commands write a top-level `sources` preference block:
+
+```json
+{
+  "sources": {
+    "glama": {
+      "enabled": true
+    },
+    "smithery": {
+      "enabled": false
+    }
+  },
+  "registries": []
+}
+```
+
+ToolPin also maintains a GitHub-backed curated registry. Current ToolPin
+versions expose it as the built-in `toolpin` source and fetch
+`https://raw.githubusercontent.com/proofofwork-agency/toolpin/main/registry/v0/servers`
+first, falling back to the bundled snapshot if the hosted file is unavailable
+or invalid.
+
+See [ToolPin Curated Registry](./toolpin-curated-registry.md) for the PR-based
+review workflow.
+
+## Official-Compatible Registry
+
+Use this for company or private registries that expose the MCP Registry `/v0/servers` response shape.
+
+```json
+{
+  "registries": [
+    {
+      "id": "company",
+      "type": "official-compatible",
+      "url": "https://registry.company.com/v0",
+      "mode": "installable",
+      "trust": "private"
+    }
+  ]
+}
+```
+
+Then run:
+
+```sh
+toolpin registry list
+toolpin ingest --source company
+toolpin search postgres --source company
+toolpin install company/postgres --client claude --update-lock
+```
+
+Installable entries still need enough machine-readable metadata for ToolPin to build a lockable install plan: a package or remote target, version, transport, source metadata, and any declared secrets.
+
+Verified metadata comes from an installable source that exposes reviewable MCP
+Registry-style server records, such as the Official MCP Registry, Docker MCP
+Catalog, or an `official-compatible` custom/curated registry. For a directory
+result to become installable, curate it into metadata with package/remotes,
+exact versions, repository URLs, and artifact pins where available, such as OCI
+`@sha256:` digests or MCPB `fileSha256` values.
+
+## Discovery Registries
+
+Broad directories and scraped indexes should start as discovery sources:
+
+```json
+{
+  "registries": [
+    {
+      "id": "glama-public",
+      "type": "http-json",
+      "url": "https://example.com/mcp-servers.json",
+      "mode": "discovery"
+    }
+  ]
+}
+```
+
+Discovery entries can appear in search and info views when their source is enabled. ToolPin refuses to install them until they normalize into a source that is explicitly marked `installable`, or an adapter can safely re-resolve them to an installable registry entry.
+
+This is why a source such as Glama can be useful for discovery while still not
+providing installable metadata. It may describe many servers, gateways, or
+directory matches, but ToolPin still needs a matching official entry with a
+lockable package or remote target before it can review, install, and enforce the
+entry.
+
+This keeps the product claim precise: ToolPin can search broad directories, but only installs servers it can normalize, review, lock, and enforce.
+
+## Config Reference
+
+Each entry in `.toolpin/registries.json` supports:
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `id` | yes | — | Stable source identifier used by `--source`. |
+| `url` | yes | — | Registry endpoint. For `official-compatible`, ToolPin appends `/servers`. |
+| `type` | no | `official-compatible` | `official-compatible` (MCP Registry `/v0/servers` shape) or `http-json` (response with a `servers` or `entries` array). |
+| `mode` | no | `installable` for `official-compatible`, `discovery` for `http-json` | Whether entries from this source can be installed. |
+| `label` | no | the `id` | Display label in `toolpin registry list` and the TUI. |
+| `trust` | no | `private` | One of `canonical`, `curated`, `directory`, `private`. |
+| `enabled` | no | `true` | For custom registry entries, set to `false` to hide the source from `--source all`; optional built-ins are toggled through top-level `sources` preferences or `toolpin registry enable/disable`. Pinned sources such as `toolpin` cannot be disabled. |
+| `authEnv` | no | — | Environment variable name that holds an auth token; marks the source `authRequired`. Advisory only — ToolPin does not yet send this token in registry requests. |
+| `description` | no | generated | Human-readable source description. |
+
+Invalid `type` or `mode` values are rejected. If a custom entry reuses a built-in `id`, the built-in wins and the custom entry is ignored.
+
+## Source Resolution and Caching
+
+`--source all` fetches every enabled source in parallel and deduplicates entries by repository URL, server name, and version. On collisions, `toolpin` beats `official`, which beats `docker`, which beats any custom source. Disabled sources can remain in the cache, but browse/search filter them out until they are enabled again.
+
+The TUI Browse list uses the same source priority by default: `toolpin`,
+`official`, `docker`, then other enabled sources. Press `a` to cycle sort modes
+or `g` to cycle the exact source filter.
+
+`toolpin ingest` always fetches live and writes the combined result to `.toolpin/registry-cache.json` (a `{ generatedAt, entries }` document). Other commands read that cache when `--live` is omitted; if the cache is missing or does not contain the requested source, they transparently fall back to a live fetch. Pass `--live` to bypass the cache entirely. A cache file that exists but is not valid registry-cache JSON raises a `CacheSchemaError` instead of falling back.
+
+## TUI Installed View
+
+Run:
+
+```sh
+toolpin tui
+```
+
+Open the `Installed` tab to inspect servers already written to supported config files across folder/project and global/user scopes. The view shows:
+
+- config file, client, and scope
+- locked, unlocked, or drift state
+- registry match status: `registry:exact`, `registry:alias`, or `registry:none`
+- locked and latest known versions
+- lifecycle action: `action:update`, `action:adopt`, or `action:none`
+- test source: `test:config` when ToolPin can test the installed client config
+- delete, update/adopt, explicit version relock, doctor, and `test-installed` actions
+
+Runtime status is advisory. ToolPin can mark a server `reachable` after `t` succeeds and `stale` when lock/config or version drift is detected. It does not claim process monitoring unless ToolPin owns the runtime or can query a client/gateway API.