@cyanautomation/kaseki-agent 1.4.1

package/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+All notable changes to Kaseki Agent are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.0](https://github.com/CyanAutomation/kaseki-agent/compare/v1.3.0...v1.4.0) (2026-05-08)
+
+### Features
+
+* add CLI commands for configuration, health checks, instance listing, reporting, execution, secrets management, API service, and setup wizard ([a6ddde6](https://github.com/CyanAutomation/kaseki-agent/commit/a6ddde6371a50352b2f2fdd9e6d89aa13c956286))
+* Add Pi Progress Summarizer with enhanced event handling and logging ([7aa8bb9](https://github.com/CyanAutomation/kaseki-agent/commit/7aa8bb974b645cc75c497f3acd0f8e12f1f8a9be))
+* Enhance documentation and implement new features for kaseki-agent ([4df2c4b](https://github.com/CyanAutomation/kaseki-agent/commit/4df2c4b8b30a1e05e4eb07785c75ecc44f87f53f))
+* Implement list command to display Kaseki instances with filtering and sorting ([9bd47e8](https://github.com/CyanAutomation/kaseki-agent/commit/9bd47e896f56432f5060a59d27c21ad24026e05f))
+* Migrate Kaseki Agent to NPM package and enhance documentation ([7e825f4](https://github.com/CyanAutomation/kaseki-agent/commit/7e825f46bf05176ea4eeebce12256166623155ed))
+* **validation:** enhance handling of missing npm scripts in validation commands ([1bfe5f8](https://github.com/CyanAutomation/kaseki-agent/commit/1bfe5f8d65aeb7597c88c3faaddad96157463350))
+
+## [1.3.0](https://github.com/CyanAutomation/kaseki-agent/compare/v1.2.0...v1.3.0) (2026-05-08)
+
+### Features
+
+* add instance state derivation and metadata reader scripts to the Dockerfile ([b554b33](https://github.com/CyanAutomation/kaseki-agent/commit/b554b33bf28dba4bf49acfb7402a9f718df96374))
+* enhance printf safety in github operations; add validation and logging improvements; introduce comprehensive test suite ([fd8457e](https://github.com/CyanAutomation/kaseki-agent/commit/fd8457e897fc0b82fc1ff2afc0e5b4cdf05751d1))
+* enhance validation and error handling in json_encode and validate_numeric functions; add comprehensive test suite for printf safety ([7b5c828](https://github.com/CyanAutomation/kaseki-agent/commit/7b5c828c3fa01c4d802220e4f1d26b09ff8c2c3c))
+
+### Bug Fixes
+
+* move coverage variable declaration to the correct scope in restoration summary ([04f5c38](https://github.com/CyanAutomation/kaseki-agent/commit/04f5c384342c7fcd3c5491d8dcaf5a60f31c3763))
+* optimize coverage calculation in restoration summary logging ([259d5fa](https://github.com/CyanAutomation/kaseki-agent/commit/259d5fa6673bb8b990b33a4ac20a6ed4e0f41c9e))
+* update shellcheck directives for improved script linting ([602d994](https://github.com/CyanAutomation/kaseki-agent/commit/602d9949f5cc6e268984eea05c073b6db0039de8))
+
+## [1.2.0](https://github.com/CyanAutomation/kaseki-agent/compare/v1.1.0...v1.2.0) (2026-05-07)
+
+### Features
+
+* enhance error handling in log scanning and centralize error patterns ([c485b40](https://github.com/CyanAutomation/kaseki-agent/commit/c485b405bf8b5f12dd2b26ade127a4494c65ed78))
+
+## [1.1.0](https://github.com/CyanAutomation/kaseki-agent/compare/v1.0.1...v1.1.0) (2026-05-07)
+
+### Features
+
+* add extraction functions for validation and quality failure reasons ([f8f8ef3](https://github.com/CyanAutomation/kaseki-agent/commit/f8f8ef3327d90e396cdb3df00bf4b5ed5ab9a834))
+* enhance documentation with additional guidance on allowlist patterns and task prompts ([17451da](https://github.com/CyanAutomation/kaseki-agent/commit/17451da713cc4755f450d88fe13e360a7d5721a0))
+* enhance error reporting with structured failure reasons and API updates ([8846e9d](https://github.com/CyanAutomation/kaseki-agent/commit/8846e9d2bb1c903793269723de887ee27d3189c7))
+* enhance pre-flight validation with comprehensive pattern matching functions and integration tests ([0480bc5](https://github.com/CyanAutomation/kaseki-agent/commit/0480bc5066aa67e3582936d6a4188bd8acb62280))
+* Implement comprehensive allowlist restoration system in kaseki-agent ([9367503](https://github.com/CyanAutomation/kaseki-agent/commit/9367503ac3ad1d3dd53afd63bbc8b981665e843e))
+* implement fail-fast validation behavior in Kaseki Agent ([d07b28c](https://github.com/CyanAutomation/kaseki-agent/commit/d07b28ccae7215064b43d4ec610b2e4df60abb9c))
+* Implement Phase 1 Error Reporting Enhancements ([421390b](https://github.com/CyanAutomation/kaseki-agent/commit/421390b7ab063cc8839116c4b9de37c2d0806d04))
+* remove trigger for Docker build workflow after release ([99ed6c5](https://github.com/CyanAutomation/kaseki-agent/commit/99ed6c5d03a161ba0eda5a6c792e27bb10849b3b))
+
+## [1.0.1](https://github.com/CyanAutomation/kaseki-agent/compare/v1.0.0...v1.0.1) (2026-05-07)
+
+### Bug Fixes
+
+* disable PR comments in semantic-release to avoid permission errors ([0701e3e](https://github.com/CyanAutomation/kaseki-agent/commit/0701e3ebf6042a2999102c6cae19c1c7f33dee4c))
+
+## 1.0.0 (2026-05-07)
+
+### Features
+
+* add artifact, log, status, and webhook routes ([d592e12](https://github.com/CyanAutomation/kaseki-agent/commit/d592e129038fac33cb7541e77e1776baf30edfa9))
+* Add comprehensive implementation summary for Kaseki Agent API service ([bad4d94](https://github.com/CyanAutomation/kaseki-agent/commit/bad4d94fccc0bc5feab07c64def7a41a897ca7f8))
+* add kaseki-cli command-line interface and demo ([0d2a566](https://github.com/CyanAutomation/kaseki-agent/commit/0d2a566156b15fae950c8115d4591236eb3763bf))
+* Add post-implementation verification checklist for Kaseki Agent ([bb5e8ad](https://github.com/CyanAutomation/kaseki-agent/commit/bb5e8ad8d441e81781e421d248cbc0e4ff040b54))
+* add semantic release configuration and changelog ([d77a35a](https://github.com/CyanAutomation/kaseki-agent/commit/d77a35ab7eb6f2ccbe9676b227223764a55bef74))
+* add test utilities and validation tests for PreFlightValidator and configuration loading ([47bbed6](https://github.com/CyanAutomation/kaseki-agent/commit/47bbed69ad13351b804dc417fe7f3e6c831acc0f))
+* Implement EventCounterAggregator for event stream processing ([be990ac](https://github.com/CyanAutomation/kaseki-agent/commit/be990ace9b16924c706b09070f0a986883d46686))
+* Implement idempotency support and pre-flight validation for job submissions ([d5e0592](https://github.com/CyanAutomation/kaseki-agent/commit/d5e05923ddd3596c471ac86ff867f25cefa92e39))
+* Implement Kaseki API client and service ([c779c9e](https://github.com/CyanAutomation/kaseki-agent/commit/c779c9e27ff09c2bc621019f883e026ced45732a))
+* migrate project to TypeScript and update testing framework ([9309bdc](https://github.com/CyanAutomation/kaseki-agent/commit/9309bdc551c76841c61f60dcf481b6bcbceb2a7b))
+* Refactor and expand public API exports, add job lookup middleware, and implement utility functions ([74dfd62](https://github.com/CyanAutomation/kaseki-agent/commit/74dfd62f442dfa58b97fd201994f4fb9f539d4ce))
+
+### Bug Fixes
+
+* Adjust formatting in verification checklist for clarity ([e028619](https://github.com/CyanAutomation/kaseki-agent/commit/e0286191e1d9056264d10339c7f619658d16fa64))
+* correct regex pattern for matching imports in add-js-extensions script ([4cbe203](https://github.com/CyanAutomation/kaseki-agent/commit/4cbe2031a7364022463ac10bf2f030e1ca140b12))
+* Correct regex pattern for matching imports in add-js-extensions.ts ([38fb48a](https://github.com/CyanAutomation/kaseki-agent/commit/38fb48a16c5ad869dc5efe36b1f906d7910a70d9))
+* correct regex pattern for matching imports without extensions ([79bdabe](https://github.com/CyanAutomation/kaseki-agent/commit/79bdabe0a744bf7568c1af68f2dc91af76e532f1))
+* correct regex pattern for matching relative imports in add-js-extensions script ([fb8f509](https://github.com/CyanAutomation/kaseki-agent/commit/fb8f509ea05a1bc460f4caa29e1113069bf00c81))
+* disable no-explicit-any rule in TypeScript ESLint configuration ([ed905cb](https://github.com/CyanAutomation/kaseki-agent/commit/ed905cb7e8ef937989bc0ccfa5f56c6ce4d3a58c))
+* Update readFileSync mock handling and improve instance stage resolution logic ([7e5afb8](https://github.com/CyanAutomation/kaseki-agent/commit/7e5afb87b2ab9fa808b3af9daad7c563dc48800d))
+
+## [Unreleased]
+
+### Features
+
+### Bug Fixes
+
+### Documentation
+
+### Performance Improvements
+
+---
+
+## [0.1.0] - 2026-05-07
+
+### Features
+- Initial release of Kaseki Agent ephemeral coding-agent runner
+- Multi-stage Docker build with dependency caching
+- OpenRouter API integration for Pi CLI coding agents
+- GitHub Actions workflow for multi-arch image builds (amd64 + arm64)
+- Quality gates: diff size limits, changed-file allowlist, secret scanning
+- Kaseki CLI for monitoring and analyzing runs
+- Kaseki API service for job scheduling and webhook management
+- Comprehensive logging and result artifacts
+
+### Bug Fixes
+
+### Documentation
+- Complete README with usage examples
+- Contributing guidelines for prompt changes and test expectations
+- Deployment documentation for Docker Compose and Node.js
+- Development workflow guide
+- API documentation and CLI reference
+
+[Unreleased]: https://github.com/CyanAutomation/kaseki-agent/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/CyanAutomation/kaseki-agent/releases/tag/v0.1.0

package/CLAUDE.md

@@ -0,0 +1,336 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+Kaseki Agent is an ephemeral coding-agent runner: it spins up a disposable Docker container, clones a target Git repository inside it, invokes the Pi CLI coding agent via OpenRouter, runs validation commands, and collects artifacts. Each run is a numbered instance (kaseki-1, kaseki-2, …).
+
+## Current Infrastructure Status (May 2026)
+
+- **Node.js**: v24 (bookworm-slim base image)
+- **Docker Build**: Optimized multi-stage with consolidated RUN layers
+- **CI/CD**: Parallelized pipeline with GHA caching (80-90% hit rate)
+  - **GitHub Actions**: All actions updated to native Node.js 24 support (v6+ for checkout/setup-node, v7+ for upload-artifact)
+  - **Trivy Scanner**: Pinned to v0.36.0 (no floating @master refs)
+- **Security**: Trivy scanning with SBOM generation
+- **Deployment**: Docker Compose (preferred) with Node.js fallback
+
+## Architecture: Host-Container Separation
+
+Two layers, each with its own script:
+
+**Host (`run-kaseki.sh`)** — runs on the bare host:
+
+- Auto-generates instance names, creates per-run workspace and results directories
+- Resolves the OpenRouter API key (env var or secret file), mounts it read-only
+- Launches Docker with hardened runtime flags (`--read-only`, `--cap-drop ALL`, tmpfs, non-root user)
+- Cleans up on exit
+
+**Container (`kaseki-agent.sh`)** — runs inside the container:
+
+- Clones the repo at the requested ref
+- Prepares Node.js dependencies via a 4-layer cache (stamp check → workspace cache → image seed cache → fresh install)
+- Invokes Pi with a configurable timeout
+- Runs validation commands sequentially, recording timings
+- Enforces quality gates (diff size, changed-file allowlist, secret scan)
+- Writes all artifacts to `/results`
+
+**Supporting utilities (Node.js):**
+
+- `pi-event-filter.js` — filters raw Pi JSONL, strips thinking blocks, emits `pi-events.jsonl` + `pi-summary.json`
+- `kaseki-report.js` — reads a results directory and prints a compact diagnostic report
+- `kaseki-cli.js` + `kaseki-cli-lib.js` — live monitoring CLI for external AI agents (see [docs/CLI.md](docs/CLI.md))
+
+**Directory layout at runtime:**
+
+```
+/agents/kaseki-template/          # Dockerfile, scripts (this repo)
+/agents/kaseki-runs/kaseki-N/     # Per-run workspace (cloned repo, node_modules)
+/agents/kaseki-results/kaseki-N/  # Artifacts (logs, diff, metadata, summary)
+/agents/kaseki-cache/             # Optional host-level dependency cache
+```
+
+## Common Commands
+
+```bash
+# Basic run (auto-generates kaseki-N)
+OPENROUTER_API_KEY=sk-or-... ./run-kaseki.sh
+
+# Explicit instance name
+OPENROUTER_API_KEY=sk-or-... ./run-kaseki.sh kaseki-7
+
+# API key via secret file
+OPENROUTER_API_KEY_FILE=~/secrets/openrouter_api_key ./run-kaseki.sh
+
+# Custom target repo + branch
+REPO_URL=https://github.com/org/repo GIT_REF=feature/branch OPENROUTER_API_KEY=... ./run-kaseki.sh
+
+# Health/sanity check (no agent run)
+./run-kaseki.sh --doctor
+
+# Build image locally
+docker build -t kaseki-template:latest .
+
+# Generate diagnostic report for a completed run
+docker run --rm --entrypoint kaseki-report \
+  -v /agents/kaseki-results/kaseki-4:/results:ro \
+  kaseki-template:latest /results
+```
+
+## Deploying the Kaseki API Service
+
+### ✅ Recommended: Docker Compose
+
+```bash
+# Start the API service (see docs/DEPLOYMENT.md for full options)
+export KASEKI_API_KEYS=sk-your-secret-key
+cd /agents/kaseki-template
+docker-compose up -d
+
+# Monitor
+docker-compose logs -f kaseki-api
+```
+
+### Fallback: Node.js Process
+
+```bash
+# Install and run (if Docker is unavailable)
+npm install
+KASEKI_API_KEYS=sk-your-secret-key npm run kaseki-api
+```
+
+See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for comprehensive deployment guidance.
+
+## Key Environment Variables
+
+| Variable | Default | Notes |
+|---|---|---|
+| `OPENROUTER_API_KEY` | — | Required (or use file) |
+| `OPENROUTER_API_KEY_FILE` | `/run/secrets/openrouter_api_key` | Preferred; mounted read-only |
+| `REPO_URL` | CyanAutomation/crudmapper | Target repo |
+| `GIT_REF` | main | Branch/tag/commit |
+| `KASEKI_MODEL` | openrouter/free | Pi model string |
+| `KASEKI_AGENT_TIMEOUT_SECONDS` | 1200 | Pi invocation timeout |
+| `TASK_PROMPT` | *(code fix task)* | Agent instruction |
+| `KASEKI_VALIDATION_COMMANDS` | `npm run check;npm run test;npm run build` | Semicolon-separated; missing npm scripts are skipped (non-fatal) |
+| `KASEKI_CHANGED_FILES_ALLOWLIST` | `src/lib/parser.ts tests/parser.validation.ts` | Space-separated patterns (agent phase) |
+| `KASEKI_VALIDATION_ALLOWLIST` | — | Space-separated patterns (validation phase; optional) |
+| `KASEKI_MAX_DIFF_BYTES` | 200000 | Max diff size (200 KB) |
+| `KASEKI_DEBUG_RAW_EVENTS` | 0 | Keep raw Pi JSONL |
+| `KASEKI_KEEP_WORKSPACE` | 0 | Remove per-run workspace after each run |
+| `KASEKI_STREAM_PROGRESS` | 1 | Stream sanitized progress lines |
+| `KASEKI_IMAGE` | docker.io/cyanautomation/kaseki-agent:latest | Image to use |
+
+## Quality Gates and Exit Codes
+
+Quality gates run after the agent completes, before reporting success:
+
+| Gate | Exit Code | Variable |
+|---|---|---|
+| Missing API key / config | 2 | — |
+| Empty git diff | 3 | — |
+| Diff exceeds max bytes | 4 | `KASEKI_MAX_DIFF_BYTES` |
+| Changed file outside allowlist | 5 | `KASEKI_CHANGED_FILES_ALLOWLIST` |
+| Validation phase files outside allowlist | 7 | `KASEKI_VALIDATION_ALLOWLIST` |
+| Secret scan hit (sk-or-* leak) | 6 | — |
+| Pi agent timeout | 124 | `KASEKI_AGENT_TIMEOUT_SECONDS` |
+| Validation command failure | propagated | `KASEKI_VALIDATION_COMMANDS` |
+
+## Result Artifacts
+
+All written to `/agents/kaseki-results/kaseki-N/`:
+
+- `metadata.json` — timestamps, exit codes per stage, model, instance name
+- `result-summary.md` — human-readable status + key facts
+- `pi-events.jsonl` / `pi-summary.json` — filtered agent events and stats
+- `git.diff` / `git.status` / `changed-files.txt` — repo changes
+- `validation.log` / `validation-timings.tsv` — command output + timing
+- `quality.log` / `secret-scan.log` — gate failures
+- `restoration.jsonl` — structured allowlist restoration events (JSONL format)
+- `restoration-report.md` — human-readable allowlist restoration report
+- `progress.log` / `progress.jsonl` — sanitized stage and Pi event progress
+- `cleanup.log` — mandatory post-run cleanup summary
+- `stdout.log` / `stderr.log` / `exit_code` — raw execution output
+
+## Dependency Caching
+
+`kaseki-agent.sh` uses a stamp-based, 4-layer cache to avoid redundant `npm ci` runs:
+
+1. Check if node_modules + lock hash stamp already match → skip
+2. Restore from workspace cache (`/workspace/.kaseki-cache/<repo-hash>/<lock-hash>/`)
+3. Restore from image seed cache (`/opt/kaseki/workspace-cache/`)
+4. Run `npm ci --prefer-offline` or `npm install`
+
+The stamp file lives outside the repo directory to keep `git.status` clean.
+
+## Security Hardening
+
+- API key is **never passed as an env var to child processes** — resolved from file at runtime
+- Docker runtime: `--read-only`, `--cap-drop ALL`, `--security-opt no-new-privileges:true`, non-root user (UID 10001)
+- Secret scan checks the results, workspace git metadata, and source dirs for `sk-or-*` patterns
+
+## Container Image Scanning
+
+Kaseki-agent container images are scanned for vulnerabilities using industry-standard tools:
+
+### Automated Scanning (CI/CD)
+
+GitHub Actions automatically scans images on every build using **Trivy**:
+
+```yaml
+- name: Run Trivy vulnerability scanner
+  uses: aquasecurity/trivy-action@v0.36.0
+  with:
+    image-ref: 'docker.io/cyanautomation/kaseki-agent:latest'
+    format: 'sarif'
+    output: 'trivy-results.sarif'
+    severity: 'HIGH,CRITICAL'
+
+- name: Upload to GitHub Security tab
+  uses: github/codeql-action/upload-sarif@v4
+  with:
+    sarif_file: 'trivy-results.sarif'
+```
+
+Results are published to GitHub's **Security** → **Dependabot alerts** tab.
+
+### Manual Scanning
+
+To scan the image locally:
+
+```bash
+# Install Trivy (macOS)
+brew install trivy
+
+# Install Trivy (Linux)
+curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin
+
+# Scan latest image
+trivy image docker.io/cyanautomation/kaseki-agent:latest
+
+# Scan with severity filter
+trivy image --severity HIGH,CRITICAL docker.io/cyanautomation/kaseki-agent:latest
+
+# Generate JSON report
+trivy image --format json --output report.json docker.io/cyanautomation/kaseki-agent:latest
+```
+
+### Known Vulnerabilities
+
+Check GitHub Settings → Code security → Dependabot alerts for any discovered vulnerabilities. Most are transitive (in Pi CLI dependencies) and are addressed via dependency updates.
+
+### Image Integrity (Optional)
+
+Images can be signed using **cosign** for supply chain security:
+
+```bash
+# Verify signed image (requires public key)
+cosign verify --key cosign.pub docker.io/cyanautomation/kaseki-agent:latest
+
+# View image attestation
+cosign verify-attestation --key cosign.pub docker.io/cyanautomation/kaseki-agent:latest
+```
+
+See [SECURITY.md](SECURITY.md) for detailed vulnerability response procedures.
+
+## Diagnosing Failures
+
+Recommended inspection order:
+
+1. `kaseki-report /agents/kaseki-results/kaseki-N` (compact summary, includes allowlist metrics)
+2. `result-summary.md` → status + failed command
+3. `restoration-report.md` → if many files were restored before validation
+4. `metadata.json` → per-stage exit codes
+5. `stdout.log` / `stderr.log` → execution flow
+6. `pi-summary.json` / `pi-events.jsonl` → agent activity
+7. `validation.log` + `validation-timings.tsv` → command failures
+8. `quality.log` + `changed-files.txt` → allowlist/diff violations
+9. `secret-scan.log` → credential detection
+
+## Allowlist Configuration & Troubleshooting
+
+**Problem: Too many files are restored before validation?**
+
+See [docs/QUALITY_GATES.md](docs/QUALITY_GATES.md) for:
+
+- Allowlist pattern syntax and examples
+- Pre-built templates for common task types
+- How to use `scripts/suggest-allowlist.sh` to auto-generate patterns
+- How to use `scripts/dry-run-allowlist.sh` to preview restoration
+- Decision tree for choosing the right allowlist
+
+**Problem: Agent made too many unintended changes?**
+
+See [docs/TASK_PROMPT_TEMPLATES.md](docs/TASK_PROMPT_TEMPLATES.md) for:
+
+- How to write clear, scoped task prompts
+- Examples of good vs. bad prompts
+- Anti-patterns that lead to scope creep
+- How to combine prompts with allowlist for best results
+
+## CI/CD
+
+`.github/workflows/build-docker-image.yml` builds multi-arch images (amd64 + arm64 via QEMU), runs smoke tests (Pi CLI available, metadata structure valid), and publishes to `docker.io/cyanautomation/kaseki-agent:latest`.
+
+## External Agent Monitoring with Kaseki CLI
+
+The **Kaseki CLI** enables external AI agents to interrogate running and completed kaseki instances in real-time. This is useful for:
+
+- **Status polling**: Get current stage, elapsed time, timeout risk
+- **Error detection**: Identify failures in validation, quality gates, secret scans
+- **Anomaly flagging**: Warn when timeout is imminent (>85% elapsed)
+- **Log streaming**: Follow logs live as agent runs
+- **Post-run analysis**: Comprehensive summary of changes, validation results, metrics
+
+### Quick Example
+
+```bash
+# List all instances
+./kaseki-cli.js list
+
+# Get status of a running instance (JSON)
+./kaseki-cli.js status kaseki-1
+
+# Detect errors
+./kaseki-cli.js errors kaseki-1
+
+# Get post-run analysis
+./kaseki-cli.js analysis kaseki-1
+
+# Live monitor with anomaly alerts
+./kaseki-cli.js watch kaseki-1 --interval=2
+
+# Stream logs in real-time
+./kaseki-cli.js follow kaseki-1
+
+# Show sanitized progress events
+./kaseki-cli.js progress kaseki-1 --tail=25
+```
+
+### Integration Pattern
+
+An external agent can use the CLI to monitor kaseki:
+
+```bash
+#!/bin/bash
+while true; do
+  STATUS=$(./kaseki-cli.js status kaseki-1)
+  RUNNING=$(echo $STATUS | jq -r '.running')
+  TIMEOUT_RISK=$(echo $STATUS | jq -r '.timeoutRiskPercent')
+  
+  # Alert on timeout risk
+  if (( $(echo "$TIMEOUT_RISK >= 85" | bc -l) )); then
+    echo "⚠ Timeout imminent: ${TIMEOUT_RISK}%"
+  fi
+  
+  # Exit when complete
+  [ "$RUNNING" = "false" ] && break
+  sleep 5
+done
+
+# Final analysis
+./kaseki-cli.js analysis kaseki-1
+```
+
+See [docs/CLI.md](docs/CLI.md) for comprehensive documentation, library usage, and advanced integration patterns.