aloita-extensions 0.4.7 → 0.4.8

package/README.md

@@ -1,413 +1,57 @@
 # aloita-extensions
 
-Pi extensions that **replace both** the [Aura SignalR receiver](https://github.com/frankvl76/aura-signalr-client) and the [Aura MCP server](https://github.com/frankvl76/aura-mcp-server) with a single Pi extension.
+A Pi extension. One long-running Pi session connects to your Aloita server and works on tickets natively — no separate MCP server or subprocesses.
 
-Instead of spawning `claude -p` / `opencode` per ticket and talking to Aloita over MCP stdio, **one Pi session connects to Aloita over SignalR and works on tickets natively.** The 28 `aura_*` tools are registered as first-class Pi tools — no MCP, no subprocess, no separate FastAPI dashboard.
+## Install
 
-```
-                ┌─────────────────────────────────────────────┐
-                │  ONE Pi session (this extension loaded)      │
-                │                                              │
-   Aloita ──SignalR──► onWebhookEvent                          │
-   board         │        ├─ dedup → resolve folder           │
-   (formerly     │        ├─ set "In Progress" + agent-task    │
-   "Aura")       │        └─ pi.sendUserMessage(prompt) ──┐    │
-        ◄─REST───│◄── aura_* tools (28) ◄─────────────── the   │
-                │    (get ticket, comment, checklist, …) agent │
-                │                                              │
-                │    on agent_end → "Done" + drain next queued │
-                └─────────────────────────────────────────────┘
-```
-
-## What this replaces
-
-| Old (Python)                         | New (this extension)                                   |
-|---------------------------------------|--------------------------------------------------------|
-| `signalr_receiver.py` (2848 lines)    | `src/signalr.ts` + `src/index.ts` webhook handling     |
-| `signalr_loop_bridge.py` + supervisor | gone — the Pi session **is** the long-lived consumer   |
-| FastAPI dashboard + `static/`         | `ctx.ui.setStatus()` footer + `notify()` + `/aloita-*` |
-| `aura-mcp-server/server.py` (28 tools)| `src/tools.ts` — same 28 tools, registered natively    |
-| `aura_client.py` (httpx)              | `src/aura-client.ts` (`fetch`)                         |
-| Subprocess spawn + `.cmd` shims       | gone — no subprocesses                                 |
-| Usage reconstruction from transcripts | `message_end` usage → `/agent-run-usage` on `agent_end` |
-| `AuraAgentLogPusher` + stdout line reader | `src/agent-log.ts` — fed from Pi streaming events (see §Agent log streaming) |
-| `--resume <sessionID>` dance          | gone — the session is already long-lived               |
-
-## Quick start
-
-**Prerequisites:** Pi (`@earendil-works/pi-coding-agent`) on your PATH and Node 18+.
-
-### 1. Install the extension (one command)
+Requires Pi (`@earendil-works/pi-coding-agent`) on your PATH and Node 18+.
 
-```powershell
+```sh
 pi install npm:aloita-extensions
 ```
 
-That's it. `pi install` writes the package to Pi's global settings (`~/.pi/agent/settings.json` → `packages: [...]`) and fetches its `dependencies` (`ws`). Plain `pi` (no flags) now auto-loads the extension on **every startup** — no manual path configuration, no `--extension` flag, no rebuild step.
-
-Pi bundles the `@earendil-works/*` and `typebox` packages this extension imports (declared as `peerDependencies`), so they are provided by Pi at runtime.
-
-> **Offline / air-gapped install:** if the npm tarball (`.tgz`) is available locally instead of published to a registry, install directly from it: `pi install ./aloita-extensions-0.2.0.tgz`. See [§Distributable](#distributable) for details.
-
-Manage the registration:
-
-```powershell
-pi list                               # confirm it's registered
-pi remove npm:aloita-extensions       # unregister
-pi update --extensions                # update all installed packages
-```
-
-### 2. Configure Aloita access
-
-Set your Aloita server URL + API key (env vars are the simplest — good for secrets):
-
-```powershell
-# PowerShell (current session):
-$env:ALOITA_URL = "https://your-aloita-server"
-$env:ALOITA_API_KEY = "kai_your_key_here"
-
-# Or persist as user environment variables (run once):
-setx ALOITA_URL "https://your-aloita-server"
-setx ALOITA_API_KEY "kai_your_key_here"
-```
-
-Alternatively, copy `config.example.json` to one of these paths and edit (full schema in [§Configure](#configure)):
-- `~/.pi/aloita.json` — global (**recommended** for `repos`, capabilities, and auto-start settings)
-- `<cwd>/.pi/aloita.json` — project-local (preferred for per-project overrides)
-
-**Or skip the env vars entirely** — run `/aloita-configure` inside Pi and set the server URL + API key in the **Connection settings** screen. They persist to `~/.pi/aloita.json` (global) so every Pi session on this machine uses them.
-
-Launch `pi`. The footer shows `● Aloita: connected` when the SignalR socket is up.
-
-### 3. (Optional) Auto-start + `/aloita-configure`
+Pi auto-loads the extension on every startup. Manage it with:
 
-To let this Pi session automatically start a dedicated child `pi` in specific project folders, open the interactive settings UI:
-
-```
-/aloita-configure
-```
-
-Toggle which projects are in the auto-start allow-list, adjust options, then **Save & close** — changes persist to the config file and hot-reload immediately. See [§Auto-start supervisor](#auto-start-supervisor) and [§`/aloita-configure`](#aloita-configure--interactive-settings-ui) for detail. (Auto-start is opt-in and off by default.)
-
-## Distributable
-
-The extension ships as an npm tarball (`npm pack` output): `aloita-extensions-0.2.0.tgz`. This is the single artifact for distribution — it contains exactly the package contents (source, docs, README, LICENSE, config example, tsconfig) and nothing else (no `node_modules`, no `.git`, no test artifacts).
-
-Two install paths from the tarball:
-
-1. **Publish to npm**, then install by name (recommended for repeated installs):
-   ```powershell
-   npm publish aloita-extensions-0.2.0.tgz   # one-time publish
-   pi install npm:aloita-extensions           # install on any machine
-   ```
-
-2. **Install directly from the tarball** (no registry needed — good for air-gapped / private setups):
-   ```powershell
-   pi install ./aloita-extensions-0.2.0.tgz
-   ```
-   This registers the tarball path in Pi's settings and auto-loads the extension on every startup, just like the npm path.
-
-A `distributable.zip` is attached to the packaging ticket — it contains the `.tgz` plus this README, so a developer has everything needed in one download.
-
----
-
-## Install (local development)
-
-For hacking on this extension from a clone:
-
-```powershell
-git clone https://github.com/frankvl76/aloita-extensions
-cd aloita-extensions
-npm install            # fetches ws + dev/type deps
-npm run build          # tsc --noEmit type-check
-npm test               # node --test src/*.test.ts
-```
-
-Register the local folder so it auto-loads (reads the `pi.extensions` manifest from `package.json`):
-
-```powershell
-# Global — loads in EVERY project folder (matches the one-Pi-per-folder model).
-pi install C:\path\to\aloita-extensions
-
-# Project-local — only the current folder:
-pi install -l C:\path\to\aloita-extensions
-```
-
-`pi install` stores a path relative to `~/.pi/agent`; `pi list` prints the resolved absolute path so you can sanity-check it. Global packages are loaded regardless of project trust, so they apply in every cwd.
-
-Because Pi loads extensions via [jiti](https://github.com/unjs/jiti) on each launch, **source edits are picked up immediately on the next `pi` start** and `/reload` hot-reloads them in a running session — no rebuild step.
-
-### Manual / one-off (no registration)
-
-For a single run with no registration, use the explicit flag:
-
-```powershell
-pi --extension C:\path\to\aloita-extensions\src\index.ts
+```sh
+pi list                            # confirm it's registered
+pi remove npm:aloita-extensions    # unregister
+pi update --extensions             # update installed packages
 ```
 
 ## Configure
 
-Two sources, first non-empty wins:
-
-1. **Env vars** (good for secrets): `ALOITA_URL`, `ALOITA_API_KEY` (also `AURA_REPOS`).
-2. **JSON file** discovered at one of:
-   - `<extensionDir>/aloita.json` — sibling of `package.json`
-   - `<cwd>/.pi/aloita.json` — project-local (**preferred**, per-folder)
-   - `~/.pi/aloita.json` — global
-
-Copy `config.example.json` to one of those paths and edit. Full schema:
-
-| Field                  | Default | Purpose                                                                 |
-|------------------------|---------|-------------------------------------------------------------------------|
-| `aloitaUrl`            | —       | Base URL of the Aloita server (env `ALOITA_URL`).                       |
-| `apiKey`               | —       | `kai_…` key (env `ALOITA_API_KEY`).                                     |
-| `subscription`         | see ex  | `{ events, allProjects, allUsers, projectIds, userIds }` bitmask filter.|
-| `projectFolders`       | `{}`    | `projectId → local path` override (wins over Aloita-side `LocalFolder`).  |
-| `projectFilter`        | `""`    | If set, this session only claims tickets for that project id.           |
-| `matchAllProjects`     | `false` | If true, claim every ticket regardless of folder (uses this cwd).       |
-| `repos`                | `""`    | `${REPOS}` expansion target (env `AURA_REPOS`).                         |
-| `labelToCommand`       | see ex  | Ticket label → command template.                                        |
-| `defaultCommand`       | `aura-work-on-ticket` | Fallback command.                                         |
-| `guardStatus`          | `true`  | Block the agent from changing ticket status (enforces the #1 rule).     |
-| `autoFinalizeOnAgentEnd` | `true` | Set ticket "Done" when the triggered turn ends.                         |
-| `postUsage`            | `true`  | POST per-model token/cost to Aloita on `agent_end` (see §Usage post-back).|
-| `postDiff`             | `true`  | POST the run's git diff to Aloita's per-ticket diff viewer on `agent_end` (see §Run diff post-back).|
-| `streamAgentLog`       | `true`  | Stream the agent's text to Aloita's per-ticket agent-log tab in real time (see §Agent log streaming).|
-| `dedupWindowSeconds`   | `2`     | Webhook dedup window.                                                   |
-| `autoStartProjects`    | `false` | Supervisor: poll `/api/projects` and spawn a child `pi` in each NEW project's folder (see §Auto-start supervisor). |
-| `autoStartPollSeconds` | `60`    | Auto-start poll interval (seconds).                                     |
-| `autoStartCreateFolder`| `true`  | Auto-start: `mkdir -p` the project folder if it doesn't exist yet.       |
-| `autoStartPiCommand`   | `""`     | Auto-start: override the `pi` command to spawn (default `pi.cmd`/`pi`). |
-| `autoStartExcludeProjects` | `[]` | Auto-start: project ids to never launch.                                |
-| `autoStartSeedExisting`| `false` | Auto-start: launch for all existing projects on startup (not just new). |
-| `autoStartProjectIds` | `[]`    | Auto-start: allow-list of project ids to launch for (new projects do nothing until added here — use `/aloita-configure`). |
-| `capabilities`         | `[]`    | GLOBAL fallback caps registered against the auth user (see §Capability tiers). |
-| `userMappings`         | `{}`    | GLOBAL per-agent-user profiles + their capability tiers (see §Capability tiers). |
-
-## How a ticket flows through Pi
-
-1. **`session_start`** → opens the SignalR WebSocket to `<aloitaUrl>/hubs/webhooks`, handshakes, subscribes. Status footer shows `○ aloita: connected`.
-2. **`WebhookEvent`** arrives → dedup (2s fingerprint) → resolve working dir → decide whether *this* session claims it (see *Multi-project* below) → fetch ticket context → resolve label → command → set **In Progress** + `agent-task/start` → `pi.sendUserMessage(prompt)`.
-3. The Pi agent **works the ticket** using the native `aura_*` tools (get context, comment, attachments, checklist, conversations, search data…). Its streamed text is mirrored live to Aloita's per-ticket agent-log tab (see §Agent log streaming).
-4. **`agent_end`** → finalize: set **Done** + `agent-task/end` → drain the next queued ticket if any.
-5. **`StopTask`** (user clicks Stop in Aloita UI) → drops queued + `ctx.abort()` the active turn.
-6. **`session_shutdown`** → closes the socket cleanly.
-
-## Label routing (which prompt runs)
-
-When a ticket is claimed, its labels are matched (case-insensitive, trimmed, first match wins) against `labelToCommand` to pick the prompt template; any unmatched label (or no label) falls back to `defaultCommand`. Defaults (`src/config.ts`) — override/add in your `aloita.json`:
-
-| Label                  | Command                              | What the agent does                                                                          |
-|------------------------|--------------------------------------|----------------------------------------------------------------------------------------------|
-| `plan`                 | `aura-plan-ticket`                   | Write a technical plan/spec, attach it; no code.                                             |
-| `review`               | `aura-review-ticket`                 | Review recent changes for the ticket; no code.                                              |
-| `document`             | `aura-document`                      | Generate documentation.                                                                      |
-| `workflow-implementation` | `aloita-workflow-implement-with-pr` | Implement on a `feature/<name>` branch off latest `main`, then **open a PR into `staging`**. |
-| *(no / unmatched label)* | `aura-work-on-ticket` *(default)*  | Implement the ticket directly (full work loop, no git/PR).                                   |
-
-To add your own, map a label to a command name and define that template in `PROMPTS` (`src/prompts.ts`).
-
-## Multi-project (one Pi per folder)
+Set your server URL and API key via environment variables:
 
-A Pi session is bound to its launch cwd, so run **one Pi per project folder** — exactly the model `RUNNING.md` already documents for the supervisor:
-
-```powershell
-# In project A's folder, dedicated to project A:
-cd C:\path\to\projectA
-pi --extension ...\aloita-extensions\src\index.ts
-#   → set projectFilter to project A's id in .\.pi\aloita.json
-```
-
-Ticket-claiming logic (`src/working-dir.ts shouldClaimTicket`):
-- `matchAllProjects: true` → claim everything (use this cwd).
-- `projectFilter: "<id>"` → claim only that project.
-- **default** → claim only when the ticket's resolved folder exists **and equals this session's cwd**.
-
-## Auto-start supervisor
-
-Normally you start one Pi per project folder manually (`cd <folder> && pi`). With `autoStartProjects: true`, this Pi session becomes a **supervisor**: it polls `GET /api/projects` every `autoStartPollSeconds` and, for each project that is in your **allow-list** (`autoStartProjectIds`) and not yet launched, spawns a **detached child `pi`** in that project's folder.
-
-**Allow-list model:** a brand-new project does **nothing** until you explicitly opt it in — either by adding its id to `autoStartProjectIds` in the config file, or interactively via `/aloita-configure` (recommended). This keeps you in control of which folders get a child pi.
-
-```json
-{
-  "autoStartProjects": true,
-  "repos": "C:\\Users\\frank\\source\\repos",
-  "autoStartCreateFolder": true,
-  "autoStartPollSeconds": 60
-}
+```sh
+export ALOITA_URL="https://your-aloita-server"
+export ALOITA_API_KEY="kai_your_key_here"
 ```
 
-**How a project is launched** (pure logic in `src/project-launcher.ts`, I/O in `src/index.ts`):
-1. Poll → `normalizeProjects` → `detectProjectsToLaunch` (allow-listed projects not yet launched).
-2. Resolve the folder, in order: `projectFolders[id]` override → project `LocalFolder` → `$REPOS/<sanitized-name>` (derived from `repos`).
-3. If the folder doesn't exist and `autoStartCreateFolder` is on, `mkdir -p` it.
-4. Write a tiny project-local `.pi/aloita.json` containing `{ "projectFilter": "<id>" }` so the child claims only that project.
-5. `spawn(<pi>, { detached: true, stdio: "ignore" })` + `child.unref()` — the child survives the supervisor.
+Or run `/aloita-configure` inside Pi to set them (and other options) in an
+interactive settings screen — values persist to `~/.pi/aloita.json` and apply
+to every Pi session on the machine.
 
-Credentials are passed via `ALOITA_URL` / `ALOITA_API_KEY` env vars, **not** written into the per-project file, so no secrets are duplicated.
+A `config.example.json` ships with the package; copy it to `~/.pi/aloita.json`
+(global) or `<cwd>/.pi/aloita.json` (project-local) and edit.
 
-**Why polling:** Aloita's `WebhookEventType` bitmask only covers ticket events today — there is no `ProjectCreated` flag. Polling `/api/projects` is the server-agnostic signal. If Aloita adds a `ProjectCreated` event later, only the supervisor's trigger changes; the pure planning layer stays as-is.
-
-**Safe by default:** off unless you opt in; never blocks the session; failed launches/polls log a warning and continue.
-
-## `/aloita-configure` — interactive settings UI
-
-The `/aloita-configure` command opens a full-screen TUI wizard (built from Pi's `SelectList` + `SettingsList` components) where you can manage all Aloita extension settings without editing JSON. All settings persist to the **global** config file (`~/.pi/aloita.json`) so they apply to every Pi session on this machine.
-
-- **Connection settings** — server URL, API key (`kai_…`), and agent user IDs. These are the credentials every Pi session needs to connect to Aloita. Set them once here and they're global — no need to repeat `ALOITA_URL`/`ALOITA_API_KEY` env vars per session. Changing them triggers an immediate SignalR reconnect.
-- **Model capabilities** — browse the models you've configured in Pi (from your providers — `ctx.modelRegistry.getAvailable()`) and toggle which to broadcast to Aloita. Costs are **auto-filled from Pi's model pricing** (`Model.cost`). The display name defaults to the model name. This is how Aloita learns what models this machine can run and what they cost — used for `/cost` and complexity-tier mapping.
-- **Auto-start projects** — browse every project on the Aloita board and toggle which ones are in the allow-list (`autoStartProjectIds`). Searchable for large boards.
-- **Auto-start options** — master switch, poll interval (30s/60s/2m/5m/10m presets), folder creation, seed-existing.
-- **General options** — status guard, auto-finalize, token-usage / diff / agent-log post-backs.
-- **Save & close** — persists changes to the config JSON file and hot-reloads. **Cancel** discards.
-
-The API key is masked in the input dialog (`kai_••••••`). Press Esc at any prompt to skip that field without changing it. Connection settings are written to `~/.pi/aloita.json` (global) — env vars (`ALOITA_URL`/`ALOITA_API_KEY`) still take precedence at load time if set.
-
-Changes persist via `src/config-store.ts` (read → merge → write), which shallow-merges so untouched keys survive and secrets (`aloitaUrl`/`apiKey`) are never written into the file.
+Launch `pi`. The footer shows the connection status when the socket is up.
 
 ## Commands
 
-| Command             | Action                                                    |
-|---------------------|-----------------------------------------------------------|
-| `/aloita-status`    | Print connection state, active ticket, queue depth.       |
-| `/aloita-connect`   | Force reconnect the SignalR socket.                       |
-| `/aloita-disconnect`| Disconnect the socket.                                    |
-| `/aloita-next`      | Force-drain the next queued ticket into this session.     |
-| `/aloita-configure` | Interactive settings UI: toggle auto-start projects, edit options, persist. |
-
-## Tools (28, grouped like the MCP server)
-
-**Essential** — `aura_get_ticket_context`, `aura_add_comment`, `aura_upload_attachment`, `aura_update_ticket_status` *(guarded)*, `aura_create_subtask`, `aura_add_checklist_item`, `aura_toggle_checklist_item`, `aura_set_custom_field`.
-
-**Important** — `aura_search_tickets`, `aura_list_tickets`, `aura_update_ticket` *(status guarded)*, `aura_list_projects`, `aura_list_comments`, `aura_upload_comment_attachment`, `aura_list_attachments`, `aura_download_attachment`.
-
-**Nice-to-have** — `aura_assign_ticket`, `aura_create_ticket`, `aura_list_labels`, `aura_list_users`, `aura_log_time`, `aura_get_activity`.
-
-**Search data** — `aura_search_console_query`, `aura_ga4_report`, `aura_pagespeed_audit`.
-
-**Conversation** — `aura_start_conversation`, `aura_reply_in_conversation`, `aura_resolve_conversation`.
-
-> Asking a question (`aura_start_conversation`) used to require an exit/resume dance because `claude -p` was stateless. In Pi the session just idles — when the human answers, a new webhook event arrives and `sendUserMessage` continues the **same** session. No session-ID bookkeeping.
-
-## Critical rules (preserved from the Python stack)
-
-- **Agents must not change ticket status.** Enforced at runtime by a `tool_call` interceptor (`guardStatus`): `aura_update_ticket_status` is blocked outright; the `status` field is stripped from `aura_update_ticket`. The orchestrator owns status (In Progress on start, Done on `agent_end`).
-- **Working dir must already exist** — never auto-created (`resolveWorkingDir` returns null if missing; the ticket is skipped with a log line).
-- **Run one SignalR subscription per Aloita auth user.** Like the receiver, one connection per Pi process.
-- **Stable per-run `sessionId`.** On `session_start` the extension mints one UUID (`runSessionId`) and sends it in the Subscribe payload's `SessionId` field, then reuses that same id for every per-ticket artifact — `agent-task/start`|`end`, usage, diff, and the agent-log stream. This lets the Agent Activity orbit render each Pi run as its own satellite and pin activity to it (without it, the orbit merges an agent's connections into a single satellite).
-
-## Capability tiers (global, broadcast on connect)
-
-Capabilities tell Aloita what models this machine can run and what they cost. Aloita uses them two ways:
-
-1. **Pricing** — upserts an `AgentModelPricing` row (`Source=ClientRegistered`, never clobbering an `AdminOverride`) so `/cost` can price runs.
-2. **Complexity mapping** — links each model into the per-user complexity-tier admin UI, so Aloita's `AnalyzeTaskComplexity` flow can stamp the right model on a ticket based on its tier.
-
-This is **global config** (not per-project) — put it in `~/.pi/aloita.json` so every Pi session on this machine advertises the same set. Two sources, unioned:
-
-- `capabilities[]` — top-level fallback, registered against the auth user (the `.env` key).
-- `userMappings[<userId>].capabilities[]` — explicit per agent user (**preferred**).
-
-```json
-"userMappings": {
-  "927fc980-4cd6-4323-ac72-2a9be24f2730": {
-    "tool": "pi",
-    "capabilities": [
-      { "tool": "pi", "provider": "anthropic", "model": "claude-sonnet-4-5",
-        "displayName": "Sonnet 4.5 (medium)",
-        "inputCostPerMTok": 3, "outputCostPerMTok": 15,
-        "cachedInputCostPerMTok": 0.3, "cacheWriteCostPerMTok": 3.75 }
-    ]
-  }
-}
-```
-
-**Auth binding:** Aloita attributes `RegisterCapabilities` to the *connected* user; only SuperAdmin can register for other users. So the auth user's caps go on the main connection; each *other* mapped user gets its own helper connection (authenticated with that user's `apiKey`, `registerOnly` mode — no Subscribe, just kept alive so the caps stay registered). Include `apiKey` on every non-auth `userMappings` entry.
-
-On `session_start`, the extension resolves the auth user via `GET /api/profile`, builds the plan (`src/capabilities.ts`), and starts the main + helper connections. `/aloita-connect` re-runs the whole flow.
-
-## Usage post-back (on `agent_end`)
-
-When the Pi job for a ticket finishes (`agent_end`), the extension POSTs the run's token/cost to `/api/tickets/{id}/agent-run-usage`. This is the smart orchestration moment — usage is accumulated **while a ticket is active** and flushed exactly once when the turn ends.
-
-- **Source of truth:** Pi's per-assistant-message `usage` on `message_end` (`input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`, `cost.total`), plus `message.provider` / `message.model`. This is the Pi equivalent of Claude's authoritative `result.modelUsage`.
-- **Per-model breakdown:** aggregated by `(provider, model)` and sent as the `models[]` array Aloita's `AgentRunUsageEndpoints` expects. One `AgentRunUsage` row is written per model.
-- **Best-effort, never blocks:** posts happen after the turn ends and before finalize; a failure logs a warning but does not block status/queue drain.
-- **Zero-row visibility:** if no usage was captured (e.g. the turn was aborted), a single zero-token row is still posted so the run shows up in `/cost` rather than silently absent — matching the Python receiver.
-- **Auto-stub pricing:** Aloita auto-creates an `AgentModelPricing` stub for any unknown `(tool, provider, model)` triple, so cost is never a silent `$0`.
-
-Toggle with `postUsage: false` to disable.
-
-## Run diff post-back (on `agent_end`)
-
-When the Pi job for a ticket finishes, the extension captures what the agent changed in the ticket's working directory and POSTs a unified diff to Aloita's per-ticket **diff viewer** — `POST /api/tickets/{id}/diffs` (`TicketDiffEndpoints.cs`). This is the "review without leaving the kanban" artifact, ported 1:1 from the Python receiver's `post_agent_run_diff`.
-
-- **Baseline snapshot at start:** when a ticket is injected, the extension snapshots the working dir's HEAD (`git rev-parse --short HEAD`) *before* the agent runs. The post-run diff is taken against that baseline, so it captures **both committed and uncommitted changes** made during this run — not the whole history.
-- **Untracked files included:** `git diff <base>` is appended with each untracked file (`git ls-files --others --exclude-standard`) rendered as a new-file diff via `git diff --no-index -- /dev/null <path>` — exactly the receiver's technique.
-- **Body:** `{ title, diffText, source: AgentRun(1), baseRef, headRef, sessionId }`. The server stores the raw diff verbatim and caches parsed summary counts (files/additions/deletions).
-- **Best-effort, never blocks:** runs last in `agent_end` (after status is finalized), gated on `postDiff`. A non-git folder, a git failure, or an API error logs a warning and never affects the ticket. `postDiff: false` disables it.
-- **No working dir → skipped:** when a ticket's working dir doesn't resolve (or isn't a git repo), capture is skipped silently.
-
-## Agent log streaming (real time)
-
-While a ticket is active, the extension mirrors the agent's activity to Aloita's per-ticket **agent-log** tab in real time — a direct port of the Python receiver's `AuraAgentLogPusher`. This is what makes a run observable live (and reviewable afterward) without the old subprocess/dashboard.
-
-- **Same pipeline & contract as the receiver:** entries are buffered and flushed in batches of ≤ 50 every 0.5 s to `POST /api/tickets/{id}/agent-log/batch`, each carrying `{ content, sessionId, source, timestamp }`. Best-effort — a failed push logs a warning and never blocks the run.
-- **No subprocess → events are the source.** The old receiver read the CLI's stdout line-by-line. Here Pi *is* the agent, so the equivalent "display lines" are captured from Pi's streaming events and fed to the same pusher:
-  - `message_update` → assistant **text deltas**, split into newline-delimited lines (the analog of the receiver's `read_line_unbounded`). Thinking blocks are intentionally not streamed, matching the old adapter which surfaced display text only.
-- **No tool noise.** Tool calls and results (`▶ bash(…)` / `✓ bash` / `✗ … (error)` markers) are intentionally **not** logged — only the assistant's own text and the lifecycle markers are streamed, to keep the log readable.
-- **Lifecycle mirrors the receiver:** a `--- started ---` line is pushed when the ticket is injected; the pusher is drained + flushed (`close()`) in `agent_end` **before** finalize/usage (the same ordering the receiver's `finally` block uses), and on StopTask/shutdown.
-- **Toggle:** `streamAgentLog: false` disables it with zero overhead (no pusher is created; the feed handlers short-circuit).
-
-The implementation is isolated in `src/agent-log.ts` (`AgentLogPusher`, `TextLineBuffer`, `createAuraAgentLogPoster`), unit-tested with Node's built-in test runner (`npm test`).
+| Command              | Action                                          |
+|----------------------|-------------------------------------------------|
+| `/aloita-status`     | Show connection state, active ticket, queue.    |
+| `/aloita-connect`    | Force reconnect.                                 |
+| `/aloita-disconnect` | Disconnect.                                      |
+| `/aloita-next`       | Drain the next queued ticket.                   |
+| `/aloita-configure`  | Interactive settings UI.                        |
 
 ## Logging
 
-The extension **never writes to stdout/stderr** — that would corrupt Pi's TUI rendering. All diagnostics (connection events, webhook handling, usage/diff post-backs, auto-start launches, capability registration) go to a **log file**:
+Diagnostics go to `~/.pi/aloita.log` (never stdout/stderr, which would corrupt
+Pi's TUI). Set the level via `ALOITA_LOG_LEVEL` (`debug`/`info`/`warn`/`error`/`off`,
+default `info`) and the path via `ALOITA_LOG_FILE`.
 
-``
-~/.pi/aloita.log
-```
-
-Tail it in a separate terminal while Pi runs:
-
-```powershell
-Get-Content ~/.pi/aloita.log -Wait -Tail 20
-# or on Linux/macOS:
-tail -f ~/.pi/aloita.log
-```
-
-**Log levels** (set via `ALOITA_LOG_LEVEL`, case-insensitive): `debug` > `info` (default) > `warn` > `error` > `off`.
-
-**Custom log file** (optional): set `ALOITA_LOG_FILE` to any path (`~` is expanded).
-
-User-facing events (ticket started/finished, errors) still appear as transient toast notifications via `ctx.ui.notify()`, and connection state lives in the footer via `ctx.ui.setStatus()` — the correct Pi UI channels. `/aloita-status` shows a concise one-line summary as a toast; the full detail goes to the log file.
+## License
 
-## Status & caveats
-
-This is a v1 port. Tested live: REST (`GET /api/projects` → 28 projects), SignalR (connect → handshake → subscribe → ping → clean disconnect), capability plan build + auth-user resolution, and usage POST + read-back all pass against the real server.
-
-Known differences from the Python receiver, by design:
-- **Subscription billing only.** The old receiver had two billing paths (Agent SDK credit via `claude -p`, and subscription via the loop bridge). A live Pi session is subscription-billed.
-- **No web dashboard.** Visibility is the Pi status footer + notifications + `/aloita-status`. The full event log / terminal-stream dashboard is gone.
-- **`autoFinalizeOnAgentEnd` marks Done after the triggered turn.** If the agent posts a `aura_start_conversation` and stops, the ticket is still marked Done (matching the old receiver's behavior on `claude -p` exit) — the conversation is resumed when the next webhook arrives. Set `autoFinalizeOnAgentEnd: false` to keep tickets In Progress until a human moves them.
-
-## Layout
-
-```
-src/
-├── index.ts        # entry: lifecycle, webhook→sendUserMessage, queue, finalize, status guard, usage flush, commands
-├── config.ts       # env + JSON config loader (global userMappings + capabilities)
-├── aura-client.ts  # fetch-based port of aura_client.py (get/post/put/delete/upload/download)
-├── signalr.ts      # hand-rolled SignalR JSON protocol over ws (main + registerOnly helper mode)
-├── tools.ts        # all 28 aura_* tools (port of server.py)
-├── prompts.ts      # embedded command templates + label→command routing
-├── capabilities.ts # builds the capability broadcast plan (main + per-user helper split)
-├── agent-log.ts    # real-time agent-log streamer (port of AuraAgentLogPusher) + TextLineBuffer + tool-summary helpers
-├── usage.ts        # accumulates per-model token/cost, posts to /agent-run-usage on agent_end
-├── working-dir.ts  # resolveWorkingDir + shouldClaimTicket (port of resolve_working_dir)
-├── project-launcher.ts # pure auto-start logic (normalize/detect/plan) — see §Auto-start supervisor
-├── config-store.ts # read/write/merge the JSON config file for /aloita-configure
-├── aloita-configure.ts # interactive /aloita-configure settings UI (SelectList + SettingsList)
-```
+MIT

package/config.example.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./config.schema.json",
-  "aloitaUrl": "https://srv1322862.hstgr.cloud",
+  "aloitaUrl": "https://your-aloita-server",
   "apiKey": "kai_REPLACE_ME",
 
   "subscription": {
@@ -12,16 +12,16 @@
     "allProjects": true,
     "allUsers": false,
     "projectIds": [],
-    "userIds": ["5fcb57d1-f3a8-4501-b6f6-82228425b6a3"]
+    "userIds": ["00000000-0000-0000-0000-000000000000"]
   },
 
   "projectFolders": {
-    "00000000-0000-0000-0000-000000000000": "C:\\Users\\frank\\source\\repos\\my-project"
+    "00000000-0000-0000-0000-000000000000": "/path/to/my-project"
   },
 
   "projectFilter": "",
   "matchAllProjects": false,
-  "repos": "C:\\Users\\frank\\source\\repos",
+  "repos": "/path/to/your/repos",
 
   "labelToCommand": {
     "plan": "aura-plan-ticket",
@@ -34,35 +34,35 @@
   "guardStatus": true,
   "autoFinalizeOnAgentEnd": true,
   "postUsage": true,
-  "// postDiff": "Capture the run's git diff (vs the HEAD snapshot taken at ticket start) and POST it to Aloita's per-ticket diff viewer (POST /api/tickets/{id}/diffs). Port of the Python receiver's post_agent_run_diff. Best-effort; never blocks or fails the ticket.",
+  "// postDiff": "Capture the run's git diff and post it to the per-ticket diff viewer. Best-effort; never blocks the ticket.",
   "postDiff": true,
-  "// streamAgentLog": "Stream the agent's text + tool activity to Aloita's per-ticket agent-log tab in real time (POST /api/tickets/{id}/agent-log/batch). Port of the Python receiver's AuraAgentLogPusher. Best-effort; never blocks.",
+  "// streamAgentLog": "Stream the agent's text to the per-ticket agent-log tab in real time. Best-effort; never blocks.",
   "streamAgentLog": true,
   "dedupWindowSeconds": 2,
 
-  "// logging": "Diagnostics go to ~/.pi/aloita.log (never stdout/stderr, which would corrupt Pi's TUI). Override the path via env ALOITA_LOG_FILE. Level via ALOITA_LOG_LEVEL (debug/info/warn/error/off, default info). See README §Logging.",
+  "// logging": "Diagnostics go to ~/.pi/aloita.log. Override the path via env ALOITA_LOG_FILE. Level via ALOITA_LOG_LEVEL (debug/info/warn/error/off, default info).",
 
-  "// autoStart": "Supervisor mode: when on, this Pi session periodically polls /api/projects and spawns a detached child `pi` in each NEW project's folder, so a Pi CLI is online the moment a project is created — no manual `cd <folder> && pi`. Off by default. See README §Auto-start supervisor.",
+  "// autoStart": "Supervisor mode: when on, periodically check for new projects and spawn a detached child pi in each new project's folder. Off by default.",
   "autoStartProjects": false,
   "// autoStartPollSeconds": "Poll interval for new projects, in seconds.",
   "autoStartPollSeconds": 60,
-  "// autoStartCreateFolder": "mkdir the project folder if it doesn't exist yet (a brand-new Aloita project usually has no folder on disk). This is what makes 'no manual step' actually work.",
+  "// autoStartCreateFolder": "Create the project folder if it doesn't exist yet.",
   "autoStartCreateFolder": true,
   "// autoStartPiCommand": "Override the pi command to spawn (defaults to pi.cmd on Windows, pi elsewhere).",
   "autoStartPiCommand": "",
   "// autoStartExcludeProjects": "Project ids to never auto-start.",
   "autoStartExcludeProjects": [],
-  "// autoStartSeedExisting": "When true, launch a child pi for EVERY existing project on supervisor startup (not just new ones). Default false — only newly-created projects are launched.",
+  "// autoStartSeedExisting": "When true, launch a child pi for every existing project on startup (not just new ones). Default false.",
   "autoStartSeedExisting": false,
-  "// autoStartProjectIds": "Allow-list of project ids that the supervisor should auto-start a child pi for. A brand-new project does nothing until you add its id here. Easiest via /aloita-configure.",
+  "// autoStartProjectIds": "Allow-list of project ids to auto-start a child pi for. A new project does nothing until added here. Easiest via /aloita-configure.",
   "autoStartProjectIds": [],
 
-  "// capabilities": "GLOBAL fallback caps registered against the auth user. Prefer userMappings below. Each entry pushes pricing into Aloita AND links the model into the per-user complexity-tier admin UI.",
+  "// capabilities": "Global fallback model capabilities registered against the auth user. Prefer userMappings below.",
   "capabilities": [],
 
-  "// userMappings": "Per-agent-user profiles. Key = Aloita agent user id. The auth user (env key) may omit apiKey; OTHER users must include their own apiKey so their capabilities register over a connection authenticated as them (Aloita binds RegisterCapabilities to the connected user).",
+  "// userMappings": "Per-agent-user profiles. Key = agent user id. The auth user may omit apiKey; other users must include their own apiKey.",
   "userMappings": {
-    "927fc980-4cd6-4323-ac72-2a9be24f2730": {
+    "00000000-0000-0000-0000-000000000000": {
       "tool": "pi",
       "capabilities": [
         {

package/package.json

@@ -1,25 +1,14 @@
 {
   "name": "aloita-extensions",
-  "version": "0.4.7",
-  "description": "Pi extensions that replace the Aura SignalR receiver + Aura MCP server. A single Pi session connects to Aloita (formerly Aura) over SignalR and works on tickets natively.",
+  "version": "0.4.8",
+  "description": "A Pi extension: one Pi session connects to an Aloita server and works on tickets natively.",
   "keywords": [
     "pi-package",
     "aloita",
-    "aura",
-    "kanban",
-    "signalr",
     "agent"
   ],
   "license": "MIT",
-  "author": "Frank Vliegen <frankvl76@users.noreply.github.com>",
-  "homepage": "https://github.com/frankvl76/aloita-extensions#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/frankvl76/aloita-extensions.git"
-  },
-  "bugs": {
-    "url": "https://github.com/frankvl76/aloita-extensions/issues"
-  },
+  "author": "Frank Vliegen",
   "type": "module",
   "engines": {
     "node": ">=18"
@@ -31,7 +20,6 @@
   },
   "files": [
     "src/",
-    "docs/",
     "README.md",
     "LICENSE",
     "config.example.json",

package/src/index.ts

@@ -44,11 +44,15 @@ import { createExtensionLogger, type LogSink, type AloitaLogger } from "./logger
 import {
 	detectProjectsToLaunch,
 	normalizeProjects,
+	parsePid,
+	pidFilePath,
 	planLaunch,
+	reconcileLaunched,
+	resolveProjectDir,
 	type LaunchPlan,
 	type ProjectInfo,
 } from "./project-launcher.ts";
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
 
 interface QueuedTicket {
@@ -474,6 +478,20 @@ export default function aloitaExtension(pi: ExtensionAPI) {
 
 	// ── Auto-start supervisor ──────────────────────────────────────────────
 
+	/** Best-effort liveness probe for a pid: `process.kill(pid, 0)` sends no
+	 *  signal and only reports whether the process exists. EPERM (exists but
+	 *  not ours) counts as alive; ESRCH (no such process) counts as dead.
+	 *  Used by the supervisor to tell a previously-launched child pi is still
+	 *  running so it won't re-spawn a duplicate on restart. */
+	function probePidAlive(pid: number): boolean {
+		try {
+			process.kill(pid, 0);
+			return true;
+		} catch (e) {
+			return (e as NodeJS.ErrnoException).code === "EPERM";
+		}
+	}
+
 	/** Polls `/api/projects` and spawns a detached child `pi` in each new
 	 *  project's folder, so a Pi CLI is online the moment a project is created.
 	 *  Started on `session_start` when `autoStartProjects` is on; stopped on
@@ -482,8 +500,11 @@ export default function aloitaExtension(pi: ExtensionAPI) {
 		private timer: ReturnType<typeof setTimeout> | null = null;
 		private running = false;
 		/** Project ids we've already launched during this supervisor lifetime, so
-		 *  we never double-launch even if the allow-list keeps mentioning them. */
-		private readonly launched = new Set<string>();
+		 *  we never double-launch even if the allow-list keeps mentioning them.
+		 *  Reconciled against persistent pidfiles on every tick so that a
+		 *  restarted supervisor recognizes children that are still running —
+		 *  the fix for the duplicate-sessions-on-restart bug. */
+		private launched = new Set<string>();
 
 		start(): void {
 			if (this.timer) return;
@@ -521,6 +542,16 @@ export default function aloitaExtension(pi: ExtensionAPI) {
 			try {
 				const raw = await client.get("/api/projects");
 				const projects = normalizeProjects(raw);
+				// Reconcile against persistent pidfiles FIRST: a freshly-restarted
+				// supervisor has an empty `launched` set, but the detached child pi
+				// processes from the previous session are still alive. Without this
+				// step, detectProjectsToLaunch would return every allow-listed
+				// project and we'd spawn duplicates. Projects whose pidfile is stale
+				// (child exited) are dropped from the set so they can be re-launched.
+				this.launched = reconcileLaunched(
+					this.launched,
+					await this.collectPidStatuses(projects),
+				);
 				// Allow-list model: launch only for projects the operator opted in
 				// (autoStartProjectIds) and hasn't launched yet this lifetime.
 				const toLaunch = detectProjectsToLaunch(this.launched, config.autoStartProjectIds, projects);
@@ -569,6 +600,51 @@ export default function aloitaExtension(pi: ExtensionAPI) {
 				shell: process.platform === "win32",
 			});
 			child.unref();
+			// Record the child's pid next to its config so a future/restarted
+			// supervisor can detect it is still running and skip re-launching
+			// (the duplicate-session fix). On Windows `shell:true` the pid is the
+			// cmd.exe wrapper, which stays alive exactly as long as pi does, so it
+			// is a faithful liveness proxy on both platforms.
+			if (typeof child.pid === "number" && child.pid > 0) {
+				try {
+					await writeFile(pidFilePath(plan.cwd), String(child.pid), "utf8");
+				} catch (e) {
+					log(`[aloita] auto-start pidfile write failed for ${plan.projectId}: ${(e as Error).message}`);
+				}
+			}
+		}
+
+		/** Read each project's pidfile (when its folder resolves) and probe the
+		 *  recorded pid for liveness. Used by {@link tick} to reconcile the
+		 *  in-memory `launched` set against persistent state. Stale pidfiles
+		 *  (dead pid) are cleaned up here so they don't linger. */
+		private async collectPidStatuses(projects: ProjectInfo[]) {
+			const allowList = new Set(config.autoStartProjectIds);
+			const statuses = [];
+			for (const project of projects) {
+				if (!allowList.has(project.id)) continue;
+				const dir = resolveProjectDir(project, config);
+				if (!dir) continue;
+				const file = pidFilePath(dir);
+				let content: string | null = null;
+				try {
+					content = await readFile(file, "utf8");
+				} catch {
+					// No pidfile yet — never launched, or launched this lifetime
+					// before the write completed. Nothing to reconcile.
+					continue;
+				}
+				const pid = parsePid(content);
+				if (pid === null) continue;
+				const alive = probePidAlive(pid);
+				if (!alive) {
+					// Stale: the child is gone. Best-effort cleanup so the file
+					// doesn't keep referencing a recycled pid later.
+					try { await rm(file, { force: true }); } catch { /* best-effort */ }
+				}
+				statuses.push({ projectId: project.id, pid, alive });
+			}
+			return statuses;
 		}
 	}
 

package/src/project-launcher.test.ts

@@ -21,7 +21,11 @@ import {
 	detectNewProjects,
 	detectProjectsToLaunch,
 	normalizeProjects,
+	parsePid,
+	pidFilePath,
 	planLaunch,
+	reconcileLaunched,
+	resolveProjectDir,
 	shouldAutoStart,
 	type AutoStartConfig,
 	type ProjectInfo,
@@ -321,3 +325,98 @@ describe("planLaunch — plan shape", () => {
 		assert.match(res.reason, /allow-list/);
 	});
 });
+
+// ── pidfile helpers (duplicate-session fix) ───────────────────────────────
+
+describe("pidFilePath", () => {
+	it("places the pidfile in <dir>/.pi/aloita.autostart.pid", () => {
+		const p = pidFilePath("/repos/alpha");
+		assert.match(p, /[\\/]\.pi[\\/]aloita\.autostart\.pid$/);
+	});
+});
+
+describe("parsePid", () => {
+	it("parses a plain integer", () => {
+		assert.equal(parsePid("12345"), 12345);
+	});
+
+	it("tolerates surrounding whitespace/newlines", () => {
+		assert.equal(parsePid("  4242\n"), 4242);
+	});
+
+	it("returns null for empty / missing content", () => {
+		assert.equal(parsePid(null), null);
+		assert.equal(parsePid(undefined), null);
+		assert.equal(parsePid(""), null);
+		assert.equal(parsePid("   "), null);
+	});
+
+	it("returns null for non-numeric or non-positive content", () => {
+		assert.equal(parsePid("not-a-pid"), null);
+		assert.equal(parsePid("0"), null);
+		assert.equal(parsePid("-5"), null);
+	});
+});
+
+describe("resolveProjectDir", () => {
+	it("mirrors planLaunch folder resolution (override wins)", () => {
+		const cfg = baseConfig({ repos: "/repos", projectFolders: { p1: "$REPOS/alpha" } });
+		assert.equal(resolveProjectDir({ id: "p1", name: "Alpha" }, cfg), "/repos/alpha");
+	});
+
+	it("derives $REPOS/<slug> when nothing else is set", () => {
+		const cfg = baseConfig({ repos: "/repos" });
+		assert.equal(resolveProjectDir({ id: "p1", name: "My Cool Project" }, cfg), "/repos/my-cool-project");
+	});
+
+	it("returns null when nothing resolves", () => {
+		const cfg = baseConfig({ repos: "" });
+		assert.equal(resolveProjectDir({ id: "p1", name: "Alpha" }, cfg), null);
+	});
+});
+
+describe("reconcileLaunched", () => {
+	it("adds projects whose child is still alive (the restart/duplicate fix)", () => {
+		// Fresh supervisor after restart: launched set is empty, but the child
+		// for p1 is still running (alive pidfile). p1 must NOT be re-launched.
+		const out = reconcileLaunched(new Set(), [
+			{ projectId: "p1", pid: 111, alive: true },
+		]);
+		assert.ok(out.has("p1"));
+	});
+
+	it("removes projects with a stale (dead) pidfile so they re-launch", () => {
+		const out = reconcileLaunched(new Set(["p1", "p2"]), [
+			{ projectId: "p1", pid: 111, alive: false }, // child died
+		]);
+		assert.ok(!out.has("p1"), "p1 should be dropped (stale)");
+		assert.ok(out.has("p2"), "p2 untouched");
+	});
+
+	it("leaves projects with no pidfile untouched", () => {
+		// Launched this lifetime before the pidfile existed — don't lose it,
+		// and don't add unknown projects either.
+		const out = reconcileLaunched(new Set(["p3"]), []);
+		assert.ok(out.has("p3"));
+		assert.equal(out.size, 1);
+	});
+
+	it("combines alive/stale/unknown in one pass", () => {
+		const out = reconcileLaunched(new Set(["p1", "p4"]), [
+			{ projectId: "p1", pid: 1, alive: true },  // keep (alive)
+			{ projectId: "p2", pid: 2, alive: true },  // add (alive)
+			{ projectId: "p3", pid: 3, alive: false }, // not present, no-op (was never in set)
+			{ projectId: "p4", pid: 4, alive: false }, // drop (stale)
+		]);
+		assert.ok(out.has("p1"));
+		assert.ok(out.has("p2"));
+		assert.ok(!out.has("p3"));
+		assert.ok(!out.has("p4"));
+	});
+
+	it("does not mutate the input set", () => {
+		const input = new Set(["p1"]);
+		reconcileLaunched(input, [{ projectId: "p2", pid: 9, alive: true }]);
+		assert.deepEqual([...input], ["p1"]);
+	});
+});

