@phnx-labs/agents-cli 1.20.51 → 1.20.53

package/dist/lib/feed.js

@@ -0,0 +1,627 @@
+/**
+ * Feed store -- structured block records published by agents waiting on user
+ * input (AskUserQuestion). The outbound counterpart to the inbound mailbox:
+ * the mailbox delivers messages TO agents; the feed surfaces decisions agents
+ * need FROM the user.
+ *
+ * Layout: <feedDir>/<blockId>.json
+ *   Each file is one open block -- a question the agent asked. One block per
+ *   session: a new AskUserQuestion in the same session replaces the previous
+ *   block (an agent can only ask one question at a time). Removed when the
+ *   session advances past the block.
+ *
+ * A block carries enough identity (sessionId, mailboxId, host, runtime) for
+ * `agents feed` to aggregate across hosts and for `agents message` to route
+ * a reply back to the right agent.
+ *
+ * Answer lifecycle:
+ *   - A block may be answered from any surface (feed, terminal, tmux, cloud).
+ *   - The first answer wins: `recordAnswer` atomically checks an answered
+ *     marker so exactly one surface can claim the block.
+ *   - Answered blocks stay visible until the agent consumes the message and
+ *     continues, so the UI can show delivered/consumed/continued receipts.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getFeedDir, getUserAgentsDir } from './state.js';
+import { isHighConsequenceAllowed } from './operator.js';
+/**
+ * Stable block id for a session. One block per session -- a new question
+ * replaces the previous one (the agent can only ask one question at a time).
+ */
+export function blockIdForSession(sessionId) {
+    const safeSessionId = sessionId.replace(/[^A-Za-z0-9._-]/g, '-');
+    return `block-${safeSessionId}`;
+}
+function blockPath(root, blockId) {
+    if (!/^[A-Za-z0-9._-]+$/.test(blockId)) {
+        throw new Error(`Invalid feed block id: ${blockId}`);
+    }
+    return path.join(root, `${blockId}.json`);
+}
+function answeredDir(root) { return path.join(root, 'answered'); }
+function receiptDir(root) { return path.join(root, 'receipts'); }
+function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+function safeReadJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function atomicWriteJson(file, value) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(value, null, 2), 'utf-8');
+    fs.renameSync(tmp, file);
+}
+/** Read one block record. Returns undefined when missing or corrupt. */
+export function readBlock(blockId, root) {
+    const parsed = safeReadJson(blockPath(root ?? getFeedDir(), blockId));
+    if (!parsed || !parsed.blockId || !parsed.sessionId || !parsed.questions?.length)
+        return undefined;
+    return parsed;
+}
+/**
+ * Atomically claim the first answer for a block. Returns `{ ok: true }` when
+ * this call is the first to answer; returns `{ ok: false, existing }` when a
+ * different surface already answered the block. The marker file is created
+ * with `O_EXCL` so two concurrent claimers cannot both succeed.
+ *
+ * High-consequence blocks require a verified operator identity. Unverified
+ * answers (no operatorId or not in the registry/allowed list) are refused.
+ */
+export function recordAnswer(blockId, answer, root) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    const operatorId = answer.operatorId;
+    if (block?.consequence && block.consequence !== 'normal') {
+        // Operators live in ~/.agents/operators.yaml — never the feed store root.
+        if (!operatorId || answer.verified !== true || !isHighConsequenceAllowed(block.consequence, operatorId)) {
+            return {
+                ok: false,
+                unauthorized: true,
+                reason: `High-consequence block '${block.consequence}' requires a verified, authorized operator.`,
+            };
+        }
+    }
+    ensureDir(answeredDir(dir));
+    const marker = path.join(answeredDir(dir), `${blockId}.json`);
+    const record = {
+        answeredAt: new Date().toISOString(),
+        answeredFrom: answer.answeredFrom,
+        answeredBy: answer.answeredBy,
+        operatorId: answer.operatorId,
+        verified: answer.verified,
+    };
+    // Try to create the answered marker atomically.
+    try {
+        const fd = fs.openSync(marker, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644);
+        try {
+            const buf = Buffer.from(JSON.stringify(record, null, 2), 'utf-8');
+            fs.writeSync(fd, buf, 0, buf.length);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EEXIST') {
+            const existing = safeReadJson(marker);
+            return { ok: false, existing: existing ?? { answeredAt: '', answeredFrom: 'unknown' } };
+        }
+        throw err;
+    }
+    // Marker created successfully -- mirror the answer into the block file.
+    if (block) {
+        block.answer = record;
+        publishBlock(block, dir);
+    }
+    return { ok: true };
+}
+/** Read the answer record for a block, if one exists. */
+export function getAnswerRecord(blockId, root) {
+    return safeReadJson(path.join(answeredDir(root ?? getFeedDir()), `${blockId}.json`));
+}
+/** True when the block has already been answered. */
+export function isBlockAnswered(blockId, root) {
+    return fs.existsSync(path.join(answeredDir(root ?? getFeedDir()), `${blockId}.json`));
+}
+/** Receipt lifecycle rank — higher means further along; never regress. */
+const RECEIPT_STATUS_RANK = {
+    queued: 0,
+    consumed: 1,
+    continued: 2,
+};
+/**
+ * Record a delivery-receipt transition for a message tied to a block.
+ * Updates the receipts list in the block file. Status is monotonic
+ * (queued → consumed → continued): a late `queued` write cannot overwrite
+ * an already-recorded `consumed`/`continued` (race with mailbox drain).
+ */
+export function recordMessageReceipt(blockId, receipt, root) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    if (!block)
+        return;
+    const receipts = block.receipts ?? [];
+    const idx = receipts.findIndex((r) => r.msgId === receipt.msgId);
+    if (idx >= 0) {
+        const prev = receipts[idx];
+        if (RECEIPT_STATUS_RANK[receipt.status] < RECEIPT_STATUS_RANK[prev.status]) {
+            return; // do not regress
+        }
+        receipts[idx] = receipt;
+    }
+    else {
+        receipts.push(receipt);
+    }
+    block.receipts = receipts;
+    publishBlock(block, dir);
+}
+/** Read the receipt list for a block. */
+export function getBlockReceipts(blockId, root) {
+    return readBlock(blockId, root)?.receipts ?? [];
+}
+/** Mark a block as "continued" -- the agent consumed the answer and moved on. */
+export function recordContinued(blockId, root) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    if (!block)
+        return;
+    block.continuedAt = new Date().toISOString();
+    publishBlock(block, dir);
+}
+/** Mark a decision-class block as hard-parked (no safe default existed). */
+export function recordParked(blockId, root) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    if (!block)
+        return;
+    block.parkedAt = new Date().toISOString();
+    publishBlock(block, dir);
+}
+/** Mark that the approval safe-default was applied by policy. */
+export function recordDefaulted(blockId, root) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    if (!block)
+        return;
+    block.defaultedAt = new Date().toISOString();
+    publishBlock(block, dir);
+}
+/** Mark that an urgent block was paged to the phone. */
+export function recordNotified(blockId, root) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    if (!block)
+        return;
+    block.notifiedAt = new Date().toISOString();
+    publishBlock(block, dir);
+}
+/** Convenience: record that a terminal answer closed the block. */
+export function recordTerminalAnswer(blockId, root) {
+    recordAnswer(blockId, { answeredFrom: 'terminal' }, root);
+}
+/** Remove answered marker and receipts for a block (used by block removal/GC). */
+export function clearBlockLifecycle(blockId, root) {
+    const dir = root ?? getFeedDir();
+    for (const sub of [answeredDir(dir), receiptDir(dir)]) {
+        try {
+            fs.unlinkSync(path.join(sub, `${blockId}.json`));
+        }
+        catch {
+            // ignore missing
+        }
+    }
+}
+/** Atomic write a block record to the feed store. Clears stale lifecycle state. */
+export function publishBlock(block, root) {
+    const dir = root ?? getFeedDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const target = blockPath(dir, block.blockId);
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(block, null, 2), 'utf-8');
+    fs.renameSync(tmp, target);
+}
+/** Read all block records. Returns them sorted by stable block filename. */
+export function listBlocks(root) {
+    const dir = root ?? getFeedDir();
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const blocks = [];
+    for (const name of names.filter(n => n.endsWith('.json')).sort()) {
+        try {
+            const raw = fs.readFileSync(path.join(dir, name), 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed.blockId && parsed.sessionId && parsed.questions?.length) {
+                blocks.push(parsed);
+            }
+        }
+        catch {
+            // skip corrupt / partial files
+        }
+    }
+    return blocks;
+}
+/** Remove a block record and its lifecycle sidecars. Returns true if the file was deleted. */
+export function removeBlock(blockId, root) {
+    const dir = root ?? getFeedDir();
+    clearBlockLifecycle(blockId, dir);
+    try {
+        fs.unlinkSync(blockPath(dir, blockId));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Hook installation
+// ---------------------------------------------------------------------------
+/**
+ * The feed-publish PreToolUse hook script (Python, mirroring 09-mailbox-inject.py).
+ * Embedded so it ships with the compiled CLI and can be installed to the
+ * CLI-writable user hooks dir without a separate file in the npm tarball.
+ */
+export const FEED_PUBLISH_HOOK_SCRIPT = `#!/usr/bin/env python3
+"""Publish and clear open-block records for \`agents feed\`.
+
+The manifest invokes this script for top-level AskUserQuestion calls, waiting
+notifications, question answers, and session lifecycle events. One atomic file
+per session means a new block replaces the previous block. Answer/resume/stop
+events remove it so \`agents feed\` only lists decisions that are still open.
+
+Sub-agent gate: when the PreToolUse payload carries \`agent_type\`, this is a
+Task/Agent subagent -- skip. Only the top-level agent publishes. Verified on
+Claude Code 2.1.170 (2026-07).
+
+Fail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.
+"""
+import os
+import sys
+import json
+import re
+import socket
+import tempfile
+from datetime import datetime, timezone
+
+WAITING_NOTIFICATION_TYPES = {
+    "permission_prompt",
+    "idle_prompt",
+    "elicitation_dialog",
+}
+CLEAR_EVENTS = {
+    "PostToolUse",
+    "Stop",
+    "SessionEnd",
+}
+
+
+def read_json(path):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+def write_json(path, value):
+    dir_name = os.path.dirname(path)
+    os.makedirs(dir_name, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(value, f, indent=2)
+        os.replace(tmp, path)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except Exception:
+            pass
+
+
+def main():
+    raw = sys.stdin.read()
+    try:
+        payload = json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return
+
+    # Sub-agent gate.
+    if payload.get("agent_type"):
+        return
+
+    session_id = payload.get("session_id", "")
+    if not session_id:
+        return
+
+    safe_session_id = re.sub(r"[^A-Za-z0-9._-]", "-", session_id)
+    block_id = f"block-{safe_session_id}"
+    home = os.environ.get("HOME") or os.path.expanduser("~")
+    feed_dir = os.path.join(home, ".agents", ".history", "feed")
+    answered_dir = os.path.join(feed_dir, "answered")
+    target = os.path.join(feed_dir, f"{block_id}.json")
+    hook_event = payload.get("hook_event_name", "PreToolUse")
+
+    if hook_event in CLEAR_EVENTS:
+        try:
+            os.unlink(target)
+        except FileNotFoundError:
+            pass
+        except Exception:
+            pass
+        # Also clear the answered marker so a future question for this session
+        # is not permanently locked.
+        try:
+            os.unlink(os.path.join(answered_dir, f"{block_id}.json"))
+        except FileNotFoundError:
+            pass
+        except Exception:
+            pass
+        return
+
+    # Terminal answers (human typed in the TUI) record an answered marker and
+    # remove the block file so the feed stops showing it within one poll cycle.
+    # The marker stays behind so a concurrent surface cannot double-answer.
+    if hook_event == "UserPromptSubmit":
+        os.makedirs(answered_dir, exist_ok=True)
+        marker = os.path.join(answered_dir, f"{block_id}.json")
+        try:
+            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
+            record = {
+                "answeredAt": datetime.now(timezone.utc).isoformat(),
+                "answeredFrom": "terminal",
+            }
+            with os.fdopen(fd, "w") as f:
+                json.dump(record, f, indent=2)
+        except FileExistsError:
+            pass
+        except Exception:
+            pass
+        # Remove the visible block so the feed drops the answered question.
+        try:
+            os.unlink(target)
+        except FileNotFoundError:
+            pass
+        except Exception:
+            pass
+        return
+
+    notification_type = None
+    if hook_event == "Notification":
+        notification_type = payload.get("notification_type", "")
+        if notification_type not in WAITING_NOTIFICATION_TYPES:
+            return
+        # Claude emits a generic permission notification after presenting an
+        # AskUserQuestion. Keep the structured questions and options already
+        # published for this session instead of replacing them with that less
+        # useful notification text.
+        try:
+            with open(target) as existing_file:
+                existing = json.load(existing_file)
+            if existing.get("kind") == "question":
+                return
+        except Exception:
+            pass
+        message = payload.get("message", "")
+        if not message:
+            return
+        normalized_questions = [{
+            "text": message,
+            "header": payload.get("title") or notification_type.replace("_", " ").title(),
+            "multiSelect": False,
+        }]
+        kind = "notification"
+    else:
+        tool_input = payload.get("tool_input", {})
+        questions = tool_input.get("questions", [])
+        if not questions:
+            return
+        normalized_questions = []
+        for q in questions:
+            if not isinstance(q, dict):
+                continue
+            question = {
+                "text": q.get("question", q.get("header", "")),
+                "header": q.get("header"),
+                "multiSelect": q.get("multiSelect", False),
+            }
+            raw_opts = q.get("options", [])
+            if raw_opts:
+                question["options"] = [
+                    {"label": o.get("label", ""), "description": o.get("description")}
+                    for o in raw_opts
+                    if isinstance(o, dict)
+                ]
+            normalized_questions.append(question)
+        if not normalized_questions:
+            return
+        kind = "question"
+
+    # Identity from env (set by agents-cli at spawn).
+    mailbox_id = os.path.basename(
+        os.environ.get("AGENTS_MAILBOX_DIR", "").rstrip("/")
+    ) or session_id
+
+    hostname = os.environ.get("AGENTS_SYNC_MACHINE_ID") or socket.gethostname()
+    host = hostname.split(".")[0].strip().lower()
+    host = re.sub(r"[^a-z0-9_-]", "-", host) or "unknown"
+
+    runtime = os.environ.get("AGENTS_RUNTIME", "headless")
+
+    block = {
+        "blockId": block_id,
+        "sessionId": session_id,
+        "mailboxId": mailbox_id,
+        "host": host,
+        "runtime": runtime,
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "questions": normalized_questions,
+        "kind": kind,
+    }
+    if notification_type:
+        block["notificationType"] = notification_type
+
+    # Optional multi-operator control metadata passed by the agent in the
+    # AskUserQuestion tool_input. Defaults keep the existing behavior.
+    controls = payload.get("tool_input", {}) if hook_event != "Notification" else {}
+    block_class = controls.get("blockClass") if isinstance(controls, dict) else None
+    if block_class in ("approval", "decision"):
+        block["blockClass"] = block_class
+    consequence = controls.get("consequence") if isinstance(controls, dict) else None
+    if consequence:
+        block["consequence"] = consequence
+    allowed = controls.get("allowedOperators") if isinstance(controls, dict) else None
+    if isinstance(allowed, list):
+        block["allowedOperators"] = [str(a) for a in allowed]
+    timeout = controls.get("timeoutMinutes") if isinstance(controls, dict) else None
+    if isinstance(timeout, (int, float)) and timeout > 0:
+        block["timeoutMinutes"] = int(timeout)
+    safe_default = controls.get("safeDefault") if isinstance(controls, dict) else None
+    if isinstance(safe_default, str):
+        block["safeDefault"] = safe_default
+    cost = controls.get("costOfDelay") if isinstance(controls, dict) else None
+    if cost in ("low", "medium", "high"):
+        block["costOfDelay"] = cost
+
+    # Publishing a new question clears any stale answered marker from the
+    # previous question in this session.
+    try:
+        os.unlink(os.path.join(answered_dir, f"{block_id}.json"))
+    except FileNotFoundError:
+        pass
+    except Exception:
+        pass
+
+    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a
+    # HOME override on every platform. Use the same anchor so hooks and the CLI
+    # always read/write one feed store (including temp-home and sandbox runs).
+    os.makedirs(feed_dir, exist_ok=True)
+
+    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(block, f, indent=2)
+        os.replace(tmp, target)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass  # fail open
+`;
+/** Manifest entry for the feed-publish hook, matching the ManifestHook shape. */
+export const FEED_PUBLISH_HOOK_MANIFEST = {
+    name: 'feed-publish',
+    events: ['PreToolUse'],
+    matcher: 'AskUserQuestion',
+    script: '10-feed-publish.py',
+    timeout: 5,
+};
+export const FEED_NOTIFICATION_HOOK_MANIFEST = {
+    name: 'feed-publish-notification',
+    events: ['Notification'],
+    matcher: 'permission_prompt|idle_prompt|elicitation_dialog',
+    script: '10-feed-publish.py',
+    timeout: 5,
+};
+export const FEED_ANSWERED_HOOK_MANIFEST = {
+    name: 'feed-clear-answered',
+    events: ['PostToolUse'],
+    matcher: 'AskUserQuestion',
+    script: '10-feed-publish.py',
+    timeout: 5,
+};
+export const FEED_LIFECYCLE_HOOK_MANIFEST = {
+    name: 'feed-clear-lifecycle',
+    events: ['Stop', 'UserPromptSubmit', 'SessionEnd'],
+    script: '10-feed-publish.py',
+    timeout: 5,
+};
+/**
+ * Install the feed-publish hook script into the user hooks dir and add its
+ * manifest entry to the user agents.yaml. The system repo is an auto-pulled,
+ * read-only mirror, so runtime-managed hooks must never write there.
+ * Idempotent -- skips if the script is already present and up to date.
+ */
+export function ensureFeedPublishHook(userAgentsDir = getUserAgentsDir()) {
+    try {
+        const hooksDir = path.join(userAgentsDir, 'hooks');
+        const scriptPath = path.join(hooksDir, '10-feed-publish.py');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        let installed = false;
+        if (!fs.existsSync(scriptPath) || fs.readFileSync(scriptPath, 'utf-8') !== FEED_PUBLISH_HOOK_SCRIPT) {
+            const tmpScript = `${scriptPath}.${process.pid}.tmp`;
+            fs.writeFileSync(tmpScript, FEED_PUBLISH_HOOK_SCRIPT, { mode: 0o755 });
+            fs.renameSync(tmpScript, scriptPath);
+            installed = true;
+        }
+        const agentsYamlPath = path.join(userAgentsDir, 'agents.yaml');
+        const yamlDoc = fs.existsSync(agentsYamlPath)
+            ? yaml.parseDocument(fs.readFileSync(agentsYamlPath, 'utf-8'))
+            : new yaml.Document({});
+        if (yamlDoc.errors.length > 0) {
+            throw new Error(`Cannot install feed hook: ${agentsYamlPath} is invalid YAML`);
+        }
+        const desiredHooks = {
+            'feed-publish': {
+                agents: ['claude'],
+                events: ['PreToolUse'],
+                matcher: 'AskUserQuestion',
+                script: '10-feed-publish.py',
+                timeout: 5,
+            },
+            'feed-publish-notification': {
+                agents: ['claude'],
+                events: ['Notification'],
+                matcher: 'permission_prompt|idle_prompt|elicitation_dialog',
+                script: '10-feed-publish.py',
+                timeout: 5,
+            },
+            'feed-clear-answered': {
+                agents: ['claude'],
+                events: ['PostToolUse'],
+                matcher: 'AskUserQuestion',
+                script: '10-feed-publish.py',
+                timeout: 5,
+            },
+            'feed-clear-lifecycle': {
+                agents: ['claude'],
+                events: ['Stop', 'UserPromptSubmit', 'SessionEnd'],
+                script: '10-feed-publish.py',
+                timeout: 5,
+            },
+        };
+        for (const [name, definition] of Object.entries(desiredHooks)) {
+            if (!yamlDoc.getIn(['hooks', name])) {
+                yamlDoc.setIn(['hooks', name], definition);
+                installed = true;
+            }
+        }
+        if (installed) {
+            const tmpYaml = `${agentsYamlPath}.${process.pid}.tmp`;
+            fs.writeFileSync(tmpYaml, String(yamlDoc));
+            fs.renameSync(tmpYaml, agentsYamlPath);
+        }
+        return { installed };
+    }
+    catch (err) {
+        return { installed: false, error: err.message };
+    }
+}

package/dist/lib/git.d.ts

@@ -88,9 +88,25 @@ export declare function commitAndPush(repoPath: string, message: string): Promis
  */
 export declare function hasUncommittedChanges(repoPath: string): Promise<boolean>;
 /**
- * Check if a directory is a git repository.
+ * Check if a directory is a git repository (**synchronous, root-only**).
+ *
+ * Tests for a `.git` entry directly under `dir`, so it recognizes only a
+ * repository *root* — it returns false inside a subdirectory and for linked
+ * worktrees (whose `.git` is a file pointing elsewhere is caught, but a nested
+ * cwd is not). This is deliberate: the system-repo sync callers here always
+ * pass a known root. For the async, worktree-correct predicate used by teams,
+ * see `isGitRepo` in `lib/teams/worktree.ts` (which shells out to
+ * `git rev-parse --git-dir`). The two are intentionally **not** merged.
  */
 export declare function isGitRepo(dir: string): boolean;
+/**
+ * Return the absolute path to the git working-tree root containing `dir`.
+ *
+ * Shells out to `git rev-parse --show-toplevel`, so it resolves correctly from
+ * any subdirectory and for linked worktrees (unlike the root-only, synchronous
+ * {@link isGitRepo} above). Throws if `dir` is not inside a git repository.
+ */
+export declare function getGitRoot(dir: string): Promise<string>;
 /**
  * Initialize a git repo in an existing directory.
  */

package/dist/lib/git.js

@@ -403,11 +403,30 @@ export async function hasUncommittedChanges(repoPath) {
     }
 }
 /**
- * Check if a directory is a git repository.
+ * Check if a directory is a git repository (**synchronous, root-only**).
+ *
+ * Tests for a `.git` entry directly under `dir`, so it recognizes only a
+ * repository *root* — it returns false inside a subdirectory and for linked
+ * worktrees (whose `.git` is a file pointing elsewhere is caught, but a nested
+ * cwd is not). This is deliberate: the system-repo sync callers here always
+ * pass a known root. For the async, worktree-correct predicate used by teams,
+ * see `isGitRepo` in `lib/teams/worktree.ts` (which shells out to
+ * `git rev-parse --git-dir`). The two are intentionally **not** merged.
  */
 export function isGitRepo(dir) {
     return fs.existsSync(path.join(dir, '.git'));
 }
+/**
+ * Return the absolute path to the git working-tree root containing `dir`.
+ *
+ * Shells out to `git rev-parse --show-toplevel`, so it resolves correctly from
+ * any subdirectory and for linked worktrees (unlike the root-only, synchronous
+ * {@link isGitRepo} above). Throws if `dir` is not inside a git repository.
+ */
+export async function getGitRoot(dir) {
+    const root = await simpleGit(dir).revparse(['--show-toplevel']);
+    return root.trim();
+}
 /**
  * Initialize a git repo in an existing directory.
  */