delimit-cli 4.6.0 → 4.6.1

package/CHANGELOG.md

@@ -36,14 +36,17 @@ customizations around our managed section).
 - Documentation refreshes: cross-agent-handoff worked example surfaced on README,
   test-count badge bumped, misleading version stamps removed.
 
-### Known issue (pre-existing, fix tracked)
-
-- **`delimit attest mcp` exit codes** (LED-1403): on tool error (e.g. no
-  lockfile → npm audit unavailable) and unknown attestation kind, the CLI
-  currently returns exit 1 instead of the expected exit 2. CI/CD pipelines
-  that gate on tier-2 (treating "tool unavailable" as a hard error vs.
-  "fail" which is a soft check) should pin this expectation. Tracked for
-  fix in a follow-up release.
+### Known issue (pre-existing, fix tracked) — **RETRACTED 2026-05-15**
+
+> ~~**`delimit attest mcp` exit codes** (LED-1403): on tool error (e.g. no
+> lockfile → npm audit unavailable) and unknown attestation kind, the CLI
+> currently returns exit 1 instead of the expected exit 2.~~
+>
+> **Retraction:** the original report was a phantom test failure caused by a
+> corrupted local git worktree (LED-1401), not a real CLI bug. On a clean
+> clone, all 6 `attest-mcp` test suites pass and the CLI returns the correct
+> exit codes (0 pass+skip / 1 fail / 2 error per STR-656). LED-1403 closed
+> `not_reproducible`. No customer action required.
 
 
 ## [4.5.2] - 2026-05-02

package/bin/delimit-cli.js

@@ -4629,9 +4629,19 @@ program
         const prePushPath = path.join(hooksDir, 'pre-push');
         const marker = '# delimit-governance-hook';
 
