pome-sh 0.6.6

package/node_modules/@pome-sh/shared-types/src/task-vocab.ts

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * task-vocab — the W3 "scenario → task" wire-vocabulary rename (FDRS-653).
+ *
+ * W3 decision (binding, 2026-06): everything "scenario" becomes "task" on the
+ * wire, and criterion kinds `D` / `P` become `code` / `model`. The cloud DB is
+ * already renamed (`tasks` table, `runs.task_name`); this module gives the
+ * shared trace format the same vocabulary WITHOUT breaking 0.3.0-era artifacts.
+ *
+ * Tolerant-reader contract (the 0.3.0 compatibility window):
+ *   - Canonical schemas and types use the NEW vocabulary only
+ *     (`task_name`, `task_hash`, `task_source`, `task_id`, `promoted_task_id`,
+ *     `task_step_id`, criterion kind `code` / `model`).
+ *   - Readers accept BOTH the old and the new keys and normalize to the new
+ *     vocabulary at parse time. Nothing a 0.3.0-era artifact contains becomes
+ *     invalid: shipped CLIs vendor shared-types 0.3.0 and keep sending
+ *     `scenario_*` keys and `D` / `P` criterion kinds for at least one more
+ *     release train (the CLI vendored-tarball bump rides FDRS-654/657).
+ *   - When BOTH keys are present, the new key wins (a 0.5.0-aware writer is
+ *     more authoritative about the canonical field than a mirrored legacy key).
+ *
+ * The window closes with the next major once no supported CLI emits the old
+ * vocabulary; removal of the aliases goes through the deprecation policy.
+ */
+
+/**
+ * Old wire key → canonical wire key for the RENAME-on-read surfaces of the
+ * /v1 contract (run / session / result wire objects):
+ *   - `scenario_name` / `scenario_hash`   — Run rows + POST /v1/sessions/{id}/result
+ *   - `scenario_source` / `scenario_id`   — POST /v1/sessions
+ *   - `promoted_scenario_id`              — Run rows (M0.5 replay-loop linkage)
+ *
+ * DELIBERATELY NOT in this map: `scenario_step_id` on RecorderEvent rows
+ * (events.jsonl). The frozen v1 event row has PRESERVE semantics — the legacy
+ * key stays as-sent while readers additionally populate `task_step_id` — which
+ * is handled by the reader schemas in `./recorder-events.ts`, NOT by this
+ * delete-the-legacy-key map.
+ */
+export const LEGACY_TASK_VOCAB_KEY_MAP = {
+  scenario_name: "task_name",
+  scenario_hash: "task_hash",
+  scenario_source: "task_source",
+  scenario_id: "task_id",
+  promoted_scenario_id: "promoted_task_id",
+} as const;
+
+/**
+ * Rename legacy `scenario_*` keys on a raw wire object to their canonical
+ * `task_*` names. Non-objects pass through untouched (the wrapped schema then
+ * reports the real type error). When both the legacy and the canonical key are
+ * present the canonical value wins and the legacy key is dropped.
+ *
+ * Used as a `z.preprocess` step in front of the canonical object schemas —
+ * this is the "tolerant reader" half of the 0.3.0 compatibility window.
+ *
+ * DO NOT apply this helper to recorder-event rows (events.jsonl). Event rows
+ * require `scenario_step_id` preserved as-sent (frozen v1 trace format), and
+ * this function's rename-and-delete semantics would strip that step linkage
+ * if the key were mapped. `scenario_step_id` is intentionally absent from
+ * `LEGACY_TASK_VOCAB_KEY_MAP`, so this function leaves it intact — event-row
+ * normalization lives in `recorderEventSchema` / `eventSchema`
+ * (`./recorder-events.ts`).
+ */
+export function normalizeTaskVocabKeys(value: unknown): unknown {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return value;
+  }
+  const record = value as Record<string, unknown>;
+  let out: Record<string, unknown> | null = null;
+  for (const [legacyKey, canonicalKey] of Object.entries(LEGACY_TASK_VOCAB_KEY_MAP)) {
+    if (legacyKey in record) {
+      out ??= { ...record };
+      if (!(canonicalKey in record)) {
+        out[canonicalKey] = record[legacyKey];
+      }
+      delete out[legacyKey];
+    }
+  }
+  return out ?? value;
+}
+
+/** Legacy criterion kind → canonical criterion kind (W3: D→code, P→model). */
+export const LEGACY_CRITERION_KIND_MAP = {
+  D: "code",
+  P: "model",
+} as const;

package/node_modules/@pome-sh/twin-github/FIDELITY.md

