harnery 0.0.1 → 0.2.1

package/dist/core/agents/render/prompt-context.js

@@ -0,0 +1,335 @@
+/**
+ * UserPromptSubmit UX renderer. Combines the peer-refresh dedup, the
+ * council-pending hash-dedup, and the Cursor set-task staleness nudge.
+ * agent-hook's user_prompt.submit post-emit handler calls this
+ * and forwards the result as the harness-shaped additionalContext payload.
+ *
+ * Three hash-dedup'd subsections combined into one additionalContext payload:
+ *   1. Peer table: semantically-relevant peer fields hashed; only re-emits
+ *      when peers change (name + instance_id + session_id + kind + started_at
+ *      + sorted(files_touched) + platform, sorted by instance_id).
+ *   2. Council pending: pending open-council IDs hashed; re-emits when the
+ *      ID set changes.
+ *   3. Task staleness nudge (cursor only, since CC enforces via the Stop hook
+ *      transcript scan). Fires when `task` is null or `task_updated_at` is
+ *      older than HARNERY_TASK_STALE_SECONDS (default 1800 = 30 min). Hash-deduped
+ *      against the previous nudge state.
+ *
+ * Hash files live at:
+ *   .harnery/.last-peer-hash.<instance_id>
+ *   .harnery/.last-council-hash.<instance_id>
+ *   .harnery/.last-task-nudge-hash.<instance_id>
+ *
+ * First call always emits (hash files don't exist).
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { coordEnv } from "../../../lib/env.js";
+import { formatPendingCouncils } from "./session-context.js";
+/**
+ * Build the combined UserPromptSubmit additionalContext string. Returns "" when
+ * nothing has changed since the last call (so the caller can skip the JSON emit).
+ *
+ * Side effects: updates `.harnery/.last-peer-hash.<id>` and `.harnery/.last-council-hash.<id>`
+ * when their respective sections re-emit (or removes the council hash when no
+ * councils are pending, matching the bash behavior).
+ */
+export function renderPromptContext(opts) {
+    const { coordRoot, instanceId, sessionId, agentName, taskNudge } = opts;
+    const sections = [];
+    // 1. Peer table with hash dedup.
+    const peerTable = computePeerTableIfChanged(coordRoot, instanceId, sessionId);
+    if (peerTable)
+        sections.push(peerTable);
+    // 2. Council pending with hash dedup.
+    if (agentName) {
+        const councilMsg = computeCouncilPendingIfChanged(coordRoot, instanceId, agentName);
+        if (councilMsg)
+            sections.push(councilMsg);
+    }
+    // 3. Task staleness nudge (cursor only).
+    if (taskNudge) {
+        const nudgeMsg = computeTaskNudgeIfChanged(coordRoot, instanceId);
+        if (nudgeMsg)
+            sections.push(nudgeMsg);
+    }
+    return sections.join("\n\n");
+}
+/** The set-task staleness nudge for Cursor.
+ * Emits a one-line reminder when `task` is null or `task_updated_at` is older
+ * than HARNERY_TASK_STALE_SECONDS (default 1800). Hash-deduped against previous
+ * nudge state. */
+function computeTaskNudgeIfChanged(coordRoot, selfInstanceId) {
+    const hbPath = join(coordRoot, ".harnery", "active", `${selfInstanceId}.json`);
+    if (!existsSync(hbPath))
+        return "";
+    let hb;
+    try {
+        hb = JSON.parse(readFileSync(hbPath, "utf8"));
+    }
+    catch {
+        return "";
+    }
+    const threshold = Number.parseInt(coordEnv("TASK_STALE_SECONDS") ?? "1800", 10);
+    const taskValue = hb.task ?? "";
+    let needsNudge = false;
+    let message = "";
+    if (!taskValue) {
+        needsNudge = true;
+        message =
+            "Heads up: your `task` field is unset. Run `agents set-task \"<short focus>\"` so peers + the coord dashboard can see what you're working on. (Cursor sessions can't enforce this from the Stop hook the way Claude Code does, so this is a one-time soft reminder per staleness state.)";
+    }
+    else if (hb.task_updated_at) {
+        const updatedSec = Math.floor(Date.parse(hb.task_updated_at) / 1000);
+        const nowSec = Math.floor(Date.now() / 1000);
+        if (Number.isFinite(updatedSec) && updatedSec > 0) {
+            const ageSec = nowSec - updatedSec;
+            if (ageSec > threshold) {
+                needsNudge = true;
+                message = `Heads up: your \`task\` field hasn't changed in ${ageSec}s (threshold ${threshold}s). If you've moved on from "${taskValue.slice(0, 60)}", update via \`agents set-task "<new focus>"\`. Pass an empty string to clear.`;
+            }
+        }
+    }
+    const hashFile = join(coordRoot, ".harnery", `.last-task-nudge-hash.${selfInstanceId}`);
+    if (!needsNudge) {
+        try {
+            if (existsSync(hashFile))
+                rmSync(hashFile, { force: true });
+        }
+        catch {
+            /* swallow */
+        }
+        return "";
+    }
+    // Dedup on a state-hash (task value + threshold) so same-state turns don't re-nudge.
+    const state = `${taskValue}|stale=1|threshold=${threshold}`;
+    const newHash = sha256Hex16(state);
+    const oldHash = safeRead(hashFile);
+    if (oldHash && oldHash === newHash)
+        return "";
+    writeHashFile(hashFile, newHash);
+    return message;
+}
+function computePeerTableIfChanged(coordRoot, selfInstanceId, selfSessionIdFallback) {
+    const activeDir = join(coordRoot, ".harnery", "active");
+    if (!existsSync(activeDir))
+        return "";
+    // Read self heartbeat for session_id (group key); fall back to the caller's hint.
+    let mySessionId = selfSessionIdFallback;
+    const selfHb = readHeartbeat(join(activeDir, `${selfInstanceId}.json`));
+    if (selfHb?.session_id)
+        mySessionId = selfHb.session_id;
+    if (!mySessionId)
+        return "";
+    // Collect peer heartbeats.
+    const peers = [];
+    for (const f of readdirSync(activeDir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const hb = readHeartbeat(join(activeDir, f));
+        if (!hb?.instance_id || hb.instance_id === selfInstanceId)
+            continue;
+        peers.push(hb);
+    }
+    if (peers.length === 0)
+        return "";
+    // Build hash basis: sorted-by-instance_id projection of semantically-relevant fields.
+    const basis = peers
+        .map((p) => ({
+        name: p.name ?? null,
+        instance_id: p.instance_id ?? null,
+        session_id: p.session_id ?? null,
+        kind: p.kind ?? null,
+        started_at: p.started_at ?? null,
+        files_touched: Array.from(p.files_touched ?? []).sort(),
+        platform: p.platform ?? null,
+    }))
+        .sort((a, b) => (a.instance_id ?? "").localeCompare(b.instance_id ?? ""));
+    const newHash = sha256Hex16(JSON.stringify(basis));
+    const hashFile = join(coordRoot, ".harnery", `.last-peer-hash.${selfInstanceId}`);
+    const oldHash = safeRead(hashFile);
+    if (oldHash && oldHash === newHash)
+        return "";
+    // Render peer table via the same formatter used at SessionStart.
+    const table = formatPeerTable(peers, mySessionId);
+    if (!table)
+        return "";
+    // Persist hash atomically (temp + rename, same convention as other coord writes).
+    writeHashFile(hashFile, newHash);
+    return table;
+}
+function computeCouncilPendingIfChanged(coordRoot, selfInstanceId, agentName) {
+    const councilsDir = join(coordRoot, ".harnery", "councils");
+    if (!existsSync(councilsDir))
+        return "";
+    const canonicalName = agentName.startsWith("agent-") ? agentName : `agent-${agentName}`;
+    // Collect pending council IDs (open councils where I'm a member and haven't contributed).
+    const pendingIds = [];
+    try {
+        for (const f of readdirSync(councilsDir)) {
+            if (!f.endsWith(".json"))
+                continue;
+            try {
+                const m = JSON.parse(readFileSync(join(councilsDir, f), "utf8"));
+                if (m.status !== "active" || m.round_status !== "open")
+                    continue;
+                if (!m.council_id || !m.members?.includes(canonicalName))
+                    continue;
+                const round = m.current_round ?? 1;
+                const contributionPath = join(councilsDir, m.council_id, `round-${round}`, `${canonicalName}.md`);
+                if (existsSync(contributionPath))
+                    continue;
+                pendingIds.push(m.council_id);
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    catch {
+        return "";
+    }
+    pendingIds.sort();
+    const hashFile = join(coordRoot, ".harnery", `.last-council-hash.${selfInstanceId}`);
+    const newHash = sha256Hex16(pendingIds.join("\n"));
+    const oldHash = safeRead(hashFile);
+    // Clear hash file when no councils pending, matching bash behavior.
+    if (pendingIds.length === 0) {
+        try {
+            if (existsSync(hashFile))
+                rmSync(hashFile, { force: true });
+        }
+        catch {
+            /* swallow */
+        }
+        return "";
+    }
+    // Always update hash file when pending councils exist (eager-rewrite, matches bash).
+    writeHashFile(hashFile, newHash);
+    if (oldHash && oldHash === newHash)
+        return "";
+    return formatPendingCouncils(coordRoot, agentName);
+}
+/* ---------- helpers ---------- */
+function readHeartbeat(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function safeRead(path) {
+    try {
+        return readFileSync(path, "utf8").trim();
+    }
+    catch {
+        return "";
+    }
+}
+function sha256Hex16(input) {
+    return createHash("sha256").update(input).digest("hex").slice(0, 16);
+}
+function writeHashFile(path, value) {
+    try {
+        mkdirSync(join(path, ".."), { recursive: true });
+        const tmp = `${path}.${process.pid}.tmp`;
+        writeFileSync(tmp, value, "utf8");
+        renameSync(tmp, path);
+    }
+    catch {
+        /* swallow */
+    }
+}
+/* The peer-table formatter is a near-duplicate of session-context.ts's, but
+ * intentionally co-located here so the prompt-context renderer is self-contained
+ * (no cross-file imports of formatting internals). If both renderers diverge,
+ * pull the shared bits into a small util module. */
+function formatPeerTable(peers, mySessionId) {
+    if (peers.length === 0)
+        return "";
+    const nowSec = Math.floor(Date.now() / 1000);
+    const fold = {};
+    for (const p of peers) {
+        const kind = p.kind ?? "unknown";
+        if (kind === "transient" && p.session_id) {
+            fold[p.session_id] = (fold[p.session_id] ?? []).concat(p.files_touched ?? []);
+        }
+    }
+    const rows = peers
+        .filter((p) => (p.kind ?? "unknown") !== "transient")
+        .map((p) => {
+        const folded = fold[p.instance_id ?? ""] ?? [];
+        const display = Array.from(new Set([...(p.files_touched ?? []), ...folded])).sort();
+        return { ...p, display_files: display };
+    });
+    const blocking = rows.filter((p) => p.session_id !== mySessionId).sort(byStartedAt);
+    const group = rows.filter((p) => p.session_id === mySessionId).sort(byStartedAt);
+    const out = [];
+    const blk = renderSubtable(blocking, "Other agent groups active (their files block you):", nowSec);
+    if (blk)
+        out.push(blk);
+    const grp = renderSubtable(group, "Your group (subagents / parent / siblings; no mutual block):", nowSec);
+    if (grp)
+        out.push(grp);
+    return out.join("\n\n");
+}
+function byStartedAt(a, b) {
+    return (a.started_at ?? "").localeCompare(b.started_at ?? "");
+}
+function renderSubtable(rows, header, nowSec) {
+    if (rows.length === 0)
+        return "";
+    const first = rows.slice(0, 10).map((r) => formatRow(r, nowSec));
+    const overflow = rows.length > 10 ? `\n  +${rows.length - 10} more` : "";
+    return `${header}\n${first.join("\n")}${overflow}`;
+}
+function formatRow(r, nowSec) {
+    const taskPart = r.task ? ` "${r.task.slice(0, 60)}"` : "";
+    // Fall back started_at → last_heartbeat; if neither is a valid timestamp,
+    // show "age unknown" rather than the epoch-derived "20608d ago" ghost.
+    const startedSec = parseIsoSec(r.started_at) ?? parseIsoSec(r.last_heartbeat);
+    const ageFrom = startedSec === null ? "age unknown" : fmtAge(nowSec - startedSec);
+    const filesPart = fmtFiles(r.display_files);
+    const lastActivity = fmtLastActivity(r, nowSec);
+    const turnSummary = r.turn_summary ? `\n    last turn: ${r.turn_summary.slice(0, 80)}` : "";
+    // Prefer a short instance_id over a bare "unknown" so an incomplete row is
+    // still identifiable.
+    const label = r.name ?? (r.instance_id ? r.instance_id.slice(0, 8) : "unknown");
+    return `  - agent-${label}${taskPart}   (${ageFrom}, ${filesPart}${lastActivity})${turnSummary}`;
+}
+function fmtFiles(files) {
+    if (files.length === 0)
+        return "nothing yet";
+    if (files.length <= 3)
+        return `holds: ${files.join(", ")}`;
+    return `holds: ${files.slice(0, 3).join(", ")}, +${files.length - 3} more`;
+}
+function fmtLastActivity(r, nowSec) {
+    if (!r.last_tool)
+        return "";
+    const lastTs = parseIsoSec(r.last_heartbeat) ?? parseIsoSec(r.started_at);
+    const tail = r.last_tool_target ? ` ${r.last_tool_target.slice(0, 60)}` : "";
+    // No valid timestamp → render the tool without an absurd age.
+    if (lastTs === null)
+        return `, last: ${r.last_tool}${tail}`;
+    return `, last: ${r.last_tool}${tail} ${fmtAge(nowSec - lastTs)}`;
+}
+/** Epoch-seconds for an ISO string, or null when missing/unparseable (so callers
+ * can render "age unknown" instead of an epoch-derived absurd age). */
+function parseIsoSec(iso) {
+    if (!iso)
+        return null;
+    const ms = Date.parse(iso);
+    return Number.isFinite(ms) ? Math.floor(ms / 1000) : null;
+}
+function fmtAge(secs) {
+    if (secs < 60)
+        return `${Math.floor(secs)}s ago`;
+    if (secs < 3600)
+        return `${Math.floor(secs / 60)}m ago`;
+    if (secs < 86400)
+        return `${Math.floor(secs / 3600)}h ago`;
+    return `${Math.floor(secs / 86400)}d ago`;
+}

package/dist/core/agents/render/session-context.d.ts

@@ -0,0 +1,39 @@
+/**
+ * SessionStart UX renderer: combines the peer table, the wiring check, and
+ * the pending-council formatter so agent-hook session.start can emit the
+ * combined `systemMessage` JSON directly.
+ *
+ * Outputs a Claude Code SessionStart hookSpecificOutput.additionalContext
+ * string.
+ */
+import { statSync } from "node:fs";
+export interface RenderOpts {
+    coordRoot: string;
+    instanceId: string;
+    sessionId: string;
+    agentName?: string;
+    /** Harness label rendered in parens after the self-name (e.g. "Cursor", "Codex").
+     * Claude Code omits it. */
+    platformLabel?: string;
+}
+/**
+ * Build the combined SessionStart systemMessage. Returns the additionalContext
+ * string (or "" if there's nothing to say).
+ */
+export declare function renderSessionContext(opts: RenderOpts): string;
+/**
+ * Returns a list of wiring issues (empty when everything's wired). Checks
+ * parent core.hooksPath + one representative submodule.
+ */
+export declare function checkWiring(coordRoot: string): string[];
+/**
+ * Returns the formatted council invite reminder
+ * (or "" when no councils await input).
+ */
+export declare function formatPendingCouncils(coordRoot: string, agentName: string): string;
+/**
+ * Suppress unused import warning when statSync isn't used in this file
+ * (kept exported for future renderers, e.g. heartbeat-freshness coloring).
+ */
+export declare const _ensureStatSyncImported: typeof statSync;
+//# sourceMappingURL=session-context.d.ts.map

package/dist/core/agents/render/session-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-context.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/render/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAyC,QAAQ,EAAE,MAAM,SAAS,CAAC;AAmB1E,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+BAC2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAoC7D;AAwHD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAiCvD;AA6CD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAiDlF;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,iBAAW,CAAC"}

package/dist/core/agents/render/session-context.js

@@ -0,0 +1,283 @@
+/**
+ * SessionStart UX renderer: combines the peer table, the wiring check, and
+ * the pending-council formatter so agent-hook session.start can emit the
+ * combined `systemMessage` JSON directly.
+ *
+ * Outputs a Claude Code SessionStart hookSpecificOutput.additionalContext
+ * string.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { resolveBinName } from "../../config.js";
+/**
+ * Build the combined SessionStart systemMessage. Returns the additionalContext
+ * string (or "" if there's nothing to say).
+ */
+export function renderSessionContext(opts) {
+    const { coordRoot, instanceId, sessionId, agentName, platformLabel } = opts;
+    const messages = [];
+    // 1. Self-name line + peer table (folded if peers present)
+    const peers = readActivePeers(coordRoot, instanceId);
+    const peerTable = formatPeerTable(peers, sessionId);
+    if (agentName) {
+        const suffix = platformLabel ? ` (${platformLabel})` : "";
+        const selfLine = `You are agent-${agentName}${suffix}.`;
+        messages.push(peerTable ? `${selfLine}\n\n${peerTable}` : selfLine);
+    }
+    else if (peerTable) {
+        messages.push(peerTable);
+    }
+    // 2. Linked-worktree detection
+    if (isLinkedWorktree(coordRoot)) {
+        messages.push(`Running inside worktree ${process.cwd()}. The coord layer is scoped to this worktree only; use \`${resolveBinName(coordRoot)} worktree diff\` to check for conflicts against sibling worktrees.`);
+    }
+    // 3. Council invites
+    if (agentName) {
+        const councilMsg = formatPendingCouncils(coordRoot, agentName);
+        if (councilMsg)
+            messages.push(councilMsg);
+    }
+    // 4. Wiring check
+    const wiringIssues = checkWiring(coordRoot);
+    if (wiringIssues.length > 0) {
+        const wiringSummary = `Coordination hooks are NOT wired: the E-guard will not block conflicting commits, and post-commit claim pruning will not run. Run \`scripts/setup-hooks.sh\` to fix. Detected:\n${wiringIssues.map((i) => `  - ${i}`).join("\n")}`;
+        messages.push(wiringSummary);
+    }
+    return messages.join("\n\n");
+}
+/** Read all peer heartbeats from .harnery/active/, excluding self. */
+function readActivePeers(coordRoot, selfInstanceId) {
+    const out = [];
+    const dir = join(coordRoot, ".harnery", "active");
+    if (!existsSync(dir))
+        return out;
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        try {
+            const hb = JSON.parse(readFileSync(join(dir, f), "utf8"));
+            if (!hb.instance_id || hb.instance_id === selfInstanceId)
+                continue;
+            out.push(hb);
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return out;
+}
+/**
+ * Renders the peer table as
+ * two subsections: "Other agent groups active" (blocking) and "Your group"
+ * (subagents/siblings, no mutual block). Folds transient subagents' files
+ * into their parent session.
+ */
+function formatPeerTable(peers, mySessionId) {
+    if (peers.length === 0)
+        return "";
+    const nowSec = Math.floor(Date.now() / 1000);
+    // Fold transient peers' files into their session_id parent.
+    const fold = {};
+    for (const p of peers) {
+        const kind = p.kind ?? "unknown";
+        if (kind === "transient" && p.session_id) {
+            fold[p.session_id] = (fold[p.session_id] ?? []).concat(p.files_touched ?? []);
+        }
+    }
+    const rows = peers
+        .filter((p) => (p.kind ?? "unknown") !== "transient")
+        .map((p) => {
+        const folded = fold[p.instance_id ?? ""] ?? [];
+        const display = Array.from(new Set([...(p.files_touched ?? []), ...folded])).sort();
+        return { ...p, display_files: display };
+    });
+    const blocking = rows.filter((p) => p.session_id !== mySessionId).sort(byStartedAt);
+    const group = rows.filter((p) => p.session_id === mySessionId).sort(byStartedAt);
+    const sections = [];
+    const blockingSection = renderSubtable(blocking, "Other agent groups active (their files block you):", nowSec);
+    if (blockingSection)
+        sections.push(blockingSection);
+    const groupSection = renderSubtable(group, "Your group (subagents / parent / siblings; no mutual block):", nowSec);
+    if (groupSection)
+        sections.push(groupSection);
+    return sections.join("\n\n");
+}
+function byStartedAt(a, b) {
+    return (a.started_at ?? "").localeCompare(b.started_at ?? "");
+}
+function renderSubtable(rows, header, nowSec) {
+    if (rows.length === 0)
+        return "";
+    const first = rows.slice(0, 10).map((r) => formatRow(r, nowSec));
+    const overflow = rows.length > 10 ? `\n  +${rows.length - 10} more` : "";
+    return `${header}\n${first.join("\n")}${overflow}`;
+}
+function formatRow(r, nowSec) {
+    const taskPart = r.task ? ` "${r.task.slice(0, 60)}"` : "";
+    const ageFrom = fmtAge(nowSec - parseIsoSec(r.started_at));
+    const filesPart = fmtFiles(r.display_files);
+    const lastActivity = fmtLastActivity(r, nowSec);
+    const turnSummary = r.turn_summary ? `\n    last turn: ${r.turn_summary.slice(0, 80)}` : "";
+    return `  - agent-${r.name ?? "unknown"}${taskPart}   (${ageFrom}, ${filesPart}${lastActivity})${turnSummary}`;
+}
+function fmtFiles(files) {
+    if (files.length === 0)
+        return "nothing yet";
+    if (files.length <= 3)
+        return `holds: ${files.join(", ")}`;
+    return `holds: ${files.slice(0, 3).join(", ")}, +${files.length - 3} more`;
+}
+function fmtLastActivity(r, nowSec) {
+    if (!r.last_tool)
+        return "";
+    const lastTs = parseIsoSec(r.last_heartbeat ?? r.started_at);
+    const ageSec = nowSec - lastTs;
+    const tail = r.last_tool_target ? ` ${r.last_tool_target.slice(0, 60)}` : "";
+    return `, last: ${r.last_tool}${tail} ${fmtAge(ageSec)}`;
+}
+function parseIsoSec(iso) {
+    if (!iso)
+        return 0;
+    const ms = Date.parse(iso);
+    return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;
+}
+function fmtAge(secs) {
+    if (secs < 60)
+        return `${Math.floor(secs)}s ago`;
+    if (secs < 3600)
+        return `${Math.floor(secs / 60)}m ago`;
+    if (secs < 86400)
+        return `${Math.floor(secs / 3600)}h ago`;
+    return `${Math.floor(secs / 86400)}d ago`;
+}
+/**
+ * Returns a list of wiring issues (empty when everything's wired). Checks
+ * parent core.hooksPath + one representative submodule.
+ */
+export function checkWiring(coordRoot) {
+    const expected = join(coordRoot, "scripts", "hooks");
+    const issues = [];
+    // Parent repo
+    const parentHp = gitConfig(coordRoot, "core.hooksPath");
+    const parentResolved = resolveHooksPath(coordRoot, parentHp);
+    if (parentResolved !== expected) {
+        issues.push(`parent core.hooksPath=${parentHp || "<unset>"} (resolves to ${parentResolved}, expected ${expected})`);
+    }
+    // One representative submodule
+    const gitmodules = join(coordRoot, ".gitmodules");
+    if (existsSync(gitmodules)) {
+        const sampleSub = extractFirstSubmodule(gitmodules);
+        if (sampleSub) {
+            const subPath = join(coordRoot, sampleSub);
+            const subGitDir = join(subPath, ".git");
+            if (existsSync(subGitDir)) {
+                const subHp = gitConfig(subPath, "core.hooksPath");
+                const subResolved = resolveSubmoduleHooksPath(coordRoot, sampleSub, subHp);
+                if (subResolved !== expected) {
+                    issues.push(`submodule ${sampleSub} core.hooksPath=${subHp || "<unset>"} (resolves to ${subResolved}; other submodules likely affected too)`);
+                }
+            }
+        }
+    }
+    return issues;
+}
+function gitConfig(cwd, key) {
+    const result = spawnSync("git", ["-C", cwd, "config", "--get", key], { encoding: "utf8" });
+    if (result.status !== 0)
+        return "";
+    return result.stdout.trim();
+}
+function resolveHooksPath(root, hp) {
+    if (!hp)
+        return join(root, ".git", "hooks");
+    if (hp.startsWith("/"))
+        return hp.replace(/\/$/, "");
+    return join(root, hp).replace(/\/$/, "");
+}
+function resolveSubmoduleHooksPath(root, sub, hp) {
+    if (!hp)
+        return join(root, sub, ".git", "hooks");
+    if (hp.startsWith("/"))
+        return hp.replace(/\/$/, "");
+    return join(root, sub, hp).replace(/\/$/, "");
+}
+function extractFirstSubmodule(gitmodulesPath) {
+    try {
+        const content = readFileSync(gitmodulesPath, "utf8");
+        const match = content.match(/^\s*path\s*=\s*(.+)$/m);
+        return match ? match[1].trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect linked-worktree environment (`git worktree` created from the
+ * superproject) via a `git rev-parse --git-dir` vs `--git-common-dir` check.
+ */
+function isLinkedWorktree(coordRoot) {
+    const dir = spawnSync("git", ["-C", coordRoot, "rev-parse", "--git-dir"], { encoding: "utf8" });
+    const common = spawnSync("git", ["-C", coordRoot, "rev-parse", "--git-common-dir"], {
+        encoding: "utf8",
+    });
+    if (dir.status !== 0 || common.status !== 0)
+        return false;
+    const d = dir.stdout.trim();
+    const c = common.stdout.trim();
+    return d !== "" && c !== "" && d !== c;
+}
+/**
+ * Returns the formatted council invite reminder
+ * (or "" when no councils await input).
+ */
+export function formatPendingCouncils(coordRoot, agentName) {
+    const councilsDir = join(coordRoot, ".harnery", "councils");
+    if (!existsSync(councilsDir))
+        return "";
+    const canonicalName = agentName.startsWith("agent-") ? agentName : `agent-${agentName}`;
+    const pending = [];
+    try {
+        for (const f of readdirSync(councilsDir)) {
+            if (!f.endsWith(".json"))
+                continue;
+            const manifestPath = join(councilsDir, f);
+            try {
+                const m = JSON.parse(readFileSync(manifestPath, "utf8"));
+                if (m.status !== "active" || m.round_status !== "open")
+                    continue;
+                if (!m.members?.includes(canonicalName))
+                    continue;
+                const round = m.current_round ?? 1;
+                const contributionPath = join(councilsDir, m.council_id ?? "", `round-${round}`, `${canonicalName}.md`);
+                if (existsSync(contributionPath))
+                    continue; // already contributed
+                if (m.council_id)
+                    pending.push(m.council_id);
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    catch {
+        /* skip */
+    }
+    if (pending.length === 0)
+        return "";
+    const bin = resolveBinName(coordRoot);
+    const firstThree = pending.slice(0, 3);
+    const tail = pending.length > 3 ? `, +${pending.length - 3} more` : "";
+    const list = firstThree.join(", ") + tail;
+    if (pending.length === 1) {
+        return (`Council waiting on your input: \`${pending[0]}\`. ` +
+            `Run \`${bin} agents council show ${pending[0]}\` for the brief and ` +
+            `\`${bin} agents council contribute ${pending[0]} --message "<your take>"\` to weigh in.`);
+    }
+    return `Councils waiting on your input (${pending.length} open): ${list}. Run \`${bin} agents council list --mine\` to see all of them, then \`${bin} agents council show <id>\` for any brief.`;
+}
+/**
+ * Suppress unused import warning when statSync isn't used in this file
+ * (kept exported for future renderers, e.g. heartbeat-freshness coloring).
+ */
+export const _ensureStatSyncImported = statSync;