package/src/project-launcher.ts

@@ -145,6 +145,81 @@ export interface SkipResult {
 	reason: string;
 }
 
+/** Resolve the launch folder for a project using the same precedence as
+ *  {@link planLaunch} (override → LocalFolder → $REPOS/<slug>). Returns the
+ *  absolute dir, or `null` when nothing resolves. Exposed so the controller
+ *  can locate a project's pidfile for liveness reconciliation without having
+ *  to run a full {@link planLaunch} (which would also enforce create-folder
+ *  rules we don't want during a read-only reconcile). */
+export function resolveProjectDir(
+	project: ProjectInfo,
+	config: AutoStartConfig,
+): string | null {
+	return resolveLaunchFolder(project, config).dir;
+}
+
+/** Path to the pidfile the supervisor writes next to the project-local
+ *  config: `<dir>/.pi/aloita.autostart.pid`. Holds the PID of the detached
+ *  child `pi` so a restarted supervisor can tell that project's child is
+ *  still running and skip re-launching it — the fix for the duplicate-sessions
+ *  bug. */
+export function pidFilePath(dir: string): string {
+	return resolve(dir, ".pi", "aloita.autostart.pid");
+}
+
+/** Parse a pidfile's contents into a positive integer PID, or `null` when
+ *  the content is missing/empty/not a usable integer. Tolerant of trailing
+ *  whitespace/newlines. Pure. */
+export function parsePid(content: string | null | undefined): number | null {
+	if (content == null) return null;
+	const n = Number.parseInt(content.trim(), 10);
+	return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
+/** Liveness snapshot for one project's previously-launched child, as
+ *  determined by its pidfile + a liveness probe supplied by the controller
+ *  (via `process.kill(pid, 0)`). */
+export interface PidStatus {
+	projectId: string;
+	/** Pid read from the pidfile, or `null` when no pidfile exists. */
+	pid: number | null;
+	/** True when `pid` is alive (probed by the controller). Always `false`
+	 *  when `pid` is `null`. */
+	alive: boolean;
+}
+
+/** Reconcile the supervisor's `launched` set against pidfile liveness.
+ *
+ *  This is the core of the duplicate-session fix. Because the `launched` set
+ *  is in-memory and per-supervisor-lifetime, a fresh supervisor (after a Pi
+ *  restart) would otherwise see an empty set and re-spawn children that are
+ *  still running. Reconciling against the persistent pidfiles makes that set
+ *  survive restarts:
+ *
+ *  - a project whose child is **still alive** → added to the set (skip it);
+ *  - a project with a **stale** (dead) pidfile → removed from the set so it
+ *    can be re-launched (the child exited/crashed);
+ *  - a project with **no pidfile at all** → left untouched (the controller
+ *    may have launched it this lifetime before the file existed, or it simply
+ *    hasn't been launched yet).
+ *
+ *  Returns a new Set; does not mutate the input. Pure given `statuses`. */
+export function reconcileLaunched(
+	launched: Set<string>,
+	statuses: PidStatus[],
+): Set<string> {
+	const out = new Set(launched);
+	for (const s of statuses) {
+		if (s.alive) {
+			out.add(s.projectId);
+		} else if (s.pid !== null) {
+			// Stale pidfile: the child is gone, so allow a fresh launch.
+			out.delete(s.projectId);
+		}
+	}
+	return out;
+}
+
 /** Outcome of {@link planLaunch}: either an executable plan or a skip reason. */
 export type PlanResult = LaunchPlan | ({ skip: true } & SkipResult);
 

package/docs/status-indicator-preview.md

@@ -1,65 +0,0 @@
-# Aloita Status Bar — Indicator Styling (before / after)
-
-Ticket: **Pi Status Bar: Improve Aloita Connection Indicator Styling**
-
-## Requirements (all met)
-
-1. ✅ Status circle (dot) **green** to signal an active connection
-2. ✅ Label **capitalized** to "Aloita" (was "aloita")
-3. ✅ "connected" text **green** for visual clarity
-
-## How it renders
-
-Color is applied via Pi's `Theme.fg(color, text)` (`ctx.ui.theme`), which embeds
-ANSI codes the footer renders natively. `success` = green by default and respects
-the user's theme. The footer's `sanitizeStatusText` does not strip ANSI, and its
-`truncateToWidth` (from `@earendil-works/pi-tui`) is ANSI-aware, so truncation
-stays correct.
-
-### Before
-
-```
-○ aloita: connected
-● aloita: connected · working #abc-123 · +2 queued
-✕ aloita: connection lost: timeout
-```
-(all one color — the terminal's default fg)
-
-### After
-
-```
-{green}○{reset} Aloita: {green}connected{reset}
-{green}●{reset} Aloita: {green}connected{reset} · working #abc-123 · +2 queued
-{dim}✕{reset} Aloita: {dim}connection lost: timeout{reset}
-```
-
-Concrete ANSI (what `Theme.fg` actually emits):
-
-| State | Dot | Label | Connection |
-|---|---|---|---|
-| Connected & idle | `\x1b[32m○\x1b[39m` (green hollow) | `Aloita` | `\x1b[32mconnected\x1b[39m` (green) |
-| Working a ticket | `\x1b[32m●\x1b[39m` (green filled) | `Aloita` | `\x1b[32mconnected\x1b[39m` (green) |
-| Disconnected | `\x1b[2m✕\x1b[39m` (dim) | `Aloita` | `\x1b[2m<connectionState>\x1b[39m` (dim) |
-
-## Design decisions
-
-- **Green = "active connection" only.** Reserved for the connected/working
-  indicator as the ticket specifies. The working/queue suffix is left uncolored
-  so the green indicator stands out.
-- **Disconnected is dim, not red.** Neutral — avoids crying wolf during benign
-  states like "not started" / "stopped" at startup. The `✕` glyph already
-  communicates "down". (A red-for-real-errors variant is a trivial follow-up if
-  desired: pass `"error"` instead of `"dim"` in `buildStatusText`.)
-- **Internal `setStatus` key stays lowercase `"aloita"`.** The footer renders
-  only the value, not the key; the capitalized "Aloita" is the visible label.
-
-## Files
-
-- `src/status.ts` — pure `buildStatusText(input, colorizer)` + types
-- `src/status.test.ts` — 12 unit tests (`node:test`, fake tag-wrapping colorizer)
-- `src/index.ts` — `renderStatus` delegates to `buildStatusText(..., ctx.ui.theme)`
-
-## Verification
-
-- `npm run build` (`tsc --noEmit`): **green**
-- `npm test`: **42/42 pass** (12 new + 30 prior)

package/docs/ui-customisation-limits.md

@@ -1,274 +0,0 @@
-# Pi Extension — UI Customisation Limits
-
-Ticket: **Investigate UI Customisation Limits of the Pi Extension**
-
-Goal: document the technical boundaries of what the Aloita Pi extension can do
-to Pi's UI — not to commit to an implementation, but to define what options are
-on the table for future design decisions. The headline question we were asked:
-**"Could we introduce a side navigation panel? What other structural UI
-modifications are feasible?"**
-
-Source material:
-- Pi docs — `docs/tui.md`, `docs/extensions.md` (installed with
-  `@earendil-works/pi-coding-agent`)
-- Pi example extensions — `examples/extensions/custom-footer.ts`,
-  `custom-header.ts`, `overlay-qa-tests.ts`, `plan-mode/`, `modal-editor.ts`,
-  `doom-overlay/`
-- Current Aloita extension UI surface — `src/status.ts`, `src/index.ts`
-  (uses `ctx.ui.setStatus` + `ctx.ui.notify` only)
-
----
-
-## 1. The UI surface Pi exposes to extensions
-
-Everything below is reachable from the extension's `ctx` (event handlers,
-commands, tools) or from `pi` (factory). All `ctx.ui.*` component factories and
-`ctx.ui.custom()` require `ctx.mode === "tui"`; in RPC mode the fire-and-forget
-helpers (`notify`, `setStatus`, `setWidget`) still work, and in print / JSON
-mode `ctx.hasUI === false`.
-
-### 1.1 Layout-region hooks (structural)
-
-| Hook | What it replaces | Reclaims space? | Persistent? |
-|---|---|---|---|
-| `ctx.ui.setStatus(key, text)` | One footer status slot (keyed) | No — slot in existing footer | Yes |
-| `ctx.ui.setFooter(factory)` | The **entire footer** row | Yes — owns the row | Yes |
-| `ctx.ui.setHeader(factory)` | The **entire header** (logo + keybinding hints) | Yes — owns the row | Yes |
-| `ctx.ui.setWidget(key, …, { placement })` | A block **above** (default) or **below** the editor | Yes — inserts a region | Yes |
-| `ctx.ui.setEditorComponent(factory)` | The **input editor** itself | Yes — owns that region | Yes |
-| `ctx.ui.setWorkingMessage / setWorkingVisible / setWorkingIndicator` | The streaming "working" loader row | No — existing row | Streaming-only |
-| `ctx.ui.setTitle(text)` | Terminal title (OSC 0/2) | n/a | Yes |
-| `ctx.ui.setTheme(name \| Theme)` | Whole color theme | n/a | Yes |
-
-All of these are vertical regions stacked top-to-bottom:
-
-```
-┌──────── header  (setHeader) ────────────┐
-│              message stream              │  ← NOT replaceable by extensions
-│                                          │    (only message_end content mutation)
-│              ── widget above ──          │  ← setWidget (default placement)
-│              input editor                │  ← setEditorComponent
-│              ── widget below ──          │  ← setWidget({ placement: "belowEditor" })
-│              working loader              │  ← setWorkingIndicator / setWorkingMessage
-└──────── footer  (setFooter / setStatus) ┘
-```
-
-**There is no "split the message stream into a left/right column" hook.** This
-is the single biggest structural limitation (see §3).
-
-### 1.2 Dialogs (modal, blocking)
-
-`ctx.ui.select / confirm / input / editor` — all support `{ timeout }` and
-`AbortSignal`. `notify(msg, "info"|"warning"|"error")` is non-blocking.
-
-### 1.3 Custom TUI components & overlays (the powerful one)
-
-`ctx.ui.custom(component)` — replaces the whole screen with an arbitrary
-`Component` (`render(width): string[]`, `handleInput`, `invalidate`). Useful for
-wizards, menus, games (the `snake.ts` / `space-invaders.ts` / `doom-overlay/`
-examples prove real-time interaction works).
-
-`ctx.ui.custom(component, { overlay: true, overlayOptions })` — renders the
-component **on top of** the existing UI without clearing it. Options:
-
-| Option | Values |
-|---|---|
-| `anchor` | 9 positions: `top-left`, `top-center`, `top-right`, `left-center`, `center`, `right-center`, `bottom-left`, `bottom-center`, `bottom-right` |
-| `width` / `minWidth` / `maxHeight` | number or `"%"` string |
-| `offsetX` / `offsetY` | integer offset from anchor |
-| `margin` | number, or `{ top, right, bottom, left }` |
-| `row` / `col` | absolute or `%` positioning (alternative to anchor) |
-| `visible: (termW, termH) => boolean` | **responsive auto-hide** (e.g. hide < 100 cols) |
-| `onHandle(handle)` | programmatic `focus()`, `unfocus({ target })`, `setHidden(bool)`, `hide()` |
-
-Overlay capabilities (all demonstrated in `overlay-qa-tests.ts`):
-
-- **Multiple overlays can stack**, with z-order and focus cycling (Tab).
-- **Passive / non-capturing overlays** — visible alongside the active overlay
-  and the editor; user keeps typing.
-- **Real-time updates** at ~30 FPS (`doom-overlay`, `overlay-animation`) —
-  refresh-driven by `tui.requestRender()`.
-- **IME-aware inputs** via the `Focusable` interface + `CURSOR_MARKER`.
-- **Toggle visibility** programmatically via `handle.setHidden()`.
-
-### 1.4 Other customisation hooks
-
-| Hook | Purpose |
-|---|---|
-| `ctx.ui.addAutocompleteProvider(...)` | Layer custom completions on top of built-in slash/path completion (e.g. `#ticket-id`, `@user`) |
-| `ctx.ui.setEditorText / getEditorText / pasteToEditor` | Editor content control |
-| `ctx.ui.setToolsExpanded(bool)` | Tool output expansion default |
-| `ctx.ui.getAllThemes / getTheme / setTheme` | Theme management; can ship a custom theme file |
-| Tool `renderCall(args, theme, ctx)` / `renderResult(result, opts, theme, ctx)` | Custom rendering per `aura_*` tool call/result (ticket cards, status pills, diff stats) |
-| `pi.registerCommand / registerShortcut / registerFlag` | Slash commands, keybindings, CLI flags |
-| `before_agent_start` (`message` + `systemPrompt`) | Inject persistent messages or rewrite the system prompt |
-| `message_end` (return `{ message }`) | Mutate finalised message content (not chrome) |
-
----
-
-## 2. The side-navigation-panel question
-
-### TL;DR
-
-| Tier | Approach | True side-by-side? | Recommended? |
-|---|---|---|---|
-| A | Reserve a column in the message area | ✅ (ideal) | ❌ **Not exposed by Pi** — would require an upstream change |
-| B | Right-anchored **overlay** panel | ⚠️ Overlays occlude, they don't reflow | ✅ **Closest feasible analog** — 1-day spike |
-| C | `setWidget` block above/below editor | ❌ (horizontal strip, not a column) | ✅ For a compact queue/active-ticket strip |
-
-### Tier A — true persistent side-by-side: NOT available
-
-Pi's extension layout model is **vertical regions only** (§1.1). There is no
-`setSidePanel`, no `splitMain`, no column manager. The message-stream column
-width is fixed by the terminal width and is not adjustable from an extension.
-Any "side nav that lives next to the conversation and squeezes it" requires an
-upstream Pi change. Worth proposing upstream if this becomes important, but out
-of scope for an extension today.
-
-### Tier B — overlay side panel: FEASIBLE (recommended spike)
-
-This is the closest analog and is already proven by the `SidepanelComponent` in
-`overlay-qa-tests.ts` (command `/overlay-sidepanel`). Sketch:
-
-```typescript
-pi.registerCommand("aloita-panel", {
-  handler: async (_args, ctx) => {
-    await ctx.ui.custom<void>((tui, theme, _kb, done) =>
-      new AloitaSidePanel(tui, theme, done), {
-      overlay: true,
-      overlayOptions: {
-        anchor: "right-center",
-        width: "25%",
-        minWidth: 30,
-        margin: { right: 1 },
-        visible: (w) => w >= 100,   // auto-hide on narrow terminals
-      },
-    });
-  },
-});
-```
-
-**Capabilities** (all already supported):
-- Anchored to the right edge, full height, ~25% width, with a 1-col margin.
-- Auto-hides below 100 cols (the `visible` callback).
-- **Non-capturing** variant lets the user keep typing in the editor while the
-  panel is visible (`overlay-passive` example pattern).
-- Can be toggled by a `pi.registerShortcut` keybinding, with
-  `handle.setHidden()` to show/hide without rebuilding.
-- Refresh-driven by `tui.requestRender()` on Aloita events
-  (`WebhookEvent`, status changes, queue depth).
-- Can render live data: connection state, active ticket (title + status),
-  queued tickets, recent activity feed — all of which the extension already
-  holds in `src/index.ts` (`activeTicket`, `pendingQueue`, `connectionState`).
-
-**Caveat (the key boundary):**
-> **Overlays paint over content; they do not reflow it.**
-> A 25%-width right-anchored panel covers the rightmost 25% of the message
-> stream. Long code lines under the panel are occluded, not wrapped. This is
-> acceptable for a status/nav panel (short lines, user can dismiss with Esc),
-> but it is not a substitute for a true split layout.
-
-### Tier C — widget-as-panel: partial alternative
-
-`ctx.ui.setWidget("aloita-nav", lines, { placement: "belowEditor" })` is
-persistent, reflows naturally, and never occludes — but it is a horizontal
-strip, not a vertical column. Good for a compact one-line-per-item queue:
-
-```
-aloita: ● connected · working #abc — Fix login · +2 queued
-        ↑ this is what we already render via setStatus
-```
-
-A `setWidget` block below the editor could show the queue + active ticket as a
-multi-line strip. This is the lowest-effort visible upgrade and stacks cleanly
-with Tier B (panel for detail, widget for at-a-glance).
-
----
-
-## 3. Other structural UI modifications that ARE feasible
-
-Ranked by value-to-Aloita / effort:
-
-1. **Custom footer** (`setFooter`) — we already compute the data in
-   `buildStatusText`; `setFooter` would let us own the whole row (model,
-   token cost, git branch, Aloita status). Trivial follow-up to current work.
-2. **Custom header** (`setHeader`) — replace the logo + keybinding hints with
-   the Aloita project name, active model, connection state. Same factory shape
-   as `setFooter`.
-3. **Custom autocomplete** (`addAutocompleteProvider`) — `#ticket-id` →
-   surface matching tickets, `@user` → users, `/aloita-` → our commands.
-   Triggers on `#`, `@`, `/`.
-4. **Rich tool renderers** (`renderCall` / `renderResult` on the 28 `aura_*`
-   tools) — render `aura_get_ticket_context` as a ticket card, `aura_list_tickets`
-   as a kanban-style list, `aura_search_console_query` as a mini table, diffs as
-   stat pills (`+12 -3`). This is where the biggest perceived-UX win lives,
-   without touching layout.
-5. **Custom editor keybindings** (`setEditorComponent` wrapping the default) —
-   e.g. `<C-a>t` to insert the active ticket link, `<C-a>n` to inject
-   `/aloita-next`. Modal-editing example shows the pattern.
-6. **Custom working indicator** (`setWorkingIndicator`) — theme the streaming
-   spinner to Aloita colours.
-7. **Custom Aloita theme** — ship a `.pi` theme file branded to Aloita.
-8. **Overlay dialogs for high-value prompts** — e.g. when `aura_start_conversation`
-   fires, surface the question as a `SelectList` overlay the user can answer
-   with arrow keys instead of typing.
-
----
-
-## 4. Hard limitations / things we CANNOT do from an extension
-
-1. **No split-layout / column API.** Cannot reserve a side column next to the
-   message stream (§2, Tier A). This is the one structural modality that would
-   require an upstream Pi change.
-2. **Overlays occlude, they don't reflow.** Tier B panels cover content rather
-   than squeezing the conversation.
-3. **The message-stream rendering is not customisable.** Extensions can mutate
-   message *content* (`message_end` → `{ message }`) but cannot replace the
-   per-message chrome (avatars, role labels, spacing). Tools have
-   `renderCall` / `renderResult`; user/assistant messages do not.
-4. **TUI mode only for full UI.** `ctx.ui.custom`, all `set*Component`/
-   `setFooter`/`setHeader` factories, and component overlays require
-   `ctx.mode === "tui"`. RPC mode degrades to `notify` / `setStatus` /
-   `setWidget`; print / JSON modes have `ctx.hasUI === false`. Any UI feature
-   we ship must guard on `ctx.mode === "tui"` and degrade gracefully when the
-   session is driven headlessly by an Aloita webhook.
-5. **No HTML/DOM.** Pi is a terminal app; all rendering is ANSI/Unicode. A
-   web-style side nav with icons, images-in-DOM, etc. is not on the table
-   (terminal images *are* supported via the `Image` component for
-   Kitty/iTerm2/Ghostty/WezTerm/Warp, but layout is still cell-based).
-6. **One SignalR subscription per Aloita auth user.** Architectural constraint
-   from `src/signalr.ts`; bounds how many independent live-data panes we can
-   sensibly fan out (not really a UI limit, but it bounds what a "multi-project
-   dashboard panel" could show without extra helper connections).
-
----
-
-## 5. Recommendations
-
-For the immediate goal of "more structural UI for Aloita":
-
-1. **Spike Tier B — `/aloita-panel` overlay** (1 day). Use the existing
-   `SidepanelComponent` as a template. Wire it to the extension's existing
-   `activeTicket` / `pendingQueue` / `connectionState`. Make it non-capturing
-   and toggleable. This is the closest thing to a side navigation panel and
-   answers the headline question with a working prototype.
-2. **Promote `setStatus` → `setFooter`** (half day). Owns the whole footer row
-   and lets us show model + cost + branch alongside the Aloita status we
-   already render.
-3. **Add `#ticket-id` autocomplete** (half day). High perceived polish for
-   low effort.
-4. **Rich `aura_*` tool renderers** (1–2 days). The biggest UX win that does
-   not touch layout — ticket cards, kanban lists, diff stat pills.
-5. **Reserve Tier A (true split layout) as an upstream Pi feature request.**
-   If the overlay panel proves valuable but the occlusion caveat bites, that
-   is the moment to file an issue on Pi proposing a `setSidePanel`-style
-   column-aware layout manager.
-
----
-
-## 6. Verification
-
-- `npm run build` (`tsc --noEmit`): **green**
-- Investigation is documentation-only; no source changes were made to
-  `src/`. All APIs referenced are taken from the installed
-  `@earendil-works/pi-coding-agent` docs and example extensions.