@theihtisham/agent-shadow-brain 7.0.0 → 7.1.3

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [7.1.3] - 2026-11-11 - Live activity and curated memory
+
+This release follows 7.2.0 using the version number requested by the maintainer. Install `@7.1.3` explicitly when upgrading from 7.2.0.
+
+- Added a live portal with an event-driven session network, measured tool charts, host-reported phases, timeline, pause, and reduced motion.
+- Added a bounded cross-process activity journal, cursor and reset detection, metadata-only MCP instrumentation, host reporting, and separate recording and visibility controls.
+- Added memory review, typed relations, audit history, and project-scoped curation through the workspace and CLI.
+- Excluded archived, contested, and superseded memories before context ranking; briefings refresh when reviews change.
+- Added standard MCP stdio, client capability checks, project skill diagnostics, and generated launch configuration.
+- Improved workspace navigation, source coverage, graph filtering, context explanations, dark mode, and mobile layouts.
+- Fixed empty-project graph scope, preservation of pending writes during read refresh, and per-client attach/detach targeting.
+
+
+## [7.2.0] - 2026-11-11 - Context Packs and Workspace
+
+- Make the local workspace the default dashboard with overview, searchable memories, graph, context, and feature controls. Keep the previous dashboard at `/advanced`.
+- Build size-bounded, project-scoped context packs with ranked memory selection, duplicate handling, recorded source provenance, and selection explanations.
+- Use context packs for session briefings. Key cached results to the task and current settings, and check enablement before reading or returning a briefing.
+- Persist four validated feature settings for context assembly, explicit cross-project context, automatic briefings, and dashboard activity delivery.
+- Add `context-pack` and `features list|set` commands, read-only `context_pack` and `feature_flags` MCP tools, and public context and settings APIs.
+- Refresh the README and workspace guide with a concept illustration and dashboard screenshots.
+
+## [7.1.0] - 2026-11-11 - Focused Workflows and Portable Skills
+
+- Bundle six reusable skills for proportionate planning, implementation, diagnosis, review, research, and release work.
+- Add project-local skill installation for Codex, Claude Code, OpenCode, DeepSeek Harness, and compatible portable clients. Preview by default; preserve user instructions, reject conflicting local edits and stale plans, validate paths, and back up managed updates.
+- Add `skills list`, `skills show`, `skills targets`, `skills install`, and `workflow analyze` CLI commands.
+- Add read-only `workflow_analyze` and `workflow_skills` MCP tools and public library APIs.
+- Respect plan-only, diagnosis-only, and review-only scope in advisory routing. Add explicit task, mode, and complexity overrides; no provider calls or automatic task execution.
+- Verify skill packaging, fresh-consumer installation, safe update behavior, and representative task scenarios.
+
 
 ## [7.0.0] - 2026-11-11 - Durable Memory and Explained Recall
 

package/README.md

@@ -1,428 +1,90 @@
 # Agent Shadow Brain
 
-Local-first memory and coordination for AI coding agents.
+Agent Shadow Brain gives coding agents a shared local memory and a workspace you can inspect. Keep project decisions and sources together, review what is still useful, and build focused context for the next task. The live portal shows recorded sessions, tool calls, and host-reported task phases.
 
-Version: 7.0.0
+![Concept diagram showing coding agents sharing project memories and receiving a scoped, size-limited context pack](docs/assets/context-flow-v7.2.png)
 
+*Concept illustration of the memory and context flow.*
 
-Agent Shadow Brain gives tools like Codex, Claude Code, Cursor, Cline, OpenCode, Aider, and related MCP clients a shared local memory layer. It stores compact, source-backed lessons about projects, recalls them later, generates fresh-session briefings, audits memory quality, and exports JSONL training/eval packs.
+## Get started
 
