@bongos/core 1.18.3 → 1.18.18

package/docs/api/openapi.json

@@ -1,13 +1,13 @@
 {
   "openapi": "3.1.0",
   "info": {
-    "title": "Cloud Bongos — GDS API",
+    "title": "Cloud Bongos — Bongos API",
     "version": "0.0.2",
     "license": {
       "name": "AGPL-3.0-or-later",
       "url": "https://www.gnu.org/licenses/agpl-3.0.html"
     },
-    "description": "The Game Development System (GDS) API — the build-methodology backend\n(builders, tasks, claims, credits, grading, memory, dev boxes).\n\n**API version:** `v1` — served at `/api/bongos/v1`. The\nunversioned `/api/bongos` and legacy `/api/gds` are permanent aliases\npinned to this version; pin to `/api/bongos/v1` for a stable\ncontract (breaking changes ship a new `/vN`, ADR 0117). This is the\nCONTRACT version, distinct from the package build in `info.version`.\n\n**Base path:** `/api/bongos` (every path below is relative to it).\n\n**Auth:** a builder session — the `gds_session` cookie (web) or\n`Authorization: Bearer <token>` (CLI). **Ranks** gate writes and are\nenforced server-side per request, never cached (ADR 0016):\n`public` < `any-builder` < `metic+archon` < `archon`.\nEach operation carries its required rank in `x-rank`.\n\nGenerated from the live route files by `scripts/gds/gen-api-docs.js` —\ndo not hand-edit; it regenerates on every ship."
+    "description": "The Bongos API — the build-methodology backend\n(builders, tasks, claims, credits, grading, memory, dev boxes).\n\n**API version:** `v1` — served at `/api/bongos/v1`. The\nunversioned `/api/bongos` and legacy `/api/gds` are permanent aliases\npinned to this version; pin to `/api/bongos/v1` for a stable\ncontract (breaking changes ship a new `/vN`, ADR 0117). This is the\nCONTRACT version, distinct from the package build in `info.version`.\n\n**Base path:** `/api/bongos` (every path below is relative to it).\n\n**Auth:** a builder session — the `gds_session` cookie (web) or\n`Authorization: Bearer <token>` (CLI). **Ranks** gate writes and are\nenforced server-side per request, never cached (ADR 0016):\n`public` < `any-builder` < `metic+archon` < `archon`.\nEach operation carries its required rank in `x-rank`.\n\nGenerated from the live route files by `scripts/gds/gen-api-docs.js` —\ndo not hand-edit; it regenerates on every ship."
   },
   "x-api-version": "v1",
   "servers": [
@@ -644,6 +644,45 @@
         "security": []
       }
     },
+    "/auth/backchannel-logout": {
+      "post": {
+        "operationId": "post_auth_backchannel_logout",
+        "tags": [
+          "auth"
+        ],
+        "summary": "POST /auth/backchannel-logout",
+        "description": "POST /auth/backchannel-logout — the INSTANCE side of federated single-logout (ADR 0144, task 1002238). The hub POSTs a hub-signed logout token here when a builder signs out of the hub; we verify it and revoke ALL of that builder's local sessions, so one hub logout ends the session on every federated project. rank: public — the hub-signed EdDSA logout token IS the credential (like the OAuth callback), NOT a builder session. Inert (404) on an instance that does not federate through a hub (idp unset), so a self-hosted instance exposes no new surface. Idempotent: an unknown/replayed subject just revokes nothing.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "src/bongos/routes/auth.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostAuthBackchannelLogoutRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostAuthBackchannelLogoutResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          }
+        },
+        "security": []
+      }
+    },
     "/auth/cli-token/issue": {
       "post": {
         "operationId": "post_auth_cli_token_issue",
@@ -1010,6 +1049,34 @@
         ]
       }
     },
