@pome-sh/cli 0.3.0 → 0.4.0

package/node_modules/@pome-sh/twin-gmail/node_modules/@pome-sh/shared-types/dist/task.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// shared-types §3 — TASKS. Task config, the parsed task markdown shape, and the
+// persisted task row, plus their deprecated `scenario*` aliases. The provider
+// seed-state schemas consumed by `taskSchema.seedState` live in `./seed-state.ts`.
+// Re-exported through the `@pome-sh/shared-types` barrel (index.ts).
+import { z } from "zod";
+import { criterionSchema, judgeModelSchema } from "./run.js";
+import { seedStateSchema } from "./seed-state.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// 3. TASKS (formerly "scenarios") — originally adopted verbatim from
+//    oslo/pome/src/scenario/scenarioSchema.ts
+//
+// W3 vocab (FDRS-653): "task" is the canonical name; the `scenario*` exports
+// below are deprecated aliases kept for the 0.3.0 window (FDRS-654 swaps the
+// consumers).
+//
+// `criterionSchema` and `judgeModelSchema` were moved to `./run.ts` (2026-05-11
+// split) because CriterionResult depends on them; imported here from `./run.js`
+// and re-exported to consumers via the index.ts barrel.
+// ─────────────────────────────────────────────────────────────────────────────
+export const taskConfigSchema = z.object({
+    twins: z.array(z.string()).default(["github"]),
+    timeout: z.number().int().positive().default(60), // seconds
+    runs: z.number().int().positive().default(1),
+    passThreshold: z.number().min(0).max(100).default(100),
+    judge: judgeModelSchema.default("claude-haiku-4-5"), // CLI's BYOK config decides which endpoint serves this
+});
+/** @deprecated FDRS-653 — use `taskConfigSchema`. Removed after the 0.3.0 window. */
+export const scenarioConfigSchema = taskConfigSchema;
+// The parsed task (formerly "scenario") markdown shape. Criterion kinds inside
+// `criteria` normalize D→code, P→model (tolerant reader, FDRS-653).
+export const taskSchema = z.object({
+    slug: z.string().min(1),
+    title: z.string().min(1),
+    setup: z.string().default(""), // human-readable prose; ignored at runtime
+    prompt: z.string().min(1),
+    expectedBehavior: z.string().default(""), // evaluator-only, NEVER sent to agent
+    criteria: z.array(criterionSchema).min(1),
+    config: taskConfigSchema,
+    seedState: seedStateSchema,
+});
+/** @deprecated FDRS-653 — use `taskSchema`. Removed after the 0.3.0 window. */
+export const scenarioSchema = taskSchema;
+// Persisted Task row (dashboard upload path; cloud DB `tasks` table). Per
+// 04-data-model.md. Row ids keep the historical `scn_` prefix (persisted data;
+// renaming ids is a data migration, deliberately NOT part of FDRS-653).
+export const persistedTaskSchema = z.object({
+    id: z.string(), // scn_<nanoid>
+    team_id: z.string(),
+    name: z.string(),
+    source: z.string(), // raw markdown
+    source_hash: z.string(), // sha256(source)
+    uploaded_by: z.string(), // user_id
+    created_at: z.string().datetime(),
+    archived_at: z.string().datetime().nullable(),
+});
+/** @deprecated FDRS-653 — use `persistedTaskSchema`. Removed after the 0.3.0 window. */
+export const persistedScenarioSchema = persistedTaskSchema;
+//# sourceMappingURL=task.js.map

package/node_modules/@pome-sh/twin-gmail/node_modules/@pome-sh/shared-types/dist/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../src/task.ts"],"names":[],"mappings":"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"}

