@pcircle/memesh 4.7.3 → 4.8.1

package/docs/platforms/agent-messaging.md

@@ -0,0 +1,290 @@
+# Local Agent Messaging Guide
+
+MeMesh provides two complementary collaboration surfaces on one machine:
+
+- shared durable memory, including the `team` namespace, for knowledge, decisions, and coarse handoffs;
+- the `message` tool for explicit durable messages to one named recipient on the same MeMesh instance.
+
+The messaging path is durable store-and-forward. For an explicitly configured,
+active local Codex CLI session, MeMesh queues a metadata-only native wakeup;
+the session then fetches the durable payload through the scoped `message`
+operation. SQLite remains the audit and recovery authority. `poll`/`watch` are
+compatibility and diagnostic APIs, not the normal delivery loop for that active
+Codex path. A queue admission or `host_accept` is not proof that an agent read
+the payload, acknowledged it, or accepted the work.
+
+## One-time owner-private local-host setup
+
+Native delivery is optional and local to one Unix account. Do this setup once
+for the account that owns both the MeMesh database and the active host
+sessions; do not place router tokens or host config in a repository, shared
+dotfile, or world-readable temp directory.
+
+Each configured host connection attempts to start the packaged router and
+retries when its owner-private socket is absent or refused. You can also start
+the router yourself when you want to inspect it directly; it creates an
+owner-private token and socket beside the active MeMesh database on first
+start:
+
+```bash
+umask 077
+memesh-router
+```
+
+If you start it yourself, leave that process running. In a second terminal,
+verify only the installed adapter imports and the live router socket separately:
+
+```bash
+MEMESH_DOCTOR_PROBE_MESSAGE_CAPABILITY=1 memesh doctor
+MEMESH_DOCTOR_PROBE_MESSAGE_ROUTER=1 memesh doctor
+```
+
+The first command proves the installed MCP schema and adapter imports. The
+second only proves that the owner-private router socket accepts a connection.
+Neither command starts or registers a host, sends a message, proves
+`host_accept`, or wakes a stopped session.
+In particular, a socket check does not start the host it observes.
+
+The secure host-native router and adapter runtime currently supports macOS and
+Linux. Windows remains supported for core MeMesh memory, durable message
+storage, and MCP tools, but host-native wakeup fails closed before creating
+credentials, configuration, IPC listeners, or managed child processes.
+
+Create one reusable owner-private config for each local path and principal.
+The stable principal is the logical recipient. Managed processes generate a
+fresh exact session identity; the ordinary Codex path instead uses the Codex
+thread identity supplied at SessionStart. No thread ID is copied by hand.
+Ordinary sessions outside the explicit `codex-session` workspace opt-in remain
+`presence-only/inbound-unavailable`.
+
+```bash
+memesh agent setup codex-session --project my-project --principal codex-reviewer --workspace "$PWD"
+memesh agent setup codex --project my-project --principal codex-reviewer --workspace "$PWD"
+memesh agent setup claude --project my-project --principal claude-reviewer
+```
+
+### Ordinary active Codex CLI session
+
+`codex-session` is the opt-in path for an ordinary local Codex session and
+requires the MeMesh Codex plugin to be installed and enabled so Codex loads
+the packaged SessionStart hook. Run
+the setup command from the exact workspace that Codex will use; it stores the
+configured real workspace and stable principal in the owner-private
+`codex-session.json` config. Restart Codex in that workspace after setup.
+
+On `SessionStart` for `startup` or `resume`, the asynchronous companion checks
+the Codex thread identity, hook session identity, and configured workspace
+realpath before it connects to the router. A missing identity, a different
+workspace, compact lifecycle input, or a failed/disconnected connection does
+not register a host and does not wake anything.
+
+For a registered session, MeMesh invokes `codex queue` with a
+`memesh_message_available` marker containing only the project, recipient,
+target kind, message ID, and delivery ID. The message payload stays in the
+durable MeMesh inbox. Codex must then use the `message` tool to `fetch` that
+same project/recipient/target/message scope. The persisted `host_accept` means
+only that the local Codex queue accepted the marker; it is neither payload
+readback nor an `ack` or workflow disposition.
+
+If the configured Codex session is stopped, missing, disconnected, or no
+longer matches its configured workspace, MeMesh does not start or replace it.
+The durable inbox and its receipt history remain available to scoped fetch,
+cursor recovery, `poll`, or `memesh message watch` for audit and diagnosis.
+
+### Separate: MeMesh-managed Codex app-server runner
+
+```bash
+memesh-host-codex --config "$HOME/.memesh/hosts/codex.json"
+```
+
+This is separate from `codex-session`: it starts a MeMesh-owned `codex
+app-server`, creates its own thread through the private Unix/WebSocket control
+path, and registers only after that thread is ready. It does not attach to an
+ordinary Codex session. Message content never appears in MeMesh or Codex
+process arguments.
+
+### Claude channel runner
+
+Run the printed `registration_command` once to add `memesh-channel` as a
+user-scoped stdio MCP server. Claude owns that process for the session:
+
+```bash
+claude mcp add --transport stdio --scope user memesh-channel -- \
+  memesh-host-claude --config "$HOME/.memesh/hosts/claude.json"
+```
+
+Claude Channels is an upstream research-preview opt-in. Custom channels are
+not on Anthropic's approved allowlist, so start every participating Claude
+session with the printed launch command and confirm the local-development
+warning:
+
+```bash
+claude --dangerously-load-development-channels server:memesh-channel
+```
+
+Without that flag Claude may initialize the ordinary MCP transport while
+silently dropping channel events; a MeMesh `host_accept` then proves only that
+the notification was written to stdio, not that Claude admitted it. With the
+channel admitted, initialization creates and registers the exact MeMesh
+session automatically; EOF, MCP close, or normal signals unregister it.
+
+### Experimental ACP runner (not release-gated)
+
+An internal generic ACP runner remains an experimental adapter surface. No ACP
+provider is documented as a supported native-wakeup path here; protocol or
+process readiness alone is not proof that a provider accepted a message.
+
+The managed Codex app-server and Claude channel paths deliver only while their
+configured target is active and registered. If it is stopped, missing, disconnected, or replaced, MeMesh keeps the durable message but does not start
+the host, recreate the session, or silently redirect an exact-session target.
+A later eligible managed-principal registration drains only post-activation
+pending work; an exact-session target never moves to a replacement. Manual
+cursor reads remain available for audit and diagnostics, not as a requirement
+for active Codex-session delivery.
+
+## What Works Today
+
+- MCP, HTTP, and CLI use the same message lifecycle and SQLite system of record.
+- `send` creates one canonical message, recipient delivery, and payload-free notification event under an idempotency key.
+- `poll` and `memesh message watch` return only events for the exact project and recipient. They are compatibility and diagnostic paths; the opaque cursor can be persisted and reused after a timeout, dropped hint, duplicate delivery, or process restart.
+- `fetch` returns the payload only to the named recipient and matching `target_kind` in the named project. Exact-session messages require `target_kind=session`; polling and fetching do not acknowledge the message.
+- `intake`, `ack`, `disposition`, and `activation` are explicit, separate, idempotent receipt facts. Inbox/MCP ACK is valid without a host-native acceptance; host-native ACK remains bound to its `host_accept`. `receipts` returns one ordered projection and identifies each underlying fact source. For example, `manual_resume_required` does not imply ACK, acceptance, rejection, cancellation, or completion.
+- The transport, rather than model-provided payload data, records sender-host provenance.
+
+## Identity and lifecycle
+
+A **principal** is the stable logical recipient. A **session** is one live host connection for that principal. A **generation** changes when that session is replaced. An exact-session target never reroutes. A principal target can deliver only to an eligible active session after its activation checkpoint; it does not replay historical inbox contents into a first session.
+
+Persistence, dispatch attempt, host acceptance, intake, acknowledgement,
+workflow disposition, retention, and presence are independent state axes. An
+active configured Codex session receives a host-native metadata marker without
+polling. A stopped, missing, busy beyond its queue limit, disconnected, or
+unsupported session is not awakened, resumed, or replaced; durable state
+remains available for audit and recovery, subject to exact-session and
+activation-checkpoint rules.
+
+## Bounded storage and audit retention
+
+Message payload growth is observable and owner-controlled. MeMesh never deletes
+unresolved, unacknowledged, retryable, or offline-pending messages to satisfy a
+limit. Inspect logical payload bytes, protected rows, SQLite reusable pages,
+and main/WAL file sizes with an explicit policy cutoff:
+
+```bash
+memesh message storage report --cutoff 2026-08-01T00:00:00Z
+```
+
+Preview one bounded batch of old terminal payloads; nothing changes without
+`--apply`:
+
+```bash
+memesh message storage prune --cutoff 2026-08-01T00:00:00Z --batch-size 100
+memesh message storage prune --cutoff 2026-08-01T00:00:00Z --batch-size 100 --apply
+```
+
+Applied pruning replaces only payload content whose every delivery has an
+explicit ACK and a terminal workflow disposition older than the cutoff with a hash-bound
+tombstone. Message identity, routing, receipts, ACK, workflow, presence, and
+retention audit facts remain queryable. Freed SQLite pages become reusable;
+the main database file is a high-watermark and is not promised to shrink.
+Full `VACUUM` is never run by a hook or this bounded command.
+
+An owner may set `MEMESH_AGENT_MESSAGE_STORAGE_QUOTA_BYTES` to a non-negative
+integer. This is a hard **logical payload** budget, not a whole SQLite file or
+disk quota. The canonical send transaction checks it before inserting any
+message effect; an over-quota send returns `storage_quota_exceeded` and leaves
+no partial message, delivery, event, idempotency, dispatch, or receipt row.
+Metadata, indexes, append-only audit facts, reusable pages, and WAL bytes still
+consume disk and remain visible in the report; keep separate filesystem
+headroom and monitoring. Heartbeats refresh the connection lease in place;
+they do not append one audit row every interval. Connected, disconnected, and
+superseded transitions remain auditable. There is deliberately no default
+quota or automatic retention policy.
+
+## Local and Cloud boundary
+
+This guide describes only one local MeMesh instance: its SQLite durable event
+store and same-machine host-native input. Remote and cross-machine transport is
+the responsibility of MeMesh Cloud and requires its own verified relay; Cloud
+state is not evidence that this local host received a marker. A native marker,
+persistence, or fetch does not promise exactly-once cognition, a reply, or a
+stopped-session wake-up.
+
+## What This Is Not Yet
+
+- Not universal host support or stopped-session resume. This document only
+  describes the explicitly configured ordinary Codex path and the separate
+  managed Codex/Claude paths above.
+- Not topic, broadcast, lease/claim, or TTL routing. The current delivery target is one exact recipient.
+- Not arbitrary external-user access or cross-machine delivery. A local MeMesh instance is not a public collaboration service.
+- Not permission to execute payload content. The receiving host must apply its own policy and required human approval.
+
+## Support Matrix
+
+| Participant | Current path | Status today | Notes |
+|---|---|---|---|
+| Ordinary Codex CLI | `codex-session` owner-private opt-in | metadata-only native wakeup while active | Exact workspace, principal, and SessionStart identity must match; stopped or disconnected sessions are not awakened |
+| MeMesh-managed Codex app-server | `memesh-host-codex` | separate managed path | It creates its own Codex thread; it does not attach to an ordinary session |
+| Claude channel | `memesh-host-claude` | separate channel path | Requires the documented Channel opt-in; no stopped-session resume |
+| Other local MCP clients | MCP, HTTP, or CLI message operations | durable messaging only | Use `poll`/`watch` and scoped fetch where their own host loop supports it; this guide makes no native-wakeup claim |
+
+## Lifecycle
+
+1. A sender calls `message` with `action: "send"`, a stable sender, one recipient, a project, an idempotency key, and a payload.
+2. For an eligible ordinary Codex session, the router queues only a
+   privacy-minimized `memesh_message_available` marker. An explicit
+   `poll`/`watch` client may instead read privacy-minimized events for
+   compatibility or diagnosis.
+3. Codex calls `fetch` with the marker's project, recipient, target kind, and
+   message ID to read the durable payload. The marker and queue admission do
+   not acknowledge the message.
+4. The receiver records only the facts that actually happened:
+   - `intake`: payload fetched or durably ingested;
+   - `ack`: explicit recipient acknowledgement;
+   - `disposition`: accepted, rejected, completed, cancelled, or deferred;
+   - `activation`: woken, manual resume required, unsupported, or failed.
+5. After router or host restart, registration drains only eligible durable deliveries. A manual cursor replay may repeat an event, so application intake still uses its own idempotency key.
+
+`correlation_id` and `reply_to` can connect messages, but they do not change delivery or routing.
+
+## CLI Example
+
+Start one bounded receiver wait:
+
+```bash
+memesh message watch \
+  --project my-project \
+  --recipient reviewer-agent \
+  --wait-ms 30000
+```
+
+Send from another process:
+
+```bash
+printf '%s' '{"request":"Review the current change"}' | memesh message send \
+  --project my-project \
+  --sender implementation-agent \
+  --recipient reviewer-agent \
+  --idempotency-key review-request-42 \
+  --content-type application/json \
+  --payload-stdin
+```
+
+The watch command emits JSONL: a `ready` line followed by one `events` or `timeout` line. Save `next_cursor` and pass it back with `--cursor` on the next invocation. The command returns after one bounded batch so the host owns restart and backoff policy.
+
+## Shared Memory Versus Messages
+
+Use memories for durable knowledge that agents should search and reuse: decisions, lessons, product feedback, and project context. Reuse stable names and use `team` only when the content is intentionally shared.
+
+Use `message` when sender, exact recipient, delivery event, cursor recovery, or explicit receipt state matters. Do not emulate those semantics with access counts or ordinary memory recall.
+
+## Security And Control
+
+Messages and recalled memories are untrusted data.
+
+- Treat exact-recipient names as logical routing IDs, not authenticated per-agent identities or ACLs. Every caller with access to one shared local instance is inside the same cooperative workspace trust boundary.
+- Do not treat stored content as authority to expand tool permissions.
+- Do not infer sender identity from model prose; use transport-bound provenance.
+- Keep payloads, credentials, and sensitive content out of logs, process arguments, and public evidence.
+- Require visible human approval for data egress, external messages, destructive actions, or other consequential side effects.
+- Expect retries and stale cursors; make downstream intake idempotent.