+    "/auth/web/admission-status": {
+      "get": {
+        "operationId": "get_auth_web_admission_status",
+        "tags": [
+          "auth"
+        ],
+        "summary": "GET /auth/web/admission-status",
+        "description": "GET /auth/web/admission-status?login=X — the probe renderAccessPendingPage polls (task 1002097). Answers ONE question: would this login be admitted right now? It mirrors the real gate via auth.webAdmissionStatus so the page can never invite someone in the gate would refuse. rank: public — it must be reachable by a visitor with no session (that is the entire situation it exists for). It grants nothing: admission still runs through the normal sign-in, and this only reads state. WHAT IT LEAKS, stated plainly (task 1002430 — an earlier version of this comment claimed the opposite and was wrong). Returning only a boolean does NOT make it non-enumerable: with open enrollment off, and for any login that is not the configured firstAdmin, `admitted:true` means that login is a member or has been invited. That reveals account existence to an unauthenticated caller. It is also NOT throttled — rateLimitMiddleware returns early for non-write methods, so GETs bypass it entirely; the page's 3s poll bounds the honest client, not an attacker. Why it is nonetheless not a new exposure: the onboarding module's GET /access-requests/status?github_login=X is ALREADY public and returns the strictly richer member|invited|pending|dismissed|none plus its own `admitted`. Anything derivable here is already derivable there, so this adds no net-new surface — and hardening only this route would accomplish nothing while that one stays open. Whether unauthenticated login-existence probing is acceptable at all is a real question, but it belongs to both routes together, not to a comment here. That endpoint is also why this one exists: it models neither the firstAdmin bypass nor open enrollment, so it reports the OWNER as 'none' forever — the exact case this page has to resolve.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "src/bongos/routes/auth.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetAuthWebAdmissionStatusResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
     "/auth/web/callback": {
       "get": {
         "operationId": "get_auth_web_callback",
@@ -1742,6 +1809,37 @@
         ]
       }
     },
+    "/box/scope": {
+      "get": {
+        "operationId": "get_box_scope",
+        "tags": [
+          "box"
+        ],
+        "summary": "GET /box/scope",
+        "description": "GET /box/scope — the credential-FREE companion to /box/source-access (BV1.R100 / goal 1000051). Answers \"what code does my box hold RIGHT NOW?\" — the resolved sparse set + the module keys of the builder's active claims — WITHOUT issuing the pull credential. The laptop app reads it to confirm \"your box now has <module> for task N\" after a pick+claim; R104's proof reads it to VERIFY the scope is minimal (excludes other modules). Same live rank+ status + lifecycle-port scope logic as source-access, so the answer can't drift from the actual checkout — it just omits the secret. Deliberately NOT gated on a live box (boxCanHoldSource): the SCOPE is metadata, so a builder can ask \"what WOULD my box hold for my current claims\" the instant they claim, before the box has even synced. The ALLOW/DENY still comes from the live rank+status (a demoted/inactive builder gets the same 403 as source-access). allowBoxScope so it works both from the laptop app (full session) and on the box (box-scoped session) — safe here precisely because no credential is returned.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/dev-box/routes/box.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/box/source-access": {
       "get": {
         "operationId": "get_box_source_access",
@@ -3257,7 +3355,7 @@
           "done-when"
         ],
         "summary": "POST /done-when/:criterionId/satisfy",
-        "description": "Auth (Metic+): confirm a criterion — flip it to satisfied. Accepts optional satisfied_by_task_id so the UI can show which ship-task fulfilled it. When the criterion belongs to a goal and was its LAST unsatisfied one, the goal auto- flips open→achieved (ADR 0086 §6 / BV1.R63). Re-ranked Archon→Metic+ so the planner — not only the Archon — closes the criterion/goal loop; the route is pinned in route-rank-check.EXPECTED_RANKS so a further downgrade is caught. rank: metic+archon — criterion confirmation + goal auto-achieve (the closing loop).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "Auth (Metic+): confirm a criterion — flip it to satisfied. Accepts optional satisfied_by_task_id so the UI can show which ship-task fulfilled it. When the criterion belongs to a goal and was its LAST unsatisfied one, the goal auto- flips open→achieved (ADR 0086 §6 / BV1.R63). Re-ranked Archon→Metic+ so the planner — not only the Archon — closes the criterion/goal loop; the route is pinned in route-rank-check.MODULE_EXPECTED_RANKS.lifecycle so a further downgrade is caught. rank: metic+archon — criterion confirmation + goal auto-achieve (the closing loop).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/done-when.js",
         "parameters": [
@@ -5157,6 +5255,62 @@
         ]
       }
     },
+    "/inbox/{id}/ratify": {
+      "post": {
+        "operationId": "post_inbox_id_ratify",
+        "tags": [
+          "inbox"
+        ],
+        "summary": "POST /inbox/:id/ratify",
+        "description": "V3.R31 (task 252) — Archon ratifies a criterion-proposal idea, atomically: - INSERT done_when_criteria row on the target version - UPDATE idea_inbox SET status='promoted', reviewed_at=now() - INSERT karma_log (delta=+3, reason='proposal_ratified') for proposer (V3.R28 / task 248 tuned the delta from +5 → +3; tunable.) - INSERT criterion_proposal_audit row capturing who/when/what Archon-only — done_when_criteria writes are scope-shaping (criterion C2 in canonical-permissions.md). The kind='criterion-proposal' POST is Metic+ (gated above), but the ratification is the Archon decision. Returns 400 if the source idea isn't kind='criterion-proposal' or its body_md isn't a parseable {target_version, criterion_md, sort_order_hint} JSON object. Returns 404 if the idea doesn't exist. Returns 409 if the idea is already promoted/discarded/merged (status != 'open'). All four writes happen in one transaction — partial failures roll back cleanly.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/ideas/routes/inbox.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostInboxIdRatifyRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/instance": {
       "get": {
         "operationId": "get_instance",
@@ -6432,6 +6586,110 @@
         ]
       }
     },
+    "/memory/builders/{builderId}/file": {
+      "get": {
+        "operationId": "get_memory_builders_builderId_file",
+        "tags": [
+          "memory"
+        ],
+        "summary": "GET /memory/builders/:builderId/file",
+        "description": "GET /memory/builders/:builderId/file?path=... — Archon reads ONE of ANOTHER builder's files (content included). Audit-logged. 404 if the target has no file at that path.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/memory/routes/memory.js",
+        "parameters": [
+          {
+            "name": "builderId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `builderId`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetMemoryBuildersBuilderIdFileResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/memory/builders/{builderId}/files": {
+      "get": {
+        "operationId": "get_memory_builders_builderId_files",
+        "tags": [
+          "memory"
+        ],
+        "summary": "GET /memory/builders/:builderId/files",
+        "description": "GET /memory/builders/:builderId/files — Archon lists ANOTHER builder's memory file metadata. Audit-logged.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/memory/routes/memory.js",
+        "parameters": [
+          {
+            "name": "builderId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `builderId`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetMemoryBuildersBuilderIdFilesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/memory/file": {
       "get": {
         "operationId": "get_memory_file",
@@ -8525,6 +8783,37 @@
         ]
       }
     },
+    "/security/adr": {
+      "get": {
+        "operationId": "get_security_adr",
+        "tags": [
+          "security"
+        ],
+        "summary": "GET /security/adr",
+        "description": "GET /api/gds/security/adr Metic+ only. Returns the full security ADR as { adr_md, source, fetched_at } when the file is provisioned; otherwise 404 with a structured hint. The rank gate runs BEFORE the file-existence check so a Xenos sees 403 regardless of whether the document is provisioned — we don't want existence-or-not to leak below the rank line. rank: metic+archon — trust-tier access to the threat model + defenses inventory (ADR 0020).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "x-rank": "metic+archon",
+        "x-source": "src/bongos/routes/security.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/security/docs": {
       "get": {
         "operationId": "get_security_docs",
@@ -8662,7 +8951,322 @@
         ]
       }
     },
-    "/session/optimize": {
+    "/security/reports": {
+      "get": {
+        "operationId": "get_security_reports",
+        "tags": [
+          "security"
+        ],
+        "summary": "GET /security/reports",
+        "description": "GET /api/bongos/security/reports?status=<status> Archon-only, newest-first. The Archon dashboard view fetches this on load + after each adjudication action. ?status= narrows to one lifecycle bucket (open / repro_attempted / confirmed / disputed / fixed / wontfix); omitted = all. rank: archon — adjudication surface; reading every builder's reports.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/security/routes/reports.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetSecurityReportsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_security_reports",
+        "tags": [
+          "security"
+        ],
+        "summary": "POST /security/reports",
+        "description": "POST /api/bongos/security/reports — file a new vulnerability report. V3.R64 (task 283). Used by the /builder-redteam skill. Metic+ only — Xenos can't open the bounty surface (the rank gate keeps the noise-floor sane; a Xenos who finds a real flaw can flag it through normal channels). Body: { target, severity, title, description?, repro_steps_md? } Returns 201 + the inserted row (status='open' by default; the Archon view picks it up immediately). rank: metic+archon — bounty intake; Xenos kept out by design (V3.R63).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/security/routes/reports.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSecurityReportsRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSecurityReportsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/security/reports/{id}/confirm": {
+      "post": {
+        "operationId": "post_security_reports_id_confirm",
+        "tags": [
+          "security"
+        ],
+        "summary": "POST /security/reports/:id/confirm",
+        "description": "POST /api/bongos/security/reports/:id/confirm Body: { drachmae_awarded?: integer } — defaults to the severity tier bounty if omitted. Marks the report confirmed, stamps confirmed_at, and sets drachmae_awarded. rank: archon — confirms a payout-eligible report.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/security/routes/reports.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSecurityReportsIdConfirmRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSecurityReportsIdConfirmResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/security/reports/{id}/dispute": {
+      "post": {
+        "operationId": "post_security_reports_id_dispute",
+        "tags": [
+          "security"
+        ],
+        "summary": "POST /security/reports/:id/dispute",
+        "description": "POST /api/bongos/security/reports/:id/dispute Marks the report disputed and clears drachmae_awarded. rank: archon — dispute adjudication.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/security/routes/reports.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSecurityReportsIdDisputeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/security/reports/{id}/fix": {
+      "post": {
+        "operationId": "post_security_reports_id_fix",
+        "tags": [
+          "security"
+        ],
+        "summary": "POST /security/reports/:id/fix",
+        "description": "POST /api/bongos/security/reports/:id/fix Marks the report fixed and stamps fixed_at. Does not change fix_task_id — link that separately via /link-fix. rank: archon — fix-confirmation adjudication.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/security/routes/reports.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSecurityReportsIdFixResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/security/reports/{id}/link-fix": {
+      "post": {
+        "operationId": "post_security_reports_id_link_fix",
+        "tags": [
+          "security"
+        ],
+        "summary": "POST /security/reports/:id/link-fix",
+        "description": "POST /api/bongos/security/reports/:id/link-fix Body: { task_id: integer } — attaches a fix-task FK. Doesn't change status (a confirmed report can have a linked fix-task while still open work). 422 if the referenced task doesn't exist. rank: archon — linking a report to its fix-task in the queue.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/security/routes/reports.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSecurityReportsIdLinkFixRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSecurityReportsIdLinkFixResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/session/optimize": {
       "post": {
         "operationId": "post_session_optimize",
         "tags": [
@@ -9478,8 +10082,8 @@
           "tasks"
         ],
         "summary": "POST /tasks/:id/abandon",
-        "description": "POST /tasks/:id/abandon — terminal \"retire this task\" transition (task 987). The lifecycle had promote/ship/confirm/resolve but no first-class way to KILL a task that is no longer relevant: the only paths to status='abandoned' were offboarding a builder or a raw SQL UPDATE, so stale/moot tasks lingered in 'ready' as claimable noise. Refuses on a shipped task (immutable history) and on a task with an active claim (release it first); idempotent on an already- abandoned task. The abandon + its `reason` land in audit_log via the writing middleware, so the ledger keeps a record of who retired what. rank: archon — terminal lifecycle mutation / scope removal (ADR 0016). This is the inverse of /promote and belongs to the same archon-gated scope-control surface, never self-serviceable by a lower rank.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /tasks/:id/abandon — terminal \"retire this task\" transition (task 987). The lifecycle had promote/ship/confirm/resolve but no first-class way to KILL a task that is no longer relevant: the only paths to status='abandoned' were offboarding a builder or a raw SQL UPDATE, so stale/moot tasks lingered in 'ready' as claimable noise. Refuses on a shipped task (immutable history) and on a task with an active claim (release it first); idempotent on an already- abandoned task. The abandon + its `reason` land in audit_log via the writing middleware, so the ledger keeps a record of who retired what. rank: metic+archon — scope removal; the inverse of /promote, and re-ranked to match it (ADR 0152, was archon under ADR 0090). A Metic who may author, shape, and promote work may also retire it: leaving the kill switch an Archon rung higher than the create switch only forced the owner to clean up after the triage they already delegated. Not one-way any more — /promote restores an abandoned task to backlog at the same rank — and the guards below (shipped refused, active claim refused) plus the audit_log entry are unchanged.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
         "parameters": [
           {
@@ -10233,7 +10837,7 @@
           "tasks"
         ],
         "summary": "POST /tasks/:id/promote",
-        "description": "backlog→ready promotion; scope mutation; ADR 0090 (was archon).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "backlog→ready promotion; scope mutation; ADR 0090 (was archon). Also the UN-ABANDON path (ADR 0152): 'abandoned' → 'backlog'. When abandon moved down to Metic+ it needed an undo at the same rank, or a Metic's mis-retire would be unrecoverable without Archon SQL (no other route restores an abandoned task — PATCH refuses `status` outright). A restore lands in **backlog**, never straight to ready: the task was retired for a reason, so it re-enters as un-workable and takes a second, deliberate promote to become claimable again.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
         "parameters": [
@@ -10672,8 +11276,8 @@
           "versions"
         ],
         "summary": "POST /versions/:id/done-when",
-        "description": "Auth (Archon): create a done-when criterion at RUNTIME. ADR 0105 moved scope-truth seeds (versions/goals/criteria) out of the normal migration path, so a brand-new criterion on a RUNNING instance can no longer be added by a plain migration (migrations/instance/ applies only under the owner opt-in GDS_APPLY_INSTANCE_SEEDS=1, a DR step). This is the vector a planning session uses to add a criterion to a live version WITHOUT a droplet migrate. Archon- only — done_when_criteria is scope-shaping (mirrors the criterion-proposal ratify gate). Pinned in route-rank-check.MODULE_EXPECTED_RANKS. rank: archon — scope-truth write (a new criterion on a version).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "Auth (Metic+, then the goal's own authority): create a done-when criterion at RUNTIME. ADR 0105 moved scope-truth seeds (versions/goals/criteria) out of the normal migration path, so a brand-new criterion on a RUNNING instance can no longer be added by a plain migration (migrations/instance/ applies only under the owner opt-in GDS_APPLY_INSTANCE_SEEDS=1, a DR step). This is the vector a planning session uses to add a criterion to a live version WITHOUT a droplet migrate. ADR 0154 — authority over a GOAL's criteria follows GOAL OWNERSHIP, not global rank. A Metic who may create the goal (POST /goals) and author the tasks under it (POST /tasks, ADR 0090) may now write the criteria those tasks gate — but only inside a goal they own or manage. Deliberately NOT a flat re-rank: - An unsatisfied criterion permanently blocks version close (version-close.js counts satisfied === total per VERSION, regardless of goal) and goal auto-achieve (db.achieveGoalIfComplete). There is NO delete route, so it cannot be undone via the API — the same backward ratchet as unsatisfy, which stays Archon. - So a non-Archon must name a goal_id (version-level criteria stay Archon), must be that goal's OWNER or MANAGER (isGoalOwnerOrManager — the same predicate behind visibility/invite/role management), and the goal must be open on a planning/building version. That bounds the blast radius to a workspace they already hold. An unauthorized caller is masked behind bad_goal_id so the route is not an existence oracle (ADR 0112). Pinned in route-rank-check.MODULE_EXPECTED_RANKS. rank: metic+archon — criterion create, walled by goal ownership (ADR 0154).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/done-when.js",
         "parameters": [
           {
@@ -10929,18 +11533,33 @@
           "status"
         ]
       },
+      "GetAuthWebAdmissionStatusResponse": {
+        "type": "object",
+        "properties": {
+          "admitted": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "admitted"
+        ]
+      },
       "GetBackupStatusResponse": {
         "type": "object",
         "properties": {
           "backup_dir": {},
           "db_name": {},
           "latest_dump": {},
+          "stale": {},
+          "age_hours": {},
           "trigger_running": {}
         },
         "required": [
           "backup_dir",
           "db_name",
           "latest_dump",
+          "stale",
+          "age_hours",
           "trigger_running"
         ]
       },
@@ -11398,6 +12017,50 @@
           "files"
         ]
       },
+      "GetMemoryBuildersBuilderIdFileResponse": {
+        "type": "object",
+        "properties": {
+          "builder_id": {},
+          "forensic": {
+            "type": "boolean"
+          },
+          "path": {},
+          "content": {},
+          "sha256": {},
+          "byte_len": {},
+          "mtime": {},
+          "updated_at": {},
+          "created_at": {}
+        },
+        "required": [
+          "builder_id",
+          "forensic",
+          "path",
+          "content",
+          "sha256",
+          "byte_len",
+          "mtime",
+          "updated_at",
+          "created_at"
+        ]
+      },
+      "GetMemoryBuildersBuilderIdFilesResponse": {
+        "type": "object",
+        "properties": {
+          "builder_id": {},
+          "forensic": {
+            "type": "boolean"
+          },
+          "count": {},
+          "files": {}
+        },
+        "required": [
+          "builder_id",
+          "forensic",
+          "count",
+          "files"
+        ]
+      },
       "GetMemoryFileResponse": {
         "type": "object",
         "properties": {
@@ -11761,6 +12424,19 @@
           "doc"
         ]
       },
+      "GetSecurityReportsResponse": {
+        "type": "object",
+        "properties": {
+          "reports": {},
+          "bounty_table": {},
+          "statuses": {}
+        },
+        "required": [
+          "reports",
+          "bounty_table",
+          "statuses"
+        ]
+      },
       "GetSessionsIdResponse": {
         "type": "object",
         "properties": {
@@ -12136,7 +12812,14 @@
             "type": "integer",
             "minimum": 1
           },
-          "reviewed_at": {}
+          "reviewed_at": {},
+          "merged_into_idea_id": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "triage_note": {
+            "type": "string"
+          }
         },
         "additionalProperties": false
       },
@@ -12409,6 +13092,30 @@
           "interval"
         ]
       },
+      "PostAuthBackchannelLogoutRequest": {
+        "type": "object",
+        "properties": {
+          "logout_token": {
+            "type": "string",
+            "maxLength": 4096
+          }
+        },
+        "required": [
+          "logout_token"
+        ],
+        "additionalProperties": false
+      },
+      "PostAuthBackchannelLogoutResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "ok"
+        ]
+      },
       "PostAuthCliTokenIssueResponse": {
         "type": "object",
         "properties": {
@@ -12964,13 +13671,15 @@
           "claim": {},
           "task": {},
           "just_unlocked": {},
-          "overlap_warning": {}
+          "overlap_warning": {},
+          "reward": {}
         },
         "required": [
           "claim",
           "task",
           "just_unlocked",
-          "overlap_warning"
+          "overlap_warning",
+          "reward"
         ]
       },
       "PostCostRequest": {
@@ -13617,6 +14326,16 @@
           "succeeds_goal_id"
         ]
       },
+      "PostInboxIdRatifyRequest": {
+        "type": "object",
+        "properties": {
+          "notes_md": {
+            "type": "string",
+            "maxLength": 10000
+          }
+        },
+        "additionalProperties": false
+      },
       "PostInboxRequest": {
         "type": "object",
         "properties": {
@@ -13728,7 +14447,9 @@
       "PostLlmCacheLookupResponse": {
         "type": "object",
         "properties": {
-          "hit": {},
+          "hit": {
+            "type": "boolean"
+          },
           "result": {}
         },
         "required": [
@@ -13748,7 +14469,9 @@
       "PostLlmCacheStoreResponse": {
         "type": "object",
         "properties": {
-          "stored": {},
+          "stored": {
+            "type": "boolean"
+          },
           "result_cost_usd": {}
         },
         "required": [
@@ -14209,6 +14932,109 @@
           "doc"
         ]
       },
+      "PostSecurityReportsIdConfirmRequest": {
+        "type": "object",
+        "properties": {
+          "drachmae_awarded": {}
+        },
+        "additionalProperties": false
+      },
+      "PostSecurityReportsIdConfirmResponse": {
+        "type": "object",
+        "properties": {
+          "report": {}
+        },
+        "required": [
+          "report"
+        ]
+      },
+      "PostSecurityReportsIdDisputeResponse": {
+        "type": "object",
+        "properties": {
+          "report": {}
+        },
+        "required": [
+          "report"
+        ]
+      },
+      "PostSecurityReportsIdFixResponse": {
+        "type": "object",
+        "properties": {
+          "report": {}
+        },
+        "required": [
+          "report"
+        ]
+      },
+      "PostSecurityReportsIdLinkFixRequest": {
+        "type": "object",
+        "properties": {
+          "task_id": {
+            "$ref": "#/components/schemas/StringifiableId"
+          }
+        },
+        "required": [
+          "task_id"
+        ],
+        "additionalProperties": false
+      },
+      "PostSecurityReportsIdLinkFixResponse": {
+        "type": "object",
+        "properties": {
+          "report": {}
+        },
+        "required": [
+          "report"
+        ]
+      },
+      "PostSecurityReportsRequest": {
+        "type": "object",
+        "properties": {
+          "target": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "severity": {
+            "type": "string",
+            "maxLength": 32
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 50000
+          },
+          "repro_steps_md": {
+            "type": "string",
+            "maxLength": 50000
+          }
+        },
+        "required": [
+          "target",
+          "severity",
+          "title"
+        ],
+        "additionalProperties": false
+      },
+      "PostSecurityReportsResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "report": {},
+          "bounty_table": {}
+        },
+        "required": [
+          "ok",
+          "report",
+          "bounty_table"
+        ]
+      },
       "PostSessionOptimizeRequest": {
         "type": "object",
         "properties": {
@@ -15058,9 +15884,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 245,
-  "x-schema-count": 273,
+  "x-endpoint-count": 258,
+  "x-schema-count": 288,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 184,
+  "x-response-schemas": 194,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }