chore: initial commit

Author: jdalton

.agents/skills/fleet-agent-ci/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: fleet-agent-ci
+description: Run this repo's GitHub Actions workflows locally in Docker with Agent-CI to validate changes before pushing. Use before opening or updating a PR, after editing a workflow YAML under .github/workflows, or whenever catching a CI failure locally beats waiting on a remote runner.
+user-invocable: true
+allowed-tools: Bash, Read, Edit
+model: claude-haiku-4-5
+context: fork
+---
+
+# agent-ci
+
+Run the repo's CI pipeline locally before pushing. CI was green before you started, so any failure the local run surfaces comes from your changes.
+
+RedwoodJS wrote the upstream tool and skill (MIT, https://github.com/redwoodjs/agent-ci). The fleet pins `@redwoodjs/agent-ci` in the wheelhouse catalog and wires it as the `ci:local` package script (resolved via `node_modules/.bin`, never `pnpm exec`/`npx`). Edit only in `socket-wheelhouse/template/`; the cascade refreshes downstream copies.
+
+## Requirements
+
+- **Docker must be running** — each job runs in a container. On macOS the fleet uses **OrbStack** (`open -a OrbStack`; recommended over Docker Desktop). If the daemon is down, agent-ci fails fast with `couldn't use a Docker socket at /var/run/docker.sock … missing or a dangling symlink` and exit 1 — that's the daemon, not a workflow failure. Start the provider, confirm with `docker info`, re-run. No daemon and can't start one → fall back to `greening-ci` (push + watch remote).
+- **The dep is already installed** — `@redwoodjs/agent-ci` is a fleet devDependency (`catalog:`), provisioned by `pnpm install`.
+- **`--github-token` for remote reusable workflows** — every socket-\* repo's `ci.yml` calls a `SocketDev/socket-registry/.github/workflows/…` reusable workflow. agent-ci can't fetch it without a token; pass `--github-token` (no value → auto-resolves via `gh auth token`). Omitting it makes a remote-reusable CI silently fail to resolve.
+- **macOS jobs (`runs-on: macos-*`)** run in a throwaway VM and need `tart` + `sshpass` on an Apple Silicon host (`brew install cirruslabs/cli/tart hudochenkov/sshpass/sshpass`). Without both, macOS jobs are skipped with a reason — the rest of the run still proceeds.
+
+## Run
+
+The blessed entry is the canonical `ci:local` script — it already carries the full flag set (`--all --quiet --pause-on-failure --github-token`), and pnpm resolves the `agent-ci` binary from `node_modules/.bin` cross-platform:
+
+```bash
+pnpm run ci:local
+```
+
+`--all` runs the PR/push workflows for the current branch. `--quiet` suppresses the live renderer (pipe-safe). `--pause-on-failure` stops at the first failed step and holds the container open for `retry`. `--github-token` (bare → `gh auth token`) fetches the socket-registry reusable workflow every fleet `ci.yml` calls. Pipes are safe: when stdout is not a TTY the launcher detaches and the foreground process exits **77** the moment a step pauses, so `| tee log` and `> log.txt` work.
+
+There is no `--list` or dry-run flag — `run` executes. Args after the subcommand pass through, so a typo'd flag becomes a workflow arg rather than an error.
+
+To resolve the binary from a `.mts` script (not a package.json script — those resolve `node_modules/.bin` themselves), use the fleet helper, never a shelled-out `which`/`command -v` (which searches the global PATH and resolves the wrong binary — enforced by `socket/no-which-for-local-bin`):
+
+```ts
+import { whichSync } from '@socketsecurity/lib-stable/bin/which'
+
+const agentCi = whichSync('agent-ci', { path: nodeModulesBinDir, nothrow: true })
+```
+
+## Fix and retry
+
+When a step fails the run pauses (and the `run.paused` event carries the exact `retry_cmd` to copy). Fix the code, then retry the paused runner — don't restart the whole pipeline:
+
+```bash
+node_modules/.bin/agent-ci retry --name <runner-name>
+```
+
+Call the linked binary directly (the fleet form for an ad-hoc bin invocation, same as `node_modules/.bin/oxfmt` / `tsgo` in build scripts) — never `pnpm exec`/`npx`. Re-run from an earlier step with `--from-step <N>`. Repeat fix → retry until every job passes. Don't push to trigger remote CI when agent-ci can run it locally.
+
+## Reference
+
+- **Machine-readable `--json` event stream, the full requirements rationale, and the agent-ci-vs-remote-CI decision matrix**: see [reference.md](reference.md).

.agents/skills/fleet-agent-ci/reference.md

@@ -0,0 +1,60 @@
+# agent-ci reference
+
+## Contents
+
+- Machine-readable output (`--json`)
+- The exit-77 pause contract
+- Requirements rationale (Docker, install)
+- When to use agent-ci vs. remote CI
+- Command summary
+
+## Machine-readable output (`--json`)
+
+Add `--json` (or set `AGENT_CI_JSON=1`) to emit an NDJSON event stream on stdout — one JSON object per line. Use it for programmatic monitoring instead of grepping plaintext.
+
+Events:
+
+- `run.start` — carries `schemaVersion: 1` and `runId`.
+- `job.start`, `job.finish` — `status: passed | failed`.
+- `step.start`, `step.finish` — `status: passed | failed | skipped`.
+- `run.paused` — carries `runner` and `retry_cmd` (the exact command to resume).
+- `run.finish` — `status: passed | failed`.
+- `diagnostic` — non-fatal notices.
+
+`--json` is independent of `--quiet`. The diff renderer is auto-suppressed under `--json` so ANSI escapes don't collide with the stream.
+
+The robust agent loop: parse the stream, react to `run.paused` (fix the failure named in `runner`), then run the `retry_cmd` it carries. No plaintext parsing required.
+
+## The exit-77 pause contract
+
+When stdout is not a TTY (piped, redirected, captured by a parent process), the launcher detaches the run. The foreground process exits **77** the instant a step pauses. This frees the pipe — `| tee`, `> log.txt`, command substitution — while the container stays paused in the background, ready for `retry`. Exit 77 means "paused, awaiting retry," not "failed."
+
+## Requirements rationale
+
+- **Docker.** agent-ci executes each workflow job inside a container, the same way GitHub's runners do. It connects via `AGENT_CI_DOCKER_HOST` (default `unix:///var/run/docker.sock`) — **not** the standard `DOCKER_HOST` (setting `DOCKER_HOST` makes agent-ci exit with a rename error; use `AGENT_CI_DOCKER_HOST` for a remote `ssh://`/`tcp://` daemon). Without a running daemon the run cannot start; it fails fast with a dangling-socket message and exit 1. On macOS the fleet provider is **OrbStack** (`open -a OrbStack`, then `docker info` to confirm). There is no degraded mode; if you can't start a daemon, use `greening-ci` (push and watch remote CI) instead.
+- **Remote reusable workflows.** A fleet `ci.yml` doesn't contain the jobs — it `uses:` a `SocketDev/socket-registry/.github/workflows/ci.yml@<sha>` reusable workflow. agent-ci fetches that over the network, which needs `--github-token` (bare flag → `gh auth token`, or `AGENT_CI_GITHUB_TOKEN`). Without it the reusable workflow can't resolve and the run can't assemble the job graph.
+- **macOS jobs.** `runs-on: macos-*` jobs run in a real throwaway macOS VM via `tart` (Apple Silicon only) with `sshpass`. Missing either tool, or on Linux/Intel, those jobs **skip with a reason** rather than failing the run; the Linux/container jobs still execute. VM concurrency caps at `AGENT_CI_MACOS_VM_CONCURRENCY` (default 2 — tart's free tier). Windows jobs (`runs-on: windows-*`) always skip (unsupported).
+- **Missing tools in the runner image.** Jobs run in `ghcr.io/actions/actions-runner:latest`, which ships node/git/curl/jq/unzip but **not** build toolchains, `python3`, or `xz`. A job failing on a missing tool isn't your code — add a `.github/agent-ci.Dockerfile` (`FROM ghcr.io/actions/actions-runner:latest` + `apt-get install`); agent-ci picks it up automatically and caches by content hash.
+- **Install.** `@redwoodjs/agent-ci` is a fleet devDependency declared as `catalog:` in every repo's `package.json`, pinned in the wheelhouse `pnpm-workspace.yaml` catalog. `pnpm install` provisions it. The published package is a self-contained Node CLI (`dist/cli.js`) — it has no platform-binary dependencies and its `ssh2` native build scripts are declined in the fleet's `allowBuilds`/`allowScripts` (the CLI runs without them).
+
+## When to use agent-ci vs. remote CI
+
+| Situation                                                                                                    | Use                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| Edited a workflow YAML (`.github/workflows/*.yml`)                                                           | agent-ci first — a malformed workflow fails the same locally and remotely, skipping the push/wait loop. |
+| Code change that only needs lint / typecheck / unit tests                                                    | `pnpm run check --all` — faster than spinning up containers for the pure-Node gates.                    |
+| Workflow does something the local scripts don't (matrix, container steps, action wiring, secrets-shaped env) | agent-ci.                                                                                               |
+| No Docker, or the failure needs an off-machine action (a deploy, a remote service)                           | push and use `greening-ci`.                                                                             |
+
+## Command summary
+
+| Command                                                              | Purpose                                                     |
+| -------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `pnpm run ci:local`                                                  | Blessed entry — `agent-ci run --all` via `node_modules/.bin`. |
+| `node_modules/.bin/agent-ci run --all --pause-on-failure --github-token` | Run the branch's PR/push workflows; pause on first failure; fetch remote reusable workflows. |
+| `node_modules/.bin/agent-ci run --workflow <path>`                   | Run a single workflow file.                                 |
+| `node_modules/.bin/agent-ci retry --name <runner>`                   | Resume a paused runner after a fix.                         |
+| `node_modules/.bin/agent-ci retry --name <runner> --from-step <N>`   | Resume from an earlier step.                                |
+| `node_modules/.bin/agent-ci abort --name <runner>`                   | Tear down a paused runner without retrying.                 |
+
+Add `--quiet` to suppress the live renderer, `--json` for the NDJSON stream. Invoke the binary via `node_modules/.bin/agent-ci` or the `ci:local` script — never `pnpm exec`/`npx` (fleet tooling ban).

.agents/skills/fleet-auditing-api-surface/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: fleet-auditing-api-surface
+description: Audits a lib's published export surface for dead/unconsumed subpaths. For each `package.json#exports` subpath, checks whether any other fleet repo imports it and whether the lib's own `src/` references it, then classifies every subpath (dead / single-consumer / internal-only / consumed) into a ranked report. Read-only — reports prune candidates, never deletes. Use weekly (the `audit-api-surface.lock.yml` gh-aw cron drives it), before a major version bump, or when trimming bundle size on an infra lib.
+user-invocable: true
+allowed-tools: Read, Grep, Glob, Bash(node:*), Bash(rg:*), Bash(git:*), Bash(gh:*)
+model: claude-haiku-4-5
+context: fork
+---
+
+# auditing-api-surface
+
+Find published API that nobody uses. A core infra lib like `@socketsecurity/lib`
+exports 500+ subpaths; some are referenced by no other fleet repo and not even
+by the lib's own internals. That dead surface is pure carrying cost — bundle
+weight, a wider type-check graph, a tax on every refactor. This skill surfaces
+it. Read-only: it reports prune candidates, it never removes an export (mirrors
+`auditing-gha`, which reports drift but flips no setting).
+
+Repo-generic: it reads the host repo's own `package.json` name + export map, so
+the same skill audits any lib-shaped fleet repo. socket-lib is the primary
+target; other libs get a meaningful report too.
+
+## When to use
+
+- **Weekly health check** — the `audit-api-surface.lock.yml` gh-aw cron (Monday
+  09:23 UTC; source `audit-api-surface.md`) runs this and opens a tracking
+  issue. Dead surface accumulates silently; a weekly sweep keeps it visible.
+- **Before a major version bump** — a `dead` or `single-consumer` export is a
+  candidate to remove (major) or inline into its one consumer.
+- **Bundle trimming** — pairs with `trimming-bundle`; an unconsumed subpath is
+  weight no downstream needs.
+
+## What it does NOT do
+
+- **Delete anything.** Every finding is a candidate for a human. A `dead` row
+  may be a deliberate public entry point a not-yet-released consumer will use.
+- **Prove a `dead` export is safe to remove.** The scan sees only the fleet
+  repos present under `$PROJECTS` (CI clones the full roster first). A repo on
+  the roster but absent locally is reported `unscanned`, and any subpath with an
+  unscanned repo is classed `unverifiable` — never silently "dead".
+- **Go to symbol granularity.** Classification is per-subpath (per exported
+  file), not per named export. A subpath with one live symbol and ten dead ones
+  reads as `consumed`. Symbol-level analysis is a future pass.
+
+## How it classifies
+
+| Class | Meaning | Action |
+| --- | --- | --- |
+| `dead` | no internal refs, no external consumers, all repos scanned | prune candidate |
+| `single-consumer` | exactly one external consumer | candidate to inline there |
+| `internal-only` | used inside the lib, by no other repo | keep (flagged for awareness) |
+| `consumed` | ≥2 external consumers | healthy, keep |
+| `unverifiable` | no consumer found, but a roster repo was unscanned | re-run with that repo cloned |
+
+Both import forms are matched: `<pkg>/<subpath>` and the `-stable` alias
+`<pkg>-stable/<subpath>` (every consumer aliases the lib both ways in
+`pnpm-workspace.yaml`).
+
+## Run
+
+From the repo being audited:
+
+```bash
+node .claude/skills/fleet/auditing-api-surface/lib/audit-api-surface.mts --report
+```
+
+Or target a sibling checkout by name (greps the others as consumers):
+
+```bash
+PROJECTS=~/projects \
+  node .claude/skills/fleet/auditing-api-surface/lib/audit-api-surface.mts \
+  --repo socket-lib --report
+```
+
+`--report` (default) writes `.claude/reports/api-surface-audit.md` (untracked,
+per the report-location rule). `--json` prints the machine-readable result to
+stdout — the cron workflow consumes this to build its issue body.
+
+## Verify before trusting
+
+The report header states the scanned-repo count and the exact import forms
+matched. The internal-ref counter is a loose basename match (it errs toward
+keeping an export, never toward calling a live one dead). Before acting on a
+`dead` finding, confirm by hand:
+
+```bash
+rg '@socketsecurity/<pkg>(-stable)?/<subpath>' ~/projects/socket-* --glob '!**/node_modules/**'
+```
+
+A finding is a lead, not a verdict.