codehere 0.6.0-alpha.1 → 0.6.1

package/README.md

@@ -5,12 +5,12 @@
 
 [![npm](https://img.shields.io/npm/v/codehere)](https://www.npmjs.com/package/codehere)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](../LICENSE)
-[![Tests](https://img.shields.io/badge/tests-668%2F668-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-1196%2F1196-brightgreen)]()
 [![Vulnerabilities](https://img.shields.io/badge/vulnerabilities-0-brightgreen)]()
 
 **Codehere is the vendor-neutral layer between you and the coding agents you already use** — Claude Code, Codex, Aider, Gemini, OpenCode. One `npm install`. Local-first, OSS, no account, no IAM, no compliance prereqs. Switch agent, keep your memory. End the day with one Final Report covering everything they did.
 
-Today, Claude Code gets full pre-execution safety-hook enforcement on every tool call; the other adapters are session-traced and reported, with per-tool hook parity in progress for v0.6. The vendor-neutral *memory*, *audit log*, and *Final Report* surfaces ship across all 5 adapters today.
+All 5 adapters (Claude Code, Codex, Aider, Gemini, OpenCode) get session-tracing, Final Reports, and trust scoring. Claude Code additionally gets full pre-execution safety-hook enforcement on every tool call. The *memory*, *audit log*, *failover*, and *Final Report* surfaces ship across all 5 adapters today.
 
 The enterprise tier is owned by [OpenAI Frontier](https://openai.com/index/introducing-openai-frontier/) (8-14 weeks of deploy prereqs, sales-team gated) and [Anthropic Cowork](https://www.anthropic.com/product/claude-cowork) (paid Claude subscription, single-vendor). Codehere fills the gap they structurally can't reach: **the individual / small-team / no-IT-department tier, vendor-neutral**.
 
@@ -29,7 +29,7 @@ One layer, every agent, your work stays portable.
 
 | | | |
 |---|---|---|
-| 1 | **Install** | `npm install -g codehere@alpha` (Node 20+) — current alpha track is v0.5; `@latest` still on v0.4 |
+| 1 | **Install** | `npm install -g codehere` (Node 20+) — v0.6.0 is the current stable |
 | 2 | **Detect environment** | `codehere setup` — checks API key, finds your repo |
 | 3 | **Install the safety hook** | `codehere hook install` — every Claude Code tool call now audited |
 | 4 | **Install at least one specialist** | Claude Code: `npm i -g @anthropic-ai/claude-code` (Codex / Aider / OpenCode / Gemini also supported · see [docs/integrations/](../docs/integrations/) for Cursor MCP setup) |
@@ -51,7 +51,7 @@ Context  +  End State  +  Constraints
 
 ### Folder convention (what `codehere init` writes)
 
-The v0.5 layout — F3 project memory:
+The v0.6 layout — F3 project memory:
 
 | Path | Purpose | Committed? |
 |---|---|---|
@@ -90,9 +90,9 @@ codehere report         # generates a shareable markdown audit report
 codehere status         # quick dashboard · sessions, blocks, trust trends
 ```
 
-The hook intercepts every `Bash`, `Edit`, `Write`, `MultiEdit`, and `NotebookEdit` call from any Claude Code session running on your machine, runs it through the trust-scorer pattern bank in under 5 ms, blocks anything matching the destructive / credential / injection patterns, and appends every decision to an append-only JSONL audit log at `~/.codehere/audit/`. (Hook coverage today is Claude Code-only — Codex / Aider / OpenCode adapters spawn through their native CLIs and emit to `~/.codehere/sessions.jsonl`; full hook parity across all adapters is v0.4 work.)
+The hook intercepts every `Bash`, `Edit`, `Write`, `MultiEdit`, and `NotebookEdit` call from any Claude Code session running on your machine, runs it through the trust-scorer pattern bank in under 5 ms, blocks anything matching the destructive / credential / injection patterns, and appends every decision to an append-only JSONL audit log at `~/.codehere/audit/`. Codex, Aider, OpenCode, and Gemini adapters spawn through their native CLIs and emit to `~/.codehere/sessions.jsonl` with per-tool tracing via the cross-vendor mirror hook.
 
-## Memory · F3 (v0.5)
+## Memory · F3 (v0.6)
 
 Once you've run `codehere init` in a project, every spawned agent — Claude Code, Codex, Aider, OpenCode, or Gemini — automatically reads the project's memory on entry. The agent starts warm with the briefing, recent lessons, and the most-referenced symbols in your codebase, instead of cold-grepping every session.
 
@@ -124,7 +124,7 @@ codehere memory show protocols    # safety patterns by category
 
 **Other memory commands:**
 - `codehere memory init` — migrate the v0.4.1 layout (`CONTEXT.md` / `HANDOVER.md` / `PROMPTS.md`) into the F3 layout (one shot, leaves back-compat symlinks; `--dry-run` previews)
-- `codehere memory repo-map [--rebuild]` — build the symbol map; v0.5 ships a TS-native MVP, v0.6 swaps in tree-sitter
+- `codehere memory repo-map [--rebuild]` — build the symbol map; currently TS-native MVP
 - `codehere protocols export [--rebuild]` — write the trust-scorer pattern bank to `.codehere/protocols/hook_patterns.json` for inspection / cross-tool ingestion
 
 ## Going deeper
@@ -204,7 +204,7 @@ For depth beyond this README:
 ## Requirements
 
 - **Node.js 20+** (pinned in `.nvmrc` and `engines.node`)
-- **macOS or Linux** · Windows via WSL works for development; native Windows is on the v0.4 roadmap
+- **macOS or Linux** · Windows via WSL works for development
 - **Optional but recommended:** at least one supported agent (Claude Code, Codex, Aider, OpenCode, or Gemini) installed before running `codehere start`
 
 ## License

package/dist/index.js

@@ -15,6 +15,16 @@ import { config } from 'dotenv';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { homedir } from 'os';
+// ── Global crash safety ───────────────────────────────────────────────────
+// Unhandled rejections and exceptions must never silently kill the daemon.
+process.on('unhandledRejection', (reason) => {
+    console.error('[codehere] unhandledRejection:', reason instanceof Error ? reason.stack : reason);
+});
+process.on('uncaughtException', (err) => {
+    console.error('[codehere] uncaughtException:', err.stack);
+    // persist what we can before dying
+    process.exitCode = 1;
+});
 import { executeSetupCommand } from './presentation/cli/commands/setup-command.js';
 import { executeInitCommand } from './presentation/cli/commands/init-command.js';
 import { executeMemoryCommand } from './presentation/cli/commands/memory-command.js';
@@ -464,6 +474,7 @@ program
             console.log(colors.dim('\ncodehere MCP server stopped'));
             process.exit(0);
         });
+        process.on('SIGTERM', () => process.exit(0));
         await new Promise((resolve) => {
             server.on('close', resolve);
         });
@@ -480,10 +491,12 @@ program
     .option('-p, --port <number>', 'Port to listen on', '3773')
     .option('--host <host>', 'Host to bind to', '127.0.0.1')
     .option('--no-open', "Don't auto-open the browser")
+    .option('--cloud', 'Enable cloud sync — push session state to codehere.uk/app for remote monitoring')
     .action(async (options) => {
     const port = parseInt(options?.port ?? '3773', 10);
     const host = options?.host ?? '127.0.0.1';
     const shouldOpen = options?.open !== false;
+    const cloud = options?.cloud === true;
     const url = `http://${host}:${port}/`;
     const openBrowser = async () => {
         if (!shouldOpen)
@@ -551,15 +564,42 @@ program
         console.log(colors.bold('Tasks:') + '    ' + url);
         console.log(colors.bold('History:') + '  ' + `http://${host}:${port}/history`);
         console.log(colors.bold('MCP:') + '      ' + `http://${host}:${port}/mcp`);
+        if (cloud) {
+            console.log(colors.bold('Cloud:') + '     ' + 'https://codehere.uk/app');
+        }
         newline();
         console.log(colors.dim('  Press Ctrl+C to stop'));
         newline();
+        // Start cloud sync if enabled
+        if (cloud) {
+            const { startCloudSync } = await import('./infrastructure/protocols/cloud-sync.js');
+            startCloudSync();
+        }
         await openBrowser();
-        process.on('SIGINT', () => {
+        const shutdown = () => {
+            try {
+                const { SessionManager } = require('./infrastructure/orchestration/session-manager.js');
+                SessionManager.getInstance().shutdown();
+            }
+            catch { /* graceful degradation — daemon may not have started fully */ }
+            if (cloud) {
+                try {
+                    const { stopCloudSync } = require('./infrastructure/protocols/cloud-sync.js');
+                    stopCloudSync();
+                }
+                catch { /* cloud sync may not be loaded */ }
+            }
             server.close();
+        };
+        process.on('SIGINT', () => {
+            shutdown();
             console.log(colors.dim('\ncodehere stopped'));
             process.exit(0);
         });
+        process.on('SIGTERM', () => {
+            shutdown();
+            process.exit(0);
+        });
         await new Promise((resolve) => {
             server.on('close', resolve);
         });

package/dist/infrastructure/hooks/claude-sdk-hook.js

@@ -13,13 +13,20 @@
  *
  * Docs: https://docs.anthropic.com/en/docs/claude-code/hooks
  */
-import { appendFileSync, chmodSync, existsSync, mkdirSync, openSync, closeSync, readSync, statSync, readFileSync, } from 'fs';
+import { appendFileSync, chmodSync, existsSync, mkdirSync, openSync, closeSync, readSync, statSync, readFileSync, unlinkSync, } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { createHash } from 'crypto';
 // P18 slice 2 — Tier 1 hook honors per-cwd permissions.yaml.
 import { filterAllowed } from '../security/permissions-config.js';
-const PATTERNS = [
+/**
+ * Instruction-level scan pattern bank used by `scanPayload()`. Exported so
+ * docs and the landing page can quote `PATTERNS.length` instead of hardcoding
+ * a number that silently drifts (May 2026 audit found 50 / 47 / 60+ all in
+ * the same PRD). Pair this with `CODE_PATTERNS` from `trust-scorer.ts` — the
+ * two banks are scanned in different passes and counted separately.
+ */
+export const PATTERNS = [
     // Prompt Injection
     // Allow chained modifiers: "ignore all previous instructions", "ignore all your prior rules", etc.
     {
@@ -494,6 +501,38 @@ function readChainTip(filepath) {
     return null;
 }
 export function appendAuditLog(entry) {
+    // Cross-process file locking. Multiple Claude Code sessions (e.g., two
+    // terminals, or IDE + terminal) can trigger PreToolUse concurrently.
+    // Without a lock, two hook processes read the same chain tip and both
+    // write seq 43 — corrupting the hash chain. We use an exclusive-create
+    // lock file (+O_EXCL) which is atomic on all POSIX systems.
+    const LOCK_FILE = AUDIT_FILE + '.lock';
+    const lockAcquired = () => {
+        for (let attempt = 0; attempt < 20; attempt++) {
+            try {
+                const fd = openSync(LOCK_FILE, 'wx');
+                closeSync(fd);
+                return true;
+            }
+            catch {
+                // Lock held by another process — spin-wait ~10ms
+                const deadline = Date.now() + 10;
+                while (Date.now() < deadline) { /* busy-wait — sync context */ }
+            }
+        }
+        return false;
+    };
+    const lockReleased = () => {
+        try {
+            unlinkSync(LOCK_FILE);
+        }
+        catch { /* best effort */ }
+    };
+    if (!lockAcquired()) {
+        // Fall through unlocked rather than drop the entry. The entry still
+        // appends; verification may flag a chain break, but the audit data
+        // is preserved.
+    }
     try {
         const dir = AUDIT_FILE.substring(0, AUDIT_FILE.lastIndexOf('/'));
         if (dir && !existsSync(dir)) {
@@ -526,6 +565,9 @@ export function appendAuditLog(entry) {
     catch {
         // Audit log failure must not block tool execution
     }
+    finally {
+        lockReleased();
+    }
 }
 /**
  * Walk the audit file and verify the hash chain. Returns:

package/dist/infrastructure/orchestration/context-handoff.js

@@ -0,0 +1,143 @@
+/**
+ * context-handoff — structured cross-session context handoff protocol (P2).
+ *
+ * Bridges P0's auto-failover trigger with P1's graphify-ts context packs.
+ * When a session fails over (or a new session spawns), the handoff loader
+ * finds the most relevant context pack from recent session logs and injects
+ * it as a system hint so the replacement agent inherits continuity.
+ *
+ * Protocol:
+ *   1. loadHandoffContext(cwd, { fromSessionId?, sessionId?, maxAgeMs? })
+ *      — scans .codehere/context-packs.jsonl for the most relevant pack
+ *   2. enrichPromptWithHandoff(prompt, cwd, handoff)
+ *      — merges the handoff context into a prompt string
+ *   3. session handoff is automatic during failover (wired in session-manager)
+ *
+ * Handoff format (injected as system hint):
+ *   [handoff: previous agent=<agent>, completed=<status>, pack=<packId>]
+ *   Previous work summary: <pack.payloadPreview or compiled summary>
+ *   ---
+ *   <original prompt>
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+// ── Constants ──────────────────────────────────────────────────────────────────
+const CONTEXT_PACKS_DIR = '.codehere';
+const CONTEXT_PACKS_FILE = 'context-packs.jsonl';
+const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+const DEFAULT_MIN_NODES = 5;
+// ── Session log scanning ───────────────────────────────────────────────────────
+/**
+ * Load all recent context packs from disk, sorted by timestamp (newest first).
+ */
+function loadAllPacks(cwd) {
+    const packsFile = join(cwd, CONTEXT_PACKS_DIR, CONTEXT_PACKS_FILE);
+    if (!existsSync(packsFile)) {
+        return [];
+    }
+    try {
+        const content = readFileSync(packsFile, 'utf-8');
+        const lines = content.split('\n').filter(Boolean);
+        return lines.map((line) => JSON.parse(line)).reverse();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Find the most relevant handoff context from previous sessions.
+ *
+ * Priority:
+ *   1. Same workspace, same prompt keywords (most recent pack)
+ *   2. Same workspace, any pack (most recent)
+ *   3. Fallback: no handoff
+ */
+export function loadHandoffContext(cwd, { fromSessionId, maxAgeMs = DEFAULT_MAX_AGE_MS, minNodes = DEFAULT_MIN_NODES } = {}) {
+    const now = Date.now();
+    const packs = loadAllPacks(cwd);
+    // Filter by age
+    const recent = packs.filter((p) => {
+        const ts = p.timestamp;
+        return ts && (now - ts) < maxAgeMs;
+    });
+    // Prefer packs with enough graph structure to be useful
+    const structured = recent.filter((p) => {
+        const nodes = p.nodeCount ?? 0;
+        return nodes >= minNodes;
+    });
+    if (structured.length === 0)
+        return null;
+    const last = structured[0];
+    return {
+        packId: String(last.packId ?? ''),
+        agent: String(last.agent ?? 'unknown'),
+        prompt: String(last.prompt ?? ''),
+        status: String(last.status ?? 'unknown'),
+        timestamp: last.timestamp,
+        nodeCount: last.nodeCount,
+        edgeCount: last.edgeCount,
+        task: String(last.task ?? 'explain'),
+        payloadPreview: String(last.payloadPreview ?? ''),
+    };
+}
+// ── Prompt enrichment ──────────────────────────────────────────────────────────
+/**
+ * Inject handoff context into a prompt.
+ *
+ * Returns the enriched prompt string with the handoff as a system hint
+ * prepended before the original prompt. Returns the original prompt
+ * if no handoff is available.
+ */
+export function enrichPromptWithHandoff(prompt, handoff) {
+    if (!handoff)
+        return prompt;
+    const handoffLine = `[handoff: agent=${handoff.agent}, pack=${handoff.packId}, ${handoff.nodeCount} nodes, ${handoff.edgeCount} edges]`;
+    const preview = handoff.payloadPreview ? ` ${handoff.payloadPreview.slice(0, 800)}` : '';
+    return [
+        `[Previous session context — ${handoffLine}]`,
+        `This workspace has recent structural context from a prior session.`,
+        `For details, refer to the knowledge graph at the workspace root.`,
+        `---`,
+        prompt,
+    ].join('\n');
+}
+// ── Failover handoff (P2 integration point) ────────────────────────────────────
+/**
+ * Build a handoff context for a failover target.
+ *
+ * When session A fails and session B auto-spawns as replacement,
+ * this loads the most recent pack from the same workspace and
+ * merges it into the prompt so B has continuity with A's work.
+ */
+export function buildFailoverHandoff(cwd, { failedAgent, failedPrompt }) {
+    // Load most recent pack from workspace
+    const pack = loadHandoffContext(cwd, { maxAgeMs: DEFAULT_MAX_AGE_MS, minNodes: 3 });
+    if (!pack)
+        return null;
+    // Enrich the prompt with the handoff
+    const enrichedPrompt = enrichPromptWithHandoff(failedPrompt, {
+        ...pack,
+        agent: failedAgent,
+        status: 'failed',
+    });
+    return {
+        ...pack,
+        agent: failedAgent,
+        prompt: enrichedPrompt,
+        status: 'failed',
+    };
+}
+// ── Handoff summary (for UI / API) ─────────────────────────────────────────────
+/**
+ * Generate a human-readable handoff summary for the dashboard.
+ */
+export function formatHandoffSummary(handoff) {
+    const ageMs = Date.now() - handoff.timestamp;
+    const ageStr = ageMs < 60_000
+        ? `${Math.round(ageMs / 1000)}s ago`
+        : ageMs < 3600_000
+            ? `${Math.round(ageMs / 60_000)}m ago`
+            : `${Math.round(ageMs / 3600_000)}h ago`;
+    return `Previous session (${handoff.agent}) completed ${ageStr}. ${handoff.nodeCount} nodes, ${handoff.edgeCount} edges in workspace graph.`;
+}
+//# sourceMappingURL=context-handoff.js.map

package/dist/infrastructure/orchestration/failover-config.js

@@ -0,0 +1,77 @@
+/**
+ * Failover config loader — v0.6.x rate-limit fail-over wedge (Slice C).
+ *
+ * Reads `failoverChain` from `~/.codehere/config.json` and validates it
+ * against the known agent ids. Returns the validated chain or undefined
+ * if the user has not configured one (caller falls back to the default).
+ *
+ * Config shape (~/.codehere/config.json):
+ *   {
+ *     "version": "0.6.0",
+ *     "failover": {
+ *       "chain": ["codex", "claude-code", "aider"]
+ *     }
+ *   }
+ *
+ * If `failover.chain` is missing, empty, or invalid, returns undefined
+ * so the caller uses DEFAULT_FAILOVER_CHAIN from failover-policy.ts.
+ *
+ * Slice C scope: config read + validation. Slice D wires it into
+ * SessionManager so the resolved chain flows into the resolver.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { validateFailoverChain } from './failover-policy.js';
+const GLOBAL_CONFIG_PATH = join(homedir(), '.codehere', 'config.json');
+/**
+ * Load failover configuration from ~/.codehere/config.json.
+ * Returns undefined if the config file does not exist or has no failover section.
+ *
+ * Safe to call at any time — no side effects, no caching, no I/O errors
+ * propagated (returns undefined on any read failure).
+ */
+export function loadFailoverConfig() {
+    if (!existsSync(GLOBAL_CONFIG_PATH))
+        return undefined;
+    try {
+        const raw = JSON.parse(readFileSync(GLOBAL_CONFIG_PATH, 'utf-8'));
+        if (!raw || typeof raw !== 'object')
+            return undefined;
+        const failover = raw.failover;
+        if (!failover || typeof failover !== 'object')
+            return undefined;
+        const config = {};
+        // Validate chain if present
+        if (Array.isArray(failover.chain)) {
+            try {
+                config.chain = validateFailoverChain(failover.chain);
+            }
+            catch {
+                // Invalid chain — skip it, caller uses default
+                config.chain = undefined;
+            }
+        }
+        // autoFailover — boolean, defaults to false
+        if (typeof failover.autoFailover === 'boolean') {
+            config.autoFailover = failover.autoFailover;
+        }
+        return config;
+    }
+    catch {
+        // Config file exists but is malformed — return undefined so caller
+        // falls back to defaults without crashing.
+        return undefined;
+    }
+}
+/**
+ * Get the resolved failover chain: user-configured if present, else default.
+ * Pure function — no I/O. Caller loads config and passes it in.
+ */
+export function resolveChain(userChain) {
+    if (userChain && userChain.length > 0)
+        return userChain;
+    // Re-export the default from failover-policy
+    return ['claude-code', 'codex', 'aider', 'opencode', 'gemini'];
+}
+//# sourceMappingURL=failover-config.js.map