overarch-linux-x64 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yatharth Roy, The Thursday AI Company of New Delhi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# Overarch CLI v0.5.0
+
+> **The Learning Agent for Autonomous Software Engineering**  
+> *Understand • Investigate • Plan • Execute • Verify • Learn*  
+> **2026 Made By Yatharth Roy, From The Thursday AI Company of New Delhi**
+
+Overarch CLI is an autonomous, terminal-native AI coding agent built for real-world software engineering. Designed with senior-developer minimalism and strict human control, Overarch operates directly inside your terminal, learning from its mistakes and compounding engineering knowledge over time.
+
+---
+
+## What's New in v0.5.0 ("The Learning Agent")
+
+- **Terminal-Native Focus**: All web servers and webviews have been eliminated. Overarch CLI is 100% focused on the terminal developer experience.
+- **Persistent Learning Engine (`src/learning/`)**:
+  - **Project Memory (`.overarch/memory/project.json`)**: Tracks architecture notes, conventions, build/test commands, and tech stacks.
+  - **User Memory (`~/.overarch/user_memory.json`)**: Remembers user coding preferences, workflows, and stylistic rules.
+  - **Episodic Lessons (`.overarch/memory/lessons.json`)**: Automatically captures problem ➔ investigation ➔ resolution ➔ lesson whenever self-corrections or user insights occur.
+  - **Selective Prompt Injection**: Never blindly dumps memory. Retrieves token-budgeted, query-relevant context for each task.
+  - **Learning Commands**: `overarch memory show`, `overarch memory search <query>`, `overarch memory forget <id>`, `overarch learn "<lesson>"`.
+- **Claude-Like Contextual Thinking**:
+  - Dynamic thinking spinner with progressive adjectives:
+    `*Analyzing repository architecture...*`, `*Synthesizing change impact...*`, `*Investigating code paths...*`, `*Deliberating implementation plan...*`, `*Distilling project memory...*`
+- **Streamlined Status & Reduced Noise**:
+  - Eliminated redundant turn reports and mission cards during read-only interactions.
+  - Clean, minimal diffs and one-line summaries only when modifications occur.
+- **Petdex Floating Desktop Companion (`OverarchCompanion.exe`)**:
+  - **Zero Focus Stealing**: Transparent, frameless, always-on-top desktop companion built in native C# WPF using `WS_EX_NOACTIVATE`, `WS_EX_TOPMOST`, and `WS_EX_TOOLWINDOW` to ensure it never interrupts typing or terminal work.
+  - **Petdex Ecosystem Integration**: Directly discovers, loads, and switches pets from `~/.petdex/pets/` and `~/.codex/pets/` (supports 8×9 and 8×11 sprite grids, WebP and PNG formats).
+  - **Real-Time Agent State Reactions**: Visually reflects Overarch agent operations: `idle` (row 0), `thinking`/`inspecting` (row 8), `editing`/`executing` (row 7), `waiting`/`approval` (row 6), `success` (row 4), and `error`/`warning` (row 5).
+  - **Interactive Companion Controls**: Right-click context menu to switch installed pets, install from Petdex, open terminal, or reposition. Left-click drag with edge snapping and position persistence (`~/.overarch/companion_state.json`).
+  - **Bundled Offline Default**: Includes the official `savage-codex-hacker` pet definition and spritesheet for immediate out-of-the-box operation.
+- **Windows Native Integration**:
+  - **Custom GUI Installer (`dist-desktop/Overarch-Setup.exe`)**: 10-step animated installer matching custom specifications (dark navy `#081842`, burgundy titlebar `#5c1122`, elapsed timer, collapsible log, Start Menu, Desktop, and PATH registration).
+  - **Console Launcher (`dist-desktop/Overarch.exe`)**: Lightweight C# native binary (< 75KB) launching Overarch CLI directly in Windows Terminal or cmd.
+  - **Companion Launcher (`dist-desktop/OverarchCompanion.exe`)**: Ultra-lightweight native WPF companion runner (84.5 KB).
+  - **Global Command**: `overarch` available anywhere in Windows terminal.
+
+---
+
+## Core Capabilities
+
+- **7-Stage Epistemic Loop**:
+  1. `Understand`: Parse goal and establish epistemic tracking.
+  2. `Inspect`: Discover repository structure and run parallel read-only inspections.
+  3. `Plan`: Structure actionable roadmaps with clear milestones.
+  4. `Approve`: CCHCFAI human control gating and pre-mutation checkpointing.
+  5. `Execute`: Sequential deterministic tool mutations with loop prevention.
+  6. `Verify`: Autonomous verification of modifications against test suites.
+  7. `Learn`: Record lessons learned from self-correction and user feedback.
+- **CCSS 5.0 Orchestration**:
+  - `/ccss auto`: Balanced autonomy for standard feature engineering.
+  - `/ccss master`: Exhaustive planning and checkpoint validation.
+  - `/ccss god`: End-to-end full autonomy for major refactors.
+  - `/ccss control`: Supervised execution requiring explicit human approval.
+- **CCHCFAI Human Control Guardrails**:
+  - `Tier 0 (Read-Only)`: File inspection, symbol discovery, and directory listings.
+  - `Tier 1 (Safe Mutation)`: Non-destructive local modifications.
+  - `Tier 2 (State-Mutating)`: Shell execution and file creation with notification and approval gates.
+  - `Tier 3 (High-Impact)`: Mandatory explicit confirmation for deletions or out-of-scope actions.
+  - **Emergency Stop**: Instant halt via `Ctrl+C` or `/halt`.
+- **BYOK (Bring Your Own Key)**:
+  - Supports OpenAI (`gpt-4o`), Anthropic Claude (`claude-3-5-sonnet`), Google Gemini (`gemini-2.5-flash`), OpenRouter (`openrouter/auto`), and local/custom OpenAI-compatible endpoints.
+- **Ponytail Senior Dev Minimalism**:
+  - Zero third-party runtime dependencies. Built strictly on standard Node.js built-ins (`node:fs/promises`, `node:child_process`, `node:readline/promises`, `node:util.styleText`, `node:test`) and the native Windows C# compiler (`csc.exe`).
+
+---
+
+## Installation & Setup
+
+### Option 1: Custom Windows Installer (GUI)
+Run `dist-desktop/Overarch-Setup.exe` to install Overarch CLI, create desktop and Start Menu shortcuts, and register `overarch` in your system PATH.
+
+### Option 2: Run via Node.js
+```bash
+cd overarch
+npm install
+npm run build
+npm start
+```
+
+### Option 3: Global Terminal Command
+```bash
+overarch
+```
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `overarch` | Launch interactive terminal agent session |
+| `overarch memory show` | Display project memory and learned episodic lessons |
+| `overarch memory search <query>` | Search memory for specific patterns, conventions, or lessons |
+| `overarch memory forget <id>` | Remove a specific learned memory by ID |
+| `overarch learn "<lesson>"` | Teach Overarch an engineering insight or rule |
+| `overarch companion start` | Launch the floating Petdex desktop companion |
+| `overarch companion status` | Inspect companion status, active pet, and event bridge |
+| `overarch companion pets` | List all discovered Petdex pets |
+| `overarch companion select <slug>` | Switch active companion pet |
+| `overarch companion install <slug>` | Install a pet from Petdex library via official CLI |
+| `overarch setup` | Run interactive onboarding wizard (providers, keys, models) |
+| `overarch doctor` | Health check: Node environment, Git status, provider keys |
+| `overarch init` | Initialize `.overarch/` directory with project config and instructions |
+| `overarch status` | Display workspace status card (project, model, git branch) |
+| `overarch models` | List available models across supported providers |
+| `overarch config` | Inspect active hierarchical configuration |
+| `overarch sessions` | List saved sessions with timestamps and message summaries |
+| `overarch resume [id]` | Resume previous session or specific session by prefix |
+
+---
+
+## In-Session Slash Commands
+
+Inside the interactive REPL:
+
+```text
+PERSISTENT LEARNING & MEMORY
+  /memory [show]      Display project memory & learned episodic lessons
+  /memory search <q>  Search lessons, conventions, and architectural decisions
+  /memory forget <id> Remove a specific learned memory
+  /learn "<lesson>"   Record a new engineering insight into memory
+
+SESSION
+  /status             Display diagnostic dashboard card
+  /new                Start a fresh session in current project
+  /resume [id]        Resume past session by ID or prefix
+  /sessions           List saved sessions with summaries
+  /clear              Clear conversation history
+  /exit, /quit        Save session and exit cleanly
+
+PROJECT & REPOSITORY
+  /project [dir]      Inspect current workspace or switch directory
+  /project recent     List recently accessed projects
+  /init               Initialize .overarch subsystem for this project
+  /context            Deep inspection of files, stack, and tokens
+  /reload             Re-scan workspace context and instructions
+  /checkpoint [name]  Create an instant git/snapshot checkpoint
+  /checkpoints        List all saved checkpoints
+  /rollback [id]      Revert repository to a previous checkpoint
+  /diff, /changes     Inspect uncommitted git working tree changes
+
+AI & AGENT
+  /model [name]       List available models or switch active model
+  /plan [on|off]      Toggle Plan Mode (roadmap before changes)
+  /retry              Re-execute last prompt with updated approach
+  /ponytail [level]   Set Ponytail minimalism: lite | full | ultra
+  /ccss [mode]        Set CCSS mission orchestration: auto | master | god | control
+  /cchcfai [action]   Human control layer: gate | audit | halt | status
+  /companion [action] Floating desktop companion: start | stop | status | pets | select
+  /petdex [action]    Alias for /companion (Petdex integration)
+  /tools              List available tools, permission tiers, and MCP
+  /abort, /halt       Emergency stop current agent operation
+```
+
+---
+
+## Architecture
+
+```text
+Overarch CLI Architecture
+├── bin/overarch.ts            # CLI entry point, subcommands & argument dispatch
+├── src/cli/
+│    ├── repl.ts               # Terminal REPL, Claude-like spinner & command routing
+│    ├── ui.ts                 # Pixel logo, ANSI diff formatting & thinking adjectives
+│    └── commands/             # Subcommands (memory, doctor, setup, companion, status, etc.)
+├── src/companion/             # Petdex Desktop Companion Integration
+│    ├── petdex_adapter.ts     # Multi-directory pet discovery & spritesheet mapping
+│    ├── petdex_bridge.ts      # HTTP/SSE event server & desktop process manager
+│    └── types.ts              # Petdex schemas & AgentState animation row mappings
+├── src/learning/              # Persistent Learning Architecture
+│    ├── memory_manager.ts     # Disk persistence, selective retrieval & token bounding
+│    └── types.ts              # EpisodicLesson, ProjectMemory, UserMemory schemas
+├── src/agent/
+│    ├── runtime.ts            # 7-stage epistemic agent pipeline & self-correction
+│    ├── planner.ts            # CCSS modes (auto, master, god, control) & roadmaps
+│    ├── manifest.ts           # AST symbol extractor & repository intelligence
+│    ├── context.ts            # Workspace discovery & instruction loader
+│    └── context_compressor.ts # Token-efficient context compression
+├── src/security/
+│    ├── permissions.ts        # CCHCFAI Tier 0-3 permission checker
+│    └── guardrails.ts         # Path traversal defense & emergency stop
+├── src/tools/
+│    ├── filesystem.ts         # Precision slice reader, diff-aware writer & patcher
+│    ├── git.ts                # Git operations & branch inspection
+│    ├── checkpoint.ts         # Snapshot & rollback engine
+│    ├── symbols.ts            # Symbol search & reference tracking
+│    └── registry.ts           # Tool registry & OpenAI tool-calling schema export
+├── src/desktop/
+│    ├── launcher.cs           # Native Windows console launcher (< 75KB)
+│    ├── companion.cs          # Native WPF floating desktop companion (84.5 KB)
+│    └── installer.cs          # Custom WinForms GUI installer (100 KB)
+└── src/providers/
+     ├── factory.ts            # BYOK provider factory (OpenRouter, Anthropic, OpenAI, Gemini)
+     └── validator.ts          # OpenRouter tool_call_id healing & pre-flight integrity
+```
+
+---
+
+## Testing & Verification
+
+Run the full automated test suite:
+
+```bash
+npm test
+```
+
+Runs **93 automated tests** across **24 suites** with 100% pass rate using Node.js's built-in `node:test` runner.
+
+---
+
+## Credits
+
+2026 Made By Yatharth Roy, From The Thursday AI Company of New Delhi

