forge-orkes 0.62.0 → 0.63.0

package/experimental/m10/source/hooks/forge-branch-guard.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Forge PreToolUse(Bash) guardrail — protect the shared main checkout's HEAD when
+# parallel git worktrees are active.
+#
+# Blocks the "moved the shared HEAD under other sessions" catastrophe (canvaz, burned
+# twice 2026-06-05): switching branches or hard-resetting in the MAIN checkout while
+# sibling worktrees are branched off it. Orchestration-agnostic — depends only on git
+# worktree state, so it holds whether coordination is M10, Agent Teams, or manual
+# worktrees.
+#
+# Scope is deliberately narrow to avoid false positives:
+#   - fires ONLY when >1 worktree exists (single-worktree/solo work is never touched)
+#   - fires ONLY in the main checkout (linked worktrees own their own HEAD)
+#   - skips any command containing `cd` (can't reliably tell which tree it targets)
+#   - allows safe forms: file restore (`git checkout -- <path>`), branch create (`-b`)
+#
+# exit 0 = allow; exit 2 = deny. Override by running the command yourself outside Claude.
+
+set -uo pipefail
+
+PAYLOAD=$(cat)
+CMD=$(printf '%s' "$PAYLOAD" | jq -r '.tool_input.command // empty' 2>/dev/null) || exit 0
+[ -z "$CMD" ] && exit 0
+
+# Only git commands are interesting; and bail on `cd` (target tree is ambiguous).
+case "$CMD" in
+  *git*) ;;
+  *) exit 0 ;;
+esac
+case "$CMD" in
+  *"cd "*) exit 0 ;;
+esac
+
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+# Single worktree → no shared-HEAD hazard.
+wt_count=$(git worktree list 2>/dev/null | wc -l | tr -d ' ')
+[ "${wt_count:-1}" -le 1 ] && exit 0
+
+# Main checkout iff --git-dir == --git-common-dir (linked worktrees differ).
+[ "$(git rev-parse --git-dir 2>/dev/null)" = "$(git rev-parse --git-common-dir 2>/dev/null)" ] || exit 0
+
+deny() { echo "[forge-branch-guard] $*" >&2; exit 2; }
+
+# Branch switch (checkout/switch to a ref), excluding file-restore (`--`) and create (`-b`).
+switches_branch=0
+if printf '%s' "$CMD" | grep -qE '\bgit[[:space:]]+(checkout|switch)\b'; then
+  if ! printf '%s' "$CMD" | grep -qE '([[:space:]]--([[:space:]]|$))|(\bgit[[:space:]]+(checkout|switch)[[:space:]]+-[bB]\b)'; then
+    switches_branch=1
+  fi
+fi
+
+# Hard/keep/merge reset rewrites HEAD + working tree.
+hard_reset=0
+printf '%s' "$CMD" | grep -qE '\bgit[[:space:]]+reset[[:space:]]+(--hard|--keep|--merge)\b' && hard_reset=1
+
+if [ "$switches_branch" = "1" ] || [ "$hard_reset" = "1" ]; then
+  deny "Refusing to move the shared main HEAD — $wt_count worktrees are branched off it (the 'burned twice' failure). Switch/reset inside a worktree, or stop the other sessions first. Override: run the command yourself outside Claude."
+fi
+
+exit 0