-It does not change model weights by itself. It helps agents work better by giving them relevant, current, source-linked context before and during complex work.
-
-## What's New in 7.0.0
-
-- **Durable multi-agent memory.** Saves lock, reload, and merge the latest store so independent agents cannot replace each other's new memories. Queued writes acknowledge success after persistence. Failed operations remain retryable and visible in storage health.
-- **Explainable recall.** Results include matched keywords, score components, and identities reporting the same normalized content within the same project and category. Unrelated notes no longer inflate scores. Scores are ranking heuristics, not probabilities of truth or proof of independent verification.
-- **Storage diagnostics.** Use `shadow-brain storage-health --json` or MCP `global_storage_health` to inspect errors and pending operations. Invalid or unsupported stores fail explicitly and remain unchanged.
-- **Safer setup and packaging.** Installation no longer edits agent settings. Help, version, and memory diagnostics do not load provider configuration. Dependencies are refreshed, activity-log text is escaped, and package tests install a real tarball into a fresh consumer project.
-
-### Upgrade from 6.x
-
-Use Node.js 22.12+ within 22.x, Node 24.x, or Node 26+. Back up your existing `global.json` before upgrading and stop older Shadow Brain writers; older versions do not participate in the new lock protocol. The schema remains version 1. Start integrations explicitly using the existing setup/attach commands after installation.
-
-`writeSync()` remains an in-memory operation; call `await brain.sync()` for durable persistence. `await brain.write()` resolves after the background sync or an explicit sync; a false result means persistence failed or the queue was full. Failed accepted operations remain pending for retry. Recall reads the process snapshot, refreshed by sync; it is not an instantaneous cross-process read.
-
-### New commands
-
-```bash
-shadow-brain storage-health --json
-shadow-brain storage-health --db ./global.json --json
-shadow-brain recall-explain "deployment rollback" --limit 5
-shadow-brain recall-explain "database migration" --project . --min-confidence 0.4
-```
-
-`storage-health` validates readability and schema, reports JSON even on failure, and exits with code 1 for an invalid store. It does not repair or rewrite an existing store; when checking a missing store it may create its parent directory. `lastSuccessfulSync` describes the current process only. The MCP health tool inspects existing process state without initializing or flushing it.
-
-The library exports `GlobalBrain`, `getGlobalBrain`, and their public types:
-
-```js
-import { getGlobalBrain } from '@theihtisham/agent-shadow-brain';
-const brain = getGlobalBrain({ dbPath: './global.json' });
-await brain.init();
-console.log(brain.recallScored({ keywords: ['deployment'], limit: 5 }));
-console.log(brain.getStorageHealth());
-await brain.shutdown();
-```
-
-Details: [release notes](docs/launch/RELEASE_NOTES_v7.0.0.md).
-
-## Earlier dashboard features
-
-- **Simple by default, Advanced on demand.** The dashboard opens with eight plain-English tabs (Home, Brain Map, Memories, Ask the Brain, Activity, Connected Tools, Brain Health, Settings). Flip to Advanced to reveal every feature — nothing was removed, just tidied.
-- **Brain Map.** An interactive graph of everything the brain remembers — memories, projects, tools, and tags — sized by importance (PageRank) and linked by shared context. Zoom, pan, click a node for details, and watch it grow live as new memories arrive.
-- **Realtime activity.** Memory writes, reflections, and tool events stream live over WebSocket instead of polling, with a live pulse on Home.
-- **Live Network.** A refreshed animation of your tools talking to the brain, with flowing signal pulses.
-- **Two-way knowledge seeding.** Quick-Save captures knowledge in one click; "Hand to Agent" generates a ready briefing to pass context back to any tool.
-- **Plain-language everywhere.** Cryptic feature names rewritten (e.g. Calibration → Accuracy, Pre-Mortem → Risk Check, Tokens → Cost & Usage), each with a hover description.
-
-
-## What It Actually Does
-
-- Stores cross-project and cross-agent memories in a local JSON brain at `~/.shadow-brain/global.json`.
-- Recalls memories by project, agent, category, and keywords.
-- Generates source-backed resume packs for fresh sessions, account switches, context compaction, and handoffs.
-- Audits memory quality: source coverage, stale entries, duplicates, low-quality notes, recall health.
-- Creates verified memory seed drafts from dashboard/API, then requires user, agent, or dual approval before writing to durable memory.
-- Exports JSONL rows for evals, distillation, or local fine-tuning pipelines.
-- Provides CLI, dashboard API, and MCP tool surfaces.
-- Includes safety helpers such as hook audit, detach, and action firewall checks.
-- Works without telemetry and without an API key for local memory features.
-
-## What It Does Not Claim
-
-- It does not secretly train GPT, Claude, Gemini, or any remote model.
-- It does not guarantee perfect recall.
-- It does not replace project docs, tests, source control, or human review.
-- It does not make every listed agent automatically available. Agent support depends on local installation and hook/config compatibility.
-- It does not publish or sync data unless you explicitly use export, sync, or other sharing commands.
-
-## Install
-
-```bash
-npm install -g @theihtisham/agent-shadow-brain
-```
-
-CLI binaries:
-
-```bash
-shadow-brain --help
-asb --help
-```
-
-You can also run without global install:
-
-```bash
-npx @theihtisham/agent-shadow-brain@latest --help
-```
-
-## Safe First Run
-
-Start by auditing before attaching hooks:
-
-```bash
-shadow-brain audit-hooks .
-shadow-brain live-brain status .
-```
-
-Only attach after you review what will be changed:
-
-```bash
-shadow-brain attach-all .
-```
-
-Detach later if needed:
-
-```bash
-shadow-brain detach-all .
-```
-
-## v6.0.3: Live Brain
-
-The 6.0.3 release focuses on practical long-memory improvement for agents.
-
-### Live Brain Status
-
-```bash
-shadow-brain live-brain status .
-```
-
-Shows:
-
-- memory count
-- average memory quality
-- source coverage
-- stale memories
-- duplicate clusters
-- recall eval score
-- recommended cleanup actions
-
-JSON output:
-
-```bash
-shadow-brain live-brain status . --json
-```
-
-### Agent Briefing
-
-Generate a markdown briefing for a fresh agent session:
-
-```bash
-shadow-brain live-brain brief . -o SHADOW_BRAIN_AGENT_BRIEF.md
-```
-
-The briefing includes:
-
-- rules for agents
-- top source-backed memories
-- memory warnings
-- recall health
-- commands agents should run next
-
-### Recall Eval
-
-Check whether the brain can retrieve useful memories for common agent tasks:
-
-```bash
-shadow-brain live-brain eval .
-```
-
-Custom eval queries use pipe separators:
-
-```bash
-shadow-brain live-brain eval . --queries "current blocker|do not repeat|verified command"
-```
-
-### Memory Hygiene
-
-List concrete cleanup and learning actions:
-
-```bash
-shadow-brain live-brain hygiene .
-```
-
-This highlights missing sources, stale memories, duplicates, weak recall, and missing project-scoped memories.
-
-### Training/Eval Export
-
-Export source-backed memories as JSONL:
+Use Node.js 22.12+ within 22.x, Node.js 24.x, or Node.js 26+.
 
 ```bash
-shadow-brain live-brain train-pack . --out shadow-brain-training.jsonl
+npm install -g @theihtisham/agent-shadow-brain@7.1.3
+shadow-brain dash . --no-analysis
 ```
 