-        // Resolution order: local node_modules → global PATH → npx fallback.
-        // npx is last because it can fail with Arborist 'extraneous' errors
-        // when a project's node_modules / lockfile drift (LED-1248).
+        // Resolution order: local node_modules → global PATH →
+        // global node_modules direct → npx fallback.
+        //
+        // npx is the LAST resort because on some npm-arborist environments
+        // it crashes with "Cannot read properties of undefined (reading
+        // 'extraneous')" before reaching the CLI (LED-1207, LED-1248). That
+        // failure mode silently breaks the gate and forces --no-verify,
+        // which violates the no-silent-no-verify rule.
+        //
+        // The third tier (`node $(npm root -g)/delimit-cli/bin/delimit-cli.js`)
+        // catches the case where delimit-cli is globally installed but its bin
+        // shim isn't on PATH (npm-installed-but-symlink-missing, fresh CI
+        // containers, etc.) — bypassing npm/npx entirely.
         const preCommitHook = `#!/bin/sh
 ${marker}
 # Delimit API governance gate
@@ -4640,6 +4650,8 @@ if [ -x ./node_modules/.bin/delimit-cli ]; then
   ./node_modules/.bin/delimit-cli check --staged
 elif command -v delimit-cli >/dev/null 2>&1; then
   delimit-cli check --staged
+elif _delimit_global="$(npm root -g 2>/dev/null)/delimit-cli/bin/delimit-cli.js" && [ -f "$_delimit_global" ]; then
+  node "$_delimit_global" check --staged
 else
   npx delimit-cli check --staged
 fi
@@ -4653,6 +4665,8 @@ if [ -x ./node_modules/.bin/delimit-cli ]; then
   ./node_modules/.bin/delimit-cli check --base origin/main
 elif command -v delimit-cli >/dev/null 2>&1; then
   delimit-cli check --base origin/main
+elif _delimit_global="$(npm root -g 2>/dev/null)/delimit-cli/bin/delimit-cli.js" && [ -f "$_delimit_global" ]; then
+  node "$_delimit_global" check --base origin/main
 else
   npx delimit-cli check --base origin/main
 fi

package/gateway/ai/agent_dispatch.py

@@ -36,6 +36,11 @@ DLQ_AUTO_PAUSE_THRESHOLD = 20
 TASK_TYPE_ROUTER = {
     # Outreach and social work — Gemini Flash is fast and cheap
     "outreach": "gemini",
+    # LED-2214b: substantive github outreach gets the same default
+    # routing as generic outreach (cheap, fast drafter) but is named
+    # distinctly so a regression that resurrects the generic dispatch
+    # path does not silently land here.
+    "outreach_substantive": "gemini",
     "social": "gemini",
     "content": "gemini",
     "sensor": "gemini",

package/gateway/ai/backends/git_health.py

@@ -0,0 +1,175 @@
+"""Git worktree sanity checks (LED-1411).
+
+Single source of truth for "is this directory a healthy git worktree?"
+Used by delimit_test_smoke, delimit_deploy_plan, and delimit_evidence_collect
+as a precheck before they trust ambient checkout state.
+
+Background — LED-1403 / LED-1401 incident (2026-05-14):
+`/home/delimit/npm-delimit/.git` was configured `bare = true` but had source
+files alongside, AND a stranded sibling worktree at `/tmp/delimit-mcp-main`
+where `git status` showed every file as both `D` and `??` (deleted from
+index, untracked on disk). `delimit_test_smoke` ran against this corrupt
+state and reported `attest-mcp Q2 3-tier exit codes` failures that did NOT
+exist on real main. I almost shipped a "fix" for a non-bug (LED-1403,
+closed `not_reproducible` after a fresh clone proved tests passed).
+
+This module exists so the same class of phantom failure can't recur.
+Precheck must:
+  - Add <100ms to caller startup (no network, no fetch)
+  - Emit a single actionable remediation line on failure
+  - Return a structured dict (callers may inline-handle or surface up)
+
+Memory anchor: feedback_corrupted_worktree_phantom_failures.md
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Any, Dict
+
+
+def _run(cmd: list, cwd: str, timeout: float = 2.0) -> str:
+    """Run a git command with a tight timeout. Returns stdout stripped,
+    or empty string on any failure (intentional — caller decides what
+    constitutes a failure based on the structured result, not exceptions)."""
+    try:
+        return subprocess.check_output(
+            cmd,
+            cwd=cwd,
+            stderr=subprocess.DEVNULL,
+            timeout=timeout,
+            text=True,
+        ).strip()
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return ""
+
+
+def check_worktree_sanity(repo_path: str) -> Dict[str, Any]:
+    """Verify the directory at `repo_path` is a healthy git worktree.
+
+    Checks (in order; cheapest first):
+      1. Path exists and contains a `.git` directory (or file pointing to one)
+      2. `git rev-parse --is-inside-work-tree` returns `true`
+      3. `git rev-parse --is-bare-repository` returns `false`
+      4. `git worktree list` includes the resolved CWD
+      5. `git status --porcelain=v1` does NOT show every file as BOTH
+         deleted-from-index AND untracked (the LED-1401 corruption signature)
+
+    Returns a dict with:
+      - ok: bool — overall health
+      - reason: str — short failure code (`not_a_repo`, `bare_repo_with_files`,
+        `stranded_worktree`, `corrupt_status`) when ok=False, else `healthy`
+      - detail: str — actionable remediation message
+      - path: str — the path that was checked
+
+    Non-raising: errors return ok=False with a structured reason, so callers
+    can decide whether to halt or warn.
+    """
+    p = Path(repo_path)
+    if not p.exists() or not p.is_dir():
+        return {
+            "ok": False,
+            "reason": "not_a_directory",
+            "detail": f"{repo_path} is not a directory.",
+            "path": repo_path,
+        }
+
+    git_meta = p / ".git"
+    if not git_meta.exists():
+        return {
+            "ok": False,
+            "reason": "not_a_repo",
+            "detail": f"{repo_path} has no .git/ — not a git worktree.",
+            "path": repo_path,
+        }
+
+    # Bare-repo check first (LED-1401 signature: bare=true + source files
+    # alongside). Checked BEFORE is-inside-work-tree because a bare repo
+    # answers "false" to that question — we want the more informative
+    # bare-repo message to win when both conditions hold.
+    is_bare = _run(["git", "rev-parse", "--is-bare-repository"], cwd=repo_path)
+    if is_bare == "true":
+        return {
+            "ok": False,
+            "reason": "bare_repo_with_files",
+            "detail": (
+                f"{repo_path}/.git/ has `core.bare = true` but the directory "
+                f"holds source files. Tests against this state run stale "
+                f"code. Re-clone fresh: `git clone <url> /tmp/<repo>-fresh "
+                f"&& cd /tmp/<repo>-fresh`"
+            ),
+            "path": repo_path,
+        }
+
+    # Inside-work-tree check
+    inside = _run(["git", "rev-parse", "--is-inside-work-tree"], cwd=repo_path)
+    if inside != "true":
+        return {
+            "ok": False,
+            "reason": "not_a_worktree",
+            "detail": (
+                f"{repo_path} is not inside a git work tree "
+                f"(rev-parse --is-inside-work-tree returned {inside!r}). "
+                f"Re-clone fresh: `git clone <url> /tmp/<repo>-fresh && cd /tmp/<repo>-fresh`"
+            ),
+            "path": repo_path,
+        }
+
+    # Worktree-list membership check (catches stranded sibling worktrees)
+    worktrees = _run(["git", "worktree", "list", "--porcelain"], cwd=repo_path)
+    resolved = str(p.resolve())
+    if worktrees and resolved not in worktrees:
+        # The current directory isn't a registered worktree of its own
+        # .git/ — likely a stale checkout that was wiped+repopulated outside
+        # git's awareness. This is the LED-1401 stranded-sibling signature.
+        return {
+            "ok": False,
+            "reason": "stranded_worktree",
+            "detail": (
+                f"{resolved} is not a registered worktree of its own .git/. "
+                f"Run `git worktree list` to inspect; re-clone fresh if "
+                f"orphaned: `git clone <url> /tmp/<repo>-fresh && cd /tmp/<repo>-fresh`"
+            ),
+            "path": repo_path,
+            "worktree_list": worktrees,
+        }
+
+    # LED-1401 corrupt-status signature: every file appears as BOTH `D` and `??`
+    # (deleted from index, untracked on disk). Sample the first 50 status lines
+    # — if >=10 distinct paths show this pattern, it's pathological.
+    status = _run(["git", "status", "--porcelain=v1"], cwd=repo_path, timeout=3.0)
+    if status:
+        lines = status.split("\n")[:200]
+        deleted_paths = set()
+        untracked_paths = set()
+        for line in lines:
+            if len(line) < 4:
+                continue
+            xy = line[:2]
+            path = line[3:].lstrip()
+            if "D" in xy:
+                deleted_paths.add(path)
+            if xy == "??":
+                untracked_paths.add(path)
+        overlap = deleted_paths & untracked_paths
+        if len(overlap) >= 10:
+            return {
+                "ok": False,
+                "reason": "corrupt_status",
+                "detail": (
+                    f"{repo_path} shows >={len(overlap)} files as both deleted-from-index "
+                    f"AND untracked-on-disk — the worktree was wiped and repopulated "
+                    f"outside git's awareness (LED-1401 signature). Re-clone fresh: "
+                    f"`git clone <url> /tmp/<repo>-fresh && cd /tmp/<repo>-fresh`"
+                ),
+                "path": repo_path,
+                "overlap_count": len(overlap),
+            }
+
+    return {
+        "ok": True,
+        "reason": "healthy",
+        "detail": "git worktree is healthy",
+        "path": repo_path,
+    }

