delimit-cli 4.5.13 → 4.6.0

package/gateway/ai/usage_allowlist.py

@@ -0,0 +1,198 @@
+"""Canonical usage allowlist for first-person experience claims in social drafts.
+
+Single source of truth for the LED-1334 usage gate (2026-05-12 deliberation,
+substantive unanimous). When a generated reply contains a first-person
+experience clause (e.g. "saved me", "bit me on similar projects") paired with
+a named third-party tool/service NOT on this allowlist, the validator blocks
+the draft. The draft generation prompt is rendered from the same constant so
+the prompt and validator cannot drift.
+
+Why this exists: a Reddit draft on r/mcp/1t87arl fabricated "Pinning the
+OpenAPI spec version you generated against and diffing on every Zoom release
+saved me a bunch of mystery 400s." We don't use Zoom. The prior LED-1332
+prompt rules and LED-1333 hardened claude CLI drafter both failed to catch it
+because the OpenAPI-diff tactic IS real, but the claim of having USED IT ON
+ZOOM was invented.
+
+How to edit: change USAGE_ALLOWLIST below. The prompt's GROUND-TRUTH section
+re-renders from this constant on every draft; the validator imports the same
+constant; the parity test in tests/test_usage_gate.py asserts both consumers
+see identical entries.
+"""
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+# Canonical usage allowlist. Lowercase, normalized. One entry per tool/service
+# that the founder ACTUALLY uses in their daily work and can speak to from
+# lived experience. Adding an entry is a deliberate code change; PRs editing
+# this file should describe the lived usage that backs the addition.
+USAGE_ALLOWLIST: frozenset[str] = frozenset({
+    # Coding agents (founder uses daily)
+    "claude code", "claude-code", "claude",
+    "codex", "codex cli", "codex-cli",
+    "gemini", "gemini cli", "gemini-cli",
+    "cursor",
+    # Core protocol / standards we ship on
+    "openapi", "openapi spec", "openapi schema",
+    "mcp", "model context protocol", "mcp server",
+    "github actions", "github action",
+    # Attestation stack we ship
+    "sigstore", "cosign", "rekor",
+    # Languages / runtimes we ship in
+    "python", "typescript", "javascript", "node", "npm",
+    # Cloud / deploy we use
+    "vercel",
+    # API providers we call from the deliberation engine
+    "anthropic api", "openai api", "vertex ai",
+    # Our own product surface
+    "delimit", "delimit-cli", "delimit-action", "delimit-mcp-server",
+})
+
+
+# First-person experience clauses that imply the speaker has lived/used the
+# named subject. Detection here means "the draft is claiming standing to
+# speak from use" — which must be backed by an allowlist match to be allowed.
+_FIRST_PERSON_EXPERIENCE = re.compile(
+    r"\b(?:"
+    r"saved me|bit me|got me|caught me|surprised me|burned me|tripped me up|"
+    r"what I[’']d do|the way I caught|in my experience|"
+    r"when I (?:ran|used|tried|hit|wrapped|implemented|deployed|shipped|integrated)|"
+    r"I (?:ran into|tripped over|got bit by|hit (?:this|that|the))|"
+    r"I personally|from my own work|on similar projects|"
+    r"mine still loads|mine kept (?:loading|breaking|drifting)|"
+    r"I had to|I ended up"
+    r")\b",
+    re.IGNORECASE,
+)
+
+
+# Named-product extraction: proper-noun tokens, optionally compound, optionally
+# with technical suffix (API/SDK/CLI/MCP). Tuned for permissive capture; the
+# stopword set below filters obvious false positives.
+_NAMED_PRODUCT = re.compile(
+    r"\b([A-Z][a-zA-Z0-9.+-]*(?:\s+(?:[A-Z][a-zA-Z0-9.+-]*|API|SDK|CLI|MCP))*)\b"
+)
+
+
+# Tokens that pass the proper-noun regex but are not actually third-party
+# product names. Keep this conservative — over-stopword'ing weakens the
+# guardrail. Order: sentence-starters, generic verbs, common acronyms,
+# concept words, our own ecosystem.
+_NAMED_PRODUCT_STOPWORDS: frozenset[str] = frozenset({
+    # Sentence-starters / pronouns
+    "the", "a", "an", "i", "it", "they", "we", "you", "this", "that",
+    # Question / conditional / temporal sentence-starters
+    "when", "where", "why", "what", "who", "how", "which",
+    "if", "but", "and", "or", "so", "then", "also",
+    "since", "while", "before", "after", "until", "unless",
+    "even", "though", "although",
+    # Common verbs in capitalized sentence-start position
+    "wrapping", "pinning", "running", "using", "trying", "diffing",
+    "once", "first", "second", "third", "next", "then", "yes", "no",
+    "yeah", "sure", "ok", "okay", "honestly", "curious", "neat", "cool",
+    # Technical primitives (concepts, not products)
+    "english", "ascii", "json", "yaml", "xml", "html", "css",
+    "http", "https", "rest", "graphql", "websocket", "soap", "grpc",
+    "tcp", "udp", "ssh", "tls", "ssl", "dns",
+    "ci", "cd", "pr", "prs", "pull request", "merge", "commit",
+    # OS / platforms
+    "linux", "windows", "macos", "ios", "android", "unix",
+    # Concept words people capitalize but aren't products
+    "gateway", "proxy", "middleware", "scanner", "drafter",
+    "markdown", "schema", "endpoint", "endpoints",
+    "agent", "agents", "tool", "tools", "server", "servers", "client", "clients",
+    # Generic words in sentence position
+    "spend", "auto", "neat", "cool", "nice", "great", "interesting",
+})
+
+
+def _normalize(token: str) -> str:
+    """Lowercase + collapse internal whitespace for allowlist comparison."""
+    return " ".join(token.lower().split())
+
+
+def is_on_allowlist(product: str) -> bool:
+    """Return True if `product` matches an allowlist entry.
+
+    Match is case-insensitive substring in both directions: a longer named
+    product like "Claude Code SDK" matches the "claude code" allowlist entry,
+    and a shorter named product like "MCP" matches "mcp server" by being
+    contained in the allowlist entry.
+    """
+    normalized = _normalize(product)
+    if not normalized:
+        return False
+    for entry in USAGE_ALLOWLIST:
+        if entry in normalized or normalized in entry:
+            return True
+    return False
+
+
+def extract_named_products(text: str) -> list[str]:
+    """Extract candidate third-party product names from draft text.
+
+    Returns deduped list of capitalized tokens that survived stopword
+    filtering. The list is the candidate set the usage gate then checks
+    against the allowlist.
+    """
+    if not text:
+        return []
+    raw = _NAMED_PRODUCT.findall(text)
+    out: list[str] = []
+    seen: set[str] = set()
+    for token in raw:
+        normalized = _normalize(token)
+        if not normalized or normalized in _NAMED_PRODUCT_STOPWORDS:
+            continue
+        # Drop ANY compound where ANY word is a stopword (sentence-starter
+        # capitalization sweeping "When I ran" / "Once I hit" into a fake
+        # compound product). Real product compounds like "Claude Code" /
+        # "OpenAPI Spec" have no stopwords in them.
+        parts = normalized.split(" ")
+        if any(p in _NAMED_PRODUCT_STOPWORDS for p in parts):
+            continue
+        if normalized in seen:
+            continue
+        seen.add(normalized)
+        out.append(token)
+    return out
+
+
+def find_off_allowlist_experience_claims(text: str) -> list[dict]:
+    """Detect first-person experience clauses paired with off-allowlist products.
+
+    The LED-1334 usage gate. If the text contains a first-person experience
+    clause AND mentions a named product not on the allowlist, returns a list
+    of {clause, product} dicts. Empty list means the draft passes.
+
+    Returns the FULL list (not first-match) so the orchestrator can surface
+    all violations when blocking.
+    """
+    if not text:
+        return []
+    clause_match = _FIRST_PERSON_EXPERIENCE.search(text)
+    if not clause_match:
+        return []
+    clause = clause_match.group(0)
+    products = extract_named_products(text)
+    violations: list[dict] = []
+    for product in products:
+        if is_on_allowlist(product):
+            continue
+        violations.append({"clause": clause, "product": product})
+    return violations
+
+
+def format_for_prompt() -> str:
+    """Render the allowlist as a human-readable list for system-prompt injection.
+
+    Output is deterministic (alphabetized) so prompt parity tests stay stable.
+    """
+    return "\n".join(f"  - {entry}" for entry in sorted(USAGE_ALLOWLIST))
+
+
+def allowlist_as_sorted_tuple() -> tuple[str, ...]:
+    """Return the allowlist as a sorted tuple for parity assertions in tests."""
+    return tuple(sorted(USAGE_ALLOWLIST))