-This is useful for:
+Run the dashboard command from your project directory. It opens the local workspace and skips background project analysis. Open the printed address if the browser does not start automatically. Use a second terminal for other commands while the dashboard is running.
 
-- retrieval evals
-- local distillation experiments
-- supervised fine-tuning datasets
-- memory regression tests
+## Watch activity as it happens
 
-The export is only data preparation. You choose the downstream training/eval tool.
+Open **Live** in the workspace, or add `/live` to its address. Select a session to inspect its event network, reported phases, and timeline. Charts summarize tool throughput, errors, and measured duration in the loaded window. Pause updates or reduce motion at any time.
 
-## Core Memory Commands
+![Live portal with a session network, observed tool calls, timing charts, and host-reported task phases](docs/assets/live-v7.1.3.png)
 
-Recall from the global brain:
+*Running portal with scripted local MCP clients and synthetic data. Client labels in this demonstration do not prove native client installation or model connectivity.*
 
-```bash
-shadow-brain global recall --query "current blocker next step" --json --limit 8
-```
+The standalone MCP service measures calls made through it. A connected host can explicitly report phases or its own tool events; these remain labeled **Host-reported**. Activity recording stores bounded metadata, not prompts, tool arguments, or memory content. The latest 500 events are retained, with visible notices for incomplete windows.
 
-Show global stats:
+## Review the context your agent uses
 
-```bash
-shadow-brain global stats
-```
+- **Overview** shows project inventory, review states, recorded-source coverage, and recent activity.
+- **Memories** lets you inspect content, sources, review history, and links. Mark entries active, archived, or contested.
+- **Graph** connects projects, agents, and memories, including explicit support, contradiction, and replacement links.
+- **Context** builds a copyable project pack and explains what was selected or excluded.
+- **Integrations** shows client capabilities, project skill-file presence, and safe local diagnostics.
+- **Features** controls context packs, cross-project context, automatic briefings, activity visibility, and activity recording separately.
 
