agentlinkops 0.6.8 → 0.6.10

package/skills/agentlinkops-connect/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agentlinkops-connect
 description: How to use AgentLinkOps correctly through its MCP tools, the agentlinkops CLI or HTTP. Load before the first AgentLinkOps tool call in a session, and whenever a task connects a client, picks an MCP view, finds a command, watches an earned link, reads a check result or evidence, or checks usage. Not for outreach, browsing or local ledger edits.
-allowed-tools: Read Bash(agentlinkops skill *) Bash(agentlinkops tools *) Bash(agentlinkops describe *) Bash(agentlinkops call *) Bash(agentlinkops agent *) Bash(agentlinkops doctor *)
+allowed-tools: Read Bash(agentlinkops skill *) Bash(agentlinkops check *) Bash(agentlinkops setup --plan *) Bash(agentlinkops tools *) Bash(agentlinkops describe *) Bash(agentlinkops call *) Bash(agentlinkops agent *) Bash(agentlinkops doctor *)
 ---
 
 # Connect to AgentLinkOps
@@ -14,9 +14,26 @@ AgentLinkOps stores verified backlink observations, monitoring history and evide
 
 ## Set up once
 
-`npx -y agentlinkops agent setup` installs this pack for each detected agent client and writes the MCP entry for the view that client should use; it stores no credential. Sign in through the client's OAuth flow. If the CLI is not installed, connect the client to `https://app.agentlinkops.com/mcp` by hand and let the person approve the workspace and scopes. `agentlinkops agent status` shows what is configured.
+Inspect `npx -y agentlinkops agent setup --help` for the installed version before selecting payloads. CLI 0.6.10 installs the connection skill and its reference by default, with MCP setup for detected clients. Select optional guidance explicitly. CLI 0.6.9 and earlier can install the complete pack. Native-client acceptance remains separate from package checks. Setup stores no credential.
 
-## Minimal example (after reading the reference)
+For a chosen hosted task, sign in through the client's OAuth flow. If the CLI is not installed, connect the client to `https://app.agentlinkops.com/mcp` by hand and let the person approve the workspace and scopes. `agentlinkops agent status` shows what is configured.
+
+## Check a supplied pair (after reading the reference)
+
+With an available CLI, use the person's chosen URLs as literal arguments:
+
+```sh
+agentlinkops check --source SOURCE_URL --target TARGET_URL --scope exact --json
+```
+
+When the person asks to save the portable result, add `--out FILE` with their
+chosen path, such as `--out native-result.json`. The command saves the portable
+JSON result and still prints it. Read the saved JSON before reporting its state,
+check date, coverage and evidence limits.
+
+This fetches the source page and returns an accountless observation. It needs no hosted connection, repository, ledger, CRM or publisher recipe. Read the structured state and evidence limits: exit zero means a result was returned, and unknown does not prove removal. A usage or configuration failure supplies no observation.
+
+## Hosted example (after reading the reference)
 
 1. `get_workspace` with `{}`: limits, usage and membership.
 2. `list_projects` with `{"limit": 20}`: the websites this credential can see. Take ids from this answer.
@@ -34,8 +51,14 @@ On the CLI the same three verbs are `agentlinkops tools [TOOLSET]`, `agentlinkop
 
 ## Installed skill set
 
-Run `agentlinkops skill --list` for the versioned set installed with this CLI. It includes connect (access and evidence rules), discovery (sourced prospect research), campaigns (campaign judgment), CRM (local records) and assets (a specific linkable resource). Read an individual skill with its full name, for example `agentlinkops skill agentlinkops-discovery`. Research and local work do not require buying a supplier subscription.
+Run `agentlinkops skill --list` for the versioned set installed with this CLI. The bundled optional set includes discovery (sourced prospect research), campaigns (campaign judgment), CRM (local records) and assets (a specific linkable resource). Install only what the person chooses with `agentlinkops agent setup --skill ID`. These skills and local records are not prerequisites for checking supplied links. Read an individual skill with its full name, such as `agentlinkops skill agentlinkops-discovery`. Research and local work do not require buying a supplier subscription.
+
+## Optional recipes and customer policy
+
+CLI 0.6.10's default connection setup excludes campaign, CRM and publisher workflows. Use the selectors only when the installed CLI’s help supports them. Inspect `agentlinkops setup --plan --goal GOAL --mode MODE` when a task needs a plan. Select an optional recipe with `agentlinkops agent setup --recipe ID`: `site-context-brief`, `sourced-linkable-asset`, `qualified-campaign-handoff` or `placement-reconciliation`. Repeat the flag for multiple recipes. The installer reports their versions and associated skills. Installed recipes live in `../../references/recipes/`; read a selected recipe that fits the person's task. For the optional site brief, select it separately with `agentlinkops agent setup --recipe site-context-brief` before reading [the site brief recipe](../../references/recipes/site-context-brief.md).
+
+Preview `agentlinkops agent remove --recipe ID` or `--skill ID`, then add `--apply` to remove unchanged installer-owned files. The installer refuses skill removal while a recipe it owns still needs the skill. Keep the skill or preview selecting that recipe and its skill together after reconciling customer edits. The installer preserves edited dependent bodies, which can still block joint removal. It also refuses removal when it cannot trust the dependency metadata. Targeted connection-skill removal refuses surviving optional payloads or retained MCP ownership.
 
-## Choose the task
+For an intended complete uninstall, preview `agentlinkops agent remove --scope project` (or `user`), then add `--apply`. Recipe-only removal preserves the connection, other skills, shared support and customer edits. A connection-skill upgrade retains earlier optional payloads until explicitly removed. Full-pack setup is available with `--all-skills`.
 
-Use `agentlinkops setup --plan --goal GOAL --mode MODE` to inspect requirements without changing records. Goals include `build-content`, `prepare-campaign` and `verify-links`; modes are `local`, `hosted` and `external`. Read the [site and context brief](../../references/recipes/site-context-brief.md) when the task needs a site brief. Route sourced drafts to `agentlinkops-assets`, campaign handoffs to `agentlinkops-campaigns`, and placement reconciliation to `agentlinkops-crm`. The [recipe catalog](../../references/recipes/catalog.json) records versions, required inputs and untested capabilities.
+Follow the customer's existing instructions, editorial rules and tools. These optional methods never authorize outreach, publication, spending or provider activation. The installer reports conflicts instead of replacing customer files. A connection or installation is separate from a successful link check and a published package release.

package/skills/agentlinkops-connect/references/agentlinkops.md

@@ -6,21 +6,33 @@ for links a person supplies. Your agent keeps campaign judgment, browsing, email
 records. This page is the complete agent reference: the same text prints from
 `agentlinkops skill`, ships inside the installed `agentlinkops-connect` skill as
 `references/agentlinkops.md`, and is served at `https://agentlinkops.com/SKILL.md`. Read it in