package/dist/bin/overarch.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/overarch.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { parseCliArgs } from '../src/cli/args.js';
+import * as ui from '../src/cli/ui.js';
+import { doctor } from '../src/cli/commands/doctor.js';
+import { init } from '../src/cli/commands/init.js';
+import { status } from '../src/cli/commands/status.js';
+import { listSessions } from '../src/cli/commands/sessions.js';
+import { handleConfigCommand } from '../src/cli/commands/config.js';
+import { startRepl } from '../src/cli/repl.js';
+import { loadConfig } from '../src/config/index.js';
+import { listModels } from '../src/providers/factory.js';
+import { runOnboarding, runSetup } from '../src/cli/commands/onboarding.js';
+import { handleMemoryCommand, handleLearnCommand } from '../src/cli/commands/memory.js';
+import { handleCompanionCommand } from '../src/cli/commands/companion.js';
+import { handleAuditCommand } from '../src/cli/commands/audit.js';
+import { handleUpdateCommand } from '../src/cli/commands/update.js';
+import { policyEngine } from '../src/security/policy.js';
+const USAGE = `
+${ui.bold('Overarch CLI')} — The Learning Agent for Autonomous Software Engineering (v0.8.0)
+
+${ui.bold('Usage')}
+  overarch                     Start interactive session
+  overarch "fix failing tests" One-shot prompt
+  overarch <command>           Run a command
+
+${ui.bold('Commands')}
+  doctor              Check environment, Git, and configuration
+  init                Initialize project config & instructions
+  setup               Run interactive setup / onboarding
+  audit [opts]        View, filter, or export CCHCFAI policy audit log
+  update [--check]    Check packages and verify SHA-256 integrity
+  memory [show|search] Inspect project and episodic memory
+  learn "<insight>"   Record a persistent engineering lesson
+  companion [start|pets] Floating Petdex desktop companion
+  config [get|set]    Inspect or modify configuration
+  status              Show active project, model, and git status
+  models              List available models across BYOK providers
+  sessions            List saved sessions with summaries
+  resume [id]         Resume last session or specific session by ID
+
+${ui.bold('Options')}
+  --model <id>   Use specific model (e.g. gpt-4o, claude-sonnet-4-20250514)
+  --folder, -f   Specify workspace directory to operate in
+  --compact      Compact terminal output mode
+  --setup        Run setup before starting
+  --safe-only    Run in SAFE-ONLY mode (blocks destructive shell or file mutations)
+  --resume, -r   Resume last session
+  --yes, -y      Auto-approve all actions
+  --verbose      Show detailed output
+  --version, -v  Print version
+  --help, -h     Print this help
+
+${ui.dim('2026 Made By Yatharth Roy, From The Thursday AI Company of New Delhi')}
+`;
+process.on('SIGINT', () => {
+    policyEngine.terminateAllProcesses();
+    process.exit(130);
+});
+async function main() {
+    try {
+        const args = parseCliArgs();
+        if (args.safeOnly) {
+            policyEngine.setSafeOnly(true);
+        }
+        if (args.version) {
+            console.log('overarch-cli 0.8.0\n2026 Made By Yatharth Roy, From The Thursday AI Company of New Delhi');
+            return;
+        }
+        if (args.help) {
+            console.log(USAGE);
+            return;
+        }
+        if (args.folder) {
+            process.chdir(args.folder);
+        }
+        let config = await loadConfig();
+        // Apply accent and avatar globally
+        if (config.ui?.accentColor) {
+            ui.setAccent(config.ui.accentColor);
+        }
+        if (config.ui?.avatar) {
+            ui.setAvatar(config.ui.avatar);
+        }
+        if (args.setup || args.command === 'setup') {
+            await runSetup();
+            return;
+        }
+        if (!args.command) {
+            await runOnboarding();
+            config = await loadConfig();
+            await startRepl(config, args);
+            return;
+        }
+        switch (args.command) {
+            case 'doctor':
+                await doctor();
+                break;
+            case 'init':
+                await init();
+                break;
+            case 'audit':
+                await handleAuditCommand(process.argv.slice(3));
+                break;
+            case 'update':
+                await handleUpdateCommand(process.argv.slice(3));
+                break;
+            case 'models': {
+                ui.heading('Available Models');
+                const models = listModels();
+                for (const m of models) {
+                    const ctx = m.contextWindow >= 1_000_000
+                        ? `${(m.contextWindow / 1_000_000).toFixed(1)}M`
+                        : `${(m.contextWindow / 1_000).toFixed(0)}K`;
+                    const tools = m.supportsTools ? ui.green('✓ tools') : ui.dim('✗ tools');
+                    console.log(`  ${ui.bold(m.id)} ${ui.dim(`(${m.provider}, ${ctx}, ${tools})`)}`);
+                }
+                console.log(`\n${ui.dim('Use provider/model format for unlisted models: e.g. openai/gpt-4.5-preview')}`);
+                break;
+            }
+            case 'config': {
+                const rawArgs = process.argv.slice(3);
+                const sub = rawArgs[0];
+                const key = rawArgs[1];
+                const val = rawArgs[2];
+                await handleConfigCommand(sub, key, val);
+                break;
+            }
+            case 'status':
+                await status();
+                break;
+            case 'sessions':
+                await listSessions();
+                break;
+            case 'memory': {
+                const rawArgs = process.argv.slice(3);
+                await handleMemoryCommand(rawArgs[0], rawArgs[1], rawArgs[2]);
+                break;
+            }
+            case 'learn': {
+                const rawArgs = process.argv.slice(3);
+                await handleLearnCommand(rawArgs.join(' '));
+                break;
+            }
+            case 'companion':
+            case 'petdex': {
+                const rawArgs = process.argv.slice(3);
+                await handleCompanionCommand(rawArgs[0], rawArgs[1], rawArgs[2]);
+                break;
+            }
+            case 'desktop':
+            case 'gui': {
+                await runOnboarding();
+                config = await loadConfig();
+                await startRepl(config, args);
+                break;
+            }
+            case 'resume':
+                await runOnboarding();
+                config = await loadConfig();
+                await startRepl(config, { ...args, resume: true });
+                break;
+            case 'chat':
+                await runOnboarding();
+                config = await loadConfig();
+                await startRepl(config, args);
+                break;
+            default:
+                ui.error(`Unknown command: ${args.command}`);
+                console.log(USAGE);
+                process.exit(1);
+        }
+    }
+    catch (err) {
+        ui.error(err.message || String(err));
+        process.exit(1);
+    }
+}
+main();