package/node_modules/@pome-sh/twin-gmail/node_modules/@pome-sh/shared-types/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@pome-sh/shared-types",
+  "version": "0.11.0",
+  "description": "Shared wire-format contract for Pome — Zod schemas for traces, recorder events, runs, OTel mapping, and secret redaction.",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./recorder-events": {
+      "types": "./dist/recorder-events.d.ts",
+      "default": "./dist/recorder-events.js"
+    },
+    "./run": {
+      "types": "./dist/run.d.ts",
+      "default": "./dist/run.js"
+    },
+    "./otel": {
+      "types": "./dist/otel/index.d.ts",
+      "default": "./dist/otel/index.js"
+    },
+    "./otel/fixtures": {
+      "types": "./dist/otel/fixtures/index.d.ts",
+      "default": "./dist/otel/fixtures/index.js"
+    },
+    "./redaction": {
+      "types": "./dist/redaction.d.ts",
+      "default": "./dist/redaction.js"
+    }
+  },
+  "files": [
+    "dist",
+    "trace-contract.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pome-sh/digital-twins.git",
+    "directory": "packages/shared-types"
+  },
+  "homepage": "https://github.com/pome-sh/digital-twins/tree/main/packages/shared-types",
+  "bugs": {
+    "url": "https://github.com/pome-sh/digital-twins/issues"
+  },
+  "peerDependencies": {
+    "zod": "^4.1.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/node_modules/@pome-sh/twin-gmail/node_modules/@pome-sh/shared-types/trace-contract.json

@@ -0,0 +1,41 @@
+{
+  "package": "@pome-sh/shared-types",
+  "version": "0.11.0",
+  "zod": {
+    "range": "^4.1.13",
+    "major": 4
+  },
+  "exports": {
+    "root": "@pome-sh/shared-types",
+    "recorderEvents": "@pome-sh/shared-types/recorder-events",
+    "run": "@pome-sh/shared-types/run",
+    "otel": "@pome-sh/shared-types/otel",
+    "redaction": "@pome-sh/shared-types/redaction"
+  },
+  "canonicalSchemas": [
+    "recorderEventSchema",
+    "eventSchema",
+    "otelEventSchema",
+    "runSchema"
+  ],
+  "fixtures": [
+    "test/fixtures/v1/createSessionRequest/multi-twin-permissive-seed-idempotency.json",
+    "test/fixtures/v1/createSessionRequest/scenario-source-github.json",
+    "test/fixtures/v1/createSessionRequest/stored-scenario.json",
+    "test/fixtures/v1/createSessionRequestTaskVocab/stored-task.json",
+    "test/fixtures/v1/createSessionRequestTaskVocab/task-source-github.json",
+    "test/fixtures/v1/createSessionResponse/full-multi-twin.json",
+    "test/fixtures/v1/createSessionResponse/legacy-single-twin.json",
+    "test/fixtures/v1/planTier/enterprise.json",
+    "test/fixtures/v1/planTier/free.json",
+    "test/fixtures/v1/planTier/hobby.json",
+    "test/fixtures/v1/planTier/pro.json",
+    "test/fixtures/v1/planTier/self_host_annual.json",
+    "test/fixtures/v1/planTier/team.json",
+    "test/fixtures/v1/run/full-production.json",
+    "test/fixtures/v1/run/legacy-minimal.json",
+    "test/fixtures/v1/runTaskVocab/full-production-task-vocab.json",
+    "test/fixtures/v1/usage/free-tier.json",
+    "test/fixtures/v1/usage/team-tier-exhausted.json"
+  ]
+}

package/node_modules/@pome-sh/twin-gmail/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@pome-sh/twin-gmail",
+  "version": "0.1.0",
+  "description": "Deterministic Gmail-shaped twin for agent testing — SQLite-backed domain core.",
+  "private": false,
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./server": {
+      "types": "./dist/src/server.d.ts",
+      "default": "./dist/src/server.js"
+    },
+    "./*": {
+      "types": "./dist/src/*.d.ts",
+      "default": "./dist/src/*.js"
+    }
+  },
+  "bin": {
+    "twin-gmail": "./dist/src/server.js"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "HOSTED.md",
+    "LIMITS.md",
+    "README.md",
+    "REFERENCE-DIVERGENCES.md",
+    "fidelity.inventory.json",
+    "fixtures/README.md",
+    "fixtures/gmail-discovery-v1.meta.json",
+    "fixtures/gmail-discovery-v1.raw.json",
+    "fixtures/mcp-initialize.meta.json",
+    "fixtures/mcp-initialize.raw.json",
+    "fixtures/mcp-tools-call-unauth-error.raw.json",
+    "fixtures/mcp-tools-call.representative.json",
+    "fixtures/mcp-tools-list.canonical.json",
+    "fixtures/mcp-tools-list.meta.json",
+    "fixtures/mcp-tools-list.raw.json",
+    "fixtures/rest-surface.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pome-sh/sdk": "0.5.0",
+    "hono": "^4.12.27",
+    "zod": "^4.1.13"
+  },
+  "keywords": [
+    "gmail",
+    "twin",
+    "test-double",
+    "agent-testing",
+    "pome",
+    "mcp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pome-sh/digital-twins.git",
+    "directory": "packages/twin-gmail"
+  },
+  "homepage": "https://github.com/pome-sh/digital-twins/tree/main/packages/twin-gmail",
+  "bugs": {
+    "url": "https://github.com/pome-sh/digital-twins/issues"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=24"
+  }
+}