-full once per session, then use `describe` for any command's exact schema.
+full once per session, then use `describe` (or `exec describe` on MCP) for any command's exact schema.
 
 <!-- generated:skill-version begin (npm run generate:tools) -->
-Pack version 0.6.8. 125 commands in 13 toolsets.
+Pack version 0.6.10. 139 commands in 15 toolsets.
 <!-- generated:skill-version end -->
 
 ## Install and connect (once per machine)
 
 ```bash
-npx -y agentlinkops agent setup     # installs the skill pack for each detected agent client and
-                                    # writes its MCP entry; stores no credential
+npx -y agentlinkops --help          # inspect this package version's setup options
+npx -y agentlinkops agent setup     # writes the detected client's MCP entry; stores no credential
 agentlinkops agent status           # what is installed where
 ```
 
-`npx -y skills add https://agentlinkops.com` installs the skills alone; then add
+CLI 0.6.10 installs the connection skill and its reference by default. Select
+optional guidance explicitly. CLI 0.6.9 and earlier can install the complete pack.
+Check the installed version's help before using selection flags. Native-client
+acceptance remains separate from package checks.
+
+On a version supporting selections, add only the guidance the person chooses:
+`agentlinkops agent setup --skill ID` or `--recipe ID`, repeating the flag for several
+choices. `--all-skills` selects the complete pack. Recipes remain optional; their
+versioned procedures do not replace the person's existing instructions or authorize
+publication, outreach, spending or provider access. Checking supplied links does not
+require a campaign, content workflow or local CRM.
+
+`npx -y skills add https://agentlinkops.com` installs the product skills alone; then add
 `https://app.agentlinkops.com/mcp` as a remote HTTP MCP server in the client by hand. If the
 CLI is not installed, give the person that server URL and the next step instead of claiming
 the connection exists.