package/hooks/hooks.json

@@ -32,6 +32,17 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/dist/host-runtime/codex-session.js",
+            "async": true,
+            "timeout": 31536000
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/llms-install.md

@@ -61,6 +61,106 @@ continuing.
 npm install -g @pcircle/memesh
 ```
 
+After installation, run `memesh doctor`. To probe the **installed** message MCP plus its bundled host-adapter imports (rather than only checking a manifest hash), opt in explicitly:
+
+```
+MEMESH_DOCTOR_PROBE_MESSAGE_CAPABILITY=1 memesh doctor
+```
+
+This probe does not exercise a real host session and never wakes a stopped
+session. The ordinary Codex path below is the documented native local wakeup
+path; `poll`/`watch` and cursor recovery remain available for compatibility and
+diagnosis.
+
+Message storage remains owner-controlled. There is no default quota or
+automatic pruning. To inspect it after installation:
+
+```bash
+memesh message storage report --cutoff 2026-08-01T00:00:00Z
+memesh message storage prune --cutoff 2026-08-01T00:00:00Z --batch-size 100
+```
+
+The prune command is a dry-run unless `--apply` is supplied. Only old terminal
+payload content is tombstoned; unresolved/offline-pending messages and all
+lifecycle audit facts are preserved. Set an explicit hard quota for all send
+transports with `MEMESH_AGENT_MESSAGE_STORAGE_QUOTA_BYTES=<bytes>`; an
+over-quota send is rejected atomically.
+
+### Optional: one-time local host setup
+
+This is separate from MCP setup. It is for the owner of an active local Codex
+session, a MeMesh-managed Codex app-server, or a Claude channel. Keep all
+files private to that Unix account; do not commit the token or config files.
+This secure host-native runtime currently supports macOS and Linux. Windows
+can still use core MeMesh, durable messages, and MCP tools, but not this
+host-native wakeup path.
+
+Each configured host connection starts the packaged router and retries its
+connection when the owner-private socket is absent or refused. Start the router
+yourself only when you want to inspect the socket directly:
+
+```bash
+umask 077
+memesh-router
+```
+
+If you start it yourself, it creates `agent-router.sock` and `agent-router.token` beside the active
+MeMesh database (normally `~/.memesh/`) with owner-private permissions. Check
+the installed adapter imports and the live socket as distinct facts:
+
+```bash
+MEMESH_DOCTOR_PROBE_MESSAGE_CAPABILITY=1 memesh doctor
+MEMESH_DOCTOR_PROBE_MESSAGE_ROUTER=1 memesh doctor
+```
+
+The router probe does not register a host, send content, or wake a stopped
+session. Generate reusable `0600` configs; session identities are not copied
+from an active ordinary session.
+
+For an ordinary active local Codex session, first install and enable the MeMesh
+Codex plugin (Option A), which supplies the packaged SessionStart hook. Then
+run this from the exact workspace you want to configure and restart Codex in
+that same workspace:
+
+```bash
+memesh agent setup codex-session --project my-project --principal codex-recipient --workspace "$PWD"
+```
+
+This stores the configured workspace realpath and principal in
+`~/.memesh/hosts/codex-session.json`. On `SessionStart` (`startup` or
+`resume`), an asynchronous companion registers only when its Codex thread ID,
+hook session ID, and workspace realpath match that config. It receives no
+message payload. Instead, an active registered session receives a
+metadata-only `memesh_message_available` queue marker with routing identifiers,
+then uses the scoped `message` `fetch` operation to read the durable payload.
+
+`host_accept` records only that the local Codex queue accepted that marker. It
+does not prove an agent read the payload, acknowledged it, or accepted the
+work. If the session is stopped, missing, disconnected, or in another
+workspace, MeMesh neither starts nor replaces it; the durable inbox remains
+available to scoped fetch, cursor recovery, `poll`, and `memesh message watch`
+for audit and diagnosis.
+
+The following are separate managed-host paths:
+
+```bash
+memesh agent setup codex --project my-project --principal codex-recipient --workspace "$PWD"
+memesh-host-codex --config "$HOME/.memesh/hosts/codex.json"
+
+memesh agent setup claude --project my-project --principal claude-recipient
+# Run the printed `registration_command` (`claude mcp add ... memesh-host-claude ...`) once.
+# Start each participating session with the printed research-preview launch command:
+claude --dangerously-load-development-channels server:memesh-channel
+```
+
+The managed Codex runner owns its app-server and thread; Claude owns its
+Channel MCP child. Neither is the ordinary Codex-session path, and neither
+attaches to, resumes, or replaces an ordinary stopped host. When no active
+registration exists, the message remains durable with no false dispatch or
+host acceptance. The package also contains the experimental
+`memesh-host-acp` binary for protocol development, but no ACP provider is a
+documented native-wakeup integration here.
+
 Expected: exits without error; `memesh`, `memesh-mcp` and `memesh-http` are
 now in `$(npm prefix -g)/bin/`. No compiler is involved and no install script
 runs.
@@ -113,31 +213,7 @@ Expected: `memesh` is listed as enabled.
 | `memesh` absent from the list | The add did not persist. Re-run `codex mcp add memesh -- memesh-mcp` and re-check. |
 | Listed, but tool calls fail | Run `command -v memesh-mcp`. Empty output means section 2 is incomplete or PATH is wrong — fix per section 2's table. |
 
-## 4. Gemini CLI
-
-Prerequisite: section 2 — `memesh-mcp` must resolve on PATH.
-
-```
-gemini mcp add -s user memesh memesh-mcp
-```
-
-`-s user` registers at user scope, so it works from every folder.
-
-**Verify**:
-
-```
-gemini mcp list
-```
-
-Expected: `memesh` shows **Connected**.
-
-| Failure | Remedy |
-|---|---|
-| `command not found: gemini` | Gemini CLI itself is not installed — out of scope here; install it first, then re-run the add. |
-| Shows Disconnected | Run `command -v memesh-mcp`. Empty output means section 2 is incomplete or PATH is wrong — fix per section 2's table, then re-run `gemini mcp list`. |
-| `memesh` absent from the list | The add was made in a different scope or did not persist. Re-run `gemini mcp add -s user memesh memesh-mcp`. |
-
-## 5. Cursor
+## 4. Cursor
 
 Prerequisite: section 2 — `memesh-mcp` must resolve on PATH.
 

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@pcircle/memesh",
-  "version": "4.7.3",
+  "version": "4.8.1",
   "description": "MeMesh — agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
     "memesh": "dist/transports/cli/cli.js",
     "memesh-mcp": "dist/mcp/server.js",
-    "memesh-http": "dist/transports/http/server.js"
+    "memesh-http": "dist/transports/http/server.js",
+    "memesh-router": "dist/host-runtime/router.js",
+    "memesh-host-claude": "dist/host-runtime/claude.js",
+    "memesh-host-codex": "dist/host-runtime/codex.js",
+    "memesh-host-codex-session": "dist/host-runtime/codex-session.js",
+    "memesh-host-acp": "dist/host-runtime/acp.js"
   },
   "files": [
     "dist/",
@@ -17,6 +22,7 @@
     "scripts/hooks/",
     "scripts/upgrade-plugin.sh",
     "skills/",
+    "docs/platforms/agent-messaging.md",
     ".claude-plugin/",
     "README.md",
     "LICENSE",
@@ -29,10 +35,11 @@
     "test": "vitest",
     "test:e2e-dashboard": "node scripts/dashboard-e2e-smoke.mjs",
     "test:packaged": "node scripts/smoke-packed-artifact.mjs",
+    "test:packaged:upgrade": "node scripts/smoke-packed-upgrade.mjs",
     "audit:prod": "node scripts/check-consumer-audit.mjs",
-    "verify:release": "npm run lint && npm run typecheck && node scripts/check-version-coherence.mjs && node scripts/check-generated-mirror.mjs && node scripts/check-doc-claims.mjs && node scripts/audit/verification-audit.mjs && npm run audit:prod",
+    "verify:release": "npm run lint && npm run typecheck && node scripts/check-version-coherence.mjs && node scripts/check-generated-mirror.mjs && node scripts/check-agent-message-sync.mjs && node scripts/check-readme-tool-parity.mjs && node scripts/check-doc-claims.mjs && node scripts/audit/verification-audit.mjs && npm run audit:prod",
     "release:finish": "node scripts/finish-release.mjs",
-    "prepublishOnly": "npm run build && npm run verify:release && npm run test:isolated && npm run test:packaged",
+    "prepublishOnly": "npm run build && npm run verify:release && npm run test:isolated && npm run test:packaged && npm run test:packaged:upgrade",
     "typecheck": "tsc -p tsconfig.check.json && tsc -p tsconfig.check-dashboard.json",
     "lint": "eslint src/ scripts/ tests/ dashboard/src/ --max-warnings 0",
     "lint:fix": "eslint src/ scripts/ tests/ dashboard/src/ --fix",
@@ -69,6 +76,7 @@
     "express": "^5.2.1",
     "express-rate-limit": "8.5.1",
     "sqlite-vec": "^0.1.9",
+    "ws": "^8.21.3",
     "zod": "4.4.3"
   },
   "overrides": {
@@ -83,7 +91,7 @@
     "protobufjs": "^7.6.5",
     "qs": "^6.15.3",
     "sharp": "^0.35.3",
-    "ws": "^8.21.1",
+    "ws": "$ws",
     "vite": "7.3.6"
   },
   "devDependencies": {
@@ -93,6 +101,7 @@
     "@testing-library/preact": "^3.2.4",
     "@types/express": "^5.0.6",
     "@types/node": "25.6.2",
+    "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "4.1.5",
     "eslint": "^10.3.0",
     "happy-dom": "^20.9.0",

package/scripts/hooks/_generated/repo-state.js

@@ -0,0 +1,77 @@
+// ============================================================================
+// AUTO-GENERATED from src/core/repo-state.ts — DO NOT EDIT BY HAND.
+// Regenerate with: npm run build  (scripts/generate-hook-core.mjs)
+//
+// Claude Code hooks import this committed copy instead of dist/, so the
+// always-on capture path survives a missing or stale dist/ while staying
+// byte-locked to core — eliminating the hand-mirror drift behind the P0 FTS bug.
+// ============================================================================
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+const GIT_TIMEOUT_MS = 5000;
+function tryGit(cwd, args) {
+    try {
+        return execFileSync('git', ['-C', cwd, ...args], {
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function declaredVersionOf(repoRoot) {
+    try {
+        const raw = fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8');
+        const version = JSON.parse(raw).version;
+        return typeof version === 'string' && version.length > 0 ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readRepoState(cwdInput) {
+    const cwd = cwdInput && cwdInput.length > 0 ? cwdInput : process.cwd();
+    const repoRoot = tryGit(cwd, ['rev-parse', '--show-toplevel']);
+    if (!repoRoot)
+        return null;
+    const branchRaw = tryGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const branch = branchRaw && branchRaw !== 'HEAD' ? branchRaw : null;
+    const statusOut = tryGit(cwd, ['status', '--porcelain']);
+    const uncommitted = statusOut ? statusOut.split('\n').filter(l => l.trim() !== '').length : 0;
+    const lastTag = tryGit(cwd, ['describe', '--tags', '--abbrev=0']);
+    let commitsSinceTag = null;
+    if (lastTag) {
+        const count = tryGit(cwd, ['rev-list', '--count', `${lastTag}..HEAD`]);
+        const parsed = count === null ? Number.NaN : Number.parseInt(count, 10);
+        commitsSinceTag = Number.isFinite(parsed) ? parsed : null;
+    }
+    const declaredVersion = declaredVersionOf(repoRoot);
+    let declaredVersionIsTagged = null;
+    if (declaredVersion) {
+        const hit = tryGit(cwd, ['tag', '--list', `v${declaredVersion}`]);
+        declaredVersionIsTagged = hit === null ? null : hit.length > 0;
+    }
+    return { branch, uncommitted, lastTag, commitsSinceTag, declaredVersion, declaredVersionIsTagged };
+}
+export function repoStateLines(state) {
+    if (!state)
+        return [];
+    const first = [];
+    if (state.branch)
+        first.push(`branch ${state.branch}`);
+    first.push(state.uncommitted === 0 ? 'working tree clean' : `${state.uncommitted} uncommitted`);
+    const lines = ['Where the repository actually stands (read just now):', `- ${first.join(' · ')}`];
+    if (state.lastTag) {
+        const since = state.commitsSinceTag;
+        lines.push(since === null ? `- last tag ${state.lastTag}`
+            : since === 0 ? `- at tag ${state.lastTag}`
+                : `- ${since} commit${since === 1 ? '' : 's'} since ${state.lastTag}`);
+    }
+    if (state.declaredVersion && state.declaredVersionIsTagged === false) {
+        lines.push(`- package.json declares ${state.declaredVersion}, which has no tag yet`);
+    }
+    return lines;
+}