package/node_modules/@pome-sh/twin-linear/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @pome-sh/twin-linear — CHANGELOG
+
+## 0.1.0 — 2026-07-21
+
+First public release of the deterministic Linear twin:
+
+- Frozen GraphQL + OAuth surface with SQLite-backed LinearCommands.
+- Captured twenty-tool first-party Linear MCP listing and structured results.
+- Deterministic seed/reset, webhooks log, bounded state export, and recorder
+  payload projection.
+- CLI, scenario, runtime-contract, package, and signed-image integration.
+
+Authentication is Pome-owned for hosted runs. Local seeds include
+`lin_test_admin` for `resolveCredential`, and `POME_LINEAR_TOKEN` aliases the
+session JWT. There is no `provider_credentials.linear` contract.

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

@@ -0,0 +1,62 @@
+# Linear twin fidelity
+
+Heat × fidelity per [`ENDPOINT-TIERS.md`](../sdk/ENDPOINT-TIERS.md). Machine-readable twin: [`fidelity.inventory.json`](fidelity.inventory.json).
+
+## MCP launch tools (22)
+
+| Surface | Heat | Fidelity | Justification |
+| --- | --- | --- | --- |
+| `list_issues` | hot | semantic | `TC:issue-triage`; `MCP:list_issues` |
+| `get_issue` | hot | semantic | `TC:issue-triage`; `MCP:get_issue` |
+| `save_issue` | hot | semantic | `TC:issue-create\|issue-triage`; estimate/parentId/relations |
+| `list_comments` | hot | semantic | `TC:comment`; `MCP:list_comments` |
+| `save_comment` | hot | semantic | `TC:comment`; threaded `parentId` |
+| `delete_comment` | warm | semantic | Gate-1; GraphQL `commentDelete` parity |
+| `list_teams` | hot | semantic | `TC:issue-create`; `MCP:list_teams` |
+| `get_team` | warm | shape | `MCP:get_team` |
+| `list_users` | hot | semantic | `TC:issue-create`; `MCP:list_users` |
+| `get_user` | warm | shape | `MCP:get_user` |
+| `list_issue_statuses` | hot | semantic | `TC:issue-triage`; `MCP:list_issue_statuses` |
+| `get_issue_status` | warm | shape | `MCP:get_issue_status` |
+| `list_issue_labels` | hot | semantic | `TC:issue-triage`; `MCP:list_issue_labels` |
+| `create_issue_label` | warm | shape | `MCP:create_issue_label` |
+| `list_projects` | warm | semantic | SQLite project CRUD + issue linkage |
+| `get_project` | warm | semantic | SQLite project CRUD + issue linkage |
+| `save_project` | warm | semantic | SQLite project create/update |
+| `list_cycles` | warm | semantic | SQLite cycle list + issue linkage |
+| `search_documentation` | cold | shape | `MCP:search_documentation` — static/empty twin docs |
+| `list_documents` | warm | semantic | Gate-1 workspace documents (SQLite) |
+| `get_document` | warm | semantic | Gate-1 workspace documents (SQLite) |
+| `save_document` | warm | semantic | Gate-1 create/update with one parent |
+
+## GraphQL (selected)
+
+| Surface | Heat | Fidelity | Justification |
+| --- | --- | --- | --- |
+| `issues` / `issue` / issue mutations | hot | semantic | `TC:issue-triage\|issue-create`; estimate/parent |
+| `comments` / comment mutations | hot | semantic | `TC:comment`; threaded parent; `commentDelete` |
+| `teams` / `users` / `workflowStates` | hot | semantic | Context for agent chains |
+| `issueLabels` / label mutations | hot | semantic | Triage labels |
+| `projects` / `cycles` | warm | semantic | PM context backed by SQLite domain |
+| `webhooks` / webhook mutations | hot | semantic | `TC:webhook-integrate` |
+| agent session / activity mutations | warm | semantic | Emulate agent subset; MCP-absent |
+| OAuth authorize/token/revoke | hot | semantic | `TC:oauth-app` |
+
+## Named cold / unsupported
+
+| Surface | Heat | Fidelity | Notes |
+| --- | --- | --- | --- |
+| Initiatives / milestones / releases MCP | cold | unsupported | Outside Gate-1 tool set |
+| Full Linear schema tail | cold | unsupported | Loud GraphQL / 501 |
+| Document parents: initiative | cold | unsupported | Twin accepts project/team/issue/cycle only |
+
+## Opt-in OAuth scope denial
+
+`seed.strictScopes` defaults to `false`. Enable it for tasks that mint
+restricted tokens and expect Linear-like scope errors. With the flag on, GraphQL
+and MCP writes share `LinearDomain.requireScopes`. JWT / provider sessions are
+granted the full default scope set so common agent paths stay unblocked.
+
+## Tier-mismatch ledger
+
+_(empty at launch)_

