tail-fin-daemon 0.7.8

# tail-fin-daemon (`tfd`)

`tfd` is an agent-friendly daemon that manages a pool of Chrome browser sessions so that
multiple CLI calls and concurrent agents share tabs without opening redundant connections.

## Quick Start

```bash
# Build
cargo build -p tail-fin-daemon

# Start the daemon (foreground)
tfd daemon start

# Run a business command (transparent mode — acquire/release happens automatically)
tfd sa quote AAPL

# Run with an explicit session (skip auto acquire/release)
tfd --session <session_id> sa quote AAPL
```

## Commands

| Subcommand | Description |
|---|---|
| `daemon start / stop / status` | Daemon lifecycle |
| `session acquire / release / list / destroy` | Pool management |
| `sa <cmd>` | SeekingAlpha commands |
| `twitter <cmd>` | Twitter (read-only) commands |
| `grok <cmd>` | Grok commands |

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `TFD_SOCKET` | `~/.tail-fin/daemon.sock` | Unix socket path |
| `TFD_HOST` | `127.0.0.1:9222` | Chrome CDP host:port |
| `TFD_SESSION` | _(none)_ | Pin to an explicit session ID |
| `TFD_LOG` | `info` | Tracing log filter (e.g. `debug`, `tfd=trace`) |

## Session Modes

### Transparent (default)

Each invocation automatically acquires a session in `in_use` mode and releases it when
done. Multiple concurrent invocations for the same site share the same pool.

```bash
# Both commands share the pool; neither opens a redundant tab
tfd sa quote AAPL &
tfd sa quote MSFT &
```

### Explicit session

Pass `--session` (or set `TFD_SESSION`) to bind directly to a known session ID.
No acquire/release happens. Useful for long-running agent workflows that already called
`session acquire` manually.

```bash
SID=$(tfd session acquire --site sa | jq -r .session_id)
tfd --session "$SID" sa quote AAPL
tfd --session "$SID" sa news AAPL --count 10
tfd session release "$SID"
```

## Architecture

See the design spec:
[`docs/superpowers/specs/2026-04-17-tail-fin-daemon-design.md`](../../docs/superpowers/specs/2026-04-17-tail-fin-daemon-design.md)

## Limitations

- Existing-Chrome only: auto-launch (stealth browser) is not supported in the current release.
  Chrome must already be running and listening on `TFD_HOST`.
- Twitter commands are read-only (no posting).
- Unix domain sockets only; Windows is not supported.