package/gateway/ai/workers/base.py

@@ -20,7 +20,7 @@ import time
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field, asdict
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List
 
 logger = logging.getLogger("delimit.workers")
 
@@ -121,7 +121,7 @@ class Worker(ABC):
         Must return a WorkerResult with an artifact (work order).
         Must NOT modify any state — output only.
         """
-        ...
+        raise NotImplementedError("Subclasses must implement execute()")
 
     def run(self, ledger_item: Dict[str, Any]) -> WorkerResult:
         """Run the worker with timing + audit trail."""

package/gateway/ai/workers/executor.py

@@ -122,9 +122,38 @@ PROPOSE_PR_AUTHOR_NAME = "delimit-bot"
 PROPOSE_PR_AUTHOR_EMAIL = "bot@delimit.ai"
 # Hard cap on patch size — rejects accidental mega-diffs that would
 # require a different review workflow anyway.
-PROPOSE_PR_MAX_FILES = 50
-PROPOSE_PR_MAX_FILE_BYTES = 256 * 1024  # 256 KiB / file
-PROPOSE_PR_MAX_TOTAL_BYTES = 1024 * 1024  # 1 MiB / PR
+#
+# LED-2238: bumped from 256KB → 5MB per file and 1MB → 50MB per PR
+# after the original limits blocked the autonomous-build pipeline on
+# any task touching ai/server.py (542KB), ai/loop_engine.py, or other
+# normal-sized gateway files. The old limits assumed payloads went
+# through GitHub's content-API (which has its own ~50MB cap), but
+# _act_propose_pr writes via local git (`write_text` → `git add` →
+# `git commit` → `git push`), which has no API-payload constraint —
+# real git push supports multi-GB content. The caps stay as defense
+# against runaway model output, just at a level that doesn't reject
+# realistic source files.
+#
+# All three caps are overridable via env vars so an operator with a
+# legitimately-larger payload can opt in without a code change:
+#   DELIMIT_PROPOSE_PR_MAX_FILES        (default 50)
+#   DELIMIT_PROPOSE_PR_MAX_FILE_BYTES   (default 5_242_880 = 5MB)
+#   DELIMIT_PROPOSE_PR_MAX_TOTAL_BYTES  (default 52_428_800 = 50MB)
+def _env_int(name: str, default: int) -> int:
+    """Read positive integer from env var; fall back to default on bad/unset."""
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return default
+    try:
+        v = int(raw)
+        return v if v > 0 else default
+    except ValueError:
+        return default
+
+
+PROPOSE_PR_MAX_FILES = _env_int("DELIMIT_PROPOSE_PR_MAX_FILES", 50)
+PROPOSE_PR_MAX_FILE_BYTES = _env_int("DELIMIT_PROPOSE_PR_MAX_FILE_BYTES", 5 * 1024 * 1024)  # 5 MiB / file
+PROPOSE_PR_MAX_TOTAL_BYTES = _env_int("DELIMIT_PROPOSE_PR_MAX_TOTAL_BYTES", 50 * 1024 * 1024)  # 50 MiB / PR
 
 
 class ActionError(Exception):

package/gateway/ai/workers/outreach_drafter.py

@@ -11,7 +11,6 @@ Cannot: write files, post issues, commit, push.
 
 from __future__ import annotations
 
-import json
 from typing import Any, Dict
 
 from ai.workers.base import Worker, WorkerResult

package/gateway/ai/workers/pr_drafter.py

@@ -10,7 +10,6 @@ Cannot: write files, commit, push, post comments.
 
 from __future__ import annotations
 
-import json
 from typing import Any, Dict
 
 from ai.workers.base import Worker, WorkerResult

package/gateway/ai/x_ranker.py

@@ -324,13 +324,23 @@ def rank_x_targets(
 
     if enable_fit_floor and recent_topics is None:
         try:
-            from ai.social_capability.fit_floor import _recent_topic_fingerprints
-            recent_topics = _recent_topic_fingerprints(cooldown_days=cooldown_days)
+            from ai.social_capability.fit_floor import _recent_topic_fingerprints, topics_for_scope
+            # LED-1356: _recent_topic_fingerprints now returns Dict[scope, Set[str]].
+            # X targets share the 'x' scope (twitter platform also normalizes to 'x').
+            recent_topics_dict = _recent_topic_fingerprints(cooldown_days=cooldown_days)
+            recent_topics = topics_for_scope(recent_topics_dict, "x")
         except Exception as exc:  # pragma: no cover — tolerant fallback
             logger.warning("x_ranker: cooldown bootstrap failed (%s) — proceeding without", exc)
             recent_topics = set()
     elif recent_topics is None:
         recent_topics = set()
+    elif isinstance(recent_topics, dict):
+        # Caller passed the new dict shape; pick the X scope.
+        try:
+            from ai.social_capability.fit_floor import topics_for_scope
+            recent_topics = topics_for_scope(recent_topics, "x")
+        except Exception:
+            recent_topics = set()
 
     survivors: List[Dict[str, Any]] = []
     for t in targets or []:

package/gateway/core/json_schema_diff.py

@@ -15,7 +15,7 @@ general across any single-file JSON Schema.
 
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Set, Tuple
 
 
 class JSONSchemaChangeType(Enum):
@@ -107,6 +107,11 @@ class JSONSchemaDiffEngine:
         self.changes: List[JSONSchemaChange] = []
         self._old_defs: Dict[str, Any] = {}
         self._new_defs: Dict[str, Any] = {}
+        # LED-1395: cycle guard. Self-referential schemas (tree nodes,
+        # linked lists, recursive $refs) would otherwise stack-overflow
+        # the recursion in _compare_schema. Mirrors oasdiff v1.15.3's
+        # mergeProps/resolveItems/resolveContains pointer-dedup.
+        self._seen_pairs: Set[Tuple[int, int]] = set()
 
     # ------------------------------------------------------------------
     # public API
@@ -114,6 +119,7 @@ class JSONSchemaDiffEngine:
 
     def compare(self, old_schema: Dict[str, Any], new_schema: Dict[str, Any]) -> List[JSONSchemaChange]:
         self.changes = []
+        self._seen_pairs = set()
         old_schema = old_schema or {}
         new_schema = new_schema or {}
         self._old_defs = old_schema.get("definitions", {}) or {}
@@ -156,6 +162,17 @@ class JSONSchemaDiffEngine:
     def _compare_schema(self, old: Any, new: Any, path: str) -> None:
         if not isinstance(old, dict) or not isinstance(new, dict):
             return
+        # LED-1395: cycle guard. Track the pre-resolve identity pair so
+        # recursive $ref shapes (tree.children → tree, linked-list
+        # node.next → node) terminate after one visit instead of
+        # stack-overflowing. Identity-based — if the SAME old node is
+        # paired with the SAME new node again at a deeper path, every
+        # comparison further down would be redundant by definition.
+        pair_key = (id(old), id(new))
+        if pair_key in self._seen_pairs:
+            return
+        self._seen_pairs.add(pair_key)
+
         old = self._resolve(old, self._old_defs)
         new = self._resolve(new, self._new_defs)
 
@@ -307,6 +324,13 @@ class JSONSchemaDiffEngine:
             self._add(JSONSchemaChangeType.ADDITIONAL_PROPERTIES_LOOSENED, path,
                       {"old": old_ap, "new": new_ap},
                       f"additionalProperties loosened at {path or '/'}: {old_ap} → {new_ap}")
+        # Typed-map class (Dict[str, Model] / FastAPI + Pydantic default):
+        # `additionalProperties` is itself a schema. Recurse so required-field
+        # add/remove, property changes, and type widening inside the value
+        # schema are not silently invisible. Closes the same long-missed
+        # class oasdiff fixed in v1.15.3 (2026-05-14).
+        if isinstance(old_ap, dict) and isinstance(new_ap, dict):
+            self._compare_schema(old_ap, new_ap, f"{path}/additionalProperties")
 
     def _compare_required(self, old: Dict, new: Dict, path: str) -> None:
         old_req = set(old.get("required", []) or [])

package/lib/auth-signin.js

@@ -0,0 +1,136 @@
+// lib/auth-signin.js
+//
+// LED-2100: writes the delimit.ai OAuth bearer token to ~/.delimit/auth.json
+// so the gateway hosted-deliberation tier (LED-2092) can authenticate from
+// the CLI. The gateway reads `delimit_token` or `access_token` from this
+// file (see ai/deliberation.py::_read_oauth_token).
+//
+// Design notes
+//   - We MERGE into any existing auth.json rather than overwrite. The legacy
+//     `lib/auth-setup.js` writes {configured, timestamp, tools} into the same
+//     file for tool-credential bookkeeping; clobbering that would regress
+//     existing users. New keys (delimit_token, access_token, signed_in_at,
+//     email) live alongside the legacy keys.
+//   - File mode is 0600 (owner-only readable). Directory is created at 0700
+//     when missing.
+//   - Token shape is intentionally lax: accept anything non-empty after
+//     trimming. The gateway is the source of truth for token validity; the
+//     CLI must not try to second-guess JWT structure (Supabase tokens vs
+//     opaque tokens vs future formats).
+//
+// Returns: { path, email, signedInAt, merged } so callers can render a
+// consistent success message.
+
+const fs = require('fs');
+const path = require('path');
+const { delimitHome } = require('./delimit-home');
+
+const AUTH_FILE_BASENAME = 'auth.json';
+
+function authFilePath() {
+    return path.join(delimitHome(), AUTH_FILE_BASENAME);
+}
+
+/**
+ * Read the existing auth.json if present, returning a plain object. Returns
+ * an empty object on any read/parse error (we do not want to corrupt unrelated
+ * keys, but a malformed file should not block sign-in either — overwrite it).
+ */
+function readExistingAuth(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * Persist a delimit.ai OAuth bearer token to ~/.delimit/auth.json with mode
+ * 0600. Existing keys (set by auth-setup.js or other flows) are preserved.
+ *
+ * @param {object} args
+ * @param {string} args.token   Bearer token returned by delimit.ai OAuth
+ * @param {string} [args.email] Email address associated with the account
+ * @param {string} [args.now]   Override clock for deterministic tests (ISO8601)
+ * @param {string} [args.home]  Override DELIMIT_HOME for tests
+ * @returns {{ path: string, email: string, signedInAt: string, merged: boolean }}
+ */
+function writeAuthToken(args) {
+    const opts = args || {};
+    const token = (opts.token || '').toString().trim();
+    if (!token) {
+        const err = new Error('Empty token; nothing written.');
+        err.code = 'DELIMIT_SIGNIN_EMPTY_TOKEN';
+        throw err;
+    }
+
+    const home = opts.home || delimitHome();
+    if (!fs.existsSync(home)) {
+        fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    }
+    const filePath = path.join(home, AUTH_FILE_BASENAME);
+
+    const existing = readExistingAuth(filePath);
+    const merged = Object.keys(existing).length > 0;
+    const signedInAt = opts.now || new Date().toISOString();
+    const email = (opts.email || '').toString().trim();
+
+    const next = Object.assign({}, existing, {
+        delimit_token: token,
+        access_token: token,
+        signed_in_at: signedInAt,
+    });
+    if (email) {
+        next.email = email;
+    }
+
+    // Two-step write: write to a temp file with mode 0600, then rename. This
+    // avoids a window where the file exists with default permissions before
+    // chmod runs.
+    const tmpPath = filePath + '.tmp';
+    fs.writeFileSync(tmpPath, JSON.stringify(next, null, 2), { mode: 0o600 });
+    // Some umasks may still strip group/other bits to match the requested
+    // mode; explicitly chmod to be safe (no-op on most platforms but cheap).
+    try {
+        fs.chmodSync(tmpPath, 0o600);
+    } catch {
+        // Non-POSIX filesystems may reject chmod; the file is already gated
+        // by writeFileSync mode, so this is best-effort.
+    }
+    fs.renameSync(tmpPath, filePath);
+
+    return {
+        path: filePath,
+        email,
+        signedInAt,
+        merged,
+    };
+}
+
+/**
+ * Read the currently stored token, if any. Returns "" when missing or
+ * malformed. Mirrors the gateway-side resolver (ai/deliberation.py::
+ * _read_oauth_token) so callers can implement `delimit signin --status`.
+ */
+function readCurrentToken() {
+    const filePath = authFilePath();
+    const data = readExistingAuth(filePath);
+    const token = (data.delimit_token || data.access_token || '').toString().trim();
+    return token;
+}
+
+module.exports = {
+    authFilePath,
+    readExistingAuth,
+    writeAuthToken,
+    readCurrentToken,
+    AUTH_FILE_BASENAME,
+};

package/lib/auth-signout.js

@@ -0,0 +1,169 @@
+// lib/auth-signout.js
+//
+// LED-2106: convenience wrapper around `rm ~/.delimit/auth.json` that ONLY
+// removes the OAuth-related keys written by `delimit signin` (LED-2100) and
+// preserves the legacy bookkeeping keys (`configured`, `timestamp`, `tools`)
+// written by `lib/auth-setup.js`. Wiping the whole file regresses any user
+// who ran `delimit auth` for tool credential bookkeeping.
+//
+// Design notes
+//   - We MERGE-DELETE: read the file, drop the OAuth keys, write the
+//     remainder back. If the post-scrub object has zero keys, we delete
+//     the file entirely (cleanest state — equivalent to never having run
+//     `delimit signin` or `delimit auth`).
+//   - File mode is 0600 (owner-only readable). Write is atomic (tmp +
+//     rename) — same pattern as lib/auth-signin.js.
+//   - If auth.json is missing, malformed, or has no OAuth keys at all,
+//     this is a no-op (returns { changed: false }). The CLI prints
+//     "Not signed in." and exits 0 in that case.
+//
+// OAuth keys removed:
+//   - delimit_token
+//   - access_token
+//   - signed_in_at
+//   - email
+//
+// Returns: { path, changed, deleted, email } so callers can render a
+// consistent success message.
+
+const fs = require('fs');
+const path = require('path');
+const { delimitHome } = require('./delimit-home');
+
+const AUTH_FILE_BASENAME = 'auth.json';
+
+// The OAuth-related keys that `delimit signin` writes. Sign-out removes
+// EXACTLY these and nothing else. Adding to this list is a behavior
+// change that needs coordinated review (the gateway resolver in
+// ai/deliberation.py::_read_oauth_token reads `delimit_token` /
+// `access_token`).
+const OAUTH_KEYS = Object.freeze([
+    'delimit_token',
+    'access_token',
+    'signed_in_at',
+    'email',
+]);
+
+function authFilePath() {
+    return path.join(delimitHome(), AUTH_FILE_BASENAME);
+}
+
+/**
+ * Read the existing auth.json if present, returning a plain object. Returns
+ * an empty object on any read/parse error (consistent with auth-signin.js).
+ */
+function readExistingAuth(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * Write `data` to auth.json atomically with mode 0600. Mirrors the pattern
+ * used by lib/auth-signin.js::writeAuthToken.
+ */
+function writeAuthAtomic(filePath, data) {
+    const tmpPath = filePath + '.tmp';
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), { mode: 0o600 });
+    try {
+        fs.chmodSync(tmpPath, 0o600);
+    } catch {
+        // Non-POSIX filesystems may reject chmod; the file is already gated
+        // by writeFileSync mode, so this is best-effort.
+    }
+    fs.renameSync(tmpPath, filePath);
+}
+
+/**
+ * Remove the OAuth keys from ~/.delimit/auth.json, preserving any other
+ * keys written by `delimit auth` / `lib/auth-setup.js`. If no OAuth keys
+ * are present, this is a no-op. If removing the OAuth keys leaves the
+ * file empty, the file is deleted.
+ *
+ * @param {object} [args]
+ * @param {string} [args.home]  Override DELIMIT_HOME for tests
+ * @returns {{ path: string, changed: boolean, deleted: boolean, email: string }}
+ */
+function removeAuthToken(args) {
+    const opts = args || {};
+    const home = opts.home || delimitHome();
+    const filePath = path.join(home, AUTH_FILE_BASENAME);
+
+    if (!fs.existsSync(filePath)) {
+        return { path: filePath, changed: false, deleted: false, email: '' };
+    }
+
+    const existing = readExistingAuth(filePath);
+    if (Object.keys(existing).length === 0) {
+        // Malformed / empty / array. Nothing meaningful to scrub.
+        return { path: filePath, changed: false, deleted: false, email: '' };
+    }
+
+    // Detect whether any OAuth keys are actually present. If not, we treat
+    // this as "not signed in" and return changed=false WITHOUT touching the
+    // file (preserves mtime / inode / mode).
+    const hasOAuthKey = OAUTH_KEYS.some((k) => Object.prototype.hasOwnProperty.call(existing, k));
+    if (!hasOAuthKey) {
+        return { path: filePath, changed: false, deleted: false, email: '' };
+    }
+
+    const previousEmail = (existing.email || '').toString().trim();
+
+    // Build the scrubbed object: keep everything that is NOT an OAuth key.
+    const scrubbed = {};
+    for (const [k, v] of Object.entries(existing)) {
+        if (!OAUTH_KEYS.includes(k)) {
+            scrubbed[k] = v;
+        }
+    }
+
+    if (Object.keys(scrubbed).length === 0) {
+        // Nothing left worth keeping — delete the file entirely so the
+        // next session sees the cleanest possible state.
+        try {
+            fs.unlinkSync(filePath);
+        } catch {
+            // If unlink fails for some reason, fall back to writing an
+            // empty object (still valid JSON, still mode 0600).
+            writeAuthAtomic(filePath, {});
+            return {
+                path: filePath,
+                changed: true,
+                deleted: false,
+                email: previousEmail,
+            };
+        }
+        return {
+            path: filePath,
+            changed: true,
+            deleted: true,
+            email: previousEmail,
+        };
+    }
+
+    writeAuthAtomic(filePath, scrubbed);
+    return {
+        path: filePath,
+        changed: true,
+        deleted: false,
+        email: previousEmail,
+    };
+}
+
+module.exports = {
+    authFilePath,
+    readExistingAuth,
+    removeAuthToken,
+    AUTH_FILE_BASENAME,
+    OAUTH_KEYS,
+};