@matt82198/aesop 0.1.0-beta.5 → 0.1.0

package/tools/doctor.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+
+/**
+ * Aesop doctor — preflight checklist for adopter onboarding
+ *
+ * Runs diagnostic checks and prints a readiness table.
+ * Exit code 0 = all checks passed; 1 = at least one failed.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const net = require('net');
+
+const CURRENT_DIR = process.cwd();
+
+// ANSI color helpers
+const COLORS = {
+  GREEN: '\x1b[32m',
+  RED: '\x1b[31m',
+  RESET: '\x1b[0m',
+  BOLD: '\x1b[1m'
+};
+
+function colorPass() {
+  return `${COLORS.GREEN}✓ PASS${COLORS.RESET}`;
+}
+
+function colorFail() {
+  return `${COLORS.RED}✗ FAIL${COLORS.RESET}`;
+}
+
+// Check Node.js version >= 18
+function checkNodeVersion() {
+  const version = parseInt(process.versions.node.split('.')[0], 10);
+  const passed = version >= 18;
+  const hint = passed ? '' : `Found Node.js v${process.versions.node}, need >=18`;
+  return { passed, hint };
+}
+
+// Check Python available (python3 or python)
+function checkPython() {
+  // Try python3 first
+  const result3 = spawnSync('python3', ['--version'], { stdio: 'ignore', timeout: 5000 });
+  if (result3.error && result3.error.code === 'ENOENT') {
+    // python3 not found, try python fallback
+    const result = spawnSync('python', ['--version'], { stdio: 'ignore', timeout: 5000 });
+    if (result.error && result.error.code === 'ENOENT') {
+      // Neither python3 nor python found
+      return { passed: false, hint: 'python3 or python not found on PATH' };
+    }
+    if (result.status !== 0) {
+      // python exists but returned non-zero exit code
+      return { passed: false, hint: 'python found but returned non-zero exit code' };
+    }
+    return { passed: true, hint: '' };
+  }
+  if (result3.status !== 0) {
+    // python3 exists but returned non-zero exit code
+    return { passed: false, hint: 'python3 found but returned non-zero exit code' };
+  }
+  return { passed: true, hint: '' };
+}
+
+// Check git repo (.git directory exists)
+function checkGitRepo() {
+  const gitDir = path.join(CURRENT_DIR, '.git');
+  const passed = fs.existsSync(gitDir);
+  const hint = passed ? '' : 'Not inside a git repository';
+  return { passed, hint };
+}
+
+// Check aesop.config.json exists and is valid JSON
+function checkConfig() {
+  const configPath = path.join(CURRENT_DIR, 'aesop.config.json');
+  try {
+    if (!fs.existsSync(configPath)) {
+      return { passed: false, hint: 'aesop.config.json not found' };
+    }
+    const content = fs.readFileSync(configPath, 'utf8');
+    JSON.parse(content);
+    return { passed: true, hint: '' };
+  } catch (e) {
+    return { passed: false, hint: `Config parse error: ${e.message}` };
+  }
+}
+
+// Check required directories exist
+function checkDirectories() {
+  const requiredDirs = ['daemons', 'dash', 'monitor', 'tools', 'ui'];
+  const missing = requiredDirs.filter(dir => {
+    const dirPath = path.join(CURRENT_DIR, dir);
+    return !fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory();
+  });
+
+  if (missing.length === 0) {
+    return { passed: true, hint: '' };
+  } else {
+    return { passed: false, hint: `Missing: ${missing.join(', ')}` };
+  }
+}
+
+// Check git pre-push hook installed
+function checkPrePushHook() {
+  const hookPath = path.join(CURRENT_DIR, '.git', 'hooks', 'pre-push');
+  const passed = fs.existsSync(hookPath);
+  const hint = passed ? '' : 'Pre-push hook not installed at .git/hooks/pre-push';
+  return { passed, hint };
+}
+
+// Check if port 8770 is free (using socket connection test)
+function checkPort8770() {
+  return new Promise((resolve) => {
+    let resolved = false;
+    const sock = net.createConnection({ port: 8770, host: '127.0.0.1', timeout: 500 });
+
+    const cleanup = () => {
+      try {
+        sock.destroy();
+      } catch (e) {
+        // Ignore cleanup errors
+      }
+    };
+
+    sock.on('connect', () => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve({ passed: false, hint: 'Port 8770 is in use' });
+      }
+    });
+
+    sock.on('error', () => {
+      // Connection failed, port is free
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve({ passed: true, hint: '' });
+      }
+    });
+
+    sock.on('timeout', () => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve({ passed: true, hint: '' });
+      }
+    });
+
+    // Fallback timeout to ensure we resolve within 2 seconds
+    setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve({ passed: true, hint: '' });
+      }
+    }, 2000);
+  });
+}
+
+// Format a row in the readiness table
+function formatRow(label, status, hint) {
+  const statusStr = status ? colorPass() : colorFail();
+  const hintStr = hint ? ` — ${hint}` : '';
+  // Pad label to 35 chars for alignment
+  const paddedLabel = label.padEnd(35);
+  return `  ${paddedLabel} ${statusStr}${hintStr}`;
+}
+
+// Main execution
+(async function main() {
+  try {
+    console.log(`\n${COLORS.BOLD}Aesop Readiness Check${COLORS.RESET}\n`);
+
+    const syncChecks = [
+      { label: 'Node.js version ≥18', fn: checkNodeVersion },
+      { label: 'Python (python3 or python)', fn: checkPython },
+      { label: 'Git repository', fn: checkGitRepo },
+      { label: 'aesop.config.json (valid JSON)', fn: checkConfig },
+      { label: 'Required directories (daemons, dash, monitor, tools, ui)', fn: checkDirectories },
+      { label: 'Git pre-push hook installed', fn: checkPrePushHook }
+    ];
+
+    const results = [];
+
+    // Run sync checks
+    for (const check of syncChecks) {
+      const result = check.fn();
+      results.push({ label: check.label, ...result });
+      console.log(formatRow(check.label, result.passed, result.hint));
+    }
+
+    // Run async port check
+    try {
+      const portResult = await checkPort8770();
+      results.push({ label: 'Port 8770 available', ...portResult });
+      console.log(formatRow('Port 8770 available', portResult.passed, portResult.hint));
+    } catch (e) {
+      results.push({ label: 'Port 8770 available', passed: false, hint: 'Port check failed' });
+      console.log(formatRow('Port 8770 available', false, 'Port check failed'));
+    }
+
+    const allPassed = results.every(r => r.passed);
+    const passCount = results.filter(r => r.passed).length;
+    const failCount = results.length - passCount;
+
+    console.log(`\n${COLORS.BOLD}Summary: ${passCount}/${results.length} checks passed${COLORS.RESET}`);
+
+    if (allPassed) {
+      console.log(`${COLORS.GREEN}✓ You are ready to run: bash daemons/run-watchdog.sh --once${COLORS.RESET}\n`);
+      process.exitCode = 0;
+    } else {
+      console.log(`${COLORS.RED}✗ Fix the ${failCount} failed check(s) above and try again${COLORS.RESET}\n`);
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    console.error(`Error running doctor: ${err.message}`);
+    process.exit(1);
+  }
+})();

package/tools/fleet_ledger.py

@@ -3,16 +3,20 @@ r"""
 Fleet Outcome Ledger — append-only audit trail for dispatched agents.
 
 Subcommands:
-  append <timestamp> <agent_type> <model> <duration_sec> <tokens_in> <tokens_out> [verdict]
+  append <timestamp> <agent_type> <model> <duration_sec> <tokens_in> <tokens_out> [verdict] [phase] [wave]
     Manually append one ledger line (verdict = OK|FAILED|EMPTY|HUNG, default OK)
+    phase = build|verify|repair|other (optional, default null)
+    wave = wave number as integer (optional, default null)
   harvest
     Scan session tasks directories for agent outcomes and append missing entries.
     (Tracks state in ledger directory for resume capability)
   rotate
     Archive ledger lines exceeding ~200 lines to dated archive, keep recent tail in live ledger
+  summary
+    Print total cost/tokens grouped by wave number and phase; supports --json for machine reading
 
 Ledger format (markdown table):
-  | ISO ts | agent_type | model | duration_sec | tokens_in | tokens_out | verdict |
+  | ISO ts | agent_type | model | duration_sec | tokens_in | tokens_out | verdict | phase | wave |
 
 Environment:
   AESOP_STATE_ROOT: Path to state directory (default: ./state relative to cwd)
@@ -27,12 +31,10 @@ from datetime import datetime, timezone
 import re
 from collections import defaultdict
 
-
-def get_state_dir():
-    """Resolve state directory from env var or current working directory."""
-    if os.environ.get("AESOP_STATE_ROOT"):
-        return Path(os.environ["AESOP_STATE_ROOT"])
-    return Path.cwd() / "state"
+try:
+    from common import get_state_dir
+except ImportError:
+    from tools.common import get_state_dir
 
 
 def get_ledger_paths():
@@ -49,13 +51,25 @@ def ensure_ledger_header():
     ledger_file, _, ledger_dir = get_ledger_paths()
     if not ledger_file.exists():
         ledger_dir.mkdir(parents=True, exist_ok=True)
-        header = '| ISO ts | agent_type | model | duration_sec | tokens_in | tokens_out | verdict |\n'
-        header += '|--------|------------|-------|--------------|-----------|------------|--------|\n'
+        header = '| ISO ts | agent_type | model | duration_sec | tokens_in | tokens_out | verdict | phase | wave |\n'
+        header += '|--------|------------|-------|--------------|-----------|------------|--------|-------|------|\n'
         ledger_file.write_text(header, encoding='utf-8')
 
 
-def append_ledger_line(iso_ts, agent_type, model, duration_sec, tokens_in, tokens_out, verdict='OK'):
-    """Append one line to the ledger."""
+def append_ledger_line(iso_ts, agent_type, model, duration_sec, tokens_in, tokens_out, verdict='OK', phase=None, wave=None):
+    """Append one line to the ledger.
+
+    Args:
+        iso_ts: ISO 8601 timestamp
+        agent_type: agent type string
+        model: model identifier
+        duration_sec: duration in seconds
+        tokens_in: input tokens
+        tokens_out: output tokens
+        verdict: OK|FAILED|EMPTY|HUNG (default OK)
+        phase: build|verify|repair|other (optional, default None)
+        wave: wave number as int or None (optional, default None)
+    """
     ensure_ledger_header()
     ledger_file, _, _ = get_ledger_paths()
 
@@ -64,6 +78,20 @@ def append_ledger_line(iso_ts, agent_type, model, duration_sec, tokens_in, token
     model = str(model or '-').replace('|', '').strip()[:30]
     verdict = str(verdict or 'OK').replace('|', '').strip()[:10]
 
+    # Sanitize optional fields
+    if phase is not None:
+        phase = str(phase).replace('|', '').strip()[:15]
+    else:
+        phase = ''
+
+    if wave is not None:
+        try:
+            wave = str(int(wave))
+        except (ValueError, TypeError):
+            wave = ''
+    else:
+        wave = ''
+
     try:
         dur = int(duration_sec) if duration_sec else 0
     except (ValueError, TypeError):
@@ -79,7 +107,7 @@ def append_ledger_line(iso_ts, agent_type, model, duration_sec, tokens_in, token
     except (ValueError, TypeError):
         to = 0
 
-    line = f'| {iso_ts} | {agent_type} | {model} | {dur} | {ti} | {to} | {verdict} |\n'
+    line = f'| {iso_ts} | {agent_type} | {model} | {dur} | {ti} | {to} | {verdict} | {phase} | {wave} |\n'
     with open(ledger_file, 'a', encoding='utf-8') as f:
         f.write(line)
 
@@ -232,6 +260,144 @@ def rotate():
     print(f'Live ledger now has {len(new_ledger) - len(header_lines)} data lines')
 
 
+def parse_ledger_rows():
+    """Parse and return all ledger rows as structured data.
+
+    Returns:
+        list of dicts, each with keys: iso_ts, agent_type, model, duration_sec,
+        tokens_in, tokens_out, verdict, phase, wave (wave as int or None)
+
+    Returns empty list if ledger doesn't exist or is unreadable.
+    """
+    ensure_ledger_header()
+    ledger_file, _, _ = get_ledger_paths()
+
+    try:
+        lines = ledger_file.read_text(encoding='utf-8').split('\n')
+    except (IOError, OSError):
+        return []
+
+    rows = []
+    for line in lines:
+        # Skip empty, header, separator lines
+        if not line.strip() or '---|' in line or not line.startswith('|'):
+            continue
+
+        # Parse markdown table row
+        cells = [c.strip() for c in line.split('|')[1:-1]]  # split by |, skip first/last empty
+        if len(cells) < 7:
+            continue
+
+        try:
+            # Original columns: ISO ts, agent_type, model, duration_sec, tokens_in, tokens_out, verdict
+            # New columns: phase, wave
+            iso_ts = cells[0]
+            agent_type = cells[1]
+            model = cells[2]
+            duration_sec = int(cells[3]) if cells[3] else 0
+            tokens_in = int(cells[4]) if cells[4] else 0
+            tokens_out = int(cells[5]) if cells[5] else 0
+            verdict = cells[6] if len(cells) > 6 else 'OK'
+            phase = cells[7].strip() if len(cells) > 7 and cells[7].strip() else None
+            wave = cells[8].strip() if len(cells) > 8 and cells[8].strip() else None
+
+            # Try to parse wave as int
+            wave_num = None
+            if wave:
+                try:
+                    wave_num = int(wave)
+                except ValueError:
+                    pass
+
+            rows.append({
+                'iso_ts': iso_ts,
+                'agent_type': agent_type,
+                'model': model,
+                'duration_sec': duration_sec,
+                'tokens_in': tokens_in,
+                'tokens_out': tokens_out,
+                'verdict': verdict,
+                'phase': phase,
+                'wave': wave_num,
+            })
+        except (ValueError, IndexError):
+            # Skip malformed lines silently
+            continue
+
+    return rows
+
+
+def summary(output_format='text'):
+    """Aggregate ledger entries by wave and phase; report total tokens/cost.
+
+    Args:
+        output_format: 'text' (default) or 'json'
+    """
+    # Use shared parser to get rows
+    rows = parse_ledger_rows()
+
+    # Parse ledger: skip header and separator lines, parse data lines
+    by_wave_phase = defaultdict(lambda: {'tokens_out': 0, 'tokens_in': 0, 'entries': 0, 'duration': 0})
+    by_wave = defaultdict(lambda: {'tokens_out': 0, 'tokens_in': 0, 'entries': 0, 'duration': 0})
+    totals = {'tokens_out': 0, 'tokens_in': 0, 'entries': 0, 'duration': 0}
+
+    for row in rows:
+        tokens_in = row['tokens_in']
+        tokens_out = row['tokens_out']
+        duration_sec = row['duration_sec']
+        wave_num = row['wave']
+        phase = row['phase']
+
+        # Accumulate by wave+phase
+        key = (wave_num, phase)
+        by_wave_phase[key]['tokens_out'] += tokens_out
+        by_wave_phase[key]['tokens_in'] += tokens_in
+        by_wave_phase[key]['entries'] += 1
+        by_wave_phase[key]['duration'] += duration_sec
+
+        # Accumulate by wave
+        by_wave[wave_num]['tokens_out'] += tokens_out
+        by_wave[wave_num]['tokens_in'] += tokens_in
+        by_wave[wave_num]['entries'] += 1
+        by_wave[wave_num]['duration'] += duration_sec
+
+        # Accumulate totals
+        totals['tokens_out'] += tokens_out
+        totals['tokens_in'] += tokens_in
+        totals['entries'] += 1
+        totals['duration'] += duration_sec
+
+    if output_format == 'json':
+        import json
+        result = {
+            'by_wave_phase': {str(k): v for k, v in sorted(by_wave_phase.items())},
+            'by_wave': {str(k): v for k, v in sorted(by_wave.items())},
+            'totals': totals
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        # Text format: human-readable table
+        print('\n=== Ledger Summary ===')
+        print(f'\nTotal: {totals["entries"]} entries | {totals["tokens_in"]} in | {totals["tokens_out"]} out | {totals["duration"]}s\n')
+
+        if by_wave_phase:
+            print('By Wave + Phase:')
+            print('  Wave | Phase    | Entries | Tokens In | Tokens Out | Duration')
+            print('  -----|----------|---------|-----------|------------|----------')
+            for (wave_num, phase), stats in sorted(by_wave_phase.items()):
+                w_str = str(wave_num) if wave_num is not None else 'None'
+                p_str = phase if phase else '(no phase)'
+                print(f'  {w_str:4} | {p_str:8} | {stats["entries"]:7} | {stats["tokens_in"]:9} | {stats["tokens_out"]:10} | {stats["duration"]:8}')
+
+        if by_wave:
+            print('\nBy Wave (Total):')
+            print('  Wave | Entries | Tokens In | Tokens Out | Duration')
+            print('  -----|---------|-----------|------------|----------')
+            for wave_num, stats in sorted(by_wave.items()):
+                w_str = str(wave_num) if wave_num is not None else 'None'
+                print(f'  {w_str:4} | {stats["entries"]:7} | {stats["tokens_in"]:9} | {stats["tokens_out"]:10} | {stats["duration"]:8}')
+
+
 def main():
     if len(sys.argv) < 2:
         print(__doc__)
@@ -240,9 +406,9 @@ def main():
     cmd = sys.argv[1].lower()
 
     if cmd == 'append':
-        # append <ts> <agent_type> <model> <dur> <tokens_in> <tokens_out> [verdict]
+        # append <ts> <agent_type> <model> <dur> <tokens_in> <tokens_out> [verdict] [phase] [wave]
         if len(sys.argv) < 7:
-            print('Usage: fleet_ledger.py append <ts> <agent_type> <model> <dur_sec> <tokens_in> <tokens_out> [verdict]')
+            print('Usage: fleet_ledger.py append <ts> <agent_type> <model> <dur_sec> <tokens_in> <tokens_out> [verdict] [phase] [wave]')
             sys.exit(1)
 
         ts = sys.argv[2]
@@ -252,9 +418,11 @@ def main():
         ti = sys.argv[6]
         to = sys.argv[7] if len(sys.argv) > 7 else '0'
         verdict = sys.argv[8] if len(sys.argv) > 8 else 'OK'
+        phase = sys.argv[9] if len(sys.argv) > 9 else None
+        wave = sys.argv[10] if len(sys.argv) > 10 else None
 
-        append_ledger_line(ts, agent_type, model, dur, ti, to, verdict)
-        print(f'Appended: {ts} {agent_type} {model} {dur}s {ti}->{to} [{verdict}]')
+        append_ledger_line(ts, agent_type, model, dur, ti, to, verdict, phase, wave)
+        print(f'Appended: {ts} {agent_type} {model} {dur}s {ti}->{to} [{verdict}] phase={phase} wave={wave}')
 
     elif cmd == 'harvest':
         harvest()
@@ -262,6 +430,10 @@ def main():
     elif cmd == 'rotate':
         rotate()
 
+    elif cmd == 'summary':
+        output_fmt = 'json' if '--json' in sys.argv else 'text'
+        summary(output_fmt)
+
     else:
         print(f'Unknown command: {cmd}')
         print(__doc__)

package/tools/halt.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""
+Fleet kill switch — a .HALT sentinel file that daemons/run-watchdog.sh (and any
+other cardinal-rule-abiding loop) must check every cycle and refuse to do work
+while it exists.
+
+Why: wave-26 critique — autonomy expanded to self-merging portfolio PRs on green
+with no ceiling/cap/limit/abort anywhere in the harness. This is the abort.
+
+API:
+  halt(reason, state_dir=None) -> Path
+    Write the .HALT sentinel (reason + UTC timestamp, JSON) under the resolved
+    state dir. Creates the state dir if missing. Overwrites any existing sentinel
+    (last halt() call wins — reason is always the most recent one).
+
+  is_halted(state_dir=None) -> bool
+    True iff the sentinel file exists.
+
+  get_halt_info(state_dir=None) -> dict | None
+    Parsed sentinel contents ({"reason": ..., "timestamp": ...}), or None if not halted.
+
+  clear_halt(state_dir=None) -> bool
+    Remove the sentinel if present. Returns True if a sentinel was removed, False
+    if there was nothing to clear (idempotent no-op).
+
+  resolve_state_dir(config=None) -> Path
+    Precedence: AESOP_STATE_ROOT env var > aesop.config.json "state_root" > default
+    (tools/common.get_state_dir(): ./state relative to cwd). Mirrors the precedence
+    documented in aesop.config.example.json's top-level "description" field.
+
+CLI:
+  python tools/halt.py set "<reason>"   -> writes sentinel, exit 0
+  python tools/halt.py --status         -> prints halted/not-halted; exit 1 if halted, 0 if not
+  python tools/halt.py --clear          -> removes sentinel if present, exit 0
+
+Sentinel location: <state_dir>/.HALT
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+try:
+    from common import get_state_dir
+except ImportError:
+    from tools.common import get_state_dir
+
+SENTINEL_NAME = ".HALT"
+
+
+def load_config():
+    """Load aesop.config.json from current directory, return dict (or {} if absent/bad)."""
+    config_file = Path("aesop.config.json")
+    if not config_file.exists():
+        return {}
+    try:
+        with open(config_file, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        print(f"[halt] Failed to load config: {e}", file=sys.stderr)
+        return {}
+
+
+def resolve_state_dir(config=None):
+    """Resolve the state directory: AESOP_STATE_ROOT env > config state_root > default.
+
+    A relative config state_root is resolved against AESOP_ROOT (if set) else cwd,
+    matching how daemons/run-watchdog.sh resolves $AESOP_ROOT/state.
+    """
+    if os.environ.get("AESOP_STATE_ROOT"):
+        return Path(os.environ["AESOP_STATE_ROOT"])
+
+    if config is None:
+        config = load_config()
+
+    state_root = config.get("state_root") if isinstance(config, dict) else None
+    if state_root:
+        p = Path(state_root).expanduser()
+        if not p.is_absolute():
+            root = Path(os.environ.get("AESOP_ROOT", Path.cwd()))
+            p = root / p
+        return p
+
+    return get_state_dir()
+
+
+def _sentinel_path(state_dir=None):
+    if state_dir is None:
+        state_dir = resolve_state_dir()
+    return Path(state_dir) / SENTINEL_NAME
+
+
+def halt(reason, state_dir=None):
+    """Write the .HALT sentinel. Returns the sentinel Path."""
+    if state_dir is None:
+        state_dir = resolve_state_dir()
+    state_dir = Path(state_dir)
+    state_dir.mkdir(parents=True, exist_ok=True)
+
+    sentinel = state_dir / SENTINEL_NAME
+    payload = {
+        "reason": str(reason),
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+    }
+    sentinel.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    return sentinel
+
+
+def is_halted(state_dir=None):
+    """True iff the .HALT sentinel exists."""
+    return _sentinel_path(state_dir).exists()
+
+
+def get_halt_info(state_dir=None):
+    """Return parsed sentinel dict, or None if not halted / unreadable."""
+    sentinel = _sentinel_path(state_dir)
+    if not sentinel.exists():
+        return None
+    try:
+        return json.loads(sentinel.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        # Sentinel exists but is corrupt — still halted, just no parsed detail.
+        return {"reason": "(unreadable sentinel)", "timestamp": None}
+
+
+def clear_halt(state_dir=None):
+    """Remove the sentinel if present. Returns True if removed, False if absent."""
+    sentinel = _sentinel_path(state_dir)
+    if sentinel.exists():
+        sentinel.unlink()
+        return True
+    return False
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+
+    if not argv:
+        print('Usage: halt.py set "<reason>" | --status | --clear', file=sys.stderr)
+        return 2
+
+    if argv[0] == "set":
+        if len(argv) < 2 or not argv[1].strip():
+            print('Usage: halt.py set "<reason>"', file=sys.stderr)
+            return 2
+        reason = " ".join(argv[1:])
+        sentinel = halt(reason)
+        print(f"HALTED: {reason}")
+        print(f"sentinel: {sentinel}")
+        return 0
+
+    if argv[0] == "--status":
+        info = get_halt_info()
+        if info:
+            print(f"HALTED: {info.get('reason')} (since {info.get('timestamp')})")
+            return 1
+        print("not halted")
+        return 0
+
+    if argv[0] == "--clear":
+        cleared = clear_halt()
+        print("cleared" if cleared else "not halted (nothing to clear)")
+        return 0
+
+    print(f"Unknown argument: {argv[0]}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())