robot_lab-am 0.0.1

data/docs/cli-reference.md

@@ -0,0 +1,118 @@
+# CLI Reference
+
+```text
+Usage: am COMMAND [options]
+```
+
+## Commands
+
+### `am snapshot`
+
+One-shot pipeline: collect new activity, infer the current goal, write and
+print `.robot_lab_am/current_intent.md`.
+
+```bash
+am snapshot
+am snapshot --repo ~/src/other_project
+```
+
+Prints how many *new* events were collected (dedupe means a quiet repo
+reports `0` but still re-infers over the accumulated recent window).
+
+### `am start`
+
+Start the daemon for the repo. Forks and detaches by default; output goes to
+`.robot_lab_am/daemon.log`. Fails with exit `1` if a daemon is already
+running for the repo.
+
+```bash
+am start
+am start --foreground                 # stay attached (what launchd runs)
+am start --interval 5 --debounce 60   # tune the cadence
+```
+
+### `am stop`
+
+Send SIGTERM to the running daemon and wait (up to 10s) for a clean exit.
+Detects a stale pid file (crash leftover), removes it, and reports it.
+
+### `am status`
+
+Report liveness — pid checked against the real process table, plus heartbeat
+detail when available. Exits `0` if running, `1` if not, so it's scriptable:
+
+```bash
+am status && echo "monitoring" || am start
+```
+
+### `am install` / `am uninstall`
+
+Write (or remove) the per-repo launchd agent plist under
+`~/Library/LaunchAgents/`. Only touches the file; prints the `launchctl
+bootstrap` / `bootout` commands for you to run. See
+[launchd supervision](daemon.md#launchd-supervision).
+
+## Options
+
+| Option | Applies to | Default | Meaning |
+|--------|-----------|---------|---------|
+| `--repo PATH` | all commands | current directory | The repo to watch. Everything else derives from this one path. |
+| `--interval N` | `start`, `install` | `15` | Seconds between watcher polls |
+| `--debounce N` | `start`, `install` | `300` | Minimum seconds between inference runs |
+| `--foreground` | `start` | off | Run attached to the terminal instead of detaching |
+| `-h`, `--help` | — | — | Show usage |
+| `-v`, `--version` | — | — | Print version and exit |
+
+With `install`, `--interval`/`--debounce` are baked into the plist's program
+arguments.
+
+`am --help` shows the *currently effective* interval/debounce — i.e. what your
+config file and environment resolve to, not the bundled defaults.
+
+## Configuration
+
+Settings cascade through [myway_config](https://github.com/MadBomber/myway_config)
+(the same pattern as `robot_lab-to`), lowest to highest precedence:
+
+1. Bundled defaults (`lib/robot_lab/am/config/defaults.yml`)
+2. User config file — `~/.config/robot_lab_am/robot_lab_am.yml`
+   (or `$XDG_CONFIG_HOME/robot_lab_am/robot_lab_am.yml`)
+3. `RLAM_*` environment variables
+4. CLI flags / constructor keywords
+
+The user config file uses flat keys:
+
+```yaml
+# ~/.config/robot_lab_am/robot_lab_am.yml
+interval: 30
+debounce: 600
+model: qwen/qwen3.8-27b
+```
+
+| Setting | Default | Env var | Meaning |
+|---------|---------|---------|---------|
+| `provider` | `openai` | `RLAM_PROVIDER` | RubyLLM provider for inference |
+| `model` | `qwen/qwen3.8-27b` | `RLAM_MODEL` | Model name |
+| `api_base` | `http://localhost:1234/v1` | `RLAM_API_BASE` | OpenAI-compatible server URL (applied to the `openai` provider) |
+| `api_key` | *(none)* | `RLAM_API_KEY` | API key — see [API keys](#api-keys) below |
+| `interval` | `15` | `RLAM_INTERVAL` | Seconds between daemon polls |
+| `debounce` | `300` | `RLAM_DEBOUNCE` | Minimum seconds between inference runs |
+| `inference_window` | `100` | `RLAM_INFERENCE_WINDOW` | Most recent events sent to the model |
+| `terminal_log` | `~/.activity_monitor/terminal_activity.log` | `RLAM_TERMINAL_LOG` | Preexec command log path |
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success (for `status`: daemon is running) |
+| `1` | Error — unknown command/option, daemon not running, already running, start/stop timeout |
+| `130` | Interrupted (Ctrl-C) |
+
+## API keys
+
+None are needed for the default local LM Studio setup. The key passed to
+RubyLLM cascades: `api_key` config / `RLAM_API_KEY` if set → the
+chosen provider's conventional env var (`OPENAI_API_KEY`,
+`ANTHROPIC_API_KEY`, …) → a placeholder value, which keyless local servers
+accept. Inference runs in a scoped RubyLLM context, so a host application's
+global RubyLLM configuration is inherited but never mutated.

data/docs/daemon.md

@@ -0,0 +1,104 @@
+# The Daemon
+
+`am start` runs the activity monitor continuously for one repo: polling the
+watchers, accumulating events, and re-inferring the current intent whenever
+activity arrives. This is what lets it notice *drift* in direction across
+sessions, not just seed a single takeover run.
+
+## Lifecycle
+
+```bash
+am start                   # fork + detach; logs to .robot_lab_am/daemon.log
+am start --foreground      # stay attached to the terminal (what launchd runs)
+am status                  # liveness + heartbeat detail
+am stop                    # SIGTERM, waits up to 10s for a clean exit
+```
+
+`am status` when running:
+
+```text
+daemon running for /Users/you/src/my_project (pid 41820)
+  heartbeat: 2s ago
+  events logged since start: 14
+  last inference: 2026-09-01T23:22:38Z
+```
+
+Exit codes follow convention: `status` exits `0` when the daemon is running
+and `1` when it isn't, so it works in scripts.
+
+## Inference cadence — debounced, not per-event
+
+Re-running inference on every keystroke-equivalent event would be wasteful and
+noisy. Instead:
+
+- The daemon polls all three watchers every **`--interval`** seconds
+  (default **15**).
+- New events set a *dirty* flag; inference runs only when the flag is set
+  **and** at least **`--debounce`** seconds (default **300**) have passed
+  since the last inference.
+- The first activity after startup infers immediately.
+
+```bash
+am start --interval 5 --debounce 60    # snappier, chattier
+```
+
+Prefer a persistent setting? Put it in `~/.config/robot_lab_am/robot_lab_am.yml`
+or `RLAM_INTERVAL`/`RLAM_DEBOUNCE` — flags always win over
+both (see [Configuration](cli-reference.md#configuration)).
+
+A failed inference (LM Studio not running, malformed response) is logged to
+`daemon.log`, keeps the dirty flag set, and retries once the next debounce
+window opens. It never kills the daemon.
+
+## Heartbeat
+
+Every tick, the daemon rewrites `.robot_lab_am/heartbeat.json`:
+
+```json
+{"pid": 41820, "updated_at": "2026-09-01T23:23:08Z",
+ "events_total": 14, "last_inference_at": "2026-09-01T23:22:38Z"}
+```
+
+The heartbeat also beats **before** each inference call — a local model can
+take 25+ seconds to respond, and a live daemon in the middle of a slow
+inference must not look dead. `am status` combines the heartbeat with a real
+process-table check (not just the pid file's existence), and detects, reports,
+and cleans up stale pid files left by a crash.
+
+## State files
+
+Everything lives under `.robot_lab_am/` in the watched repo:
+
+| File | Purpose |
+|------|---------|
+| `events.jsonl` | Append-only event log — one JSON line per event |
+| `current_intent.md` | The inferred intent artifact ([format](index.md#what-it-produces)) |
+| `daemon.pid` | Pid of the running daemon |
+| `heartbeat.json` | Rewritten every tick |
+| `daemon.log` | Stdout/stderr of the detached daemon |
+
+## launchd supervision
+
+To have macOS start the daemon at login and restart it if it crashes:
+
+```bash
+am install
+```
+
+This writes `~/Library/LaunchAgents/com.madbomber.robot-lab-am.<repo>-<hash>.plist`
+(one agent per watched repo) configured with `RunAtLoad` and `KeepAlive`,
+running `am start --foreground` under launchd's supervision. Installing only
+writes the file — the command prints the `launchctl` invocations to actually
+load it:
+
+```bash
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.madbomber.robot-lab-am.<repo>-<hash>.plist
+```
+
+`am uninstall` removes the plist (and prints the matching `launchctl bootout`
+command if the agent was loaded).
+
+!!! tip "One repo per daemon"
+    Watching several repos is "run N instances" — one `am start` (or one
+    `am install`) per repo — not a built-in registry. Each instance derives
+    everything it needs from its single `--repo` root.

data/docs/getting-started.md

@@ -0,0 +1,112 @@
+# Getting Started
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "robot_lab-am"
+```
+
+Despite the family name, the gem is standalone: its only dependencies are
+[RubyLLM](https://rubyllm.com) (for the one-shot inference call) and
+myway_config. No robot framework required.
+
+Or install directly:
+
+```bash
+gem install robot_lab-am
+```
+
+This provides the `am` executable.
+
+## Prerequisite: a local LLM
+
+Inference runs against LM Studio's OpenAI-compatible server by default, so
+your activity log is summarized entirely on your own machine:
+
+```bash
+lms server start    # serves http://localhost:1234/v1
+```
+
+The default model is `qwen/qwen3.8-27b`. To use a different local server or
+model, set it once in your config file:
+
+```yaml
+# ~/.config/robot_lab_am/robot_lab_am.yml
+model: llama-3.3-70b
+api_base: http://localhost:8080/v1
+```
+
+or per-invocation via `RLAM_MODEL` / `RLAM_API_BASE`
+(see [Configuration](cli-reference.md#configuration)). Any RubyLLM
+provider/model can be substituted — but the default is deliberately not a
+hosted provider. See [Privacy & Redaction](privacy.md).
+
+## Optional prerequisite: terminal capture
+
+Commands you run in a terminal are read from
+`~/.activity_monitor/terminal_activity.log`, written by a bash `preexec` hook
+in your dotfiles (`~/.bashrc__activity_monitor`, registered via
+[rcaloras/bash-preexec](https://github.com/rcaloras/bash-preexec)). Each line
+is tab-delimited: `epoch.microseconds<TAB>cwd<TAB>command`.
+
+Without the hook, the terminal source is simply empty — git and Claude Code
+signals still work, and they are the richer sources anyway.
+
+!!! note "Why a custom hook instead of bash history?"
+    `~/.bash_history` is global across every terminal and repo, with no
+    timestamps and no working directory — a raw `bundle exec rake test` line
+    can't be attributed to a repo or a point in time. The `preexec` hook
+    records both. It writes plain tab-delimited text (not JSON) because it
+    runs *before* every command executes and must not fork a subprocess.
+
+## Your first snapshot
+
+From inside any git repo you've been working in:
+
+```bash
+am snapshot
+```
+
+This runs the whole pipeline once:
+
+1. Collects recent git commits + uncommitted changes, your own messages from
+   the repo's most recent Claude Code session, and terminal commands run
+   inside the repo
+2. Redacts credential-shaped values and appends the new events to
+   `.robot_lab_am/events.jsonl`
+3. Asks the local model to infer your current goal
+4. Writes `.robot_lab_am/current_intent.md` and prints it
+
+Repeated snapshots are safe: events are deduplicated against the log, so
+nothing is double-counted.
+
+## Running continuously
+
+```bash
+am start     # detaches; writes .robot_lab_am/daemon.log
+am status    # pid, heartbeat age, event count, last inference
+am stop
+```
+
+See [The Daemon](daemon.md) for lifecycle details, tuning, and launchd
+supervision.
+
+## Ignore the state directory
+
+Add the gem's state directory to the watched repo's `.gitignore`:
+
+```gitignore
+/.robot_lab_am/
+```
+
+(The daemon already excludes its own state directory from the git activity it
+reports, but there's no reason to commit event logs.)
+
+## Handing off to robot_lab-to
+
+`robot_lab-am` produces a file in a format `robot_lab-to` already knows how to
+consume — front matter + prose, the same shape as its decision files. Invoke
+`robot-to` with no objective to let the inferred intent seed the run, or with
+an explicit objective to have the intent injected as extra context.

data/docs/how-it-works.md

@@ -0,0 +1,90 @@
+# How It Works
+
+## Signal sources
+
+Three watchers read what's already on disk — no instrumentation of your tools:
+
+| Source | What it yields | Read from |
+|--------|----------------|-----------|
+| **Git** | Recent commits, plus current uncommitted changes as a WIP summary | `git log` / `git status` in the watched repo |
+| **Claude Code** | Your own plain-language messages from the repo's most recent session — stated intent, not just commands | Transcripts under `~/.claude/projects/<slug>/*.jsonl` |
+| **Terminal** | Commands run inside the repo (tests, greps, ad hoc scripts) | The global `preexec` log, filtered to lines whose `cwd` is inside the repo |
+
+The Claude Code transcripts are the richest, lowest-effort source: they
+contain natural-language intent. Git is second-richest. The terminal source is
+optional — see [Getting Started](getting-started.md#optional-prerequisite-terminal-capture).
+
+Two deliberate exclusions: the `ClaudeWatcher` skips synthetic user turns that
+are really tool-result payloads (only things *you* typed count), and the
+`GitWatcher` filters the gem's own `.robot_lab_am/` state directory out of the
+WIP summary — the monitor must not observe its own footprint.
+
+## Events
+
+Every watcher emits one normalized shape:
+
+```json
+{"timestamp": "2026-09-01T23:22:38Z",
+ "repo": "/Users/you/src/my_project",
+ "source": "terminal",
+ "kind": "command",
+ "summary": "asgard quality"}
+```
+
+`source`/`kind` pairs: `git`/`commit`, `git`/`wip`, `claude_code`/
+`user_message`, `terminal`/`command`.
+
+## Collection: redact, dedupe, append
+
+Both `am snapshot` and every daemon tick run the same collection pass:
+
+1. Ask all three watchers for their recent window of events
+2. **Redact** credential-shaped values in each summary
+   ([details](privacy.md#3-redaction))
+3. **Dedupe** against everything already in `events.jsonl`, by fingerprint
+4. Append only what's genuinely new
+
+Fingerprints make collection idempotent: repeated snapshots, daemon restarts,
+and overlapping watcher windows never duplicate a line. Most events
+fingerprint on `timestamp + source + kind + summary`; WIP events drop the
+timestamp (it's collection time, not activity time), so an unchanged dirty
+tree is recorded once, and again only when it actually changes.
+
+## Storage: JSONL, not SQLite
+
+`events.jsonl` is an append-only file, one JSON object per line. The only
+consumer is an LLM summarization pass over a bounded recent window — not ad
+hoc queries — so a database wasn't worth the dependency. (Its structural
+sibling, [`robot_lab-audit`](https://github.com/MadBomber/robot_lab-audit),
+made the opposite call because audit logs *are* queried.)
+
+## Inference
+
+The `Inferrer` takes the last 100 events, renders them oldest-to-newest as a
+timestamped activity log, and asks the model — a one-shot
+[RubyLLM](https://rubyllm.com) chat in a scoped context, no agent framework —
+for exactly this YAML:
+
+```yaml
+goal: <one or two sentences on what they're currently working toward>
+confidence: <low|medium|high>
+evidence:
+  - <short reference to a specific event that supports the goal>
+open_questions:
+  - <anything ambiguous or unresolved>
+```
+
+The response is parsed defensively — fenced YAML is extracted, and a
+malformed reply degrades to using the raw text as the goal with
+`confidence: unknown` rather than failing.
+
+A repo with no recent activity short-circuits to a "No recent activity
+detected" intent without calling the model at all.
+
+## The intent artifact
+
+`IntentWriter` renders the result to `.robot_lab_am/current_intent.md` —
+YAML front matter (confidence, timestamp, evidence, open questions) followed
+by the goal as prose. The format and the `.robot_lab_<name>/` directory
+convention deliberately match `robot_lab-to`'s decision files and run state,
+so the consumer needs nothing new to read it.

data/docs/index.md

@@ -0,0 +1,74 @@
+# robot_lab-am
+
+**A standalone repo activity monitor** — a background daemon that watches what
+*you* are doing in a repo (git activity, Claude Code sessions, terminal
+commands) and distills it into a current-goal statement via a one-shot
+[RubyLLM](https://rubyllm.com) call to a local model. Any tool can read the
+intent artifact it writes; [`robot_lab-to`](https://madbomber.github.io/robot_lab-to/)
+uses it to seed a takeover run, but nothing here depends on the RobotLab
+framework.
+
+The original point: when you say "take over," the robot should start from
+*what you were actually doing* — not from a cold objective string you typed
+at invocation time.
+
+![robot_lab-am pipeline](assets/pipeline.svg)
+
+## What it produces
+
+Every inference writes `.robot_lab_am/current_intent.md` in the watched repo —
+YAML front matter plus a prose goal statement:
+
+```markdown
+---
+confidence: high
+generated_at: '2026-09-01T23:22:56Z'
+evidence:
+- Commit d8b2f5f touches the daemon start/stop lifecycle
+- Terminal shows repeated `asgard quality` runs
+open_questions:
+- Whether the launchd agent should auto-load after install
+---
+
+Completing the robot_lab-am daemon implementation: start/stop/status
+lifecycle, heartbeat, and launchd supervision, driven toward green
+quality gates.
+```
+
+`robot_lab-to` reads this file the way it already reads `notes.md` — as the
+seed objective when none is given, or as extra context alongside one.
+
+## Design commitments
+
+- **Local-first inference.** Your activity log — commits, commands, your own
+  Claude Code messages — never leaves the machine. Inference defaults to a
+  local model served by LM Studio's OpenAI-compatible API; no hosted provider,
+  no API key. See [Privacy & Redaction](privacy.md).
+- **One repo per daemon.** Each daemon instance watches exactly one repo root.
+  Watching several repos means running several instances.
+- **Read-side opt-in.** The terminal log spans every shell on the machine, but
+  the daemon only ever parses lines whose `cwd` falls inside the watched repo.
+- **Redaction before storage.** Credential-shaped values are masked before an
+  event is written to disk or shown to the LLM.
+
+## The 60-second version
+
+```bash
+gem install robot_lab-am
+
+cd ~/src/my_project
+am snapshot        # one-shot: collect activity, infer, write current_intent.md
+am start           # or: run the daemon continuously
+am status
+```
+
+Continue with [Getting Started](getting-started.md).
+
+## Part of the RobotLab family
+
+| Gem | Role |
+|-----|------|
+| [`robot_lab`](https://github.com/MadBomber/robot_lab) | Core framework: robots, networks, MCP, memory |
+| **`robot_lab-am`** | Senses *human* activity outside any run and turns it into tasking context |
+| [`robot_lab-to`](https://github.com/MadBomber/robot_lab-to) | The consumer — autonomous "takeover" loop seeded by the inferred intent |
+| [`robot_lab-audit`](https://github.com/MadBomber/robot_lab-audit) | The structural sibling — logs *robot* activity, where this gem logs yours |

data/docs/privacy.md

@@ -0,0 +1,73 @@
+# Privacy & Redaction
+
+An activity monitor watches *you* — so the privacy posture is the design, not
+an afterthought. Three layers:
+
+## 1. Local-first inference
+
+Inference over your own activity log — commits, terminal commands, your Claude
+Code messages — shouldn't require sending that log anywhere, or holding an API
+key, just to summarize it.
+
+The `Inferrer` therefore defaults to a **local model** served by LM Studio's
+OpenAI-compatible API (`lms server start`, `http://localhost:1234/v1`),
+explicitly not a hosted provider. With the default configuration, no network
+call leaves the machine.
+
+You *can* point it at any RubyLLM provider programmatically — that's a
+deliberate, visible choice, never the default:
+
+```ruby
+RobotLab::Am::Inferrer.new(model: "claude-sonnet-4", provider: :anthropic)
+```
+
+## 2. Read-side scoping of the terminal log
+
+The `preexec` hook is necessarily global: it captures every command in every
+shell, because a shell hook can't know in advance which repo will later be
+"the watched one."
+
+The opt-in boundary is enforced **at ingestion, not capture**: the watcher
+only parses lines from `~/.activity_monitor/terminal_activity.log` whose
+`cwd` falls inside the one repo root it's watching. Every other line in that
+file is never parsed, stored, or sent to an LLM by this gem.
+
+Git and Claude Code sources are already repo-scoped at the source.
+
+## 3. Redaction
+
+Even in-scope activity can contain secrets — an API key in an `export`
+statement, credentials in a test fixture showing up in a WIP diff summary.
+The `Redactor` masks credential-shaped values in every event summary
+**before** it is written to `events.jsonl` or shown to the LLM:
+
+- `key` / `token` / `secret` / `password` / `credential` **assignments** —
+  `export MY_TOKEN=…`, `password: …`, `api_key => …` (value masked, name kept)
+- **Bearer tokens** — `Authorization: Bearer …`
+- **Well-known token formats** wherever they appear — OpenAI (`sk-…`), AWS
+  (`AKIA…`), GitHub (`ghp_…`, `github_pat_…`), Slack (`xoxb-…`)
+
+```text
+export ANTHROPIC_API_KEY=sk-ant-abc123…   →   export ANTHROPIC_API_KEY=[REDACTED]
+```
+
+!!! warning "Conservative by design — not a guarantee"
+    Redaction is pattern-based. It catches the common shapes of leaked
+    credentials, not every possible secret. Treat `.robot_lab_am/` like any
+    other local development artifact: keep it out of version control
+    (`/.robot_lab_am/` in `.gitignore`) and be deliberate if you ever switch
+    inference to a hosted provider.
+
+## What is stored, and where
+
+Everything stays in the watched repo's `.robot_lab_am/` directory — redacted
+event summaries, the inferred intent, and daemon runtime state. Nothing is
+written outside the repo, and nothing is transmitted anywhere with the
+default local-model configuration.
+
+## Log rotation
+
+The global terminal log belongs to your dotfiles, and rotating or truncating
+it there is always safe for this gem: the watcher takes only the most recent
+in-scope lines each poll, and fingerprint dedupe means rotation can never
+cause re-ingestion.