package/experimental/m10/source/hooks/forge-claim-check-doctor.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Forge claim-check hook prerequisites probe. Informational only — always exit 0.
+# Run manually or via install procedure to confirm bash/jq/sqlite3/timeout availability.
+
+set -uo pipefail
+
+check() {
+  local name=$1 cmd=$2 version_flag=${3:---version}
+  if command -v "$cmd" >/dev/null 2>&1; then
+    local ver
+    ver=$("$cmd" "$version_flag" 2>&1 | head -1)
+    printf '  ✓ %-10s %s\n' "$name" "$ver"
+  else
+    printf '  ✗ %-10s MISSING\n' "$name"
+  fi
+}
+
+echo "Forge claim-check hook — prerequisites"
+echo
+
+check "bash"     "bash"     "--version"
+check "jq"       "jq"       "--version"
+check "sqlite3"  "sqlite3"  "--version"
+
+# node ≥ 24 required for built-in node:sqlite used by MCP server
+if command -v node >/dev/null 2>&1; then
+  node_ver=$(node --version 2>&1 | head -1)
+  node_major=$(printf '%s' "$node_ver" | sed -E 's/^v?([0-9]+).*/\1/')
+  if [[ "$node_major" =~ ^[0-9]+$ ]] && (( node_major >= 24 )); then
+    printf '  ✓ %-10s %s\n' "node" "$node_ver"
+  else
+    printf '  ✗ %-10s %s (need ≥ v24 — MCP server uses built-in node:sqlite)\n' "node" "$node_ver"
+  fi
+else
+  printf '  ✗ %-10s MISSING (need ≥ v24)\n' "node"
+fi
+
+if command -v timeout >/dev/null 2>&1; then
+  printf '  ✓ %-10s %s\n' "timeout" "$(timeout --version 2>&1 | head -1)"
+elif command -v gtimeout >/dev/null 2>&1; then
+  printf '  ✓ %-10s (gtimeout) %s\n' "timeout" "$(gtimeout --version 2>&1 | head -1)"
+else
+  printf '  ✗ %-10s MISSING (optional — install coreutils for bounded queries)\n' "timeout"
+fi
+
+echo
+echo "DB lookup path: ${FORGE_CLAIMS_DB:-${CLAUDE_PROJECT_DIR:-$PWD}/.forge/.mcp-server/claims.db}"
+echo "Session id:     ${CLAUDE_SESSION_ID:-<unset — resolved from PreToolUse stdin at edit time>}"
+
+# --- Live enforcement canary ---
+# Prove the gate actually DENIES a foreign-claimed edit, against a throwaway DB (never
+# touches real claims.db). Catches the inert-gate class (identity read from the wrong
+# source, hook not wired) that a prereq check can't see — the bug that hid for days.
+echo
+echo "Enforcement canary:"
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CHK="$HOOK_DIR/forge-claim-check.sh"
+if [ ! -f "$CHK" ]; then
+  printf '  ✗ %s\n' "forge-claim-check.sh not found next to doctor — gate not installed"
+elif ! command -v sqlite3 >/dev/null 2>&1; then
+  printf '  ✗ %s\n' "sqlite3 missing — cannot run canary"
+else
+  cdb=$(mktemp); cfile="${TMPDIR:-/tmp}/forge-canary-$$"
+  sqlite3 "$cdb" "CREATE TABLE claims(file_path TEXT, session_id TEXT NOT NULL, claimed_at INTEGER, expires_at INTEGER, reason TEXT);"
+  sqlite3 "$cdb" "INSERT INTO claims VALUES('$cfile','canary-foreign', strftime('%s','now'), strftime('%s','now')+60, 'canary');"
+  printf '%s' '{"session_id":"canary-self","tool_input":{"file_path":"'"$cfile"'"}}' \
+    | env -u CLAUDE_SESSION_ID FORGE_CLAIMS_DB="$cdb" CLAUDE_PROJECT_DIR="${TMPDIR:-/tmp}" bash "$CHK" >/dev/null 2>&1
+  rc=$?
+  rm -f "$cdb"
+  if [ "$rc" -eq 2 ]; then
+    printf '  ✓ %s\n' "foreign-claimed edit DENIED (exit 2) — gate enforces"
+  else
+    printf '  ✗ %s\n' "foreign-claimed edit ALLOWED (exit $rc) — GATE IS INERT; edits are NOT protected"
+  fi
+fi
+
+exit 0