@@ -0,0 +1,322 @@
+# GitHub Twin Fidelity
+
+`@pome-sh/twin-github` is a high-fidelity test double of GitHub — not a
+universal clone. This page documents exactly which surfaces are faithful to
+GitHub today, at what tier, and how fidelity is verified.
+
+Last verified: 2026-05-27.
+
+## What "fidelity" means here
+
+Each MCP tool and REST route is classified into one of three tiers:
+
+- **`semantic`** — the stateful behavior is implemented locally and covered
+  by tests. Optimistic locking, branch ancestry, label invariants, and the
+  rest behave the way agents expect when they call real GitHub.
+- **`shape`** — the response shape is checked against captured real GitHub
+  fixtures, but the underlying behavior is not fully semantic. Useful for
+  agents that only inspect the response shape; not safe for agents that
+  rely on the side effects.
+- **`unsupported`** — not implemented. The clone returns a loud 501 envelope
+  (see below) so an agent never silently succeeds against a missing route.
+
+The bar Pome aims for is: **agents written against real GitHub run unchanged
+against the local twin for the surfaces below**, and trip a loud failure for
+anything outside them.
+
+For the build / runtime / cross-repo invariants the hosted snapshot build
+depends on (port `:3333`, `/healthz`, `GITHUB_CLONE_HOST`, `npm install`-able
+package, `node dist/src/server.js`), see
+[Runtime contract (for snapshot consumers)](README.md#runtime-contract-for-snapshot-consumers)
+in the package README. Changing any of those is a breaking change for
+`pome-cloud` and goes via a cross-repo PR.
+
+## MCP Tools
+
+| Tool | Backing surface | Tier | Tests | Known deviations |
+| --- | --- | --- | --- | --- |
+| `search_repositories` | SQLite repositories | semantic | `mcp-contract.test.ts`, `fixture-shape.test.ts` | Search query support is intentionally smaller than GitHub search syntax. |
+| `create_repository` | SQLite repositories, branches, commits, files | semantic | `mcp-contract.test.ts`, `concurrency.test.ts` | Creates a deterministic README and main branch. |
+| `fork_repository` | SQLite repository/file/commit copy | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Fork permissions and network metadata are simplified. |
+| `get_repository` | SQLite repositories | semantic | `mcp-contract.test.ts`, `fixture-shape.test.ts` | Repository object contains the fields agents use, not every GitHub field. |
+| `search_code` | SQLite default-branch files | semantic | `mcp-contract.test.ts`, `domain.test.ts`, `performance.test.ts` | Query syntax is substring based; search is scoped to the default branch. |
+| `search_users` | SQLite users | semantic | `mcp-contract.test.ts` | Organization/user scoring is simplified. |
+| `get_file_contents` | SQLite files/directories | semantic | `mcp-contract.test.ts`, `domain.test.ts`, `fixture-shape.test.ts` | Symlinks, submodules, and media/raw modes are not implemented. |
+| `list_commits` | SQLite commit graph | semantic | `mcp-contract.test.ts`, `domain.test.ts`, `fixture-shape.test.ts` | Commit listing follows the selected branch ancestry only. |
+| `create_or_update_file` | SQLite files/commits | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Requires `sha` for updates to preserve optimistic locking. |
+| `create_branch` | SQLite branches/files | semantic | `mcp-contract.test.ts`, `domain.test.ts`, `concurrency.test.ts` | Branch protection is not modeled. |
+| `push_files` | SQLite files/commits | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Multi-file pushes are one local commit; Git object APIs are simplified. |
+| `get_issue` | SQLite issues | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Issue timeline/events are not modeled. |
+| `update_issue` | SQLite issues, labels, assignees | semantic | `mcp-contract.test.ts`, `mcp-error-semantics.test.ts` | Milestones/projects are not implemented. |
+| `search_issues` | SQLite issues | semantic | `mcp-contract.test.ts`, `performance.test.ts`, `fixture-shape.test.ts` | Query syntax is substring based. |
+| `list_issues` | SQLite issues | semantic | `mcp-contract.test.ts`, `performance.test.ts`, `fixture-shape.test.ts` | Only state, labels, assignee, and pagination filters are supported. |
+| `add_issue_comment` | SQLite issue comments | semantic | `mcp-contract.test.ts`, `state-export.test.ts` | Comment edit/delete APIs are not implemented. |
+| `list_issue_comments` | SQLite issue comments | semantic | `mcp-contract.test.ts`, `state-export.test.ts` | Pagination is supported; reactions are not. |
+| `create_issue` | SQLite issues | semantic | `mcp-contract.test.ts` | Issue templates and milestones are not modeled. |
+| `list_repository_labels` | SQLite labels | semantic | `mcp-contract.test.ts` | Label URLs use deterministic local IDs. |
+| `create_label` | SQLite labels | semantic | `mcp-contract.test.ts` | Color validation is intentionally permissive. |
+| `list_issue_labels` | SQLite issue labels | semantic | `mcp-contract.test.ts` | Returns current issue label set only. |
+| `add_issue_labels` | SQLite issue labels | semantic | `mcp-contract.test.ts` | Missing labels return GitHub-shaped 422s. |
+| `remove_issue_label` | SQLite issue labels | semantic | `mcp-contract.test.ts` | Removing a missing label returns 404. |
+| `list_collaborators` | SQLite collaborators | semantic | `mcp-contract.test.ts` | Permission filtering is not implemented. |
+| `add_assignees` | SQLite issue assignees | semantic | `mcp-contract.test.ts` | Requires seeded collaborators. |
+| `get_pull_request` | SQLite pull requests | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Drafts, mergeability background jobs, and review decisions are simplified. |
+| `get_pull_request_reviews` | SQLite PR reviews | semantic | `mcp-contract.test.ts`, `state-export.test.ts` | Review dismissal is not implemented. |
+| `create_pull_request_review` | SQLite PR reviews | semantic | `mcp-contract.test.ts`, `state-export.test.ts` | Inline review comments are not created by this tool. |
+| `get_pull_request_comments` | SQLite PR review comments | semantic | `mcp-contract.test.ts` | Review comment creation is not exposed yet. |
+| `get_pull_request_files` | SQLite computed PR files | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Patches are simplified placeholders. |
+| `get_pull_request_status` | SQLite commit statuses | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Check suites and check runs are not modeled. |
+| `list_pull_requests` | SQLite pull requests | semantic | `mcp-contract.test.ts` | Sorting and advanced filters are simplified. |
+| `merge_pull_request` | SQLite merge mutation | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Merge methods are simplified to one deterministic local merge. |
+| `update_pull_request_branch` | SQLite branch head update | shape | `mcp-contract.test.ts`, `domain.test.ts` | Updates the local branch pointer and response shape, but does not create GitHub's merge commit or async update job. |
+| `create_pull_request` | SQLite pull requests/files | semantic | `mcp-contract.test.ts`, `concurrency.test.ts` | Cross-repo forks are supported only when the fork exists in the clone. |
+| `list_branches` | SQLite branches | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Pagination supported; protection metadata always false. |
+| `get_branch` | SQLite branches | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Returns shape-compatible commit object with head SHA. |
+| `delete_branch` | SQLite branches/files | semantic | `mcp-contract.test.ts`, `domain.test.ts` | 422 on default branch or branch backing an open PR; cascades file rows. |
+| `delete_file` | SQLite files/commits | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Requires `sha` for optimistic locking; advances branch head atomically. |
+| `get_commit` | SQLite commits/file_versions | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Resolves ref by SHA, branch, or tag. Stats/files reflect file_versions diff. |
+| `compare_commits` | SQLite commits (ancestry walk) | shape | `mcp-contract.test.ts`, `domain.test.ts` | First-parent ancestry only; capped at `MAX_COMPARE_DEPTH=2000`; merge-base is approximated. |
+| `get_pull_request_diff` | SQLite pull_request_files | shape | `mcp-contract.test.ts`, `domain.test.ts` | Returns a unified-diff-shaped envelope; patches are simplified placeholders. |
+| `update_pull_request` | SQLite pull requests | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Updates title/body/state/base; recomputes PR files on base change; cannot reopen a merged PR. |
+| `get_pull_request_commits` | SQLite commits walk | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Oldest-first ordering between base_sha..head_sha. |
+| `create_pull_request_review_comment` | SQLite PR review comments | semantic | `mcp-contract.test.ts`, `domain.test.ts` | 422 if path is not part of the PR; line/side stored. |
+| `add_reply_to_pull_request_comment` | SQLite PR review comments | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Inherits path/line/side from parent comment; sets `in_reply_to_id`. |
+| `update_issue_comment` | SQLite issue comments | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Updates body and `updated_at`. |
+| `delete_issue_comment` | SQLite issue comments | semantic | `mcp-contract.test.ts`, `domain.test.ts` | 404 on unknown comment. |
+| `list_milestones` | SQLite milestones | semantic | `mcp-contract.test.ts`, `domain.test.ts` | State filter (`open`/`closed`/`all`) + pagination supported. |
+| `create_milestone` | SQLite milestones | semantic | `mcp-contract.test.ts`, `domain.test.ts` | 422 on duplicate title; default state is `open`. |
+| `update_milestone` | SQLite milestones | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Closing sets `closed_at`; reopening clears it. |
+| `delete_milestone` | SQLite milestones | semantic | `mcp-contract.test.ts`, `domain.test.ts` | 404 on unknown milestone. |
+| `create_commit_status` | SQLite commit_statuses | semantic | `mcp-contract.test.ts`, `domain.test.ts` | 404 if SHA not in repo; default context is `default`. |
+| `get_combined_status_for_ref` | SQLite commit_statuses | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Combined state follows GitHub rule; empty status set returns `pending`. |
+| `create_check_run` | SQLite check_runs | semantic | `mcp-contract.test.ts`, `domain.test.ts` | 422 if `status=completed` without `conclusion`; no check_suites modeled. |
+| `list_check_runs_for_ref` | SQLite check_runs | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Pagination supported; ordered most-recent-started first. |
+| `list_tags` | SQLite tags | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Returns tag → commit SHA; tarball/zipball URLs are shaped placeholders. |
+| `list_releases` | SQLite releases | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Newest-first; includes drafts and prereleases. |
+| `get_latest_release` | SQLite releases | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Skips drafts and prereleases; 404 if none. |
+| `create_release` | SQLite releases/tags | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Auto-creates the tag from `target_commitish` if missing; 422 on duplicate tag. |
+| `get_me` | SQLite users + JWT actor | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Returns the JWT-claimed `login` (default `pome-agent`). |
+| `add_collaborator` | SQLite collaborators | semantic | `mcp-contract.test.ts`, `domain.test.ts` | Returns 201 invitation envelope for new users; 204 for existing collaborators. |
+
+## REST Surfaces
+
+The REST routes used by the MCP tools are also exposed under authenticated
+`/s/:sid/*` paths. Captured fixture checks currently cover repository search,
+issue search, contents, commits, and issue lists as `shape` tests. All
+unsupported routes return a loud 501 envelope:
+
+```json
+{
+  "message": "This endpoint is not supported by this GitHub twin clone.",
+  "_twin": {
+    "fidelity": "unsupported",
+    "supported_surfaces": [
+      "GitHub-shaped REST",
+      "POST /s/:sid/mcp",
+      "GET /s/:sid/mcp/tools",
+      "POST /s/:sid/mcp/tools/:name",
+      "POST /s/:sid/mcp/call"
+    ]
+  }
+}
+```
+
+Twin-only fields are namespaced under `_twin.*`, matching `twin-slack` and
+`twin-stripe`.
+
+If you hit this envelope and the route is one your agent needs, that's a
+fidelity gap worth filing — open an issue or a PR adding the route.
+
+## Known divergences from real GitHub
+
+These are the cross-cutting behaviors where the twin deliberately or
+provisionally differs from real GitHub. Each bullet has a structured entry in
+the Twin Fidelity Watch's `known-divergences/github.yaml` (maintained in
+pome-cloud); a lint keeps the two 1:1. The fidelity watchdog reverse-tests each one against
+upstream so a divergence that upstream "heals" becomes a tier-upgrade signal.
+
+1. **Search query syntax is substring-based.** `search_repositories`,
+   `search_code`, and `search_issues` use substring matching scoped to the
+   default branch — GitHub's search qualifiers (`in:`, `language:`, `path:`,
+   boolean operators) are not parsed.
+2. **PR diffs and patches are simplified placeholders.** `get_pull_request_diff`
+   and `get_pull_request_files` return a unified-diff-shaped envelope whose
+   `patch` bodies are placeholders, not byte-accurate GitHub patches.
+3. **`compare_commits` walks first-parent ancestry only.** Comparison follows
+   first parents, is capped at `MAX_COMPARE_DEPTH=2000`, and approximates the
+   merge-base rather than computing GitHub's exact three-dot base.
+4. **Branch protection is not modeled.** `list_branches` / `get_branch` always
+   report protection metadata as `false`; protected-branch push rejections and
+   required-status-check gating do not exist in the twin.
+5. **User objects are a documented subset of real GitHub fields.** The twin's
+   user object carries the fields agents use (`login`, `id`, `node_id`,
+   `avatar_url`, `html_url`, `type`, `site_admin`) and omits always-present
+   real-GitHub profile leaves: `gravatar_id`, `user_view_type`, and the optional
+   `hireable` / `twitter_username` / `notification_email` on `GET /user`. User
+   objects embed all over the API (`owner`, `[].user`, commit `author`/`committer`,
+   the PR-status `repository.owner`), so this divergence is registered once and
+   matched by leaf key wherever the user object nests. On an L1 read surface an upstream-only leaf the twin omits is an
+   accepted divergence (INFO), not drift — a twin returning a *subset* of GitHub's
+   fields is faithful; a twin returning a field GitHub does not is still flagged.
+6. **Repository objects are a documented subset of real GitHub fields.** The
+   twin's repository object omits three families of always-present real-GitHub
+   leaves: stat counts (`stargazers_count`, `watchers_count`, `forks_count`,
+   `open_issues_count`, `network_count`, `subscribers_count`, `size`, ...),
+   settings / merge flags (`has_*`, `allow_*`, `archived`, `disabled`,
+   `is_template`, `delete_branch_on_merge`, the squash/merge commit settings,
+   `pull_request_creation_policy`, ...), and metadata (`homepage`, `language`,
+   `mirror_url`, `license`, `topics`, `visibility`, `permissions`,
+   `temp_clone_token`, `custom_properties`, `organization`,
+   `security_and_analysis`). Repo objects embed under `head.repo` / `base.repo` /
+   `repository`; leaf-key matching covers every nesting. On an L1 read surface such
+   an upstream-only omission is an accepted divergence (INFO), not drift.
+7. **Collaborator objects omit per-collaborator permission metadata.**
+   `GET /repos/:o/:r/collaborators` objects omit the per-collaborator `permissions`
+   map and `role_name`: the twin does not model collaborator permission filtering.
+   On an L1 read surface this upstream-only omission is an accepted divergence
+   (INFO), not drift. Agents that branch on a collaborator's permission level
+   should treat this surface as shape-only until the twin models it.
+8. **Issue objects omit timeline/reaction/milestone metadata.** The twin's issue
+   object omits `milestone`, `author_association`, `type`, `active_lock_reason`,
+   `draft`, `pull_request`, `closed_by`, `reactions`, `performed_via_github_app`,
+   `state_reason`, `issue_field_values`, `sub_issues_summary`,
+   `issue_dependencies_summary`, `pinned_comment` (and the search-only `score` /
+   `search_type`): timelines, reactions, milestones, and projects are not modeled.
+   On an L1 read surface (`GET /repos/:o/:r/issues`, `.../issues/:n`,
+   `GET /search/issues`) these upstream-only omissions are accepted (INFO), not drift.
+9. **Commit objects omit comment-count and signature verification.** The twin's
+   commit object omits the nested `commit.comment_count` and `commit.verification`
+   (GPG signature) leaves: commit comments and signature verification are not
+   modeled. On an L1 read surface (`GET /repos/:o/:r/commits`, `.../commits/:ref`,
+   `.../compare/:basehead`, `.../pulls/:n/commits`) these are accepted (INFO), not drift.
+10. **Branch objects omit protection and inlined commit detail.** The twin's branch
+    object omits `protection` (branch protection is not modeled — see bullet 4) and,
+    on the branch-detail surfaces, the full-commit leaves GitHub inlines (`node_id`,
+    `commit`, `author`, `committer`, `parents`). On an L1 read surface
+    (`GET /repos/:o/:r/branches`, `.../branches/*`) these upstream-only omissions are
+    accepted (INFO), not drift.
+11. **Pull-request objects omit assignee/review/mergeability metadata.** The twin's
+    pull-request object omits `assignees`, `requested_reviewers`, `requested_teams`,
+    `labels`, `auto_merge`, `author_association` and (on the detail surface)
+    `mergeable`, `rebaseable`, `mergeable_state`, `merged_by`, `comments`,
+    `review_comments`, `maintainer_can_modify`: mergeability jobs, review decisions,
+    and label/assignee modeling are simplified. On an L1 read surface
+    (`GET /repos/:o/:r/pulls`, `.../pulls/:n`) these upstream-only omissions are
+    accepted (INFO), not drift.
+12. **Pull-request `merge_commit_sha` is GitHub's ephemeral test-merge commit.**
+    `merge_commit_sha` is the sha GitHub computes by speculatively merging the PR
+    head into the base to test mergeability — non-deterministic and not a commit in
+    either branch's history. The twin does not model that background job, so it
+    returns `null` where real GitHub returns a transient sha. On an L1 read surface
+    (`GET /repos/:o/:r/pulls`, `.../pulls/:n`) this is an accepted divergence (INFO),
+    not drift — the twin cannot reproduce an ephemeral, GitHub-internal artifact.
+13. **Issue `assignee` reflects the controlled-sandbox seed, not real GitHub.** The
+    singular `assignee` is null on real GitHub for the seeded sandbox (the seed's
+    route-A capture dropped the fictional assignees), while the twin returns its
+    seeded assignee object. On an L1 read surface (`GET /repos/:o/:r/issues`,
+    `.../issues/:n`) this seed-state difference is an accepted divergence (INFO), not
+    drift — the twin faithfully reflects its own seeded assignment.
+14. **`GET /user` is the seeded agent, not the golden's token owner.** `GET /user`
+    returns the authenticated token owner; the upstream golden is the human token
+    owner, the twin its seeded agent user. The identity leaves `blog` (real `""` vs
+    twin `null`) and `email` (real `null` vs twin's seeded address) therefore differ.
+    On this L1 read surface that is an accepted identity divergence (INFO), not drift.
+15. **`search_users` `type` reflects the local seed, not GitHub's global result set.**
+    `GET /search/users` against real GitHub is a global search whose items span real
+    users and organizations, so the `type` enum holds both `"User"` and
+    `"Organization"`. The twin searches only its local seed (the single user `alice`,
+    `type "User"` — the same value real GitHub returns for that login), so the enum
+    differs only because the local result set has no organizations. On this L1 read
+    surface that is an accepted result-set divergence (INFO), not drift — not a wrong
+    enum or casing in the serializer.
+16. **`GET /issues` excludes PRs that real GitHub models as issues (genuine gap).** Real
+    GitHub models pull requests as issues, so `GET /repos/:o/:r/issues` includes the
+    repo's open PR (with a `pull_request` member) — 3 items where the twin returns 2. The
+    twin's `/issues` excludes PRs; a faithful twin would include them. Fixing the twin is
+    out of scope, but the array-aware oracle (FDRS-455) now SEES the item-count
+    divergence: registered as accepted on the collection root so this L1 read surface is
+    INFO, not drift, and flagged as a genuine twin-fidelity gap for follow-up.
+17. **Issue `assignees`/`labels` arrays reflect the controlled-sandbox seed, not real GitHub.**
+    The plural `assignees` and the `labels` arrays are non-empty on the twin (its seeded
+    fictional assignee/label) but empty on real GitHub for the seeded sandbox — the same
+    route-A seed-state cause as the singular `assignee` (bullet 13). On the issue read
+    surfaces this array-length difference is an accepted divergence (INFO), not drift.
+18. **`/search/*` result-set item counts reflect the local seed, not GitHub's global index.**
+    A GitHub search is global (millions of matches, 30 per page); the twin searches only
+    its local seed and returns the few local matches. The `items` count (and the per-item
+    `labels` count inside a globally-returned issue) differ for the same global-vs-local
+    result-set reason as the `search_users` `type` (bullet 15). On the `/search/*` read
+    surfaces these length differences are accepted (INFO), not drift.
+19. **Commit `parents`/`files` and commit-list counts reflect the seeded sandbox git history.**
+    The commits-collection length, per-commit `parents` count (seeded commits are roots,
+    0 vs 1), and per-commit `files` changed-set count differ because the seeded sandbox's
+    git history is not a byte-for-byte mirror of the real repo's commit DAG. On the
+    `GET /repos/:o/:r/commits`, `.../commits/:ref`, `.../compare/:basehead` read surfaces
+    these length differences are accepted (INFO), not drift.
+20. **`/labels` and `/collaborators` list counts reflect the seeded sandbox content.**
+    The `/labels` (2 vs 10) and `/collaborators` (3 vs 2) collection counts reflect the
+    seeded sandbox's smaller label set and different collaborator set, not a serializer
+    bug. On these L1 read surfaces the item-count difference is an accepted divergence
+    (INFO), not drift.
+
+## How fidelity is verified
+
+Three independent checks back the tier classifications above. Each is a
+script you can run locally; CI runs the first two on every PR.
+
+### 1. Captured fixture shape tests (`bun run verify:fixtures`)
+
+The repository keeps sanitized response-shape fixtures captured from real
+GitHub via `gh api`. The verifier — driven by tests under
+`packages/twin-github/test/fixture-shape.test.ts` — boots the local twin,
+hits the equivalent local routes, and asserts the response shape matches
+the captured fixture (keys present, types compatible, optional vs required
+correct). Generated metadata (IDs, timestamps, URLs, SHAs) is allowed to
+differ; behavior-shape is not.
+
+Refresh the fixtures with `bun run capture:fixtures` when you have GitHub
+CLI auth available. The fixture set is the contract.
+
+### 2. MCP parity (`scripts/fidelity-parity.ts`)
+
+`scripts/fidelity-parity.ts` exercises all 62 MCP tools end-to-end against
+a freshly seeded local twin. It runs in two modes:
+
+- **Local-only** — every tool is invoked locally; success means the contract
+  surface is reachable and produces a well-typed response.
+- **Live read-only** — set `GITHUB_PARITY_REPO=owner/repo` and the script
+  additionally calls the same read-only endpoints on real GitHub via `gh
+  api`, asserting that response shape parity holds for the live target too.
+
+Run it: `bun run fidelity:parity`.
+
+### 3. Cross-twin review harness (`scripts/review-harness.ts`)
+
+`scripts/review-harness.ts` is a behavior harness — not a shape harness. It
+runs three end-to-end agent flows that exercise the corner cases agents
+usually trip on:
+
+- `functional-pr-flow`: create repo → branch → file → PR → approve → merge →
+  read merged file.
+- `negative-fidelity`: missing file must fail; creating a file must succeed;
+  stale `sha` update must fail.
+- `concurrency-stress`: eight concurrent writes to the same path; exactly
+  one create wins, the final file is readable.
+
+Point it at the local twin (`REVIEW_TARGET=local`) and all three tests should pass.
+
+See [`packages/twin-github/README.md`](README.md#review-harness) for auth model, MCP protocol shape, default seed, and error envelope details.
+
+### Filing a fidelity bug
+
+If you find a case where an agent's behavior diverges between real GitHub
+and the local twin in a way the tables above don't predict, open an issue
+with:
+
+1. The MCP tool or REST route involved.
+2. Minimal repro: the request, the local response, the GitHub response.
+3. Whether the divergence is shape (keys/types differ) or semantic (state
+   transition behaves differently).
+
+That's exactly the input we use to upgrade a tool from `shape` to
+`semantic`, or to add a new entry to **Known deviations** above.

package/node_modules/@pome-sh/twin-github/README.md

@@ -0,0 +1,256 @@
+# Pome Twin: GitHub
+
+> One of three twins in this repository (GitHub, Stripe x402, Slack).
+
+`@pome-sh/twin-github` is a local, stateful GitHub twin for agent testing. It exposes GitHub-shaped REST routes plus a 62-tool MCP-style API backed by the same SQLite domain services.
+
+## Quickstart
+
+```bash
+bun install
+bun run seed
+export TWIN_AUTH_SECRET=$(openssl rand -hex 32)
+bun run dev
+
+# Docker (from monorepo root; default compose service, port 3333):
+# docker compose up -d
+# curl http://127.0.0.1:3333/healthz
+```
+
+GitHub-shaped REST + MCP routes live under `/s/:sid/*` and require a
+bearer token whose `sid` claim matches the URL `:sid`. `/healthz` and
+`/admin/*` stay at the root (admin is localhost-only).
+
+```bash
+# Mint a token (32-char minimum secret recommended; use the SAME secret as the server)
+TOKEN=$(node -e "import('hono/jwt').then(m => m.sign({ sid: 'demo', team_id: 'tm_1', exp: Math.floor(Date.now()/1000)+3600 }, process.env.TWIN_AUTH_SECRET).then(t => console.log(t)))")
+
+# Public health probe — no auth
+curl http://127.0.0.1:3333/healthz
+
+# Session-scoped routes — auth required, sid in path must equal sid in claim
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:3333/s/demo/repos/acme/api/issues/1
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:3333/s/demo/mcp/tools
+
+curl -s -X POST http://127.0.0.1:3333/s/demo/mcp/call \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'content-type: application/json' \
+  -d '{"tool":"search_repositories","arguments":{"query":"acme"}}'
+```
+
+The default seed creates:
+
+- `acme/api`
+- default branch `main`
+- files `README.md` and `src/index.ts`
+- labels `bug`, `feature`, and `question`
+- issue `#1`, titled `500 error on POST /orders after deploy`
+- users/orgs `acme`, `alice`, `bob`, and `pome-agent`
+
+## APIs
+
+- REST base URL: `http://127.0.0.1:3333`
+- **Real MCP (JSON-RPC, Streamable HTTP, stateless):** `POST /s/:sid/mcp`
+  — speaks the protocol the `@modelcontextprotocol/sdk` `Client` +
+  `StreamableHTTPClientTransport` expect (`initialize`, `tools/list`,
+  `tools/call`, `ping`, `notifications/*`). 62 tools exposed via
+  `tools/list` with camelCase `inputSchema`.
+- Legacy custom MCP routes (compat surface for already-deployed agents):
+  - `GET  /s/:sid/mcp/tools` — returns `{ tools: [{ name, description, input_schema }, ...] }`
+  - `POST /s/:sid/mcp/tools/:name` — body is the tool's arguments object
+  - `POST /s/:sid/mcp/call` — body `{ tool, arguments }`
+
+All session-scoped REST and MCP routes require a bearer token whose `sid`
+claim matches the path. Mutating operations write to SQLite inside transactions
+and append to `audit_log`.
+
+### Connecting from `@modelcontextprotocol/sdk` or the Anthropic Agent SDK
+
+```ts
+// Anthropic claude-agent-sdk mcpServers config
+mcpServers: {
+  github: {
+    type: "http",
+    url: `${TWIN_BASE_URL}/s/${sid}/mcp`,
+    headers: { Authorization: `Bearer ${token}` }
+  }
+}
+```
+
+The endpoint is stateless: each POST is independent; no `Mcp-Session-Id`
+round-trip, no SSE. `GET` and `DELETE` on `/s/:sid/mcp` return 405. The
+bearer-auth contract is unchanged — the JWT `sid` claim (or
+`ghp_pome_<sid>_<hmac>` PAT) still has to match the path's `:sid`.
+
+### Tracing parity
+
+Every `tools/call` reaching `/s/:sid/mcp` produces one recorder event whose
+`request_body` is `{ tool, arguments }` and whose `response_body` is the raw
+domain return — byte-identical to what `POST /s/:sid/mcp/call` records. The
+only intentional difference is `path`. Run `bun run validate:mcp` to
+regenerate the side-by-side diff in `scripts/validate-mcp.output.txt`.
+
+## Runtime contract (for snapshot consumers)
+
+`pome-cloud` builds a Vercel Sandbox snapshot from this package's source. The
+following constraints must hold for that build to succeed and for the resulting
+snapshot to boot. Changing any of these is a breaking change for hosted; coordinate
+via a cross-repo PR.
+
+### Build
+
+- Package is `npm install`-able from `package.json` alone (no `workspace:*`
+  protocols, no bun-only deps; no committed lockfile is required, the snapshot
+  build regenerates one on each rebuild)
+- `npm run build` exits 0 and emits `dist/src/server.js`
+- Built output is loadable under Node 22 — the snapshot runs `runtime: "node22"`.
+  No Bun-only N-API consumers (see oven/bun#4290 for context on `better-sqlite3`).
+
+### Runtime
+
+- Server entry: `node dist/src/server.js` (cwd = package root)
+- Listens on `:3333`
+- Honors `GITHUB_CLONE_HOST=0.0.0.0` env (default `127.0.0.1` is unreachable
+  via Vercel Sandbox port forwarding)
+- `GET /healthz` returns 200 within ~3s of process start (the snapshot build
+  sleeps 3s after `node dist/src/server.js` before probing)
+- All admin routes are localhost-only (`/admin/*`)
+- Bearer auth at `Authorization: Bearer <jwt>` per `src/auth.ts`
+
+### Cross-repo coordination
+
+- Bumping any of the above = open a cross-repo PR (this repo + `pome-cloud`)
+- The cloud-side snapshot build script lives at
+  `pome-cloud/notes/poc-vercel-sandbox/build-twin-github-template.ts`
+- The snapshot manifest at `pome-cloud/notes/poc-vercel-sandbox/twin-snapshot.json`
+  records the OSS git sha each snapshot was built from
+
+## Review harness
+
+The side-by-side review uses three tests:
+
+- `functional-pr-flow`: create repo, create branch, write file, open PR, approve PR, merge PR, read merged file.
+- `negative-fidelity`: missing file must fail, creating a file must succeed, stale update with the wrong `sha` must fail.
+- `concurrency-stress`: eight concurrent writes to the same file path; exactly one create should win and the final file should be readable.
+
+Run against local:
+
+```bash
+PORT=3333 GITHUB_CLONE_DB=.github_clone/review-harness.db bun run dev
+REVIEW_TARGET=local bun run review:harness
+```
+
+Keep agent assertions behavior-based: compare invariants (PR merged, stale `sha` rejected), not hard-coded IDs or SHAs.
+
+## Use In A New Project
+
+1. Install and start the twin:
+
+```bash
+cd ~/pome/packages/twin-github
+bun install
+GITHUB_CLONE_DB=.github_clone/my-project.db bun run dev
+```
+
+2. Reset or seed state before each run:
+
+```bash
+curl -X POST http://127.0.0.1:3333/admin/reset
+```
+
+For a project-specific seed, post JSON to `/admin/seed`:
+
+```bash
+curl -s -X POST http://127.0.0.1:3333/admin/seed \
+  -H 'content-type: application/json' \
+  -d '{
+    "users": [
+      { "login": "my-org", "type": "Organization", "name": "My Org" },
+      { "login": "agent-user", "type": "User", "name": "Agent User" }
+    ],
+    "repositories": [
+      {
+        "owner": "my-org",
+        "name": "my-app",
+        "description": "Repository under test",
+        "default_branch": "main",
+        "collaborators": ["agent-user"],
+        "labels": [
+          { "name": "bug", "color": "d73a4a", "description": "Something is broken" }
+        ],
+        "files": [
+          { "path": "README.md", "content": "# My App\n" },
+          { "path": "src/index.ts", "content": "export const ok = true;\n" }
+        ],
+        "issues": [
+          {
+            "number": 1,
+            "title": "Fix checkout error",
+            "body": "Users see a 500 after submitting checkout.",
+            "labels": ["bug"],
+            "assignees": []
+          }
+        ]
+      }
+    ]
+  }'
+```
+
+3. Give your agent these inputs:
+
+- `POME_GITHUB_REST_URL=http://127.0.0.1:3333`
+- `POME_GITHUB_MCP_URL=http://127.0.0.1:3333/s/demo/mcp`
+- `GITHUB_MCP_TOKEN=<JWT whose sid claim is demo>`
+- task text that names the exact repo, branch, issue, file, or PR it should touch
+- the expected actor, usually `pome-agent`
+- whether it should use REST or MCP
+
+4. Keep agent assertions behavior-based:
+
+- good: "PR was merged and `claude-agent.txt` exists on `main`"
+- good: "wrong `sha` update fails"
+- bad: "PR number is exactly `1`"
+- bad: "commit SHA equals this hard-coded value"
+
+## Claude Agent Example
+
+`examples/claude-github-agent.ts` is a tiny Claude-powered GitHub agent. It reads `ANTHROPIC_API_KEY` and `ANTHROPIC_MODEL` from `../discord/.env` or from the process environment.
+
+Run against local:
+
+```bash
+GITHUB_MCP_URL=http://127.0.0.1:3333/s/demo/mcp bun run agent:claude -- \
+  "Create a branch, push claude-agent.txt, open a pull request, approve it, and merge it in acme/api."
+```
+
+The example captures the PR number returned by `create_pull_request` and reuses it for review and merge calls.
+
+## Local Commands
+
+```bash
+bun run typecheck
+bun test
+bun run smoke
+bun run verify:fixtures
+bun run fidelity:parity
+bun run validate:mcp # rewrites scripts/validate-mcp.output.txt
+bun run review:harness
+bun run agent:claude
+```
+
+`bun run capture:fixtures` uses `gh api` to refresh sanitized response-shape fixtures when GitHub CLI auth is available.
+
+## Pome CLI Entry Point
+
+The user-facing `pome` CLI lives at [`cli/`](../../cli/) in this repo. From `cli/`:
+
+```bash
+bun run dev -- twin start github --port 3333
+```
+
+The command prints:
+
+```bash
+POME_GITHUB_REST_URL=http://127.0.0.1:3333
+POME_GITHUB_MCP_URL=http://127.0.0.1:3333/s/<sid>/mcp
+```