package/dist/src/agent/context.d.ts

@@ -0,0 +1,14 @@
+import { OverarchConfig } from '../config/types.js';
+export interface ProjectContextInspection {
+    cwd: string;
+    projectTypes: string[];
+    gitBranch: string;
+    gitStatus: string;
+    filesDiscovered: number;
+    filesSample: string[];
+    instructionsSource?: string;
+    memoryEntriesCount: number;
+    estimatedTokens: number;
+}
+export declare function inspectProjectContext(cwd: string): Promise<ProjectContextInspection>;
+export declare function buildContext(cwd: string, config?: Partial<OverarchConfig>): Promise<string>;

package/dist/src/agent/context.js

@@ -0,0 +1,200 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { buildRepoManifest } from './manifest.js';
+const execAsync = promisify(exec);
+export async function inspectProjectContext(cwd) {
+    const result = {
+        cwd,
+        projectTypes: [],
+        gitBranch: 'unknown',
+        gitStatus: 'clean',
+        filesDiscovered: 0,
+        filesSample: [],
+        memoryEntriesCount: 0,
+        estimatedTokens: 0
+    };
+    // Git
+    try {
+        const { stdout: branch } = await execAsync('git branch --show-current', { cwd });
+        result.gitBranch = branch.trim() || 'HEAD';
+        const { stdout: status } = await execAsync('git status --porcelain', { cwd });
+        result.gitStatus = status.trim() ? `${status.trim().split('\n').length} modified files` : 'Clean';
+    }
+    catch {
+        result.gitBranch = 'Not a git repo';
+    }
+    // Language & Framework
+    try {
+        const pkg = JSON.parse(await fs.readFile(path.join(cwd, 'package.json'), 'utf8'));
+        result.projectTypes.push(`Node.js (${pkg.name || 'unnamed'})`);
+    }
+    catch { }
+    try {
+        await fs.readFile(path.join(cwd, 'Cargo.toml'), 'utf8');
+        result.projectTypes.push('Rust (Cargo)');
+    }
+    catch { }
+    try {
+        await fs.readFile(path.join(cwd, 'pyproject.toml'), 'utf8');
+        result.projectTypes.push('Python (pyproject.toml)');
+    }
+    catch {
+        try {
+            await fs.readFile(path.join(cwd, 'requirements.txt'), 'utf8');
+            result.projectTypes.push('Python (requirements.txt)');
+        }
+        catch { }
+    }
+    try {
+        await fs.readFile(path.join(cwd, 'go.mod'), 'utf8');
+        result.projectTypes.push('Go');
+    }
+    catch { }
+    // File discovery
+    try {
+        const ignoreList = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.turbo', '.cache']);
+        const entries = await fs.readdir(cwd, { withFileTypes: true });
+        for (const e of entries) {
+            if (ignoreList.has(e.name))
+                continue;
+            result.filesDiscovered++;
+            if (result.filesSample.length < 12) {
+                result.filesSample.push(`${e.name}${e.isDirectory() ? '/' : ''}`);
+            }
+        }
+    }
+    catch { }
+    // Instructions check
+    const candidateInstructions = [
+        { p: path.join(cwd, '.overarch', 'instructions.md'), name: '.overarch/instructions.md' },
+        { p: path.join(cwd, 'CLAUDE.md'), name: 'CLAUDE.md' },
+        { p: path.join(cwd, 'OVERARCH.md'), name: 'OVERARCH.md' },
+        { p: path.join(cwd, 'AGENTS.md'), name: 'AGENTS.md' }
+    ];
+    for (const item of candidateInstructions) {
+        try {
+            await fs.access(item.p);
+            result.instructionsSource = item.name;
+            break;
+        }
+        catch { }
+    }
+    // Memory count
+    try {
+        const mem = await fs.readFile(path.join(cwd, '.overarch', 'memory.md'), 'utf8');
+        const lines = mem.split('\n').filter(l => l.trim().startsWith('-'));
+        result.memoryEntriesCount = lines.length;
+    }
+    catch { }
+    const fullContext = await buildContext(cwd);
+    result.estimatedTokens = Math.round(fullContext.length / 4);
+    return result;
+}
+export async function buildContext(cwd, config) {
+    const parts = [];
+    // 1. Identity & Operating Model
+    parts.push(`You are Overarch, an autonomous terminal-native AI coding agent.`);
+    parts.push(`Working directory: ${cwd}`);
+    parts.push(`Operating Rules:`);
+    parts.push(`- Be concise, fast, and action-oriented.`);
+    parts.push(`- Always read files before modifying to verify exact contents.`);
+    parts.push(`- Make minimal, surgical diffs. Follow existing codebase patterns.`);
+    parts.push(`- Destructive actions (deleting files, force pushes) require explicit human confirmation.`);
+    // Ponytail tuning if active
+    const ponytail = config?.ponytail || 'full';
+    if (ponytail === 'ultra' || ponytail === 'full') {
+        parts.push(`\n[Ponytail ${ponytail.toUpperCase()} Active]: Enforce YAGNI ladder. Standard library before custom code; shortest working diff wins; zero unnecessary abstractions or unrequested boilerplate.`);
+    }
+    // CCSS mode tuning
+    const ccss = config?.ccss || 'auto';
+    parts.push(`\n[CCSS ${ccss.toUpperCase()} Mode]: Discover capabilities, orchestrate verified work, confirm key milestones, and deliver concrete results.`);
+    // CCHCFAI Human Control Protocol
+    parts.push(`\n[CCHCFAI Protocol]: Autonomy is bounded and interruptible. Classify actions into Tier 0 (Read-only), Tier 1 (Reversible local), Tier 2 (State-mutating), Tier 3 (Destructive). Halt immediately if user types /halt or Ctrl+C.`);
+    // 2. Git Status
+    try {
+        const { stdout: gitBranch } = await execAsync('git branch --show-current', { cwd });
+        const { stdout: gitStatus } = await execAsync('git status -s', { cwd });
+        let gitInfo = `Git Branch: ${gitBranch.trim() || 'HEAD (detached)'}\n`;
+        if (gitStatus.trim()) {
+            const changedFiles = gitStatus.trim().split('\n');
+            gitInfo += `Git Status: ${changedFiles.length} changed file(s):\n${changedFiles.slice(0, 8).join('\n')}`;
+            if (changedFiles.length > 8) {
+                gitInfo += `\n... and ${changedFiles.length - 8} more`;
+            }
+        }
+        else {
+            gitInfo += `Git Status: Clean working tree`;
+        }
+        try {
+            const { stdout: gitLog } = await execAsync('git log -n 3 --oneline', { cwd });
+            if (gitLog.trim()) {
+                gitInfo += `\nRecent commits:\n${gitLog.trim()}`;
+            }
+        }
+        catch { }
+        parts.push(`\n## Version Control\n${gitInfo}`);
+    }
+    catch {
+        parts.push(`\n## Version Control\nGit: Not a git repository or git unavailable.`);
+    }
+    // 3. Project Manifest & Architecture Map
+    const manifest = await buildRepoManifest(cwd);
+    if (manifest.projectTypes.length > 0) {
+        parts.push(`\n## Project Architecture\nType: ${manifest.projectTypes.join(', ')}`);
+        if (manifest.entryPoints.length > 0) {
+            parts.push(`Entry Points: ${manifest.entryPoints.join(', ')}`);
+        }
+        if (manifest.buildSystems.length > 0) {
+            parts.push(`Build Systems: ${manifest.buildSystems.join(', ')}`);
+        }
+        if (manifest.testDirectories.length > 0) {
+            parts.push(`Test Directories: ${manifest.testDirectories.join(', ')}`);
+        }
+    }
+    // 4. Workspace Structure
+    if (manifest.keyDirectories.length > 0) {
+        parts.push(`\n## Key Directories\n${manifest.keyDirectories.join('  ')}`);
+    }
+    // 5. Project Instructions (.overarch/instructions.md authoritative, or CLAUDE.md / OVERARCH.md / AGENTS.md fallback)
+    let instructionsFound = false;
+    try {
+        const instructions = await fs.readFile(path.join(cwd, '.overarch', 'instructions.md'), 'utf-8');
+        if (instructions.trim()) {
+            parts.push(`\n## Project Instructions (.overarch/instructions.md)\n${instructions.trim()}`);
+            instructionsFound = true;
+        }
+    }
+    catch { }
+    if (!instructionsFound) {
+        const candidates = ['CLAUDE.md', 'OVERARCH.md', 'AGENTS.md'];
+        for (const file of candidates) {
+            try {
+                const content = await fs.readFile(path.join(cwd, file), 'utf-8');
+                if (content.trim()) {
+                    parts.push(`\n## Project Instructions (${file})\n${content.trim()}`);
+                    break;
+                }
+            }
+            catch { }
+        }
+    }
+    // 6. Project Memory (.overarch/memory.md)
+    try {
+        const memory = await fs.readFile(path.join(cwd, '.overarch', 'memory.md'), 'utf-8');
+        if (memory.trim()) {
+            parts.push(`\n## Project Memory (.overarch/memory.md)\n${memory.trim()}`);
+        }
+    }
+    catch { }
+    // 7. README Snippet
+    try {
+        const readme = await fs.readFile(path.join(cwd, 'README.md'), 'utf-8');
+        if (readme.trim()) {
+            parts.push(`\n## README (overview)\n${readme.substring(0, 1200).trim()}`);
+        }
+    }
+    catch { }
+    return parts.join('\n');
+}

package/dist/src/agent/context_compressor.d.ts

@@ -0,0 +1,21 @@
+import { Message } from '../providers/types.js';
+export interface CompressionResult {
+    messages: Message[];
+    originalTokens: number;
+    compressedTokens: number;
+    didCompress: boolean;
+}
+/**
+ * Estimates token count from text using standard ~4 characters per token heuristic
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Estimates token count for an array of messages
+ */
+export declare function estimateMessagesTokens(messages: Message[]): number;
+/**
+ * Compresses conversation history to stay within a configured token budget,
+ * preserving critical goals, plans, recent file diffs, and verification evidence
+ * while summarizing verbose intermediate tool executions.
+ */
+export declare function compressContext(messages: Message[], maxTokens?: number): CompressionResult;