package/node_modules/@pome-sh/twin-linear/HOSTED.md

@@ -0,0 +1,46 @@
+# Hosted Linear handoff
+
+OSS package + CLI are release-ready independently of hosted support. Use this
+checklist to split **OSS-ready** work from **cloud-owned** gating. No cloud
+imports belong in this package.
+
+## OSS-ready (this repo)
+
+| Item | Status / note |
+| --- | --- |
+| Package `@pome-sh/twin-linear` | Deterministic domain, GraphQL, launch MCP tools |
+| Registry id | `linear` (twin id / CLI `--twin linear`) |
+| JWT claim | `linear_email` — default admin `admin@pome-twin.test` |
+| Agent token env | `POME_AUTH_TOKEN` + alias `POME_LINEAR_TOKEN` (same JWT) |
+| Local tokens | Seeded personal tokens (e.g. `lin_test_admin`) via `resolveCredential` |
+| Seed / admin | `/admin/seed`, `/admin/reset`, `/_pome/state`, `/_pome/events` |
+| Image tag family | `ghcr.io/pome-sh/twins:linear-*` (publish after CI + secret-scan) |
+| Local tasks | Issue triage; multi-twin with GitHub |
+| Fidelity artifacts | `fidelity.inventory.json`, `FIDELITY.md`, fixtures under `fixtures/` |
+
+## Cloud-owned (Pome Cloud — not this repo)
+
+Complete before advertising hosted Linear:
+
+1. **Registry** — Add `linear` to the mounted/provisionable twin registry and
+   consume `@pome-sh/shared-types` with `linearSeedStateSchema`.
+2. **JWT claims** — Mint the session JWT with
+   `linear_email: "admin@pome-twin.test"` by default, or the normalized
+   primary admin email from the accepted Linear seed.
+3. **Credentials** — Do **not** add `provider_credentials.linear`. Return the
+   normal `agent_token`; clients expose it as both `POME_AUTH_TOKEN` and
+   `POME_LINEAR_TOKEN`. Seeded personal tokens remain a local/dev convenience.
+4. **Digest routing** — Route the signed `ghcr.io/pome-sh/twins:linear-*`
+   digest (cosign-verify + pin). Publish Linear `api_url`, `mcp_url`, and
+   `openapi_url` under `per_twin.linear`.
+5. **Pod seed / capture** — Forward the Linear seed unchanged to the pod,
+   capture `/_pome/state` and `/_pome/events`, retain OAuth/token projection
+   redaction.
+6. **Hosted verification** — Run official-client, launch-tool MCP parity, and
+   multi-twin tasks against the hosted route before enabling the product
+   flag.
+7. **Fidelity watch** — Register the signed digest on the fidelity
+   dashboard/watch list.
+
+Until that gate passes, documentation must describe Linear as **local/OSS-ready**,
+not hosted-ready.