@@ -34,13 +46,18 @@ works:
 npx -y agentlinkops check --source https://publisher.example/resources --target https://your-site.example/guide
 ```
 
+When the person asks to save the portable JSON result, add `--json --out FILE`
+with their chosen file path. Read the saved result before reporting its state,
+check date, coverage and evidence limits. Preserve the person's other records.
+
 REST and the CLI use a scoped API key created in **Agent access > Create API key** in the
 [workspace](https://app.agentlinkops.com/app), supplied as `AGENTLINKOPS_API_KEY` in the
 environment (`AGENTLINKOPS_TOKEN` also works; the older `LINKTRAIL_*` names keep working
 during the pilot compatibility window with one warning per process). MCP OAuth tokens are
 bound to `/mcp` and are not API keys.
 
-Verify: on MCP call `get_workspace` with `{}` (a workspace name in the answer means the
+Verify: on MCP call `get_workspace` with `{}` — directly, or as
+`exec: {"command": "call get_workspace {}"}` (a workspace name in the answer means the
 connection works); on the CLI run `agentlinkops doctor` (its `cloud` and `token` lines say
 `ok` when the origin answers and the key is accepted).
 
@@ -49,9 +66,12 @@ connection works); on the CLI run `agentlinkops doctor` (its `cloud` and `token`
 One catalog, several endpoints. Every command is callable on every view; only the listing
 changes. `agentlinkops agent setup` picks the right one per client.
 
-- `/mcp` (default): `get_workspace`, `list_projects`, `list_link_watches`, `monitor_link` and
-  `list_events` listed directly, plus `search_tools`, `describe_tools`, `run_read_command` and
-  `run_write_command` for the rest; the server instructions list every command by toolset.
+- `/mcp` (default): one tool, `exec`, carries the whole catalog. Pass it CLI-style command
+  strings — `search`, `tools`, `describe`, `schema`, `call` — and the server instructions list
+  every command by toolset. Every command is also callable directly on this view (a client
+  that already knows the name may call it), and the older discovery tools
+  (`search_tools`, `describe_tools`, `run_read_command`, `run_write_command`) still answer
+  direct calls, unlisted.
 - `/mcp/all`: the flat catalog, for a client with its own tool search (Claude Code, Hermes).
 - `/mcp/{toolset}`: one group from the table at the end.
 - `/mcp/code`: `search`, `describe` and `execute`; `execute` runs your JavaScript in an isolated
@@ -61,21 +81,35 @@ changes. `agentlinkops agent setup` picks the right one per client.
 
 ## Find, describe, call
 
-The same three verbs on every surface. Never invent a command name or an argument.
+The same verbs on every surface. Never invent a command name or an argument. On MCP everything
+goes through the one `exec` tool; its `command` string is one command per call, and several
+`exec` calls can run in parallel.
 
-| Step | MCP | CLI | HTTP |
+| Step | MCP (`exec`) | CLI | HTTP |
 | --- | --- | --- | --- |
-| index | `search_tools` | `agentlinkops tools [TOOLSET]` | `GET /v1/commands` |
-| describe | `describe_tools` | `agentlinkops describe NAME` | `GET /v1/commands/{name}` |
-| call | the tool, or `run_read_command` / `run_write_command` | `agentlinkops call NAME --args JSON` | `POST /v1/commands/{name}` |
+| index | `exec: {"command": "tools"}` | `agentlinkops tools [TOOLSET]` | `GET /v1/commands` |
+| find | `exec: {"command": "search destination health"}` | `agentlinkops tools [TOOLSET]` | `GET /v1/commands` |
+| describe | `exec: {"command": "describe monitor_link"}` | `agentlinkops describe NAME` | `GET /v1/commands/{name}` |
+| drill one field | `exec: {"command": "schema monitor_link targetScope"}` | `agentlinkops schema NAME [PATH]` | `GET /v1/commands/{name}` |
+| call | `exec: {"command": "call monitor_link {\"projectId\":\"pr_..\",\"sourceUrl\":\"https://..\",\"targetUrl\":\"https://..\"}"}` | `agentlinkops call NAME --args JSON` | `POST /v1/commands/{name}` |
+
+`search` takes `--toolset` and `--limit`; `describe` takes `--output-schema`; `call` takes
+`--json` for full rows instead of the concise projection. A `describe` or `schema` answer that
+exceeds the context budget is summarized, and any field carrying a `hint` expands with
+`schema <name> <field.path>`. Find with `search`, `describe` a name once, then `call` and
+reuse the schema; an unknown name answers with the `search` that finds the current one.
 
 Read the description first; `describe` before any write. List commands answer concise rows on
-MCP and code mode, detailed rows on REST and the CLI; pass `format` (`concise` or `detailed`)
-to choose and read `defaults_applied` to know which you got. A retired command name still
-resolves to its canonical command for twelve months and the description says so.
+MCP and code mode, detailed rows on REST and the CLI; pass `format` (`concise` or `detailed`),
+or `call --json` through `exec`, to choose, and read `defaults_applied` to know which you got.
+A retired command name still resolves to its canonical command for twelve months and the
+description says so.
 
 ## Start a session
 
+For a hosted task, inspect the connection and granted scopes first. The accountless local
+check above needs no hosted session, repository, ledger or optional recipe.
+
 1. `get_workspace` with `{}`: limits, usage and membership. Needs `projects:read`, the default
    advertised scope; an authenticated connection alone does not grant more.
 2. `list_projects` with `{"limit": 20}`: the websites this credential can see. Take ids from
@@ -225,9 +259,9 @@ counts, superlatives or claims about other products beyond dated public statemen
    invitation-only hosted access; `cadenceSeconds` between 3600 and 2592000; no availability
    percentage is published.
 4. **Usage and exit are readable:** `get_usage` totals with a `check_budget` block;
-   `export_link_watches` pages monitored placements out for local CRM recovery. Boundary:
-   payment collection is not active in this build; the ledger and CRM stay in the user's own
-   files.
+   `export_link_watches` pages monitored placements out for the person's records. Boundary:
+   payment collection is not active in this build; the person chooses where to keep their
+   campaign records.
 
 The human-readable version is
 [what your agent can prove to you](https://agentlinkops.com/what-your-agent-can-prove/).
@@ -235,16 +269,18 @@ The human-readable version is
 ## Tool reference
 
 <!-- generated:skill-tools begin (npm run generate:tools; source: src/tool-registry.js) -->
-125 commands in 13 toolsets, generated from `src/tool-registry.js` (`npm run generate:tools`). Core on every view: `get_workspace`, `list_projects`, `list_link_watches`, `monitor_link`, `list_events`. The index verbs list the rest by name; `describe` is the source of truth for input schemas. Admission-gated today: request_competitor_inventory, request_domain_overview, discover_backlinks; these refuse before any persistence.
+139 commands in 15 toolsets, generated from `src/tool-registry.js` (`npm run generate:tools`). Core on every view: `get_workspace`, `list_projects`, `list_link_watches`, `monitor_link`, `list_events`. The index verbs list the rest by name; `describe` is the source of truth for input schemas. Admission-gated today: prepare_domain_baseline, start_domain_baseline, request_competitor_inventory, request_domain_overview, discover_backlinks; these refuse before any persistence.
 
 | Toolset | Commands | What it covers |
 | --- | --- | --- |
 | `monitoring` | 17 | Watch earned links and destination URLs: create, list, update, import, export, recheck. |
 | `evidence` | 17 | What a check observed: histories, snapshots, change feeds, check jobs, published contacts. |
+| `rank` | 5 | Synthetic DataForSEO rank schedules and dated history; hosted collection disabled. |
 | `discovery` | 16 | Import candidate rows, read stored runs, verify selected candidates, enroll them. |
+| `baseline` | 7 | Scoped backlink baselines; supplier admission disabled. |
 | `library` | 3 | Read and export the coverage-stated opportunity library. |
 | `competitors` | 17 | Competitor sets, dated inventories, scheduled refresh, gap and domain-mix reports. |
-| `reports` | 5 | Profile, anchor and report summaries over the tracked dataset. |
+| `reports` | 7 | Profile, anchor and report summaries over the tracked dataset. |
 | `workspace` | 16 | Workspace, projects, usage, members, invitations, scratch-resource cleanup. |
 | `notifications` | 6 | Email notification preferences, previews, tests and deliveries. |
 | `webhooks` | 6 | Webhook endpoints, state, secrets and delivery records. |
@@ -260,11 +296,11 @@ AgentLinkOps grants no access to the mailbox or local files, has no independent
 backlink index, authority metrics or email sending, does not browse sites for you and
 monitors supplied URLs. Finding prospects, campaign decisions, navigating sites and authorized
 outreach stay with the person's existing agent, research, browser and email tools; prospects,
-contacts, outreach references and earned placements stay together in their existing local
-CRM. The `agentlinkops-campaigns` and `agentlinkops-crm` skills cover those.
+contacts, outreach references and earned placements remain in their chosen files, CRM or
+other record system. The campaign and local CRM skills are optional guidance.
 
-With the installed ledger CLI, `agentlinkops connect --workspace WORKSPACE_ID --project-id
+If the person chooses the ledger CLI, `agentlinkops connect --workspace WORKSPACE_ID --project-id
 PROJECT_ID --selection selected-links.json` saves only connection metadata and a selection of
 existing ledger ids; `sync --dry-run` previews uploads offline and `sync --pull-only`
 retrieves history without creating watches. Review the plan before authorizing `sync`. The
