delimit-cli 4.5.13 → 4.6.1

package/gateway/ai/tenant_paths.py

@@ -0,0 +1,150 @@
+"""LED-2268 P0 Phase 0.2 — tenant-scoped filesystem layout.
+
+The gateway today stores everything under `~/.delimit/` (memory.jsonl,
+ledger.jsonl, evidence/, etc). That's correct for the single-tenant
+founder install but doesn't generalize once paying customers run their
+own tenants against a shared gateway host.
+
+This module owns the path-resolver primitive for the per-tenant layout:
+
+    ~/.delimit/                      ← legacy / shared root (unchanged)
+    ~/.delimit/tenants/
+        <safe-user-id>/              ← one dir per resolved API-key user
+            memory.jsonl
+            ledger.jsonl
+            evidence/
+            ...
+
+Phase 0.2 ONLY ships the resolver + sanitiser + base-dir creation. No
+existing storage is migrated; no endpoint is yet rerouted through here.
+Phase 0.3 will add the first endpoint that uses tenant_data_root() and
+copy the founder's existing single-tenant data into her own tenant
+folder.
+
+Security note: the user_id segment comes from Supabase
+`user_api_keys.user_id` (which itself comes from NextAuth users.id, a
+GitHub-OAuth-derived string). It's NEVER raw user input from the
+request — but we still sanitise it defensively so a malformed value in
+the DB can't escape into adjacent dirs via `..` or NUL bytes.
+"""
+from __future__ import annotations
+
+import os
+import re
+import string
+from pathlib import Path
+from typing import Optional
+
+
+# Base of the whole per-tenant tree. Lives under the existing delimit
+# home so backup/restore tooling sees it without extra wiring.
+def _delimit_home() -> Path:
+    """Resolve ~/.delimit/ — same convention as the rest of the gateway."""
+    home = os.environ.get("DELIMIT_HOME")
+    if home:
+        return Path(home).expanduser().resolve()
+    return Path.home() / ".delimit"
+
+
+_TENANTS_DIRNAME = "tenants"
+# Allowed chars in a sanitised user-id segment. Conservative: ASCII
+# alphanumerics + a small set of safe punctuation. Nothing that could
+# be interpreted by the shell, the path parser, or a downstream tool.
+_SAFE_CHARS = frozenset(string.ascii_letters + string.digits + "-_.")
+# Max chars in a single user-id segment. Filesystems generally allow
+# 255-byte basenames; we cap well below that and prefix-truncate +
+# hash-suffix any longer input so distinct over-long IDs don't collide.
+_MAX_SEGMENT_LEN = 64
+
+
+def safe_user_segment(user_id: str) -> Optional[str]:
+    """Sanitise a user_id into a filesystem-safe directory name.
+
+    Returns None for empty / suspicious input so callers MUST handle
+    the rejection rather than silently writing to a default dir. The
+    intentional asymmetry from `_hash_key` (which always produces a
+    valid hex string) is that an unauthenticated request can't land
+    here — only an already-validated identity does — so a None here
+    represents a corrupted DB row, not a normal failure mode.
+
+    Strategy:
+      - Strip whitespace, lowercase.
+      - Replace any char outside the safe set with '_'.
+      - If result is empty or only underscores, reject.
+      - If result is longer than _MAX_SEGMENT_LEN, truncate + append
+        a short hash suffix so distinct over-long IDs don't collide.
+      - Reject anything that resolves to '.' or '..' (defence in depth
+        against malformed DB rows like literally the string "..").
+    """
+    if not isinstance(user_id, str) or not user_id:
+        return None
+    s = user_id.strip().lower()
+    if not s:
+        return None
+    # Substitute unsafe chars one-for-one — preserves length / readability
+    # for the common case (NextAuth GitHub uses bare integer-ish strings).
+    safe = "".join(c if c in _SAFE_CHARS else "_" for c in s)
+    if not safe or safe.strip("_") == "":
+        return None
+    if safe in (".", ".."):
+        return None
+    if len(safe) > _MAX_SEGMENT_LEN:
+        # Truncate to (max - 9) so the suffix `-<8hex>` fits in budget.
+        import hashlib
+        digest = hashlib.sha256(s.encode("utf-8")).hexdigest()[:8]
+        safe = safe[: _MAX_SEGMENT_LEN - 9] + "-" + digest
+    return safe
+
+
+def tenants_root() -> Path:
+    """The shared parent of all per-tenant dirs. Always under DELIMIT_HOME."""
+    return _delimit_home() / _TENANTS_DIRNAME
+
+
+def tenant_data_root(user_id: str, *, create: bool = False) -> Optional[Path]:
+    """Resolve the on-disk root for a specific tenant's data.
+
+    Returns None if `user_id` doesn't sanitise to a usable segment.
+    Caller treats that as "unauthorised" — same shape as the validator.
+
+    If `create=True`, ensures the directory exists (mkdir -p, mode 0700).
+    Default is read-only resolve so this can be called on hot paths
+    without making syscalls when the dir is already present.
+    """
+    seg = safe_user_segment(user_id)
+    if seg is None:
+        return None
+    root = tenants_root() / seg
+    # Defence in depth: ensure the resolved path stays under tenants_root.
+    # Belt-and-braces against an unforeseen sanitiser bypass.
+    try:
+        if tenants_root().resolve() not in root.resolve().parents and \
+                root.resolve() != tenants_root().resolve():
+            return None
+    except (OSError, RuntimeError):
+        return None
+    if create:
+        root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        # Ensure tenants_root itself has the right mode too — first-
+        # ever tenant write would otherwise inherit umask.
+        try:
+            tenants_root().chmod(0o700)
+        except OSError:
+            pass
+    return root
+
+
+def list_tenants() -> list[str]:
+    """List the segment names of all tenants currently with on-disk data.
+
+    Used by maintenance / audit / backup tooling. Returns an empty list
+    when no tenants exist yet (the directory simply doesn't exist).
+    """
+    root = tenants_root()
+    if not root.is_dir():
+        return []
+    out: list[str] = []
+    for entry in root.iterdir():
+        if entry.is_dir() and entry.name and not entry.name.startswith("."):
+            out.append(entry.name)
+    return sorted(out)

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,
+};