package/node_modules/@pome-sh/twin-linear/LIMITS.md

@@ -0,0 +1,54 @@
+# Domain limits
+
+Pinned limits enforced by seed, GraphQL, MCP, and OAuth paths.
+
+| Limit | Value | Notes |
+| --- | --- | --- |
+| Issue title bytes | `512` | Loud reject above |
+| Issue / comment body bytes | `65536` | Loud reject above |
+| GraphQL query bytes | `100000` | Loud reject above |
+| GraphQL selection depth | `20` | Loud reject above |
+| Seed users / teams / issues | `500` / `50` / `5000` | Seed parse caps |
+| Seed labels / projects / cycles | `500` / `200` / `200` | Seed parse caps |
+| Seed documents | `500` | Seed parse caps |
+| Seed oauth apps / tokens / webhooks | `20` / `50` / `50` | Seed parse caps |
+| MCP `limit` / pageSize | default `50`, max `250` | list tools |
+| Relay `first`/`last` | default `50`, max `250` | GraphQL connections |
+| State export collection rows | `2000` | Newest webhook deliveries / agent activities when capped |
+| Webhook delivery log | newest `2000` | Truncation prefers newest |
+| OAuth code TTL | `600s` | From seed clock |
+| Access token TTL | `3600s` | From seed clock unless seed overrides |
+
+See `performanceBudgets` in [`fidelity.inventory.json`](fidelity.inventory.json).
+
+## Scopes
+
+- OAuth/API token **scope denial is opt-in fidelity**: set `seed.strictScopes: true`.
+  The default (`false`) matches other twins — auth gate is always on; fine-grained
+  Linear scopes are not enforced unless a task opts in.
+- When `strictScopes` is on, write mutators call `requireScopes` (`write`,
+  `issues:create`, `comments:create`; `admin` bypasses). JWT / `lin_pome_*`
+  sessions receive the full default scope set.
+
+## Webhooks
+
+- Outbound delivery enforces a **default-deny SSRF policy**: loopback, private,
+  link-local (incl. the `169.254.169.254` cloud metadata endpoint), unique-local,
+  and other non-public destinations are refused at dispatch time, validated
+  against the host's *resolved* addresses (a public name that resolves to an
+  internal IP is blocked too). Refused attempts are logged with
+  `error: "blocked_destination"` and never leave the process.
+- Loopback/private delivery for trusted lab callbacks (often `127.0.0.1`) is
+  opt-in via `LINEAR_TWIN_ALLOW_PRIVATE_WEBHOOKS=1` — an operator/deployment
+  trust decision, never settable by the agent under test.
+- URLs must be `http`/`https` without embedded credentials.
+- Delivery `fetch` also refuses redirects (`redirect: "error"`) so an allowed
+  public URL cannot bounce into link-local/metadata targets.
+
+## Recording notes
+
+- GraphQL and MCP writes go through `recorder.handle` / `reportDelta`.
+- Public OAuth (`/oauth/authorize`, `/oauth/token`, `/oauth/revoke`) sits outside
+  bearerAuth via `withPublicOAuth` and is **not** wrapped in `recorder.handle`.
+  Secrets must stay out of `/_pome/state` and any incidental recorder payloads;
+  covered by the OAuth canary matrix.

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

