loopctl-mcp-server 2.111.2 → 2.113.0

package/README.md

@@ -415,6 +415,9 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 |---|---|
 | `llm_config` | **Check your onboarding status.** Get the tenant's BYO LLM config: per-operation models and whether each key is set — `has_api_key` (Anthropic) / `has_embedding_key` (OpenAI embedding) — plus masked last-4 hints. Never returns a key. Requires **user** key. |
 | `set_llm_config` | **First-time setup (do once).** Set/rotate the tenant's OWN **Anthropic `api_key`** (powers ingest) AND **OpenAI `embedding_api_key`** (powers semantic search) — both stored encrypted, never returned — plus the per-operation models (`extraction_model`/`classification_model`/`merge_model`/`embedding_model`). Any subset; partial-merge (omitting a key leaves it untouched). **Private tier (US-41.3):** also sets `chat_provider` (`anthropic` | `openai_compatible`), `chat_base_url`, `extraction_model` (required on that provider) and `chat_api_key` (optional — omit it for a keyless local server) so ingest extraction / classification / merge / memory promotion run against YOUR OWN OpenAI-compatible endpoint and document text never leaves your boundary. Every model the config resolves to is PROBED with a trivial completion before it is saved (a 422 persists nothing); the probe re-runs on any chat-surface change (provider, base_url, key rotation, model), a private-range host is refused by the SSRF guard, and moving to a NEW host needs a matching `chat_api_key` or `acknowledge_key_transmission: true`. See [First-time setup](#first-time-setup--provision-your-byo-llm-keys). Requires **user** key. |