package/experimental/m10/source/hooks/forge-claim-check.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# Forge PreToolUse hook — cross-session file-claim collision detector.
+#
+# Contract:
+#   stdin: Claude Code PreToolUse JSON payload
+#   exit 0 = allow (no claim, own claim, no DB, no session context, unknown schema)
+#   exit 2 = deny (cross-session claim active, or any internal error — fail-closed)
+#
+# Defense-in-depth: ERR trap converts ANY unexpected failure into an exit-2 deny.
+# Never exit 1 — Claude Code treats exit 1 as soft warning; we want hard block on error.
+
+set -euo pipefail
+
+deny() {
+  echo "[forge-hook] $*" >&2
+  exit 2
+}
+
+trap 'deny "internal error at line $LINENO — denying for safety (fail-closed)"' ERR
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+DB="${FORGE_CLAIMS_DB:-$PROJECT_DIR/.forge/.mcp-server/claims.db}"
+SESSION_ID="${CLAUDE_SESSION_ID:-}"  # env override (tests); real id resolved from stdin payload below
+
+# Detect timeout wrapper (macOS lacks GNU `timeout` unless coreutils installed → `gtimeout`).
+if command -v timeout >/dev/null 2>&1; then
+  TIMEOUT_CMD=(timeout 4)
+elif command -v gtimeout >/dev/null 2>&1; then
+  TIMEOUT_CMD=(gtimeout 4)
+else
+  TIMEOUT_CMD=()  # no wrapper — sqlite call runs unbounded; busy_timeout in DB still applies
+fi
+
+PAYLOAD=$(cat)
+
+# Claude Code delivers the session id in the PreToolUse stdin payload (.session_id), NOT in
+# the environment — so a bare CLAUDE_SESSION_ID is always empty and the gate would fail-open.
+# Resolve it from stdin when no env override is set. This is the SAME identity the
+# orchestrating skill claims under (captured by the forge-session-id.sh SessionStart hook),
+# so a session's own claims are recognized (line ~88) and other sessions' claims block.
+if [ -z "$SESSION_ID" ]; then
+  SESSION_ID=$(printf '%s' "$PAYLOAD" | jq -r '.session_id // empty')
+fi
+
+# Normalize across known path fields:
+#   Edit / Write           → tool_input.file_path
+#   NotebookEdit           → tool_input.notebook_path   (validated in spike — see milestone-10-validation.md §2)
+#   MultiEdit              → tool_input.file_path       (single file, multiple edits; per docs)
+#   Future / unknown tools → tool_input.path            (defensive)
+# jq emits each matching path on its own line. Empty output = no path field present.
+FILES=$(printf '%s' "$PAYLOAD" | jq -r '
+  [ .tool_input.file_path?
+  , .tool_input.notebook_path?
+  , .tool_input.path?
+  , ( .tool_input.edits? // [] | .[]?.file_path? )
+  ] | map(select(. != null and . != "")) | unique | .[]
+')
+
+if [ -z "$FILES" ]; then
+  # No recognized path field — unknown schema. Allow (do not deny on schema drift).
+  exit 0
+fi
+
+# No DB = MCP server has never run in this repo (fresh-repo case). Fail-open only here.
+if [ ! -f "$DB" ]; then
+  exit 0
+fi
+
+if [ -z "$SESSION_ID" ]; then
+  # No resolvable identity. Distinguish genuine solo work from a broken gate: if active
+  # claims exist, multi-agent coordination is clearly in use and editing blind is unsafe
+  # → fail-CLOSED (loud). No active claims → solo work → allow. (Silent fail-open here is
+  # exactly how the gate was inert for days — never repeat it when claims are live.)
+  active=$("${TIMEOUT_CMD[@]+"${TIMEOUT_CMD[@]}"}" sqlite3 -batch "$DB" \
+    "SELECT COUNT(*) FROM claims WHERE expires_at > strftime('%s','now');" 2>/dev/null || echo 0)
+  if [ "${active:-0}" -gt 0 ]; then
+    deny "no session id (env or stdin .session_id) but $active active claim(s) exist — refusing to edit blind (fail-closed). The SessionStart hook may not have run, or this context (e.g. an Agent isolation:\"worktree\" sub-agent) has no hook config. Worktree isolation still applies; claim coordination does not."
+  fi
+  echo "[forge-hook] no session id, no active claims — allowing (single-agent mode)" >&2
+  exit 0
+fi
+
+# Resolve each path to absolute (matches what MCP server stores via path.resolve).
+abspath() {
+  case "$1" in
+    /*) printf '%s' "$1" ;;
+    *)  printf '%s/%s' "$PROJECT_DIR" "$1" ;;
+  esac
+}
+
+while IFS= read -r raw; do
+  [ -z "$raw" ] && continue
+  file=$(abspath "$raw")
+
+  # Parameterized query via .param — avoids quoting injection on path strings.
+  result=$("${TIMEOUT_CMD[@]+"${TIMEOUT_CMD[@]}"}" sqlite3 -batch "$DB" \
+    ".param set :fp '$file'" \
+    "SELECT session_id || '|' || expires_at FROM claims WHERE file_path = :fp AND expires_at > strftime('%s','now') LIMIT 1;")
+
+  [ -z "$result" ] && continue
+
+  owner="${result%%|*}"
+  expires_at="${result##*|}"
+
+  if [ "$owner" = "$SESSION_ID" ]; then
+    continue  # own claim
+  fi
+
+  expires_human=$(date -r "$expires_at" "+%Y-%m-%d %H:%M:%S %Z" 2>/dev/null || echo "epoch:$expires_at")
+  deny "Edit denied: $file claimed by session $owner until $expires_human. Call forge_release_claims in that session, or wait."
+done <<< "$FILES"
+
+exit 0

package/experimental/m10/source/hooks/forge-session-id.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Forge SessionStart hook — persist this session's Claude session_id.
+#
+# Why: file claims are owned by an identity that BOTH the claimer and the enforcer must
+# agree on. The PreToolUse enforcement hook (forge-claim-check.sh) reads the Claude
+# session_id from its stdin payload, but the orchestrating skill (plain Claude, no stdin)
+# can't read its own session_id directly — and Claude Code does NOT export it to the env.
+# So we capture it here, once per session, into a file the skill reads at claim time.
+# Net: claim owner == enforcement id == the Claude session_id. (See ADR-007.)
+#
+# Contract: exit 0 always — this hook must never block session start.
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+sid=$(cat | jq -r '.session_id // empty' 2>/dev/null || true)
+[ -z "$sid" ] && exit 0
+
+mkdir -p "$PROJECT_DIR/.forge/.mcp-server"
+printf '%s' "$sid" > "$PROJECT_DIR/.forge/.mcp-server/.session-id"
+exit 0

package/experimental/m10/source/mcp-server/README.md

@@ -0,0 +1,74 @@
+# forge-orchestrator (M10 experimental MCP server)
+
+Per-repo, single-process MCP server exposing file claims + commit queue for multi-agent Forge sessions.
+
+This server is **experimental** per `.forge/decisions/ADR-001-m10-experimental-track.md`. It is NOT installed by default. Opt-in only.
+
+## Prerequisites
+
+- **Node ≥ 20** — already required by Claude Code; no extra runtime install.
+- **git** — repo must be a git work tree (commit queue depends on `git merge-tree`, `git update-ref`).
+- **Repo dependencies** — run `npm install` once inside `.forge/.mcp-server/` to pull `@modelcontextprotocol/sdk` + `better-sqlite3`.
+
+## Startup
+
+**Do not start manually.** Claude Code spawns the server based on `.mcp.json` registration. See `example.mcp.json` for the registration block.
+
+On startup the server:
+1. Detects + adopts any stale `server.pid` (#33947 mitigation — SIGTERM, 5s grace, SIGKILL fallback).
+2. Opens `claims.db` with WAL + `busy_timeout=5000`. Creates schema if missing (`PRAGMA user_version=1`).
+3. Begins 8s stderr keepalive emissions (#40207 mitigation).
+4. Connects to stdio MCP transport.
+
+To self-test without MCP wiring: `npm run self-test` — exercises claim + release + list round-trip and exits.
+
+## Shutdown
+
+SIGTERM-driven. Claude Code sends SIGTERM when the session ends.
+
+The trap:
+- Closes the SQLite handle.
+- Removes `server.pid` if it still matches our PID.
+- Exits 0.
+
+Sessions release their own claims via `forge_release_claims`. The server itself does NOT bulk-purge claims on shutdown — multiple sessions may share one server process, and a crash should not drop unrelated sessions' claims (expired rows are cleared lazily on next access).
+
+There is no `/stop` admin tool. If you need to force shutdown, kill the PID from `server.pid`.
+
+## Known Bugs (Mitigated)
+
+- **Claude Code #33947 — pidfile orphan.** Crashed servers can leave a `server.pid` pointing to a dead process. Mitigation: startup `adoptPidfile()` SIGTERMs any live owner, falls through to SIGKILL after 5s, then writes own PID.
+- **Claude Code #40207 — premature SIGTERM on idle.** Claude Code may SIGTERM MCP servers it considers idle. Mitigation: 8-second stderr keepalive (`KEEPALIVE_MS`). Validated against >10min idle session in plan-01 (`.forge/research/milestone-10-validation.md`).
+
+## Recovery
+
+If `/mcp` shows `forge-orchestrator` as failed/stuck:
+
+1. Inspect stderr via Claude Code's MCP log panel.
+2. If a stale `server.pid` is suspected — confirm process is actually dead (`ps -p $(cat .forge/.mcp-server/server.pid)`), then delete the file.
+3. Restart via `/mcp reconnect forge-orchestrator` (or restart the Claude Code session).
+4. If `claims.db` is corrupted — delete `claims.db`, `claims.db-wal`, `claims.db-shm`. Server recreates schema on next start. **All active claims are lost.**
+
+## Logging
+
+Stderr only. Claude Code captures and surfaces MCP stderr in its log panel. There is no file log — keep it that way to avoid log-rotation responsibilities and disk-leak surprises.
+
+Three stderr line patterns:
+- `[forge-orchestrator] started pid=... db=...` — boot
+- `[forge-orchestrator] keepalive <iso8601>` — every 8s
+- `[forge-orchestrator] stale pidfile pid=... — sending SIGTERM` — orphan-detect path
+
+## Contracts
+
+- Tool schemas + semantics: `.forge/phases/m10-01-orchestration/contracts/mcp-tools.md`
+- Data model + retention: `.forge/phases/m10-01-orchestration/data-model.md`
+- Architecture rationale: `.forge/decisions/ADR-003-awareness-mcp-sqlite.md`
+- Lifecycle rationale: `.forge/decisions/ADR-005-session-lifecycle.md`
+
+## Environment Variables
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `FORGE_REPO_ROOT` | `process.cwd()` | Root for `git` invocations in `forge_queue_commit`. |
+| `FORGE_DB` | `<server-dir>/claims.db` | Override DB path (testing only). |
+| `FORGE_PIDFILE` | `<server-dir>/server.pid` | Override pidfile path (testing only). |

package/experimental/m10/source/mcp-server/example.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "forge-orchestrator": {
+      "command": "node",
+      "args": [".forge/.mcp-server/index.js"]
+    }
+  }
+}