@@ -0,0 +1,107 @@
+# `@pome-sh/twin-linear`
+
+Deterministic Linear-shaped twin for agent testing (Pome).
+
+**Status: OSS release candidate.** This package includes the deterministic
+SQLite workspace model, strict seed/reset APIs, GraphQL + OAuth surfaces,
+bounded semantic state export, recording projection, and the captured
+twenty-two-tool first-party MCP contract (Gate 0 launch + Gate-1 Wave 4).
+
+## Auth identity (frozen)
+
+| Item | Value |
+| --- | --- |
+| Claim | `linear_email` on the Pome session JWT |
+| Default local email | `admin@pome-twin.test` |
+| Agent token env | `POME_LINEAR_TOKEN` (alias of `POME_AUTH_TOKEN`) |
+| Seeded personal token | `lin_test_admin` (resolved via `resolveCredential`) |
+| Provider token prefix | `lin_pome_` |
+| Bearer | Pome session JWT, seeded Linear tokens, or `lin_pome_*` |
+
+Pome owns hosted authentication. Local runs also accept DB-backed Linear API
+tokens from the seed for official-client parity.
+
+## Gate 0 / Gate-1 artifacts
+
+| Path | Role |
+| --- | --- |
+| [`fixtures/graphql-surface.json`](fixtures/graphql-surface.json) | Frozen GraphQL query/mutation/OAuth operation floor |
+| [`fixtures/mcp-tools-list.canonical.json`](fixtures/mcp-tools-list.canonical.json) | Official Linear MCP launch set (22 tools) |
+| [`fidelity.inventory.json`](fidelity.inventory.json) | Heat × fidelity × evidence for every launch MCP/GraphQL row |
+| [`REFERENCE-DIVERGENCES.md`](REFERENCE-DIVERGENCES.md) | Emulate rejected; never an oracle |
+| [`LIMITS.md`](LIMITS.md) | Seed/GraphQL/MCP/state-export caps |
+
+See [`fixtures/README.md`](fixtures/README.md) for capture provenance.
+
+## Launch MCP tools (exactly 22)
+
+`list_issues`, `get_issue`, `save_issue`, `list_comments`, `save_comment`,
+`delete_comment`, `list_teams`, `get_team`, `list_users`, `get_user`,
+`list_issue_statuses`, `get_issue_status`, `list_issue_labels`,
+`create_issue_label`, `list_projects`, `get_project`, `save_project`,
+`list_cycles`, `search_documentation`, `list_documents`, `get_document`,
+`save_document`.
+
+These 22 are a **curated Gate-1 subset** of the official Linear MCP surface
+(which currently exposes ~50+ tools); order and names are frozen to match it
+(`save_*` upserts). Everything outside the subset is a named gap below, not a
+silent success. GraphQL still exposes `issueCreate`/`issueUpdate` for SDK
+parity.
+
+## Named gaps (not fake success)
+
+MCP tool families outside the 22-tool Gate-1 subset are not implemented:
+
+- Initiatives (`*_initiative*`), milestones (`*_milestone`), releases
+  (`*_release*`), attachments (`*_attachment*`), git diffs / PR review
+  (`*_diff*`, `merge_diff`, `submit_diff_review`), status updates
+  (`*_status_update`), agent skills (`*_agent_skill*`), and
+  `list_project_labels`
+- Implemented tools still omit some real parameters (e.g. `save_issue`
+  omits `milestone` / dueDate via MCP; `save_document` omits initiative parents)
+- Full Linear GraphQL schema tail — loud unsupported / 501
+- External webhook delivery beyond logged attempts
+
+## Non-goals
+
+- Live Linear network calls
+- Expanding MCP beyond the frozen 22-tool Gate-1 set without a new ruling
+- Hosted product enablement (see [`HOSTED.md`](HOSTED.md))
+
+## Limits
+
+See [`LIMITS.md`](LIMITS.md). Defaults/maxima are pinned in
+`fidelity.inventory.json` `performanceBudgets`.
+
+## Stateful parity with other first-party twins
+
+Linear follows the same SDK chassis as GitHub / Slack / Stripe / Gmail:
+
+| Capability | Linear | Notes vs peers |
+| --- | --- | --- |
+| `defineTwin` + SQLite domain | yes | Same `@pome-sh/sdk` boot path |
+| `/_pome/state` | yes | Bounded collection rows |
+| `/_pome/events` + durable recorder | yes | `recordingProjection` redacts secrets |
+| `/admin/reset` + `/admin/seed` | yes | Reports `state_delta` |
+| MCP + GraphQL on one domain | yes | `LinearDomain` |
+| Session identity claim | `linear_email` | Peers use provider-shaped claims |
+| Root session mount | yes | `mountSessionAtRoot: true` |
+
+## Development
+
+```bash
+npm test -w @pome-sh/twin-linear
+npm run typecheck -w @pome-sh/twin-linear
+npm run fidelity:parity -w @pome-sh/twin-linear
+```
+
+## CLI
+
+```bash
+npx @pome-sh/cli twin start linear
+# prints POME_LINEAR_REST_URL, POME_LINEAR_MCP_URL, POME_AUTH_TOKEN,
+# and the identical POME_LINEAR_TOKEN alias
+```
+
+Use `pome scenarios linear --copy` for the issue-triage and comment+label
+tasks. Hosted rollout is gated separately; see [`HOSTED.md`](HOSTED.md).