-Create a source-backed resume seed:
+![Workspace overview with project inventory, review states, and source coverage](docs/assets/overview-v7.1.3.png)
 
-```bash
-shadow-brain resume-seed . -o SHADOW_BRAIN_RESUME_SEED.md
-```
+![Memory detail showing recorded references, review controls, relationships, and audit history](docs/assets/memory-detail-v7.1.3.png)
 
-Show what a project has learned:
+*Workspace screenshots use synthetic memories. Recorded references and manual reviews help you check a claim; they do not establish its truth.*
 
-```bash
-shadow-brain timeline . --limit 30
-```
+Open **Advanced tools** or visit `/advanced` for the previous dashboard. [Workspace guide](docs/WORKSPACE.md)
 
-Create a cross-agent handoff packet:
+## Build a context pack
 
 ```bash
-shadow-brain handoff codex claude-code . --task "continue release verification"
+shadow-brain context-pack "import retry behavior" --project . --token-budget 1200
+shadow-brain features list
+shadow-brain features set automaticBriefing off
 ```
 
-Record a durable memory from a script:
-
-```bash
-node tools/record-global-memory.mjs ^
-  --project-dir "." ^
-  --project-name "my-project" ^
-  --agent codex ^
-  --category "project.lesson" ^
-  --importance 0.8 ^
-  --tags "memory,release" ^
-  --sources "README.md,CHANGELOG.md" ^
-  --content "Keep release notes source-backed and verify npm metadata before publish."
-```
+A pack starts with the selected project's memories, excludes archived, contested, and superseded entries before ranking, collapses exact duplicates, and fits the rendered text to a size budget. Add `--json` to see selection reasons, sources, and recorded relationships. Cross-project context requires both an enabled feature setting and an explicit request. Token counts are estimates.
 
-## Dashboard
+Automatic briefings use the same context selection. Cached briefings follow the current task, feature settings, and memory reviews. Inspect and change reviews in the workspace or with `shadow-brain curate --help`.
 
-Start the local dashboard:
+## Connect your coding client
 
 ```bash
-shadow-brain dash . --no-open --port 7341
+shadow-brain clients config
+shadow-brain mcp --stdio
 ```
 
-For a fast UI/API-only launch on a large repo:
+`clients config` prints a launch configuration for the installed CLI. Add it to a compatible MCP client. The stdio service provides nine read-only memory and workflow tools plus an explicit `activity_report` tool for host reports. It runs without loading provider configuration. Configure your client to use `context_pack` for curated context.
 
-```bash
-shadow-brain dash . --no-open --no-analysis --host 127.0.0.1 --port 7341
-```
+Codex, Claude Code, OpenCode, and DeepSeek Harness have documented integration paths. DeepSeek Harness requires its MCP client and filesystem skill plugins. The Integrations view checks project skill files; loading them in a host is a separate step. [Connection and activity guide](docs/WORKSPACE.md)
 
-Open:
-
-```text
-http://127.0.0.1:7341
-```
+## Add skills to a project
 