+| `github_credential` | **Is there a GitHub credential for this tenant?** (#936, `GET /api/v1/tenants/me/github-credential`) `has_token`, a masked last-4 `token_hint`, `updated_at`, and `operator_repositories`: the repositories the operator's token is lent for (`VERIFICATION_OPERATOR_TOKEN_TENANTS`) while the tenant has no token. Never returns the token. Reach for it when the merge gate refuses `{pull_request_unavailable, credential_unavailable}` or verification records `credential_unavailable`. Requires **user** key. |
+| `set_github_credential` | **Set or replace the tenant's own GitHub token** (#936, `PUT /api/v1/tenants/me/github-credential`). Every GitHub call loopctl makes for the tenant — merge gate, story and post-deploy verification, thread checkpoint reads, issue closing — then uses it for EVERY repository, replacing the operator's token even where the operator lent it. A fine-grained token on your own repositories with read access to Contents, Pull requests, Actions, Commit statuses and Deployments (plus Issues: write for issue closing). Stored encrypted, never returned, and not checked against GitHub on the way in: a token that cannot read a repository shows up as that repository's forge refusal. A thread-mode merge is still written by loopctl's GitHub App, and only for a repository the operator named for the tenant: this token never licenses it (escalated `app_not_licensed`). 422 when blank, over the server's length bound or containing anything but letters, digits and underscores; `403 custody_tier_required` on an agent-rooted tenant. Required: `token`. Requires **user** key. |
+| `clear_github_credential` | **Remove the tenant's GitHub token** (#936, `DELETE /api/v1/tenants/me/github-credential`). Calls then use the operator's token only for `operator_repositories` and are refused `credential_unavailable` everywhere else, so a pr-mode repository outside that list stops merging. Idempotent. Requires **user** key. |
 | `knowledge_llm_usage` | Per-tenant LLM token-usage summary, grouped by operation + model + source_type + day over an optional `from`/`to` range (defaults to a 90-day lookback; effective window echoed in `meta.from`/`meta.to`), with `limit`/`offset` pagination. Record-only (no budget enforcement). Requires orchestrator key. |
 
 ### Knowledge Analytics Tools (orchestrator key)
@@ -533,9 +536,9 @@ The order to wire it up, the stage machine these tools move a story through, and
 | `thread_stage_report` | **Report a stage transition of the story you claimed yourself on a thread-mode repository** (`POST /api/v1/stories/:id/stage/transitions`, US-45.9): an interactive claim of a thread-mode story is a change thread with no runner, so its claimant moves the delivery stage as a runner would (with the checkpoint's `head_sha` only entering `ci`), never into `merged` and never `merge_refused`: loopctl's App makes and records the merge; after it, `merged` -> `deployed` with the `release_id`. The first report (from `claimed`) enters the claim. A resend of a report that already landed answers 200 with `replayed: true`. On the key `claim_story` claims with. Refusals: 404; 409 `not_claimant`, `stale_claim_epoch`, `claim_not_live` (renew the lease with `renew_story_claim` while you work), `not_interactive_thread_claim`, `effect_conflict` (the body names the recorded `head_sha`), `stale_stage` (the body names the story's stage and recorded effects); 422 `invalid_payload`; 503 `busy`. |
 | `force_unclaim_story` | **Take a story back from the agent holding it** (`POST /api/v1/stories/:id/force-unclaim`). Resets it to `agent_status: pending` with `assigned_agent_id` cleared AND makes the delivery stage row follow the release back to `queued`. **A delivery story then goes to `escalated`, not back to the queue** (loopctl US-44.4): an operator taking a story back is a human decision, so a release that leaves the stage row at `queued` escalates it over `operator_released` in the same transaction, spending no attempt against the retry ceiling — it is not left in the queue behind the human's back. Put it back to work with `resolve_escalation` `to: queued`, which releases (a no-op by then) AND re-contracts. A story with no delivery stage row is simply left `pending`. A story parked at `claimed` with nobody on it is the residue of a compensation that did not complete, not what a refused dispatch normally leaves: placement releases the claim inline when a runner refuses, and the claim lease releases it unattended once `claimed_until` passes — reach for this to get it back now, or when both of those left it held. Requeues from any stage a claim holds; a stage no claim holds keeps its stage and is rebound to the new epoch; `done` and `failed` are untouched. For an ESCALATED story use `resolve_escalation` instead — that one releases AND re-contracts, so its `queued` really is placeable. Requires an orchestrator-ROLE key: the action is `exact_role: :orchestrator`, so a user or superadmin key is 403'd like any other non-member. Put it in `LOOPCTL_ORCH_KEY` (which is then the key sent, and a global `LOOPCTL_API_KEY` does not displace it) or, with no orchestrator key set, in `LOOPCTL_API_KEY`. The orchestrator key must be linked to a registered agent (400 otherwise) and the tenant must be human-anchored (403 `custody_tier_required` otherwise). Does not touch `verified_status`. Run again on an already-pending story it is still an operator's release: a row stranded behind the story's claim epoch is rebound, an in-flight row is requeued, and a row then at `queued` — including one already sitting there — is escalated over `operator_released`, as on the first run; a row already escalated, or anywhere else at that epoch, is left alone. Every 500 means the whole release rolled back and the story is still claimed: `audit_chain_append_failed` (the escalation's chain entry was refused) is a server-side condition a re-run meets again until an operator acts; `force_unclaim_failed` (the server log names the step) — call it again. A 422 means the release write itself was rejected. No request body. Required: `story_id` (refused locally if it is not a UUID). |
 | `merge_precondition` | **Run the merge gate over a story's real pull request** (`POST /api/v1/stories/:id/merge-precondition`). Both delivery gates run again over the diff that exists, plus custody, the 12-file / 1000-line hard bound, the head-has-not-moved check and the self-deploy exclusion; the story must be at stage `ci`. **Gate A reads what triage persisted, never the caller**: the lens verdicts recorded with the story's most recent triage, or a human's re-queue of a Gate A escalation — `gate_a_inputs` on the answer says which, and `missing` refuses with `gate_a_inputs_missing`. This tool sends no trio. Decisions: `allow` (recorded against the head; the only thing that licenses a merge), `refuse` (the story is escalated before this returns), `already_merged`, `head_moved`, `unevaluated` (503 with `Retry-After`). **Thread mode** (the current claim was placed under a source with `mode: thread` — the mode is bound to the dispatch at placement): no pull request; the gate judges the latest checkpoint recorded under the story's CURRENT claim, on the branch that claim's dispatch ran on, and adds refusals `empty_change`, `checkpoint_tree_mismatch`, `no_checkpoint_recorded` and `claim_ended` (the claim was released after an earlier one recorded checkpoints); the source's runners must be at contract 1.20.0+ sending checkpoint messages, or every story is refused `no_checkpoint_recorded`; the branch is judged first, and a missing branch in a readable repository (`branch_missing`), a head nobody recorded (`branch_head_unrecorded`), an earlier checkpoint (`branch_head_regressed`), or a head the stage row did not record is `head_moved` back to implementing while the claim is LIVE, and a refusal naming `claim_not_live` (escalated) when it is not; an unreadable repository refuses `pull_request_unavailable`; the diff judged is the three-dot diff against the merge base, so a base that moved on is not a refusal, and a checkpoint the base already contains (its branch deleted or not) is `already_merged` only under a recorded allow naming it, otherwise `checkpoint_on_base_without_allow`; a thread loopctl could not read refuses `thread_unreadable`; CI is read by the checkpoint's exact SHA from the GitHub Actions runs and jobs APIs (only a job of a GitHub Actions workflow run that a push of the thread branch at that commit triggered satisfies a required check, and only by concluding `success` — a skipped job fails; statuses and other check runs are recorded or ignored, never trusted) against the source's `required_checks` — a failed one refuses `required_check_failed`, one still running or not yet reported is `unevaluated` (`required_check_pending` / `required_check_missing`, retry after the answer's `Retry-After`; neither counts toward the unevaluated bound, and past the gate's CI wait limit from the story's entry into `ci` both are refused `required_check_timed_out`; per name the newest run of each workflow counts and every workflow must pass; a checkpoint changing `.github/workflows/` or `.github/actions/` is refused `ci_definition_changed`), a source requiring none refuses `required_checks_unset`, a failed read is `ci_evidence_unavailable`, and `local-gate` is recorded but never counted; the answer's `ci_evidence` is what was read and is copied onto the checkpoint; the answer carries `mode` (bound at placement, `pr` when the claim has no accepted dispatch whatever the source says now, null only on ledger contention) and `base_sha` (that merge base), an allow records it, and the merge executor merges only while the base head still equals it. Requires an orchestrator- or user-ROLE key (`exact_role: [:orchestrator, :user]`, so an agent key is 403'd); `LOOPCTL_ORCH_KEY` is sent when set, else `LOOPCTL_API_KEY`. 403 `custody_tier_required` without a human anchor, 404 for an unknown story, 422 when the story is not at `ci`. Required: `story_id` (refused locally if not a UUID) and `claim_epoch` (a non-negative integer, refused locally otherwise); optional `effect_proof`. |
-| `intake_source_enroll` | **Bind a GitHub repository to a work project and mint its webhook secret** (`POST /api/v1/intake/sources`) — the step that gives the delivery loop an input, and the row `place_dispatch` reads `repo` and `base_branch` from (its 409 `no_intake_source` means this has not been done; 409 `ambiguous_intake_source` means it has been done twice). **The secret is returned ONCE and can never be read again** — the column is encrypted at rest and redacted on the schema, so no other tool carries it and losing it costs a revoke, a re-enrolment and a reconfigured GitHub webhook. **This tool does not return it either:** a tool result lands in the transcript and the audit log, so it is written to the required `secret_file` with mode 0600 (the handling `runner_enroll` gives a runner credential) and the result carries the source row, the `webhook_url` and that path. The path is reserved before the request, so an existing file or an unwritable directory is refused with nothing enrolled, and any outcome that is not a clean creation withholds the response body — an unparsed 2xx body IS the secret. A 2xx carrying the source and the secret but no webhook path is RECOVERED rather than discarded (the path is derived from the source id, flagged `webhook_url_derived`), and an outcome that proves a source id but no usable secret REVOKES that source rather than leaving it holding the repository's unique slot. Then configure GitHub: Payload URL = the returned `webhook_url`, content type `application/json`, Secret = the contents of the file, and the **Issues** event only — `gh api repos/OWNER/REPO/hooks -f name=web -f config[url]=<webhook_url> -f config[content_type]=json -f config[secret]="$(cat <secret_file>)" -f 'events[]=issues'`. Every later delivery failure is the SAME 401 `invalid_signature` — unknown or revoked source, suspended tenant, missing or wrong signature, or a payload whose `repository.full_name` does not match — so the webhook's Recent Deliveries tab cannot tell you which. `base_branch` is set HERE: it defaults to `master` when the body does not name it, so name `main` for a repository created on GitHub since 2020 or every dispatch is cut from a trunk that does not exist. It is not nullable (a dispatch must name a branch), so null or blank is refused rather than falling back to the default, and `intake_source_update` changes it afterwards. Refusals: 403 `api_key_mint_forbidden` if your key was minted by a dispatch (this mints a credential belonging to no lineage, so only an unlineaged operator key may), 403 `custody_tier_required` on an agent-rooted tenant, 422 for a repository that is not `owner/name`, an ACTIVE source already binding it, a project that is missing / archived / not a work project, or a `target_epic_id` outside that project. `mode` picks the merge route: `pr` (the default when omitted) or `thread`, where the merge gate evaluates the story's latest recorded checkpoint instead of a pull request — which needs the source's runners at contract 1.20.0+ sending checkpoint messages, or every story is refused `no_checkpoint_recorded`; any other value, null included, is refused. The mode is bound to each implement dispatch when it is placed, so it decides only what stories placed afterwards get; a change is always allowed. A `thread` source must also name `required_checks` (422 otherwise): the CI checks the merge gate requires on a checkpoint's exact commit, GitHub Actions job names, bounded in number and length by the server; `local-gate` is refused because whoever pushed posts it. Story verification judges a story's commit against the same `required_checks` in EITHER mode, satisfied only by a job of a push run of the story's branch; it first needs an entry for this tenant in the operator's `VERIFICATION_OPERATOR_TOKEN_TENANTS` (`credential_unavailable` otherwise, whatever the list holds); then a `pr` source that names none records `no_required_checks` and reads nothing, so naming them is how a pr source opts in, and a source that names some has its (tenant, repository) pair checked against that list before any GitHub read (`credential_unavailable` if the pair is not an entry). Required: `repo_full_name`, `project_id`, `secret_file`. Optional: `base_branch`, `mode`, `required_checks`, and `target_epic_id` — **omitting the epic is not a neutral default**: with no epic every triaged report is escalated to a human and every record stays `pending_triage` until `intake_source_update` names one. Requires `LOOPCTL_USER_KEY`. |
+| `intake_source_enroll` | **Bind a GitHub repository to a work project and mint its webhook secret** (`POST /api/v1/intake/sources`) — the step that gives the delivery loop an input, and the row `place_dispatch` reads `repo` and `base_branch` from (its 409 `no_intake_source` means this has not been done; 409 `ambiguous_intake_source` means it has been done twice). **The secret is returned ONCE and can never be read again** — the column is encrypted at rest and redacted on the schema, so no other tool carries it and losing it costs a revoke, a re-enrolment and a reconfigured GitHub webhook. **This tool does not return it either:** a tool result lands in the transcript and the audit log, so it is written to the required `secret_file` with mode 0600 (the handling `runner_enroll` gives a runner credential) and the result carries the source row, the `webhook_url` and that path. The path is reserved before the request, so an existing file or an unwritable directory is refused with nothing enrolled, and any outcome that is not a clean creation withholds the response body — an unparsed 2xx body IS the secret. A 2xx carrying the source and the secret but no webhook path is RECOVERED rather than discarded (the path is derived from the source id, flagged `webhook_url_derived`), and an outcome that proves a source id but no usable secret REVOKES that source rather than leaving it holding the repository's unique slot. Then configure GitHub: Payload URL = the returned `webhook_url`, content type `application/json`, Secret = the contents of the file, and the **Issues** event only — `gh api repos/OWNER/REPO/hooks -f name=web -f config[url]=<webhook_url> -f config[content_type]=json -f config[secret]="$(cat <secret_file>)" -f 'events[]=issues'`. Every later delivery failure is the SAME 401 `invalid_signature` — unknown or revoked source, suspended tenant, missing or wrong signature, or a payload whose `repository.full_name` does not match — so the webhook's Recent Deliveries tab cannot tell you which. `base_branch` is set HERE: it defaults to `master` when the body does not name it, so name `main` for a repository created on GitHub since 2020 or every dispatch is cut from a trunk that does not exist. It is not nullable (a dispatch must name a branch), so null or blank is refused rather than falling back to the default, and `intake_source_update` changes it afterwards. Refusals: 403 `api_key_mint_forbidden` if your key was minted by a dispatch (this mints a credential belonging to no lineage, so only an unlineaged operator key may), 403 `custody_tier_required` on an agent-rooted tenant, 422 for a repository that is not `owner/name`, an ACTIVE source already binding it, a project that is missing / archived / not a work project, or a `target_epic_id` outside that project. `mode` picks the merge route: `pr` (the default when omitted) or `thread`, where the merge gate evaluates the story's latest recorded checkpoint instead of a pull request — which needs the source's runners at contract 1.20.0+ sending checkpoint messages, or every story is refused `no_checkpoint_recorded`; any other value, null included, is refused. The mode is bound to each implement dispatch when it is placed, so it decides only what stories placed afterwards get; a change is always allowed. A `thread` source must also name `required_checks` (422 otherwise): the CI checks the merge gate requires on a checkpoint's exact commit, GitHub Actions job names, bounded in number and length by the server; `local-gate` is refused because whoever pushed posts it. Story verification judges a story's commit against the same `required_checks` in EITHER mode, satisfied only by a job of a push run of the story's branch; it first needs a GitHub credential for this tenant, its own token (`set_github_credential`) or an entry in the operator's `VERIFICATION_OPERATOR_TOKEN_TENANTS` (`credential_unavailable` otherwise, whatever the list holds); then a `pr` source that names none records `no_required_checks` and reads nothing, so naming them is how a pr source opts in, and a source that names some has its (tenant, repository) credential resolved before any GitHub read (`credential_unavailable` if there is none). Required: `repo_full_name`, `project_id`, `secret_file`. Optional: `base_branch`, `mode`, `required_checks`, and `target_epic_id` — **omitting the epic is not a neutral default**: with no epic every triaged report is escalated to a human and every record stays `pending_triage` until `intake_source_update` names one. Requires `LOOPCTL_USER_KEY`. |
 | `intake_source_list` | List the tenant's intake sources (`GET /api/v1/intake/sources`): `id` (the webhook URL is `/api/v1/intake/github/<id>`), `project_id`, `repo_full_name`, `base_branch`, `mode` (`pr` or `thread`), `target_epic_id`, `revoked_at`, timestamps. **The webhook secret is not here and is not anywhere** — it is returned once by `intake_source_enroll`, so this is not how to recover one. Use it to find the source behind a 409 `no_intake_source` or `ambiguous_intake_source`, to check a repository's `base_branch` before placing work, and to identify a source left behind by an enrolment whose outcome was unknown. Optional: `include_revoked`. Requires `LOOPCTL_USER_KEY`; the only one of the four that does not also need a human-anchored tenant. |
-| `intake_source_update` | **Set where a source's work lands** (`PATCH /api/v1/intake/sources/:id`): `target_epic_id`, the epic triaged stories are created in, `base_branch`, the branch every dispatch for this repository is cut from, `mode` (`pr` or `thread`), whether the merge gate reads a pull request or the story's latest recorded thread checkpoint, and `required_checks`, the CI checks a thread checkpoint must pass on its exact commit and the checks story verification judges a story's commit by in either mode — once the tenant has an entry in the operator's `VERIFICATION_OPERATOR_TOKEN_TENANTS` (`credential_unavailable` otherwise), a pr source naming none records `no_required_checks` and reads nothing, and one naming some has its (tenant, repository) pair checked against that list before any GitHub read (a thread source must name at least one, judged over the source as it will be, so switching to `thread` without them or clearing them on a thread source is 422; `local-gate` is refused). Presence decides — a field you do not name is left exactly as it was, and naming none of them is 422 `nothing_to_update`. `mode` has no cleared state either, and a null or unknown value is refused locally; A change is always allowed and affects only stories placed afterwards: each implement dispatch records the mode, and the base branch, it was placed under, and the merge gate reads those. **Do not send `target_epic_id: null` to mean "not changing this":** an explicit null is the only way to CLEAR the epic, which returns the source to escalating every report instead of filing a story. `base_branch` has no cleared state and a null there is refused locally. This is how a source already pointed at the wrong trunk is corrected — `intake_source_enroll` takes `base_branch` itself, so a `main` repository no longer needs a second call — and the remedy for a source with no epic — every record from it stays `pending_triage` and is retried until one is named, then they promote on the next run with nothing lost. Revoked sources are 404, not a no-op: revoking clears the target so the epic can be deleted, and repointing one would put that block back. 422 when the epic is not in this source's project. Required: `source_id` (refused locally if it is not a UUID — the server answers the same 404 for malformed and unknown). Requires `LOOPCTL_USER_KEY` and a human-anchored tenant. |
+| `intake_source_update` | **Set where a source's work lands** (`PATCH /api/v1/intake/sources/:id`): `target_epic_id`, the epic triaged stories are created in, `base_branch`, the branch every dispatch for this repository is cut from, `mode` (`pr` or `thread`), whether the merge gate reads a pull request or the story's latest recorded thread checkpoint, and `required_checks`, the CI checks a thread checkpoint must pass on its exact commit and the checks story verification judges a story's commit by in either mode — once the tenant has a GitHub credential, its own token (`set_github_credential`) or an entry in the operator's `VERIFICATION_OPERATOR_TOKEN_TENANTS` (`credential_unavailable` otherwise), a pr source naming none records `no_required_checks` and reads nothing, and one naming some has its (tenant, repository) credential resolved before any GitHub read (a thread source must name at least one, judged over the source as it will be, so switching to `thread` without them or clearing them on a thread source is 422; `local-gate` is refused). Presence decides — a field you do not name is left exactly as it was, and naming none of them is 422 `nothing_to_update`. `mode` has no cleared state either, and a null or unknown value is refused locally; A change is always allowed and affects only stories placed afterwards: each implement dispatch records the mode, and the base branch, it was placed under, and the merge gate reads those. **Do not send `target_epic_id: null` to mean "not changing this":** an explicit null is the only way to CLEAR the epic, which returns the source to escalating every report instead of filing a story. `base_branch` has no cleared state and a null there is refused locally. This is how a source already pointed at the wrong trunk is corrected — `intake_source_enroll` takes `base_branch` itself, so a `main` repository no longer needs a second call — and the remedy for a source with no epic — every record from it stays `pending_triage` and is retried until one is named, then they promote on the next run with nothing lost. Revoked sources are 404, not a no-op: revoking clears the target so the epic can be deleted, and repointing one would put that block back. 422 when the epic is not in this source's project. Required: `source_id` (refused locally if it is not a UUID — the server answers the same 404 for malformed and unknown). Requires `LOOPCTL_USER_KEY` and a human-anchored tenant. |
 | `intake_source_revoke` | **Revoke an intake source** (`DELETE /api/v1/intake/sources/:id`). The verb is DELETE and the action is a revoke: `revoked_at` is stamped, the row is kept, and `intake_source_list` still returns it with `include_revoked`; nothing already received is discarded. Afterwards every delivery to that URL is refused 401 `invalid_signature` exactly as a wrong secret is, so the GitHub webhook does not know it has been cut off and should be deleted on the repository too. Idempotent — a second revoke answers 200 with the original `revoked_at`. It frees the repository's uniqueness slot (the index is partial on not-yet-revoked), so a source with a lost secret, a wrong project or a typo'd repository is corrected by revoking and enrolling again; and it clears `target_epic_id`, which is what makes that epic deletable and is the remedy an epic-delete refusal names. Required: `source_id` (refused locally if it is not a UUID). Requires `LOOPCTL_USER_KEY` and a human-anchored tenant. |
 
 ### Dispatch & Chain of Custody (v2) Tools

package/index.js

@@ -15,6 +15,7 @@ import os from "node:os";
 import crypto from "node:crypto";
 import path from "node:path";
 import { applyArgAliases } from "./lib/arg-aliases.js";
+import { articleId } from "./lib/article-id.js";
 import { clientContextHeader } from "./lib/client-context.js";
 import { resolveClaimSessionId } from "./lib/claim-session.js";
 import { degradedSearchNotice } from "./lib/search-notices.js";
@@ -78,6 +79,11 @@ import {
 } from "./lib/intake-sources.js";
 import { mcpVersion as mcpVersionRequest, packageVersion } from "./lib/mcp-version.js";
 import { revokeDispatch as revokeDispatchRequest } from "./lib/dispatch-revoke.js";
+import {
+  clearGithubCredential as clearGithubCredentialRequest,
+  githubCredential as githubCredentialRequest,
+  setGithubCredential as setGithubCredentialRequest,
+} from "./lib/github-credential.js";
 import {
   createEpic as createEpicRequest,
   deleteEpic as deleteEpicRequest,
@@ -1663,8 +1669,10 @@ async function knowledgeStats({ project_id }) {
 }
 
 async function knowledgeGraph({ article_id, depth, project_id }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const params = new URLSearchParams();
-  params.set("article_id", article_id);
+  params.set("article_id", art.id);
   if (depth != null) params.set("depth", String(depth));
   if (project_id) params.set("project_id", project_id);
   const result = await apiCall(
@@ -1677,11 +1685,13 @@ async function knowledgeGraph({ article_id, depth, project_id }) {
 }
 
 async function knowledgeSuggestLinks({ article_id, limit, threshold }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const params = new URLSearchParams();
   if (limit != null) params.set("limit", String(limit));
   if (threshold != null) params.set("threshold", String(threshold));
   const qs = params.toString();
-  const base = `/api/v1/knowledge/articles/${article_id}/suggested_links`;
+  const base = `/api/v1/knowledge/articles/${art.id}/suggested_links`;
   const result = await apiCall(
     "GET",
     qs ? `${base}?${qs}` : base,
@@ -1866,6 +1876,8 @@ async function knowledgeHeatIndex({ category, limit, since }) {
 }
 
 async function knowledgeProgressiveDrill({ article_id, body_max_bytes, body_offset }) {
+  const art = articleId(article_id, { prefix: true });
+  if (art.refusal) return toContent(art.refusal);
   const params = new URLSearchParams();
   // 0 is meaningful on both (whole body / start at the beginning), so test for
   // null/undefined rather than truthiness.
@@ -1874,7 +1886,7 @@ async function knowledgeProgressiveDrill({ article_id, body_max_bytes, body_offs
   if (body_offset !== undefined && body_offset !== null)
     params.set("body_offset", String(body_offset));
   const qs = params.toString();
-  const base = `/api/v1/knowledge/progressive/${article_id}`;
+  const base = `/api/v1/knowledge/progressive/${art.id}`;
   const result = await apiCall(
     "GET",
     qs ? `${base}?${qs}` : base,
@@ -1937,6 +1949,11 @@ async function knowledgeGet({
   body_max_bytes,
   body_offset,
 }) {
+  // A missing id went out as /undefined and a malformed one as whatever it spelled
+  // ('', '#', '..', 'x?y' each reach a different route); the server's answer read as
+  // "this article does not exist". Refused here with status 0, before any request.
+  const art = articleId(article_id, { prefix: true });
+  if (art.refusal) return toContent(art.refusal);
   const params = new URLSearchParams();
   if (project_id) params.set("project_id", project_id);
   if (story_id) params.set("story_id", story_id);
@@ -1948,7 +1965,7 @@ async function knowledgeGet({
   if (body_offset !== undefined && body_offset !== null)
     params.set("body_offset", String(body_offset));
   const qs = params.toString();
-  const path = qs ? `/api/v1/articles/${article_id}?${qs}` : `/api/v1/articles/${article_id}`;
+  const path = qs ? `/api/v1/articles/${art.id}?${qs}` : `/api/v1/articles/${art.id}`;
   const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
   return toContent(result);
 }
@@ -2026,6 +2043,8 @@ async function knowledgeCreate({
 // provided fields change. Agent role — KB-content curation, visibility-scoped
 // server-side (another agent's private/owner memory 404s).
 async function knowledgeUpdate({ article_id, title, body, category, tags, metadata }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const payload = {};
   if (title != null) payload.title = title;
   if (body != null) payload.body = body;
@@ -2035,7 +2054,7 @@ async function knowledgeUpdate({ article_id, title, body, category, tags, metada
 
   const result = await apiCall(
     "PATCH",
-    `/api/v1/articles/${article_id}`,
+    `/api/v1/articles/${art.id}`,
     payload,
     process.env.LOOPCTL_AGENT_KEY,
   );
@@ -2226,7 +2245,9 @@ async function memoryGraduate({ memory_id, re_scope }) {
 // --- Knowledge Management Tools (orch key) ---
 
 async function knowledgePublish({ article_id }) {
-  const result = await apiCall("POST", `/api/v1/articles/${article_id}/publish`, null, process.env.LOOPCTL_ORCH_KEY);
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
+  const result = await apiCall("POST", `/api/v1/articles/${art.id}/publish`, null, process.env.LOOPCTL_ORCH_KEY);
   return toContent(result);
 }
 
@@ -2281,9 +2302,11 @@ async function knowledgeBulkUnpublish({ article_ids }) {
 }
 
 async function knowledgeUnpublish({ article_id }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const result = await apiCall(
     "POST",
-    `/api/v1/articles/${article_id}/unpublish`,
+    `/api/v1/articles/${art.id}/unpublish`,
     null,
     process.env.LOOPCTL_USER_KEY
   );
@@ -2294,9 +2317,11 @@ async function knowledgeUnpublish({ article_id }) {
 // audited, visibility-scoped server-side). NOT reversible in code — #606/#605: `:archived`
 // is a terminal status. The row survives; nothing automated brings it back.
 async function knowledgeArchive({ article_id }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const result = await apiCall(
     "POST",
-    `/api/v1/articles/${article_id}/archive`,
+    `/api/v1/articles/${art.id}/archive`,
     null,
     process.env.LOOPCTL_AGENT_KEY
   );
@@ -2307,9 +2332,11 @@ async function knowledgeArchive({ article_id }) {
 // one member of that family that undoes: nothing is destroyed and nothing is rebuilt, so
 // knowledge_unsuppress restores the article to every read path immediately.
 async function knowledgeSuppress({ article_id, reason }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const result = await apiCall(
     "POST",
-    `/api/v1/articles/${article_id}/suppress`,
+    `/api/v1/articles/${art.id}/suppress`,
     { reason },
     process.env.LOOPCTL_AGENT_KEY
   );
@@ -2317,9 +2344,11 @@ async function knowledgeSuppress({ article_id, reason }) {
 }
 
 async function knowledgeUnsuppress({ article_id }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const result = await apiCall(
     "POST",
-    `/api/v1/articles/${article_id}/unsuppress`,
+    `/api/v1/articles/${art.id}/unsuppress`,
     null,
     process.env.LOOPCTL_AGENT_KEY
   );
@@ -2328,9 +2357,11 @@ async function knowledgeUnsuppress({ article_id }) {
 
 // #331: soft-delete (archive) is agent-role KB curation, same as knowledge_archive.
 async function knowledgeDelete({ article_id }) {
+  const art = articleId(article_id);
+  if (art.refusal) return toContent(art.refusal);
   const result = await apiCall(
     "DELETE",
-    `/api/v1/articles/${article_id}`,
+    `/api/v1/articles/${art.id}`,
     null,
     process.env.LOOPCTL_AGENT_KEY
   );
@@ -2610,6 +2641,27 @@ async function setLlmConfig({
   return toContent(result);
 }
 
+// --- #936: the tenant's own GitHub token ------------------------------------
+// A stored credential, so EXACT user key only, like set_llm_config.
+function userKeyApi() {
+  return {
+    apiCall: (method, path, body) =>
+      apiCall(method, path, body, process.env.LOOPCTL_USER_KEY, { exactKey: true }),
+  };
+}
+
+async function githubCredential(args) {
+  return toContent(await githubCredentialRequest(args, userKeyApi()));
+}
+
+async function setGithubCredential(args) {
+  return toContent(await setGithubCredentialRequest(args, userKeyApi()));
+}
+
+async function clearGithubCredential(args) {
+  return toContent(await clearGithubCredentialRequest(args, userKeyApi()));
+}
+
 // --- US-41.4: fail-closed no-egress guard -----------------------------------
 //
 // egress_posture is a READ available at AGENT role: an agent must be able to
@@ -2786,9 +2838,11 @@ async function knowledgeCurationLog({ kind, since, limit, offset } = {}) {
 }
 
 async function knowledgeArticleStats({ article_id }) {
+  const art = articleId(article_id, { prefix: true });
+  if (art.refusal) return toContent(art.refusal);
   const result = await apiCall(
     "GET",
-    `/api/v1/knowledge/articles/${article_id}/stats`,
+    `/api/v1/knowledge/articles/${art.id}/stats`,
     null,
     process.env.LOOPCTL_ORCH_KEY
   );
@@ -5516,7 +5570,8 @@ const TOOLS = [
         article_id: {
           type: "string",
           format: "uuid",
-          description: "Starting article UUID (required).",
+          description:
+            "Starting article UUID (required). A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
         depth: {
           type: "integer",
@@ -5549,7 +5604,8 @@ const TOOLS = [
         article_id: {
           type: "string",
           format: "uuid",
-          description: "The article to suggest links for (required).",
+          description:
+            "The article to suggest links for (required). A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
         limit: { type: "integer", description: "Max candidates (default 5)." },
         threshold: {
@@ -5899,8 +5955,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          format: "uuid",
-          description: "The UUID of the article to open (from a progressive index stub).",
+          description:
+            "The UUID of the article to open (from a progressive index stub). Or a prefix of at least 8 hex digits (the server matches its first 8). A missing, blank, shorter or non-hex value is refused locally with status 0 and no request is sent.",
         },
         body_max_bytes: {
           type: "integer",
@@ -5959,7 +6015,10 @@ const TOOLS = [
           description:
             "The UUID of the article. A unique ID PREFIX (>= 8 hex characters) also " +
             "resolves, so copy what you have rather than reconstructing 36 characters " +
-            "from memory; an ambiguous prefix is a 404, never a guess.",
+            "from memory; an ambiguous prefix is a 404, never a guess. The server matches a " +
+            "prefix on its first 8 hex digits only. Surrounding whitespace is trimmed. A " +
+            "missing or blank id, fewer than 8 hex digits, or any character other than hex " +
+            "digits and dashes is refused locally with status 0 and no request is sent.",
         },
         links: {
           type: "string",
@@ -6206,7 +6265,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the article to edit (preserved across the update).",
+          description:
+            "The UUID of the article to edit (preserved across the update). A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
         title: {
           type: "string",
@@ -6584,7 +6644,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the draft article to publish.",
+          description:
+            "The UUID of the draft article to publish. A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
       },
       required: ["article_id"],
@@ -6652,7 +6713,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the published article to unpublish.",
+          description:
+            "The UUID of the published article to unpublish. A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
       },
       required: ["article_id"],
@@ -6675,7 +6737,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the article to archive.",
+          description:
+            "The UUID of the article to archive. A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
       },
       required: ["article_id"],
@@ -6710,7 +6773,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the article to take out of retrieval.",
+          description:
+            "The UUID of the article to take out of retrieval. A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
         reason: {
           type: "string",
@@ -6738,7 +6802,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the article to restore to retrieval.",
+          description:
+            "The UUID of the article to restore to retrieval. A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
       },
       required: ["article_id"],
@@ -6760,7 +6825,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the article to delete.",
+          description:
+            "The UUID of the article to delete. A full UUID: anything else (missing, blank, a prefix) is refused locally with status 0 and no request is sent.",
         },
       },
       required: ["article_id"],
@@ -7596,6 +7662,59 @@ const TOOLS = [
       required: ["host"],
     },
   },
+  {
+    name: "github_credential",
+    description:
+      "CHECK this tenant's GitHub credential (#936): `has_token`, a masked last-4 " +
+      "`token_hint`, `updated_at`, and `operator_repositories` — the repositories the " +
+      "operator's token is lent for while you have no token of your own. NEVER returns the " +
+      "token. Reach for it when a merge gate refusal says " +
+      "`{pull_request_unavailable, credential_unavailable}`, a verification run records " +
+      "`credential_unavailable`, or an issue closure is waiting on that reason: it " +
+      "tells you whether the repository has any credential at all. Requires " +
+      "LOOPCTL_USER_KEY (403 for any other role).",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "set_github_credential",
+    description:
+      "SET OR REPLACE this tenant's own GitHub token (#936, PUT " +
+      "/api/v1/tenants/me/github-credential). From then on EVERY GitHub call loopctl makes for " +
+      "this tenant uses it — the merge gate, story and post-deploy verification, thread " +
+      "checkpoint reads and issue closing — for EVERY repository, replacing the operator's " +
+      "token even for repositories the operator lent it for. Use a fine-grained token limited " +
+      "to your own intake-source repositories with read access to Contents, Pull requests, " +
+      "Actions, Commit statuses and Deployments, plus Issues: write if loopctl should close " +
+      "the issues stories came from. Stored encrypted, never returned. NOT checked against " +
+      "GitHub here: a token that cannot read a repository shows up as that repository's forge " +
+      "refusal (a 403/404 in the merge gate or verification), so check a story after setting " +
+      "it. A thread-mode MERGE is still written by loopctl's GitHub App, and only for a " +
+      "repository the operator named for your tenant: this token never licenses it (escalated " +
+      "`app_not_licensed`). 422 when blank, over the server's length bound or containing " +
+      "anything but letters, digits and underscores; 403 " +
+      "custody_tier_required on an agent-rooted tenant. Requires LOOPCTL_USER_KEY (403 for " +
+      "any other role).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        token: {
+          type: "string",
+          description: "The GitHub token. Write-only; stored encrypted, never returned.",
+        },
+      },
+      required: ["token"],
+    },
+  },
+  {
+    name: "clear_github_credential",
+    description:
+      "REMOVE this tenant's GitHub token (#936, DELETE /api/v1/tenants/me/github-credential). " +
+      "Every GitHub call for the tenant then uses the operator's token ONLY for the " +
+      "repositories `github_credential` lists as `operator_repositories`, and is refused " +
+      "`credential_unavailable` for every other one — a pr-mode repository outside that list " +
+      "stops merging. Idempotent. Requires LOOPCTL_USER_KEY (403 for any other role).",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
   {
     name: "llm_config",
     description:
@@ -8013,7 +8132,8 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          description: "The UUID of the article to inspect.",
+          description:
+            "The UUID of the article to inspect. Or a prefix of at least 8 hex digits (the server matches its first 8). A missing, blank, shorter or non-hex value is refused locally with status 0 and no request is sent.",
         },
       },
       required: ["article_id"],
@@ -9023,13 +9143,13 @@ const TOOLS = [
             "merge gate allows it, and the checks story verification judges a story's commit " +
             "by in EITHER mode: GitHub Actions job names as they appear on the commit, satisfied " +
             "only by a job of a PUSH run of the story's branch. A `thread` source must name at " +
-            "least one (422 otherwise). Verification first needs an entry for this tenant in " +
-            "the operator's VERIFICATION_OPERATOR_TOKEN_TENANTS (`credential_unavailable` " +
-            "otherwise, whatever this list holds); then a `pr` source that names none records " +
-            "`no_required_checks` and reads nothing (naming them is how a pr source opts in), " +
-            "and a source that names some has its (tenant, repository) pair checked against " +
-            "that list before any GitHub read (`credential_unavailable` if the pair is not an " +
-            "entry). Distinct, non-blank names, bounded in number and length by the server (422 past them). " +
+            "least one (422 otherwise). Verification first needs a GitHub credential for this " +
+            "tenant: its own token (set_github_credential) or an entry in the operator's " +
+            "VERIFICATION_OPERATOR_TOKEN_TENANTS (`credential_unavailable` otherwise, whatever " +
+            "this list holds); then a `pr` source that names none records `no_required_checks` " +
+            "and reads nothing (naming them is how a pr source opts in), and a source that " +
+            "names some has its (tenant, repository) credential resolved before any GitHub " +
+            "read (`credential_unavailable` if there is none). Distinct, non-blank names, bounded in number and length by the server (422 past them). " +
             "`local-gate` is refused: whoever pushed posts it, so it is only recorded.",
         },
         secret_file: {
@@ -9140,13 +9260,13 @@ const TOOLS = [
             "merge gate allows it, and the checks story verification judges a story's commit " +
             "by in EITHER mode: GitHub Actions job names as they appear on the commit, satisfied " +
             "only by a job of a PUSH run of the story's branch. A `thread` source must name at " +
-            "least one (422 otherwise). Verification first needs an entry for this tenant in " +
-            "the operator's VERIFICATION_OPERATOR_TOKEN_TENANTS (`credential_unavailable` " +
-            "otherwise, whatever this list holds); then a `pr` source that names none records " +
-            "`no_required_checks` and reads nothing (naming them is how a pr source opts in), " +
-            "and a source that names some has its (tenant, repository) pair checked against " +
-            "that list before any GitHub read (`credential_unavailable` if the pair is not an " +
-            "entry). Distinct, non-blank names, bounded in number and length by the server (422 past them). " +
+            "least one (422 otherwise). Verification first needs a GitHub credential for this " +
+            "tenant: its own token (set_github_credential) or an entry in the operator's " +
+            "VERIFICATION_OPERATOR_TOKEN_TENANTS (`credential_unavailable` otherwise, whatever " +
+            "this list holds); then a `pr` source that names none records `no_required_checks` " +
+            "and reads nothing (naming them is how a pr source opts in), and a source that " +
+            "names some has its (tenant, repository) credential resolved before any GitHub " +
+            "read (`credential_unavailable` if there is none). Distinct, non-blank names, bounded in number and length by the server (422 past them). " +
             "`local-gate` is refused. Omit to leave the current list alone.",
         },
       },
@@ -9825,6 +9945,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       );
     },
     declaredToolArgs(name),
+    name,
   );
 
   switch (name) {
@@ -10182,6 +10303,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "set_llm_config":
       return await setLlmConfig(args);
 
+    // #936: the tenant's own GitHub token
+    case "github_credential":
+      return await githubCredential(args);
+
+    case "set_github_credential":
+      return await setGithubCredential(args);
+
+    case "clear_github_credential":
+      return await clearGithubCredential(args);
+
     case "knowledge_llm_usage":
       return await knowledgeLlmUsage(args);
 

package/lib/arg-aliases.js

@@ -66,8 +66,26 @@ const ARG_ALIASES = {
   limit: ["max_results"],
 };
 
+// TOOL-SCOPED aliases, keyed by tool name, applied only when the called tool declares the
+// canonical and not the alias. `id` cannot go in the global table above: memory_forget and
+// others declare `id` as their own parameter, and the drift guard refuses it there.
+//
+// `article_id <- id` on knowledge_get is measured: 17 of 96 knowledge_get calls in mac-mini's
+// session transcripts (2026-10-01) passed `{"id": ...}`, the key every search result carries
+// its id under, and the request went out as `/api/v1/articles/undefined`. All 30
+// knowledge_get 404s in production for 2026-09-25..30 were that request.
+// knowledge_progressive_drill is the same mechanism: its documented input is a progressive
+// index stub, which carries the id under the same `id` key. A write verb never joins: there
+// the alias would turn a harmless miss into a write against an id copied from the wrong row.
+const TOOL_SCOPED_ALIASES = {
+  knowledge_get: { article_id: ["id"] },
+  knowledge_progressive_drill: { article_id: ["id"] },
+};
+
+// Whitespace-only is blank, matching articleId(), which trims: otherwise a "  " article_id
+// blocks the rescue here and is then refused as missing there, discarding a good `id`.
 function isBlank(v) {
-  return v === undefined || v === null || v === "";
+  return v === undefined || v === null || (typeof v === "string" && v.trim() === "");
 }
 
 /**
@@ -78,8 +96,11 @@ function isBlank(v) {
  * supplied, only a fill of a declared key is reported as a rescue — the rest are inert
  * conveniences. Omit it and every fill is reported (the conservative default for a tool
  * whose schema is not known, e.g. the per-tenant `cr_*` tools).
+ *
+ * `toolName` selects that tool's TOOL_SCOPED_ALIASES, which apply only when BOTH `declared`
+ * and `toolName` are given.
  */
-function applyArgAliases(args, onAliasUsed, declared) {
+function applyArgAliases(args, onAliasUsed, declared, toolName) {
   if (!args || typeof args !== "object" || Array.isArray(args)) return args;
 
   const out = { ...args };
@@ -109,6 +130,24 @@ function applyArgAliases(args, onAliasUsed, declared) {
     }
   }
 
+  const scoped =
+    declaredSet !== null && toolName && Object.hasOwn(TOOL_SCOPED_ALIASES, toolName)
+      ? TOOL_SCOPED_ALIASES[toolName]
+      : {};
+  for (const [canonical, aliases] of Object.entries(scoped)) {
+    if (!declaredSet.has(canonical) || !isBlank(out[canonical])) continue;
+    const alias = aliases.find((a) => !declaredSet.has(a) && !isBlank(out[a]));
+    if (alias === undefined) continue;
+    out[canonical] = out[alias];
+    if (typeof onAliasUsed === "function") {
+      try {
+        onAliasUsed({ canonical, alias });
+      } catch {
+        // Telemetry must never break a tool call.
+      }
+    }
+  }
+
   // Some callers send a numeric arg as a string ("6"). Coerce so downstream validation and
   // the outbound query string both see a number rather than rejecting or double-encoding.
   if (typeof out.limit === "string" && /^\d+$/.test(out.limit.trim())) {
@@ -118,4 +157,4 @@ function applyArgAliases(args, onAliasUsed, declared) {
   return out;
 }
 
-export { ARG_ALIASES, applyArgAliases };
+export { ARG_ALIASES, TOOL_SCOPED_ALIASES, applyArgAliases };

package/lib/article-id.js

@@ -0,0 +1,17 @@
+/**
+ * An `article_id` bound for a URL path or query: trimmed (an id pasted with a trailing newline
+ * is the id), then held to the shared `uuid()` check in lib/delivery-loop.js. Returns `{ id }`
+ * to send, or `{ refusal }` (status 0, value never echoed).
+ *
+ * The reads whose server path resolves an id prefix (#652: knowledge_get,
+ * knowledge_progressive_drill, knowledge_article_stats) pass `{ prefix: true }`; every other
+ * article verb takes a full UUID. A missing id used to go out as `/undefined` and come back as
+ * a 404 that agents read as "the article does not exist".
+ */
+import { uuid } from "./delivery-loop.js";
+
+export function articleId(value, { prefix = false } = {}) {
+  const trimmed = typeof value === "string" ? value.trim() : value;
+  const refusal = uuid(trimmed, "article_id", { prefix });
+  return refusal ? { refusal } : { id: trimmed };
+}

package/lib/delivery-loop.js

@@ -48,7 +48,9 @@ function refuse(body) {
 }
 
 /**
- * A client-side shape check on the ids that go into a URL PATH: `story_id` and `runner_id`.
+ * A client-side shape check on the ids that go into a URL PATH: `story_id` and `runner_id`
+ * here, and `article_id` on the knowledge verbs through `lib/article-id.js` (which adds the
+ * `prefix` grammar its reads accept).
  *
  * EXPORTED, because it is one check and not a pattern to copy. `update_story`
  * (`lib/story-update.js`) interpolates a `story_id` into a path exactly as the verbs below do
@@ -111,15 +113,30 @@ function refuse(body) {
  * into the transcript.
  */
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-export function uuid(value, field) {
-  if (typeof value !== "string" || value.trim() === "") {
+const PREFIX_RE = /^[0-9a-f-]+$/i;
+
+// `prefix: true` also accepts what the server's id-prefix fallback resolves (#652,
+// `Knowledge.id_prefix_range/1`, reached by knowledge_get, knowledge_progressive_drill and
+// knowledge_article_stats): hex digits and dashes with at least 8 hex digits, dashless or
+// partial. The server compares only the FIRST 8 hex digits and resolves when exactly one
+// article has them: the rest of a longer value is not checked, so a full-length id with a
+// wrong tail resolves to the article owning its first 8 (#652's design, for confabulated tails).
+// Only hex and dashes are accepted, so nothing in a prefix can change the route ('#', '?', '/').
+export function uuid(value, field, { prefix = false } = {}) {
+  if (value === undefined || value === null || (typeof value === "string" && value.trim() === "")) {
     return refuse(`\`${field}\` is required.`);
   }
 
+  if (typeof value !== "string") {
+    return refuse(`\`${field}\` must be a string; got a ${Array.isArray(value) ? "array" : typeof value}.`);
+  }
+
+  if (prefix && PREFIX_RE.test(value) && value.replace(/-/g, "").length >= 8) return null;
+
   if (!UUID_RE.test(value)) {
     return refuse(
-      `\`${field}\` must be a UUID (8-4-4-4 hex digits then 12, lowercase or upper). ` +
+      `\`${field}\` must be a UUID (8-4-4-4 hex digits then 12, lowercase or upper)` +
+        (prefix ? " or a prefix of at least 8 hex digits. " : ". ") +
         `Got a ${value.length}-character string that is not one. The value is not repeated ` +
         `here: a malformed id is often something pasted into the wrong argument, and a tool ` +
         `result lands in the transcript.`,

package/lib/github-credential.js

@@ -0,0 +1,45 @@
+/**
+ * `github_credential`, `set_github_credential`, `clear_github_credential` — the tenant's own
+ * GitHub token (#936), `GET|PUT|DELETE /api/v1/tenants/me/github-credential`.
+ *
+ * loopctl calls GitHub for a tenant in the merge gate, story and post-deploy verification,
+ * thread checkpoint reads and issue closing. Each call authenticates with the tenant's own
+ * token when one is set, else with the operator's token for the (tenant, repository) pairs
+ * the operator named in VERIFICATION_OPERATOR_TOKEN_TENANTS, else not at all
+ * (`credential_unavailable`). The tenant's token is what lets loopctl serve a repository
+ * the operator's token cannot, without ever reading one the tenant cannot.
+ *
+ * All three need the `:user` key: the endpoint manages a stored credential. The token is
+ * never returned — reads show `has_token`, a last-4 `token_hint` and the repositories the
+ * operator's token is lent for.
+ */
+
+export const GITHUB_CREDENTIAL_PATH = "/api/v1/tenants/me/github-credential";
+
+function refuse(body) {
+  return { error: true, status: 0, body };
+}
+
+export async function githubCredential(_args = {}, { apiCall } = {}) {
+  return apiCall("GET", GITHUB_CREDENTIAL_PATH, null);
+}
+
+/**
+ * A missing or non-string token is refused HERE, before any call, and the refusal never
+ * repeats the value: a tool result lands in the transcript.
+ */
+export async function setGithubCredential({ token } = {}, { apiCall } = {}) {
+  if (typeof token !== "string" || token.trim() === "") {
+    return refuse(
+      "`token` is required: a GitHub token (a fine-grained token limited to your own " +
+        "repositories is the intended shape) with read access to contents, pull requests, " +
+        "actions, commit statuses and deployments, plus issues: write for issue closing.",
+    );
+  }
+
+  return apiCall("PUT", GITHUB_CREDENTIAL_PATH, { token });
+}
+
+export async function clearGithubCredential(_args = {}, { apiCall } = {}) {
+  return apiCall("DELETE", GITHUB_CREDENTIAL_PATH, null);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.111.2",
+  "version": "2.113.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",