package/node_modules/@pome-sh/twin-linear/REFERENCE-DIVERGENCES.md

@@ -0,0 +1,50 @@
+# Reference divergences — Emulate is not an oracle
+
+Emulate’s Linear package may be used as a **coverage checklist**. It is **never** a behavioral oracle for `@pome-sh/twin-linear`.
+
+## Oracles
+
+1. Frozen official Linear MCP launch listing → [`fixtures/mcp-tools-list.canonical.json`](fixtures/mcp-tools-list.canonical.json)
+2. Frozen GraphQL operation inventory → [`fixtures/graphql-surface.json`](fixtures/graphql-surface.json)
+3. Linear public GraphQL / OAuth / webhook docs
+4. `@linear/sdk` smoke tests against root `/graphql`
+5. This package’s invariants (SQLite, seed clock, null state_delta on no-ops, loud 501)
+
+## Explicitly rejected Emulate-known behaviors
+
+| Rejected behavior | Twin rule |
+| --- | --- |
+| In-memory Store nondeterminism | SQLite + deterministic ids from seed clock / sequences |
+| HTML inspector as product surface | `/_pome/state` digests only |
+| Silent stub success for unsupported fields | Loud GraphQL errors or 501 unsupported envelope |
+| Session-less opaque tokens without sid binding | Tokens table binds `sid`; root mount uses `resolveCredential` |
+
+## Offline fidelity notes
+
+| Surface | Official expectation | Twin behavior |
+| --- | --- | --- |
+| Issue archive | Soft archive with `archivedAt` | `issueArchive` / `issueUnarchive` set/clear timestamps |
+| OAuth actor | user vs app | Seed `oauth_apps[].actor` authoritative |
+| Webhook headers | `Linear-Delivery`, `Linear-Event`, optional `Linear-Signature` | Emitted on mutation dispatch |
+| Agent sessions | Subset for local agent tests | GraphQL-only create/update/activity (not in MCP launch set) |
+| MCP documents tools | Full parent set incl. initiative | Gate-1: project/team/issue/cycle parents only |
+| MCP tool count | ~50+ live tools | Frozen 22-tool Gate-1 subset |
+
+## Webhook asymmetries (documented Gate-0 gaps)
+
+These are intentional twin divergences — not silent stubs:
+
+| Mutation / path | Official-ish expectation | Twin behavior |
+| --- | --- | --- |
+| `agentSessionCreateOnIssue` | `AgentSessionEvent` create webhook | Emits webhook (`action: created`) |
+| `agentSessionCreateOnComment` | Same family as on-issue create | **No webhook** — session row only (mention path stays quiet) |
+| `createProject` / `updateProject` (MCP `save_project`) | Project create/update webhook | **No webhook emit** — projects mutate SQLite state only |
+| `agentActivityCreate` with `type: prompt` | Prompted session event | Emits `AgentSessionEvent` / `prompted` |
+| Issue / comment CRUD | Issue / Comment webhooks | Emitted (create/update/remove/archive) |
+
+## Other non-oracles
+
+- Real Linear.app network sync
+- Full GraphQL schema / introspection dump
+- Production rate limits, inbox, initiatives, customer APIs
+- Expanding MCP beyond the frozen 22-tool Gate-1 set without a new ruling