-The v6 dashboard includes a **Live Brain** tab for memory health, source coverage, recall evals, hygiene actions, top memories, and the generated agent briefing.
-
-It also includes:
-
-- **Memory Browser intelligence cards** for total memories, source coverage, fresh learning, seed queue, top categories, agent coverage, and top tags.
-- **Memory Seeder** for controlled research-to-memory workflows. Drafts stay out of the global brain until approval is complete.
-- **Token Economy accuracy split**: current runtime agent is shown separately from historical model spend, so old Claude/Cursor spend records do not imply the dashboard is running that agent.
-
-### Realtime Activity (new in 6.1.0)
-
-The dashboard now streams brain activity live over its WebSocket instead of polling. Memory writes, dreams, seed drafts/commits, collisions, sub-agent spawns, and consolidation cycles appear the instant they happen.
-
-- **Live Pulse** card on the Overview with a streaming mini-feed and an events/min rate.
-- **Activity Log** tab with filter chips, a pulsing LIVE badge, pause/resume, clear, search, and an events/min sparkline.
-- **Connection indicator** in the header — green when the realtime socket is live, amber while reconnecting.
-- **Cross-process aware**: a memory written by an agent in a *different* terminal is picked up by watching `~/.shadow-brain/global.json`, so the feed reflects the whole machine, not just this process.
-
-Polling remains as a 15-second reconciliation fallback; live events arrive in well under a second.
-
-### Intelligence Hub — Memory Constellation (new in 6.2.0)
-
-A new **Intelligence** tab turns the brain into an interactive graph. Every memory, project, agent, and tag is a node in a force-directed **Memory Constellation**, sized by importance (PageRank blended with each memory's own score) and linked by project, author, tags, and shared-tag relatedness.
-
-- **Interactive**: scroll to zoom, drag to pan, click a node to focus its neighborhood and open a detail drawer; hover for a tooltip.
-- **Filters + search** by node type (memory / project / agent / tag).
-- **Live**: new memories pulse into the graph over the realtime stream.
-- **Analytics strip**: source-coverage gauge, agent-contribution and category charts, tag cloud, and a recent-memory feed.
-- Works instantly on your existing `~/.shadow-brain/global.json` — no project analysis or setup step.
-
-Several previously sparse tabs were also rebuilt with real visualizations: **Pre-Mortem** (risk matrix + failure cards), **Attention** (weighted heat bars), **Calibration** (Brier/trust chart), **Reputation** (trust rings), **Causal Chains** (node-link DAG), and **Branch Brains** (stat cards).
-
-Constellation API:
-
-```text
-GET /api/v6/memory-graph
-```
-
-
-Memory seeding API:
-
-```text
-GET  /api/v6/seed-drafts
-POST /api/v6/seed-draft
-POST /api/v6/seed-approve
-POST /api/v6/seed-reject
-POST /api/v6/seed-commit
-GET  /api/v6/memory-intelligence
-```
-
-Useful API endpoints:
-
-```text
-GET/POST /api/v6/live-brain
-GET/POST /api/v6/resume-pack
-GET/POST /api/v6/ww2br-recall
-GET/POST /api/v6/memory-browser
-```
-
-Example:
-
-```bash
-curl "http://127.0.0.1:7341/api/v6/live-brain?projectDir=C:/path/to/project"
-```
-
-## MCP Tools
-
-The MCP server exposes memory and agent-control tools for compatible clients.
-
-New in 6.3.0:
-
-- `global_recall_scored` — recall with a per-memory confidence score (recency, author importance, cross-agent corroboration, prior usage, keyword relevance). Results are ranked by confidence so agents can weight memories instead of trusting every hit equally. Supports `minConfidence` to drop low-trust hits.
-
-New in 6.0.3:
-
-- `live_brain_status`
-- `live_brain_brief`
-- `live_brain_train_pack`
-
-Existing useful tools include:
-
-- `global_recall`
-- `global_recall_scored`
-- `global_stats`
-- `global_timeline`
-- `subconscious_inject`
-- `agent_handoff`
-- `firewall_check`
-
-Start MCP from the dashboard API or existing CLI/server integration, depending on your setup.
-
-## How Agents Should Use It
-
-Recommended workflow for complex work:
-
-1. Run `shadow-brain live-brain status <project>`.
-2. Generate or read a live briefing.
-3. Verify current project docs and source files.
-4. Work normally.
-5. Record only durable, source-backed lessons after proof.
-6. Run recall evals when memory quality starts to drift.
-
-Good memories are short, action-oriented, and source-backed:
-
-```text
-[lesson:release-readme-v1] Before publishing, verify package.json version, package-lock root version, README install commands, build output, and npm pack contents.
-Sources: package.json; package-lock.json; README.md
-Tags: release,npm,verification
-```
-
-Bad memories are vague:
-
-```text
-Make project better.
-```
-
-## Local Data
-
-Default global brain:
-
-```text
-~/.shadow-brain/global.json
-```
-
-Project-local generated files may include:
-
-```text
-SHADOW_BRAIN_AGENT_BRIEF.md
-SHADOW_BRAIN_RESUME_SEED.md
-shadow-brain-training.jsonl
-```
-
-Do not store secrets, API keys, passwords, private keys, or raw credentials in memory content, metadata, tags, prompts, reports, or exported training data.
-
-## Development
+Six bundled skills cover workflow selection, implementation, debugging, review, research, and release. They help a client focus on the requested work, plan when useful, and verify the result.
 
 ```bash
-npm ci --ignore-scripts
-npm run verify
-npm run test:package
+shadow-brain skills list
+shadow-brain skills install . --target codex
+shadow-brain skills install . --target codex --apply
 ```
 
-Focused tests:
-
-```bash
-npx vitest run tests/brain/live-brain.test.ts tests/brain/context-continuity.test.ts
-```
-
-On Windows PowerShell, if execution policy blocks `npm.ps1`, use:
-
-```powershell
-npm.cmd run build
-npx.cmd vitest run tests\brain\live-brain.test.ts
-```
+The first install command previews the files. The second applies the install and preserves your existing project instructions. Choose `claude-code`, `opencode`, `deepseek-harness`, or `portable` for other clients. Discovery depends on each client's skill support. [Skill integration guide](docs/WORKFLOW_INTEGRATION.md)
 
-## Release Checklist
+## Upgrade and reference
 
-Run `npm run verify`, `npm audit --audit-level=high`, and `npm run test:package`. Inspect the package allowlist, then publish the verified tarball. Confirm the npm version, integrity, and GitHub tag before announcing a release. See [the complete release checklist](docs/launch/RELEASE_CHECKLIST_v7.0.0.md).
+If you are upgrading from 6.x, back up `~/.shadow-brain/global.json` and stop older writers before using 7.x. The 7.x writers use a new lock protocol and keep memory schema version 1. [7.0 migration notes](docs/launch/RELEASE_NOTES_v7.0.0.md)
 
-## License
+Version **7.1.3** is the requested release number for this upgrade, published after 7.2.0. Install it explicitly as shown above: semver-based update tools may otherwise prefer 7.2.0.
 
-MIT
+- [7.1.3 release notes](docs/launch/RELEASE_NOTES_v7.1.3.md)
+- [Earlier CLI, MCP, seeding, and export guide](https://github.com/ihtishaam-dev/agent-shadow-brain/blob/v7.1.0/README.md)
+- [Changelog](CHANGELOG.md) · [MIT license](LICENSE)

package/dist/activity-cli.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerActivityCommands(program: Command): void;
+//# sourceMappingURL=activity-cli.d.ts.map

package/dist/activity-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-cli.d.ts","sourceRoot":"","sources":["../src/activity-cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyDpC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2C/D"}

package/dist/activity-cli.js

@@ -0,0 +1,78 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { Command } from 'commander';
+import { activityJournalFor } from './brain/activity-journal.js';
+import { reportAgentActivity } from './brain/activity-reporting.js';
+import { FEATURE_SETTINGS_FILENAME, FeatureSettingsStore } from './brain/feature-settings.js';
+function stores(opts) {
+    const dbPath = path.resolve(opts.db ?? path.join(os.homedir(), '.shadow-brain', 'global.json'));
+    const settings = new FeatureSettingsStore({
+        filePath: opts.settings ?? (opts.db ? path.join(path.dirname(dbPath), FEATURE_SETTINGS_FILENAME) : undefined),
+    });
+    return { brain: { dbPath }, settings };
+}
+function storeOptions(command) {
+    return command.option('--db <path>', 'Use the activity journal adjacent to this memory store')
+        .option('--settings <path>', 'Explicit feature-settings file');
+}
+function cursorNumber(input) {
+    if (input === undefined)
+        return undefined;
+    if (!/^\d+$/.test(input) || !Number.isSafeInteger(Number(input))) {
+        throw new TypeError('Activity cursor must be a nonnegative integer.');
+    }
+    return Number(input);
+}
+function durationNumber(input) {
+    if (input === undefined)
+        return undefined;
+    const value = Number(input);
+    if (!/^\d+(?:\.\d+)?$/.test(input) || !Number.isFinite(value) || value > Number.MAX_SAFE_INTEGER) {
+        throw new TypeError('Activity duration must be a nonnegative number of milliseconds.');
+    }
+    return value;
+}
+export function registerActivityCommands(program) {
+    const activity = new Command('activity').description('Report or read bounded local activity metadata');
+    storeOptions(activity.command('report').description('Record an explicitly reported session, phase, or tool event'))
+        .argument('<kind>', 'session-start, phase, tool-start, tool-end, or session-end')
+        .requiredOption('--project-id <id>', 'Project label')
+        .requiredOption('--session <id>', 'Host session label')
+        .requiredOption('--agent <id>', 'Agent label')
+        .option('--phase <phase>', 'understand, plan, work, or verify')
+        .option('--tool <name>', 'Tool label')
+        .option('--correlation <id>', 'Shared ID for the tool start and end')
+        .option('--outcome <outcome>', 'success, error, or cancelled')
+        .option('--duration-ms <number>', 'Host-reported tool duration in milliseconds')
+        .action(async (kind, opts) => {
+        const durationMs = durationNumber(opts.durationMs);
+        const { brain, settings } = stores(opts);
+        const result = await reportAgentActivity(brain, settings, {
+            kind, projectId: opts.projectId, sessionId: opts.session, agent: opts.agent,
+            phase: opts.phase, tool: opts.tool, correlationId: opts.correlation, outcome: opts.outcome, durationMs,
+        });
+        console.log(JSON.stringify(result, null, 2));
+    });
+    storeOptions(activity.command('tail').description('Read a page of recent activity or continue from a cursor'))
+        .option('--project-id <id>', 'Filter by recorded project label')
+        .option('--cursor <number>', 'Continue after this event sequence')
+        .option('--journal-id <id>', 'Journal ID paired with a previous cursor')
+        .action((opts) => {
+        const { brain, settings } = stores(opts);
+        const flags = settings.get().features;
+        const enabled = { liveEnabled: flags.liveActivity, recordingEnabled: flags.activityRecording };
+        if (!flags.liveActivity) {
+            console.log(JSON.stringify({
+                ...enabled, events: [], journalId: null, revision: 0, oldestSequence: null, latestSequence: 0,
+                nextAfterSequence: 0, cursor: 0, hasMore: false, gap: false, reset: false, retainedCount: 0, droppedCount: 0,
+            }, null, 2));
+            return;
+        }
+        const page = activityJournalFor(brain).read({
+            projectId: opts.projectId, afterSequence: cursorNumber(opts.cursor), journalId: opts.journalId, limit: 200,
+        });
+        console.log(JSON.stringify({ ...enabled, ...page, cursor: page.nextAfterSequence }, null, 2));
+    });
+    program.addCommand(activity);
+}
+//# sourceMappingURL=activity-cli.js.map

package/dist/activity-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-cli.js","sourceRoot":"","sources":["../src/activity-cli.ts"],"names":[],"mappings":"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"}

package/dist/adapters/index.d.ts

@@ -9,7 +9,8 @@ import { AiderAdapter } from './aider.js';
 import { CursorAdapter } from './cursor.js';
 import { WindsurfAdapter } from './windsurf.js';
 import { CopilotAdapter } from './copilot.js';
-export declare const ALL_ADAPTERS: Record<AgentTool, () => AgentAdapter>;
+/** File adapters are distinct from clients that connect through MCP and skills. */
+export declare const ALL_ADAPTERS: Record<Exclude<AgentTool, 'deepseek-harness'>, () => AgentAdapter>;
 export declare function createAdapter(tool: AgentTool): AgentAdapter;
 export declare function detectRunningAgents(projectDir: string): Promise<AgentAdapter[]>;
 export { ClaudeCodeAdapter, KiloCodeAdapter, ClineAdapter, OpenCodeAdapter, CodexAdapter, RooCodeAdapter, AiderAdapter, CursorAdapter, WindsurfAdapter, CopilotAdapter, };

package/dist/adapters/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,YAAY,CAW9D,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,CAI3D;AAED,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAcrF;AAED,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,aAAa,EACb,eAAe,EACf,cAAc,GACf,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,mFAAmF;AACnF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,kBAAkB,CAAC,EAAE,MAAM,YAAY,CAW3F,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,CAI3D;AAED,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAcrF;AAED,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,aAAa,EACb,eAAe,EACf,cAAc,GACf,CAAC"}

package/dist/adapters/index.js

@@ -9,6 +9,7 @@ import { AiderAdapter } from './aider.js';
 import { CursorAdapter } from './cursor.js';
 import { WindsurfAdapter } from './windsurf.js';
 import { CopilotAdapter } from './copilot.js';
+/** File adapters are distinct from clients that connect through MCP and skills. */
 export const ALL_ADAPTERS = {
     'claude-code': () => new ClaudeCodeAdapter(),
     'kilo-code': () => new KiloCodeAdapter(),
@@ -22,9 +23,9 @@ export const ALL_ADAPTERS = {
     'copilot': () => new CopilotAdapter(),
 };
 export function createAdapter(tool) {
+    if (!Object.hasOwn(ALL_ADAPTERS, tool))
+        throw new Error(`No native file adapter for ${tool}. Use its MCP or project-skill integration.`);
     const factory = ALL_ADAPTERS[tool];
-    if (!factory)
-        throw new Error(`Unknown agent tool: ${tool}`);
     return factory();
 }
 export async function detectRunningAgents(projectDir) {