-Python CRM helper separately needs `AGENTLINKOPS_API_URL` and `AGENTLINKOPS_API_KEY`.
+optional Python CRM helper separately needs `AGENTLINKOPS_API_URL` and `AGENTLINKOPS_API_KEY`.

package/skills/agentlinkops-crm/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: agentlinkops-crm
 description: Manage the AgentLinkOps local backlink and outreach CRM, user-selected disavow lists, branded HTML reports and cloud event sync. Use for durable campaign records, link reporting or explicit disavow-list management; does not connect a mailbox, send outreach or upload disavow files.
-allowed-tools: Read Bash(python3 ../../scripts/agentlinkops.py *) Bash(node cli/agentlinkops.mjs *) Bash(agentlinkops *)
+allowed-tools: Read Bash(python3 ../../scripts/agentlinkops.py *) Bash(python3 ../../scripts/outreach-crm-draft.py *) Bash(node cli/agentlinkops.mjs *) Bash(agentlinkops *)
 ---
 
-**The local surface is the ledger file, not this CRM.** `.agentlinkops/links.jsonl` in the user's repository (or a `.linktrail/` directory from an earlier install, read until `agentlinkops migrate` renames it) declares the links they expect, want and have earned, and `agentlinkops check` runs the exact cloud verifier against it without an account. Run the CLI as `node cli/agentlinkops.mjs` from the repository or plugin-package root (`cli/linktrail.mjs` still works and prints a one-line notice); the packaged plugin ships the CLI, its pinned verifier modules and their one dependency (parse5, MIT) inside the package, so `check` runs with no npm install and no network. It needs Node 22 or newer (`adopt` reads SQLite databases through `node:sqlite`); the Python helper below needs Python 3.10+. This CRM is one optional adapter beside CSV and JSONL: it is available, tested and unchanged, and nothing requires it. When a user already keeps links here, `agentlinkops adopt <db>` reads it into ledger entries — read-only, adding no schema — and previews unless `--write` is given. Do not propose the CRM as the place a user should start keeping links; propose it when they want contacts and outreach activity beside them, or when they already have one.
+**For the optional bundled CLI, the local surface is the ledger file.** `.agentlinkops/links.jsonl` in the user's repository (or a `.linktrail/` directory from an earlier install, read until `agentlinkops migrate` renames it) declares the links they expect, want and have earned, and `agentlinkops check` runs the exact cloud verifier against it without an account. Run the CLI as `node cli/agentlinkops.mjs` from the repository or plugin-package root (`cli/linktrail.mjs` still works and prints a one-line notice); the packaged plugin ships the CLI, its pinned verifier modules and their pinned runtime dependencies inside the package, so the installed package needs no npm install; checking a publisher still requires a read-only network fetch. It needs Node 22 or newer (`adopt` reads SQLite databases through `node:sqlite`); the Python helper below needs Python 3.10+. This CRM is one optional adapter beside CSV and JSONL: it is available, tested and unchanged, and nothing requires it. When a user already keeps links here, `agentlinkops adopt <db>` reads it into ledger entries — read-only, adding no schema — and previews unless `--write` is given. Do not propose the CRM as the place a user should start keeping links; propose it when they want contacts and outreach activity beside them, or when they already have one.
 
 To record a link in the ledger: `agentlinkops add --source URL --target URL --intent expected [--anchor TEXT] [--ref ID] [--note TEXT]` (`--intent wanted` for a link not yet earned; `agentlinkops init` first in a repository without `.agentlinkops/`). `agentlinkops check` then verifies every expected link and exits 0 when all are present, 1 when one is observed absent with complete evidence, 2 on a usage or ledger error; an unknown never fails.
 
@@ -26,4 +26,18 @@ For recurring cloud changes, use the host's already connected AgentLinkOps tools
 
 Sync updates `cloud_state` on placements and preserves local status, notes and opportunity relationships. A fetch failure is not proof that a backlink disappeared. Keep `unknown`, `suspected_missing` and confirmed outcomes distinct. Read the new events and decide what action, if any, the user's agent should take; receipt of an event does not authorize sending an email.
 
-Use the [placement reconciliation recipe](../../references/recipes/placement-reconciliation.md) to reconcile an exact source and destination with retained evidence, checkpoints and an optional monitoring plan.
+Recipes are optional. Choose `agentlinkops agent setup --recipe placement-reconciliation` before reading `../../references/recipes/placement-reconciliation.md` for an exact source and destination, retained evidence, checkpoints and optional monitoring. Removing the recipe preserves your local records and existing reconciliation process.
+
+For a draft-only file from an existing frozen report, read [portable ledger
+handoff](../../references/portable-ledger-handoff.md). It needs explicit customer
+workspace/project/site and external-ID mappings, verifies the report hash and
+refuses mismatched sites or conflicting output. It does not verify hosted grants,
+import into a vendor or send messages. Keep replied, suppressed and unknown facts
+separate from monitoring state; a saved file does not establish destination
+readback or permission to send.
+
+When the user selects an existing local Outreach CRM with `projects/<project>/drafts`,
+use [local CRM draft handoff](../../references/local-crm-draft-handoff.md) for exact
+body/manifest saving, interrupted-save recovery and readback. This adapter preserves
+the complete original request and explicit site binding. It does not import contacts,
+check current sender authority, activate sequences or provide a native vendor API.

package/src/citations/adapter.js

@@ -256,7 +256,8 @@ export function createOpenAiCompatibleEngine({ baseUrl, model, apiKey, fetchImpl
 // overview linked to — the citation equivalent of a chat engine's source list.
 // The fixture below proves the parser against the documented response shape;
 // the live adapter activates with credentials in fleet, never before.
-export function createGoogleAioEngine({ fetchImpl, credentials, costEstimateUsd = 0.0012, locationCode = 2840, country, languageCode = 'en', device = 'desktop', timeoutMs = CITATION_LIMITS.timeoutMs, maxResponseBytes = CITATION_LIMITS.answerBytes } = {}) {
+const GOOGLE_AIO_BASE_COST_USD = 0.002;
+export function createGoogleAioEngine({ fetchImpl, credentials, costEstimateUsd = GOOGLE_AIO_BASE_COST_USD, locationCode = 2840, country, languageCode = 'en', device = 'desktop', timeoutMs = CITATION_LIMITS.timeoutMs, maxResponseBytes = CITATION_LIMITS.answerBytes } = {}) {
   const doFetch = fetchImpl ?? globalThis.fetch?.bind(globalThis);
   const error = (code, message, details = {}) => Object.assign(new EngineError(message), { code, ...details });
   if (country !== undefined) {
@@ -390,6 +391,6 @@ function parseAioResponse(body, prompt) {
     citations,
     fanOut: [],
     usage: { input_tokens: 0, output_tokens: 0 },
-    costEstimateUsd: body?.cost ?? 0.0012,
+    costEstimateUsd: body?.cost ?? GOOGLE_AIO_BASE_COST_USD,
   };
 }

package/src/citations/browser/chatgpt-citations.js

@@ -38,13 +38,48 @@ export function readChatgptCitationState(input) {
   const anonymous = root.matches(selectors.at(-1));
   let panelEligible = anonymous && groups.length > 0 && groups.length <= 50;
   const publisherLabels = [];
+  const strayKinds = {};
+  // Current anonymous layout (observed 2026-09-25): inline citations and source pills are
+  // buttons whose sources travel as JSON in data-assistant-sources-payload, each entry
+  // {attribution, title, url}. A payload that does not parse to valid URLs is unresolved.
+  const payloadButtons = new Set();
+  const payloadSources = [];
+  if (anonymous) {
+    for (const element of Array.from(root.querySelectorAll('[data-assistant-sources-payload]'))) {
+      let entries = null;
+      try { entries = JSON.parse(element.getAttribute('data-assistant-sources-payload')); } catch { entries = null; }
+      const parsed = (Array.isArray(entries) ? entries : []).map(entry => {
+        try {
+          const url = new URL(entry?.url);
+          return ['https:', 'http:'].includes(url.protocol) && !url.username && !url.password ? { url: url.href, title: String(entry.title || entry.attribution || '').trim() } : null;
+        } catch { return null; }
+      });
+      if (!parsed.length || parsed.some(item => !item) || concealed(element)) { unresolved = true; panelEligible = false; continue; }
+      payloadButtons.add(element);
+      payloadSources.push(...parsed);
+    }
+  }
   if (anonymous) {
     // A new anonymous layout with unrecognized citation controls is not proof
-    // of absence. Never use unrelated page-wide links to fill this gap.
+    // of absence. Never use unrelated page-wide links to fill this gap. Three control kinds
+    // observed 2026-09-25 never carry sources and are recognized explicitly: code-block
+    // Copy code buttons inside <pre>, table Copy table buttons (data-table-copy-state), and
+    // entity chips (data-content-reference-type="entity"), which open an entity panel. A brand
+    // named in an entity chip is still counted as a mention from the answer text.
     const actions = root.querySelector('[role="group"][aria-label="Response actions"]');
     const unsupported = Array.from(root.querySelectorAll('a[href], button, [role="button"], cite, sup, [data-citation], [data-citation-id]'));
-    if (unsupported.some(element => !actions?.contains(element) && !groups.some(group => group.contains(element)))) {
-      unresolved = true; panelEligible = false;
+    const recognizedControl = element => element.tagName === 'BUTTON' && (Boolean(element.closest?.('pre')) ||
+      element.getAttribute('data-table-copy-state') !== null ||
+      (element.getAttribute('data-content-reference-type') === 'entity' && element.getAttribute('data-assistant-entity-reference') !== null));
+    const stray = unsupported.filter(element => !actions?.contains(element) && !groups.some(group => group.contains(element)) &&
+      !payloadButtons.has(element) && !recognizedControl(element));
+    if (stray.length) { unresolved = true; panelEligible = false; }
+    // Diagnostics only: which kinds of element blocked the read, by tag and a sanitized
+    // role. Never URLs, text or attributes that could carry page content.
+    for (const element of stray) {
+      const role = (element.getAttribute('role') || '').toLowerCase();
+      const kind = String(element.tagName || 'unknown').toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 20) + (role ? `[${/^[a-z-]{1,20}$/.test(role) ? role : 'other'}]` : '');
+      if (kind in strayKinds || Object.keys(strayKinds).length < 10) strayKinds[kind] = (strayKinds[kind] || 0) + 1;
     }
   }
   for (const group of groups) {
@@ -70,11 +105,14 @@ export function readChatgptCitationState(input) {
     }
     // Observed anonymous pills are buttons without URLs. Their labels are
     // not URL evidence; a partial anchor list cannot resolve those controls.
-    if (!resolved || group.querySelector('button, [role="button"]')) unresolved = true;
+    // A group whose every control carries a parsed sources payload is resolved by it.
+    const payloadResolved = payloadButtons.size > 0 && (() => { const controls = Array.from(group.querySelectorAll('button, [role="button"]')); return controls.length > 0 && controls.every(control => payloadButtons.has(control)); })();
+    if (!payloadResolved && (!resolved || group.querySelector('button, [role="button"]'))) unresolved = true;
   }
+  sources.push(...payloadSources);
   const labels = [...new Set(publisherLabels)];
   panelEligible = panelEligible && labels.length > 0 && labels.length <= 50;
-  const state = { found: true, anonymous, groups: groups.length, unresolved, sources, panelEligible };
+  const state = { found: true, anonymous, groups: groups.length, unresolved, sources, panelEligible, strayKinds };
   if (!input.prepare) return state;
   if (!panelEligible || !unresolved) return {state};
   // Keep the exact assistant and control references in-page. No DOM identities,
@@ -145,6 +183,22 @@ export function readChatgptCitationState(input) {
 const unavailable = () => Object.assign(new Error('ChatGPT citation controls could not be resolved.'), {code:'CITATION_EXTRACTION_UNAVAILABLE'});
 const responseBindings = new WeakMap();
 const bindingCurrent = binding => binding.evaluate(value => typeof value.isCurrent === 'function' && value.isCurrent());
+// ChatGPT renders some failures as the assistant turn itself ("Something went wrong...").
+// Such a turn is not an answer: read as one, it would record a false not_cited. Only a short
+// turn made of a known failure message counts, so a real answer that quotes one is kept.
+const CHATGPT_FAILURE_MESSAGES = [
+  /^something went wrong\b/i,
+  /^there was an error generating a response\b/i,
+  /^hmm\.{0,3}\s*something seems to have gone wrong\b/i,
+  /^network error\b/i,
+  /^too many requests\b/i,
+  /^you('|’)ve reached our limit of messages\b/i,
+];
+export function isChatgptFailureMessage(text) {
+  const body = String(text ?? '').replace(/^\s*#{1,6}\s*ChatGPT said:\s*/i, '').trim();
+  return body.length > 0 && body.length < 400 && CHATGPT_FAILURE_MESSAGES.some(pattern => pattern.test(body));
+}
+
 export async function releaseChatgptResponseBinding(page) {
   const binding = responseBindings.get(page);
   responseBindings.delete(page);
@@ -202,7 +256,7 @@ export async function extractChatgptSources(page, legacyExtract) {
     const state = await page.evaluate(readChatgptCitationState, PROVIDER_MODEL_RESPONSE_SELECTORS.chatgpt);
     let sources;
     if (!state.found || state.unresolved) {
-      if (!state.found || !state.panelEligible) throw unavailable();
+      if (!state.found || !state.panelEligible) throw Object.assign(unavailable(), { strayKinds: state.strayKinds ?? {} });
       sources = await extractControlledPanel(page,binding);
     } else if (state.anonymous || state.groups) sources = [...new Map(state.sources.map(source => [source.url, source])).values()];
     else sources = await legacyExtract(page);

package/src/citations/browser/engine.js

@@ -11,11 +11,13 @@
 // browser tooling still runs every non-browser engine, and `citation doctor`
 // reports the gap instead of the whole CLI failing to load.
 import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { EngineError } from '../adapter.js';
 import {createProxyAdmission,proxyFailureReason} from './proxy-admission.js';
-import { extractBoundChatgptResponse, extractChatgptSources, releaseChatgptResponseBinding } from './chatgpt-citations.js';
+import { extractBoundChatgptResponse, extractChatgptSources, releaseChatgptResponseBinding, isChatgptFailureMessage } from './chatgpt-citations.js';
 
 const MODULE_LOADERS = {
   'playwright-core': () => import('playwright-core'),
@@ -58,6 +60,46 @@ const ENGINE_NOMINAL_COST = Object.freeze({
 });
 const DEFAULT_NOMINAL_COST = 0.03;
 
+// The vendored display bootstrap stops Xvfb only through cleanup(). A Node process that is
+// killed or crashes leaves Xvfb running under init (the measurement VPS held 32 of them on
+// 2026-09-24), so a detached watchdog ends it within five seconds of this process
+// disappearing. The pid comes from Xvfb's own lock file and is killed only while it is still
+// Xvfb, so a recycled pid is never signalled. Returns the function that retires the watchdog.
+export function guardDisplay(display, { spawnProcess = spawn, readLock = readFileSync, parentPid = process.pid } = {}) {
+  const number = Number(String(display).replace(/^:/, ''));
+  let xvfbPid;
+  try { xvfbPid = Number(String(readLock(`/tmp/.X${number}-lock`, 'utf8')).trim()); } catch { return () => {}; }
+  if (![number, xvfbPid, parentPid].every(Number.isInteger) || xvfbPid <= 1) return () => {};
+  const script = `while kill -0 ${parentPid} 2>/dev/null; do sleep 5; done; [ "$(cat /proc/${xvfbPid}/comm 2>/dev/null)" = Xvfb ] && kill ${xvfbPid}`;
+  let watchdog;
+  try { watchdog = spawnProcess('/bin/sh', ['-c', script], { detached: true, stdio: 'ignore' }); watchdog.unref?.(); }
+  catch { return () => {}; }
+  return () => { try { watchdog.kill('SIGKILL'); } catch {} };
+}
+
+// A browser composer can lose keystrokes (a login modal taking focus mid-typing is the
+// observed case: on 2026-09-25, 4 of 30 ChatGPT slots submitted a truncated prompt and were
+// answered as a different question). The prompt must be exactly what the panel says, both
+// in the composer before submit and in the submitted turn afterwards.
+export const normalizePrompt = text => String(text ?? '').replace(/^\s*you said:\s*/i, '').replace(/\s+/g, ' ').trim();
+export async function ensurePromptEntered(prompt, { readComposer, fill, settle = async () => {} }) {
+  const expected = normalizePrompt(prompt);
+  if (normalizePrompt(await readComposer()) === expected) return 'typed';
+  await fill(prompt); await settle();
+  if (normalizePrompt(await readComposer()) === expected) return 'filled';
+  throw new EngineError('the prompt could not be entered completely', { retriable: true });
+}
+// Runs in the page: the text of the latest user turn, or null when none is found.
+// Observed 2026-09-25: li[data-message-role="user"] > ... > p[data-user-message-copy].
+// Older layouts used data-message-author-role / data-turn.
+export function readChatgptSubmittedPrompt() {
+  for (const selector of ['[data-message-role="user"] [data-user-message-copy]', '[data-message-role="user"]', '[data-message-author-role="user"]', '[data-turn="user"]']) {
+    const node = Array.from(document.querySelectorAll(selector)).at(-1);
+    if (node) return node.innerText;
+  }
+  return null;
+}
+
 export function createBrowserEngine({ engineName, env = process.env, onEvent = () => {}, runtime = {} } = {}) {
   if (!BROWSER_PROVIDERS.includes(engineName)) {
     throw new EngineError(`unknown browser engine: ${engineName} (known: ${BROWSER_PROVIDERS.join(', ')})`);
@@ -89,6 +131,7 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
   let running=false,contextCleanupFailed=false;
   let browserHandle = null;   // { browser, cleanup } for the whole epoch
   let displayHandle = null;
+  let releaseDisplayGuard = null;
   let providerConfig = null;
   async function closeQuietly(action) {
     let timer;
@@ -96,6 +139,17 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
     finally { clearTimeout(timer); }
   }
 
+  // The watchdog is retired only after a confirmed close; otherwise it stays armed and
+  // ends Xvfb once this process exits.
+  async function closeDisplay() {
+    // A second call after a failed close finds no handle; that is not a confirmed close.
+    if (!displayHandle) return true;
+    const closed = await closeQuietly(() => displayHandle.cleanup?.());
+    if (closed) { releaseDisplayGuard?.(); releaseDisplayGuard = null; }
+    displayHandle = null;
+    return closed;
+  }
+
   async function ensureProviderConfig() {
     if (providerConfig) return providerConfig;
     const { PROVIDER_CONFIGS } = await load('./gen/core/providers/index.js');
@@ -124,6 +178,7 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
     // engines that block headless render headfully inside a virtual display.
     if (platform === 'linux' && !display.detectDisplay()) {
       displayHandle = await display.ensureDisplay({ allowExistingDisplay: false });
+      releaseDisplayGuard = (runtime.guardDisplay ?? guardDisplay)(displayHandle.display);
       await event(`display: ${displayHandle.display}`);
     }
 
@@ -151,8 +206,7 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
       browser,
       cleanup: async () => {
         const browserClosed=await closeQuietly(() => browser.close());
-        const displayClosed=await closeQuietly(() => displayHandle?.cleanup?.());
-        displayHandle = null;
+        const displayClosed=await closeDisplay();
         if(browserClosed)contextCleanupFailed=false;
         return browserClosed&&displayClosed;
       },
@@ -163,11 +217,26 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
   async function loadStorageState() {
     // Accountless measurement never opens session files, even when they exist.
     if (authentication === 'accountless') return undefined;
+    const failure = () => Object.assign(new EngineError('Saved browser session is unavailable or unsafe. Restore private session storage or run citation login again.'), { code: 'BROWSER_SESSION_INVALID' });
+    let handle;
     try {
-      const { readFile } = await load('node:fs/promises');
-      return JSON.parse(await readFile(join(sessionDir, `${engineName}.json`), 'utf8'));
-    } catch {
-      return undefined; // anonymous session: several surfaces work logged-out
+      const storage = await load('node:fs/promises');
+      const directory = await storage.lstat(sessionDir);
+      if (!directory.isDirectory() || (platform !== 'win32' && (directory.mode & 0o7777) !== 0o700)) throw failure();
+      const filename = join(sessionDir, `${engineName}.json`);
+      const before = await storage.lstat(filename);
+      if (!before.isFile() || (platform !== 'win32' && (before.mode & 0o7777) !== 0o600)) throw failure();
+      handle = await storage.open(filename, 'r');
+      const opened = await handle.stat();
+      if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || (platform !== 'win32' && (opened.mode & 0o7777) !== 0o600)) throw failure();
+      const state = JSON.parse(await handle.readFile('utf8'));
+      if (!state || !Array.isArray(state.cookies) || !Array.isArray(state.origins)) throw failure();
+      return state;
+    } catch (error) {
+      if (error.code === 'ENOENT') return undefined;
+      throw failure();
+    } finally {
+      try { await handle?.close(); } catch { throw failure(); }
     }
   }
 
@@ -220,10 +289,10 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
     estimateCostUsd: () => ENGINE_NOMINAL_COST[engineName] ?? DEFAULT_NOMINAL_COST,
 
     async run({ prompt }) {
+      const storageState = await loadStorageState();
       const config = await ensureProviderConfig();
       const { browser } = await ensureBrowser();
       admission.assertReady();
-      const storageState = await loadStorageState();
       const context = await browser.newContext({
         storageState,
         locale: 'en-US',
@@ -318,12 +387,16 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
             await editor.locator.fill(prompt);
           });
           await page.waitForTimeout(600);
-          const typedCheck = await editor.locator.inputValue().catch(() => '');
-          if (typedCheck.trim().length === 0) {
-            await editor.locator.fill(prompt).catch(() => {});
-          }
           await config.afterTypingHook?.(page);
           await config.beforeSubmitHook?.(page);
+          // Checked after the modal hooks, immediately before submit: the composer must hold
+          // the whole prompt. One fill is the recovery; otherwise the sample fails closed.
+          const entered = await ensurePromptEntered(prompt, {
+            readComposer: () => editor.locator.evaluate(node => (typeof node.value === 'string' ? node.value : node.innerText) || '').catch(() => ''),
+            fill: text => editor.locator.fill(text).catch(() => {}),
+            settle: () => page.waitForTimeout(400),
+          });
+          if (entered === 'filled') await event('prompt refilled after incomplete typing');
 
           // Submit: the surface's own send button when it exposes one; Enter fallback.
           // Allow the surface to settle; response extraction remains fail-closed.
@@ -336,15 +409,29 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
 
         await config.waitForResponse(page);
         if (!answer) answer = await config.extractResponse(page);
+        if (engineName === 'chatgpt') {
+          // The answer belongs to the prompt only if the submitted turn is the panel prompt.
+          const submitted = await page.evaluate(readChatgptSubmittedPrompt).catch(() => null);
+          if (typeof submitted !== 'string') await event('submitted prompt could not be read; not verified');
+          else if (normalizePrompt(submitted) !== normalizePrompt(prompt)) {
+            throw new EngineError('chatgpt: the submitted prompt differs from the panel prompt', { retriable: true });
+          }
+        }
+        if (engineName === 'chatgpt' && isChatgptFailureMessage(answer)) {
+          throw new EngineError('chatgpt: the surface returned an error message instead of an answer', { retriable: true });
+        }
         if (!answer || answer.trim().length < 40) {
           const reason = engineName === 'bing'
             ? 'bing: no AI answer block rendered for this prompt (organic results only — never a citation verdict)'
             : `${engineName}: answer extracted empty`;
           throw new EngineError(reason, { retriable: true });        }
         let extractionFailed = config.citationExtraction === 'unsupported';
-        const sources = await config.extractSources(page).catch(async () => {
+        const sources = await config.extractSources(page).catch(async cause => {
           extractionFailed = true;
-          await event('sources extraction failed; observation retained as unknown');
+          // Tag and role counts only (see readChatgptCitationState); they say which layout
+          // change blocked the read without carrying page content.
+          const kinds = Object.entries(cause?.strayKinds ?? {}).map(([kind, count]) => `${kind}x${count}`).join(', ');
+          await event(`sources extraction failed; observation retained as unknown${kinds ? ` (unrecognized: ${kinds})` : ''}`);
           return [];
         });
         const screenshotPng = await page.screenshot({ fullPage: false }).catch(() => null);
@@ -384,17 +471,18 @@ export function createBrowserEngine({ engineName, env = process.env, onEvent = (
       let confirmed=true;
       try{if(browserHandle)confirmed=await browserHandle.cleanup();}
       finally{
-        const displayClosed=await closeQuietly(() => displayHandle?.cleanup?.());
-        confirmed=confirmed&&displayClosed;displayHandle=null;browserHandle=null;
+        const displayClosed=await closeDisplay();
+        confirmed=confirmed&&displayClosed;browserHandle=null;
       }
       return confirmed;
     },
   };
   const sample=engine.run.bind(engine),closeBrowser=engine.close.bind(engine);
-  const policyCodes=new Set(['CITATION_EXTRACTION_UNAVAILABLE','BROWSER_AUTH_POLICY_INVALID','PROXY_REQUIRED','PROXY_POLICY_INVALID','PROXY_POLICY_CONFLICT','PROXY_CONFIGURATION_INVALID','PROXY_ACQUIRE_FAILED','PROXY_SUPPLIER_INVALID','PROXY_LEASE_INVALID','PROXY_LEASE_EXPIRED','PROXY_QUARANTINE_FAILED','PROXY_RELEASE_FAILED','PROXY_RECEIPT_FAILED','PROXY_CUSTODY_UNAVAILABLE','BROWSER_CLEANUP_UNCONFIRMED','BROWSER_RUN_IN_PROGRESS']);
+  const policyCodes=new Set(['CITATION_EXTRACTION_UNAVAILABLE','BROWSER_AUTH_POLICY_INVALID','BROWSER_SESSION_INVALID','PROXY_REQUIRED','PROXY_POLICY_INVALID','PROXY_POLICY_CONFLICT','PROXY_CONFIGURATION_INVALID','PROXY_ACQUIRE_FAILED','PROXY_SUPPLIER_INVALID','PROXY_LEASE_INVALID','PROXY_LEASE_EXPIRED','PROXY_QUARANTINE_FAILED','PROXY_RELEASE_FAILED','PROXY_RECEIPT_FAILED','PROXY_CUSTODY_UNAVAILABLE','BROWSER_CLEANUP_UNCONFIRMED','BROWSER_RUN_IN_PROGRESS']);
   const safeError=cause=>{
     const code=policyCodes.has(cause?.code)?cause.code:'BROWSER_RUN_FAILED';
-    const error=Object.assign(new EngineError(code==='CITATION_EXTRACTION_UNAVAILABLE'?'Citation binding or extraction was unavailable.':code==='BROWSER_RUN_FAILED'?'Browser sample failed.':'Browser admission or cleanup failed.',{retriable:code==='BROWSER_RUN_FAILED'&&cause?.retriable===true}),{code});
+    const message=code==='BROWSER_SESSION_INVALID'?'Saved browser session is unavailable or unsafe. Restore private session storage or run citation login again.':code==='CITATION_EXTRACTION_UNAVAILABLE'?'Citation binding or extraction was unavailable.':code==='BROWSER_RUN_FAILED'?'Browser sample failed.':'Browser admission or cleanup failed.';
+    const error=Object.assign(new EngineError(message,{retriable:code==='BROWSER_RUN_FAILED'&&cause?.retriable===true}),{code});
     if(code==='BROWSER_RUN_FAILED'||cause?.unknown===true)error.unknown=true;
     return error;
   };