package/gateway/ai/backends/tools_infra.py

@@ -72,6 +72,19 @@ _CREDENTIAL_FALSE_POSITIVES = re.compile(
     r"_data\[|_result\[|"
     # LED-1278 (b): function-call RHS with leading underscore (e.g. _load_token())
     r"=\s*_\w+\(|"
+    # LED-1278 (c) [2026-05-22]: naked function-call RHS without leading
+    # underscore. Matches the common shape `const token = readCurrentToken();`
+    # in bin/delimit-cli.js — the token is being READ from somewhere, not
+    # hardcoded. Tightened with `\s*;?\s*$` to require end-of-statement so
+    # we don't suppress `token = realLeak("AKIAIOSFODNN7EXAMPLE")` shapes
+    # where the call argument is itself a literal secret.
+    r"=\s*\w+\([^)]{0,40}\)\s*;?\s*$|"
+    # LED-1278 (c) [2026-05-22]: parenthesized property-access fallback chain
+    # like `const token = (options.token || process.env.TOKEN)`. Common shape
+    # for CLI option parsing where the RHS reads from a known input source,
+    # never a literal. Requires the open-paren to be followed by a word + dot
+    # (property access) so we don't match `token = ("AKIA..." || "")` shapes.
+    r"=\s*\(\s*\w+\.\w+|"
     # LED-1278 (b): documentation/example placeholders in angle brackets
     r"<[^>]*?(?:long|same|random|your|placeholder|example|secret|token|key)[^>]*?>|"
     # Bare `if not <var>:` and similar control-flow lines that mention

package/gateway/ai/cli_contract.py

@@ -0,0 +1,185 @@
+"""LED-1415 — CLI subprocess contract.
+
+The deliberation engine drives 4 model CLIs as subprocesses
+(claude / codex / gemini / cursor) and treats their stdout as model
+verdict text. Three classes of bug have surfaced in this pipeline:
+
+  1. Banner contamination — the Delimit governance shim leaks ASCII
+     art onto stdout instead of stderr (PR #154, fixed by LED-1428).
+  2. Empty/silent responses — CLI exits 0 but stdout is empty
+     (transient API issues, OOM, network blips). Caught by LED-1416's
+     retry state machine.
+  3. Schema drift — CLI changes its output shape between versions
+     (e.g., adds an auto-correction line at the top). Caught
+     reactively by failing deliberation panels.
+
+This module holds the ONE contract that every CLI response must
+satisfy + the ONE validator that enforces it. Both the per-CLI mock
+tests (tests/test_cli_contract.py) AND the weekly real-CLI smoke
+script (scripts/smoke_cli_contracts.py) call validate_cli_contract()
+so the contract definition lives in exactly one place — extending
+it doesn't require changing two places to remember.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+# The 4 known CLIs the deliberation engine targets. cursor is included
+# even though it's not yet installed in the dev environment — adding
+# it to the contract surface now means the validator is ready when it
+# lands; smoke skips when the binary isn't present.
+KNOWN_CLI_NAMES = ("claude", "codex", "gemini", "cursor")
+
+
+# Minimum scrubbed-response length we'll accept as "looks like a real
+# model verdict" rather than "leftover garbage after banner strip."
+# Calibrated against historical scrub-debug.jsonl entries: every real
+# round-1/round-2 verdict from past deliberations was >= 60 chars;
+# every banner-only contamination was < 30 chars. 30 is the cutoff
+# the production scrubber already uses; keeping that here means the
+# validator + the scrubber agree.
+MIN_VERDICT_LEN = 30
+
+
+# Patterns that signal "the response is contamination, not a verdict."
+# Each gets the response REJECTED even if length and scrub passed.
+_CONTAMINATION_MARKERS = (
+    re.compile(r"^\[scrub:\s*contaminated\b", re.IGNORECASE),
+    re.compile(r"^\[.+\bunavailable\b.+\bnot found in PATH\]", re.IGNORECASE),
+    re.compile(r"^\[.+\bskipped under INTERNAL_PYTEST_GUARD", re.IGNORECASE),
+    re.compile(r"^\[.+\btimed out after\b", re.IGNORECASE),
+    re.compile(r"^\[.+\breturned empty response\]", re.IGNORECASE),
+    re.compile(r"^\[.+\berror:.+\]\s*$", re.IGNORECASE),
+)
+
+
+# A response should contain at least ONE of these markers to be
+# recognizable as a panel verdict. The deliberation engine prompts all
+# models to end with `VERDICT: ...` so we expect to see it. Falling
+# back: "AGREE" / "DISAGREE" / "REMEDIATE" / "AGREE WITH MODIFICATIONS"
+# all appear in real responses even when the trailing VERDICT line is
+# omitted by a chatty model.
+_VERDICT_HINT_RE = re.compile(
+    r"\b(VERDICT:|AGREE|DISAGREE|REMEDIATE|APPROVE|REJECT)\b",
+    re.IGNORECASE,
+)
+
+
+@dataclass
+class CliContractResult:
+    """Outcome of validating one CLI's response.
+
+    `ok` is True iff every contract clause passed. `failures` is the
+    list of clauses that fired — the smoke script ntfys with this list
+    so the operator can see exactly what shape the regression took.
+    """
+    cli: str
+    raw_len: int
+    scrubbed_len: int
+    ok: bool
+    failures: List[str] = field(default_factory=list)
+    preview: str = ""  # First 200 chars of scrubbed text, for log readability
+
+
+def validate_cli_contract(
+    cli_name: str,
+    raw_stdout: str,
+    raw_stderr: str = "",
+    expect_verdict_hint: bool = True,
+) -> CliContractResult:
+    """Apply the per-CLI contract to one subprocess response.
+
+    Mirrors the EXACT production scrub path so the validator's view
+    matches what ai/deliberation.py's _call_cli sees. Failures append
+    a short reason string; an empty failures list means the response
+    is contract-clean.
+
+    Args:
+        cli_name: which CLI produced this (claude/codex/gemini/cursor);
+            used in the failure messages.
+        raw_stdout: subprocess.stdout bytes decoded to str.
+        raw_stderr: subprocess.stderr bytes decoded to str. The
+            contract is permissive on stderr — banner output is
+            ALLOWED there (intentional shim behavior); but completely
+            empty stderr + completely empty stdout is suspicious.
+        expect_verdict_hint: when True, fail the response if it
+            doesn't contain at least one verdict marker. Mock tests
+            and the smoke script set this; tests of low-content
+            responses (e.g., a `--version` smoke) set False.
+
+    Returns:
+        CliContractResult with `ok`, `failures`, and a preview.
+    """
+    # Import lazily so this module can be imported in a context where
+    # ai.deliberation isn't available (e.g., the smoke script when
+    # gateway code path changes).
+    failures: List[str] = []
+    try:
+        from ai.deliberation import _scrub_cli_output
+        scrubbed = _scrub_cli_output(raw_stdout, source=cli_name).strip()
+    except Exception as exc:
+        return CliContractResult(
+            cli=cli_name,
+            raw_len=len(raw_stdout),
+            scrubbed_len=0,
+            ok=False,
+            failures=[f"scrub_failed:{type(exc).__name__}:{str(exc)[:80]}"],
+            preview="",
+        )
+
+    # 1. Contamination markers — if the scrubber returned one, fail.
+    for pat in _CONTAMINATION_MARKERS:
+        if pat.search(scrubbed):
+            failures.append(f"contamination_marker:{pat.pattern[:40]}")
+            break
+
+    # 2. Minimum length. Below MIN_VERDICT_LEN is almost certainly
+    # garbage even if scrub didn't tag it.
+    if len(scrubbed) < MIN_VERDICT_LEN and "contamination_marker" not in " ".join(failures):
+        failures.append(f"too_short:{len(scrubbed)}<{MIN_VERDICT_LEN}")
+
+    # 3. Verdict hint — at least one of VERDICT:/AGREE/DISAGREE/REMEDIATE/
+    # APPROVE/REJECT must appear. Skip when expect_verdict_hint=False.
+    if expect_verdict_hint and not _VERDICT_HINT_RE.search(scrubbed):
+        failures.append("no_verdict_hint")
+
+    # 4. Doesn't start with a known banner prefix (defense-in-depth on
+    # top of scrub). If a brand-new banner shape lands tomorrow that
+    # the scrubber doesn't know about, this should catch it.
+    if scrubbed.startswith("["):
+        # Bracketed prefix is almost always a tool-emitted status line
+        # (e.g. "[Delimit]" / "[claude error: ...]") not a model verdict.
+        if not any(scrubbed.lower().startswith(p) for p in (
+            "[delimit", "[scrub:", "[claude", "[codex", "[gemini", "[cursor",
+        )):
+            # Unknown bracketed prefix — surface for inspection
+            failures.append(f"unknown_bracketed_prefix:{scrubbed[:40]!r}")
+
+    return CliContractResult(
+        cli=cli_name,
+        raw_len=len(raw_stdout),
+        scrubbed_len=len(scrubbed),
+        ok=not failures,
+        failures=failures,
+        preview=scrubbed[:200],
+    )
+
+
+def format_contract_report(results: List[CliContractResult]) -> str:
+    """Human-readable summary of N validation results for ntfy / logs."""
+    lines = []
+    n_ok = sum(1 for r in results if r.ok)
+    lines.append(f"CLI contract: {n_ok}/{len(results)} clean")
+    for r in results:
+        flag = "OK" if r.ok else "FAIL"
+        lines.append(f"  [{flag}] {r.cli:8s} raw={r.raw_len}B scrubbed={r.scrubbed_len}B")
+        if not r.ok:
+            for f in r.failures:
+                lines.append(f"           ↳ {f}")
+            if r.preview:
+                lines.append(f"           preview: {r.preview[:100]!r}")
+    return "\n".join(lines)

package/gateway/ai/governance.py

@@ -13,7 +13,10 @@ This replaces _with_next_steps — governance IS the next step system.
 import json
 import logging
 import os
+import re
+import subprocess
 import time
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -826,6 +829,184 @@ def govern(tool_name: str, result: Dict[str, Any], project_path: str = ".") -> D
     return governed_result
 
 
+# ─────────────────────────────────────────────────────────────────────
+# LED-2214b-followup — sensor_github_issue sync impl
+# ─────────────────────────────────────────────────────────────────────
+#
+# The outreach daemon's monitor_phase needs to call the same logic that
+# delimit_sensor_github_issue (MCP tool) runs, but synchronously and
+# without the _with_next_steps wrapping. Before this extraction the
+# daemon tried to import the impl from two paths that don't exist —
+# `ai.governance._sensor_github_issue_impl` and
+# `backends.governance_bridge.sensor_github_issue` — and silently fell
+# back to "monitor skipped" on every tick, leaving the entire reply-
+# tracking cycle dead.
+#
+# Now both callers share this function. The MCP tool wraps the result
+# with `_with_next_steps`; the daemon consumes the raw dict.
+
+_NEGATIVE_KEYWORDS = (
+    "not interested", "won't be", "will not", "don't need", "do not need",
+    "no thanks", "pass on", "not a fit", "not for us", "closing",
+    "won't adopt", "will not adopt", "reject", "declined",
+)
+
+_REPO_FORMAT_RE = re.compile(r"^[\w.-]+/[\w.-]+$")
+
+# Module-local guard so the warning fires at most once per process.
+_REPO_ALLOWLIST_WARNED = False
+
+
+def _check_repo_allowlist(repo: str) -> Optional[Dict[str, Any]]:
+    """Return a refusal dict if the repo isn't in DELIMIT_ALLOWED_REPOS.
+
+    Duplicates the logic of ai.server._check_repo_allowlist intentionally:
+    importing from ai.server would create a circular import (server.py
+    imports from governance). Mirror with care — both copies must stay
+    in sync until LED-216 splits the allowlist into its own module.
+    """
+    global _REPO_ALLOWLIST_WARNED
+    allowlist_raw = os.environ.get("DELIMIT_ALLOWED_REPOS", "").strip()
+    if not allowlist_raw:
+        if not _REPO_ALLOWLIST_WARNED:
+            logger.warning(
+                "DELIMIT_ALLOWED_REPOS unset — sensor_github_issue calls "
+                "pass through to gh api using the caller's token."
+            )
+            _REPO_ALLOWLIST_WARNED = True
+        return None
+    allowed = {entry.strip().lower() for entry in allowlist_raw.split(",") if entry.strip()}
+    if (repo or "").strip().lower() not in allowed:
+        return {
+            "error": "repo_not_allowlisted",
+            "repo": repo,
+            "allowed": sorted(allowed),
+            "hint": (
+                "Repo not in DELIMIT_ALLOWED_REPOS. Add it or use a tool "
+                "that does not reach external APIs."
+            ),
+        }
+    return None
+
+
+def _sensor_github_issue_impl(
+    repo: str,
+    issue_number: int,
+    since_comment_id: int = 0,
+) -> Dict[str, Any]:
+    """Sync implementation of the sensor_github_issue MCP tool.
+
+    Returns the RAW result dict (no _with_next_steps wrapping). Callers
+    that want the MCP wrapping apply it themselves. Returns
+    ``{"error": ..., "has_new_activity": False}`` on any failure mode
+    rather than raising — the outreach daemon's monitor loop relies on
+    fail-soft behavior so one bad LED doesn't kill the whole tick.
+
+    Result schema (success path):
+      {
+        "repo": str, "issue_number": str,
+        "signal": {id, venture, metric, source, timestamp, severity},
+        "issue_state": "open" | "closed" | "unknown",
+        "new_comments": [{id, author, created_at, body}, ...],
+        "latest_comment_id": int,
+        "total_comments": int,
+        "has_new_activity": bool,
+      }
+    """
+    # Validate inputs — defense-in-depth even though subprocess.run with
+    # list argv (no shell=True) makes classic injection inert.
+    if not _REPO_FORMAT_RE.match(repo or ""):
+        return {"error": f"Invalid repo format: {repo!r}. Use owner/repo.",
+                "has_new_activity": False}
+    if ".." in repo:
+        return {"error": "Invalid repo: path traversal sequences not allowed",
+                "has_new_activity": False}
+    if not isinstance(issue_number, int) or issue_number <= 0:
+        return {"error": f"Invalid issue number: {issue_number}",
+                "has_new_activity": False}
+
+    refusal = _check_repo_allowlist(repo)
+    if refusal is not None:
+        refusal.setdefault("has_new_activity", False)
+        return refusal
+
+    try:
+        # Fetch comments
+        comments_jq = (
+            "[.[] | {id: .id, author: .user.login, "
+            "created_at: .created_at, body: (.body | .[0:500])}]"
+        )
+        comments_proc = subprocess.run(
+            ["gh", "api",
+             f"repos/{repo}/issues/{issue_number}/comments",
+             "--jq", comments_jq],
+            capture_output=True, text=True, timeout=30,
+        )
+        if comments_proc.returncode != 0:
+            return {
+                "error": f"gh api comments failed: {(comments_proc.stderr or '').strip()[:200]}",
+                "has_new_activity": False,
+            }
+        all_comments = json.loads(comments_proc.stdout) if comments_proc.stdout.strip() else []
+        new_comments = [c for c in all_comments if c.get("id", 0) > since_comment_id]
+
+        # Fetch issue state
+        issue_jq = "{state: .state, labels: [.labels[].name], reactions: .reactions.total_count}"
+        issue_proc = subprocess.run(
+            ["gh", "api",
+             f"repos/{repo}/issues/{issue_number}",
+             "--jq", issue_jq],
+            capture_output=True, text=True, timeout=30,
+        )
+        if issue_proc.returncode != 0:
+            return {
+                "error": f"gh api issue failed: {(issue_proc.stderr or '').strip()[:200]}",
+                "has_new_activity": False,
+            }
+        issue_info = json.loads(issue_proc.stdout) if issue_proc.stdout.strip() else {}
+        issue_state = issue_info.get("state", "unknown")
+
+        # Severity classification — green default; amber on closed; red on
+        # negative keyword in any new comment body.
+        severity = "green"
+        combined_body = " ".join(c.get("body", "") or "" for c in new_comments).lower()
+        has_negative = any(kw in combined_body for kw in _NEGATIVE_KEYWORDS)
+        if has_negative:
+            severity = "red"
+        elif issue_state == "closed":
+            severity = "amber"
+
+        latest_comment_id = max((c.get("id", 0) for c in all_comments), default=since_comment_id)
+        repo_key = repo.replace("/", "_")
+
+        return {
+            "repo": repo,
+            "issue_number": str(issue_number),
+            "signal": {
+                "id": f"sensor:github_issue:{repo_key}:{issue_number}",
+                "venture": "delimit",
+                "metric": "outreach_issue_activity",
+                "source": f"https://github.com/{repo}/issues/{issue_number}",
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "severity": severity,
+            },
+            "issue_state": issue_state,
+            "new_comments": new_comments,
+            "latest_comment_id": latest_comment_id,
+            "total_comments": len(all_comments),
+            "has_new_activity": len(new_comments) > 0,
+        }
+    except subprocess.TimeoutExpired:
+        return {"error": "gh command timed out after 30s",
+                "has_new_activity": False}
+    except json.JSONDecodeError as exc:
+        return {"error": f"Failed to parse gh output: {exc}",
+                "has_new_activity": False}
+    except Exception as exc:  # noqa: BLE001 — sensor must fail soft
+        logger.error("sensor_github_issue impl error: %s", exc)
+        return {"error": str(exc), "has_new_activity": False}
+
+
 def _deep_get(d: Dict, key: str) -> Any:
     """Get a value from a dict, supporting nested keys with dots."""
     if "." in key: