aimux-cli 0.1.16 → 0.1.19

package/README.md

@@ -16,8 +16,8 @@ aimux uses `tmux` as its terminal runtime substrate. Each project gets its own m
 - **Dashboard view** — see all running, offline, and remote agents at a glance
 - **Multi-instance** — run aimux in multiple terminal tabs; agents from other instances appear inline and can be taken over
 - **Agent lifecycle** — two-step kill (`[x]` stops → offline, `[x]` again → graveyard), with `aimux graveyard resurrect` for recovery
-- **Task delegation** — agents can delegate work to each other via `.aimux/tasks/`, with automatic dispatch, completion notifications, and dashboard badges
-- **Threaded orchestration** — direct messages, handoffs, and task assignment all flow through durable `.aimux/threads/` state with queued delivery when recipients are busy
+- **Task delegation** — agents can create explicit handoff records in `.aimux/tasks/`; users and control-plane clients can coordinate teammate work through the metadata API
+- **Threaded orchestration** — direct messages, handoffs, and task assignment all flow through durable `.aimux/threads/` state and explicit user/agent workflow actions
 - **Dashboard orchestration actions** — from the main dashboard, use `S` to send a message, `H` to send a handoff, `T` to assign a task, `o` to jump to the most relevant thread, and `R` to reply when something is waiting on you
 - **Workflow view** — a dedicated workflow screen groups related task/review/revision chains, supports actionable filters, and exposes explicit accept/block/complete/reopen/review controls
 - **Next-action guidance** — dashboard rows and details surface `on me`, `blocked`, family-chain pressure, and the single most relevant next orchestration step
@@ -50,7 +50,7 @@ curl -fsSL https://raw.githubusercontent.com/TraderSamwise/aimux/master/scripts/
 ```
 
 This installs the bundled release under `~/.aimux/native/` and links `aimux` into `~/.local/bin`.
-It still requires Node.js >= 18 and `tmux` in `PATH`; it does not require npm/yarn on the target machine.
+It still requires Node.js >= 24 and `tmux` in `PATH`; it does not require npm/yarn on the target machine.
 
 To install a specific version:
 
@@ -58,6 +58,15 @@ To install a specific version:
 curl -fsSL https://raw.githubusercontent.com/TraderSamwise/aimux/master/scripts/install.sh | AIMUX_VERSION=0.1.13 sh
 ```
 
+To install a frozen local build from the current checkout:
+
+```bash
+AIMUX_RELEASE_VERSION=0.1.16-local.$(git rev-parse --short HEAD) yarn release:asset
+scripts/install.sh release/aimux-darwin-arm64.tar.gz
+```
+
+That keeps `aimux` as a stable installed artifact under `~/.aimux/native/` instead of a live symlink to the repository.
+
 ### Build from source
 
 ```bash
@@ -71,7 +80,33 @@ yarn build
 yarn link
 ```
 
-Requires Node.js >= 18 and `tmux` in `PATH`.
+Requires Node.js >= 24 and `tmux` in `PATH`.
+
+### Develop the App from Source
+
+The browser/mobile client lives in `app/` and talks to the local aimux daemon.
+
+```bash
+yarn install
+cp app/.env.example app/.env
+yarn dev:gui:web      # web app + local daemon
+yarn dev:gui:ios      # build/install/open iOS simulator dev build
+yarn dev:gui:android  # build/install/open Android emulator dev build
+```
+
+Use `aimux-dev` for repo-linked Aimux development. It uses `~/.aimux-dev`, daemon port `43191`, development defaults, and the local web app at `http://localhost:8081`. Keep `aimux` reserved for stable/prod-like project work and remote auth against `https://aimux.app`.
+
+For an already-installed native dev build:
+
+```bash
+yarn build
+node bin/aimux-dev daemon ensure
+cd app
+yarn dev:native:local
+```
+
+Only one Expo/Metro process can own port `8081`. If the simulator loads another
+app's JavaScript bundle, stop that other Expo process and restart Aimux Metro.
 
 ## Quick Start
 
@@ -121,12 +156,12 @@ Each active project may have one daemon-managed project service. That project se
 
 There is no per-project host election anymore. Dashboard processes are clients, not control-plane owners.
 
-Desktop/Tauri now talks to the live control plane directly:
+The user-facing client (browser + mobile) at `app/` talks to the live control plane directly:
 
 - daemon HTTP is used for project discovery / service discovery
 - project-service HTTP is used for live project state and awaited lifecycle actions
-- `statusline.json` remains a derived artifact for tmux/status/debugging, not the desktop's primary transport
-- desktop loading state should clear on heartbeat reconciliation of the expected state change, not on HTTP return alone
+- `statusline.json` remains a derived artifact for tmux/status/debugging, not the client's primary transport
+- client loading state should clear on heartbeat reconciliation of the expected state change, not on HTTP return alone
 
 Terminal clients are isolated from each other:
 
@@ -187,13 +222,9 @@ aimux worktree create feature-x --project /abs/path/to/repo --json
 desktop terminal focus now uses the thin tmux fast-control entrypoint via the project service and terminal client tty
 ```
 
-HTTP-backed agent I/O helpers:
+HTTP-backed agent output helpers:
 
 ```bash
-# Send raw input to a running agent through the project service
-aimux host agent-send <sessionId> "hello\r"
-printf 'hello\r' | aimux host agent-send <sessionId> --stdin
-
 # Read a tmux pane snapshot for a running agent
 aimux host agent-read <sessionId> --start-line -80
 
@@ -208,21 +239,10 @@ Ephemeral project events:
 curl -N http://127.0.0.1:<project-service-port>/events
 ```
 
-These commands are additive control-plane helpers on top of the existing `aimux -> tmux -> codex/claude` runtime. They do not replace the native TUI path; they reuse the same session write path and tmux pane capture path through the project HTTP service.
+These commands are additive control-plane helpers on top of the existing `aimux -> tmux -> codex/claude` runtime. They do not replace the native TUI path; they reuse the tmux pane capture path through the project HTTP service.
 
 For desktop / GUI callers, prefer explicit `--project` usage instead of relying on launcher cwd.
 
-Structured message parts:
-
-- `POST /agents/input` accepts either plain `data` or ordered `parts`.
-- `parts` currently supports:
-  - `{ "type": "text", "text": "..." }`
-  - `{ "type": "image", "path": "/abs/path.png", "alt": "..." }`
-  - `{ "type": "image", "url": "https://...", "alt": "..." }`
-  - `{ "type": "image", "attachmentId": "att_123", "alt": "..." }`
-- Parts preserve inline ordering for GUI / HTTP callers.
-- Today, tmux-backed agent sessions still receive image parts as explicit inline image descriptors in the prompt text. This preserves message structure now, but it is not yet binary image upload/attachment transport.
-
 Example:
 
 ```json
@@ -239,9 +259,28 @@ Example:
 
 Runtime health:
 
-- The desktop UI now surfaces project-runtime health and exposes a repair/restart control path.
 - The tmux statusline shows `ctl ok`, `ctl daemon↓`, or `ctl stale`.
 - `ctl stale` means the project-service `statusline.json` snapshot has stopped updating, which usually means the project service died.
+- Persistent runtime logging is disabled by default. Enable it with config, env, or CLI flags when reproducing a bug:
+
+```bash
+aimux --debug
+AIMUX_LOG=1 AIMUX_LOG_LEVEL=debug aimux
+AIMUX_LOG=1 AIMUX_LOG_CATEGORIES=daemon,session,tmux aimux
+```
+
+- Project logs are written under `~/.aimux/projects/<project-id>/logs/aimux.jsonl`.
+- Daemon logs are written under `~/.aimux/daemon/logs/daemon.jsonl`.
+- Child stdout/stderr is captured separately as `daemon-stdio.log` or `project-service-stdio.log` when logging is enabled.
+
+```bash
+aimux logs path
+aimux logs tail -n 100
+aimux logs path --daemon
+aimux logs tail --daemon
+aimux logs clear
+```
+
 - Manual recovery is now:
 
 ```bash
@@ -277,21 +316,73 @@ Navigation ownership rule:
   - [src/tmux/control-script.test.ts](src/tmux/control-script.test.ts)
 - Do not clone “similar” ordering logic in the Node runtime for live-pane shortcuts. If the user is pointing at the visible live footer chips and references `n/p`, the shortcut belongs to the tmux layer unless there is a strong reason otherwise.
 
-The desktop app now exposes these flows directly over daemon/project-service HTTP:
+The browser/mobile client at `app/` exposes these flows directly over daemon (port 43190) and per-project metadata-server HTTP:
 
-- dashboard worktree/agent management
-- spawn, fork, rename, migrate, stop, kill
-- graveyard browse + resurrect
+- dashboard monitoring and read-only session views
+- graveyard browsing
 - worktree create + remove
 - activity, workflow, threads, plans, and graveyard secondary screens
-- direct message compose, handoff send/accept/complete, and task/review workflow actions
-- thread state updates and per-message delivery visibility
+- thread and workflow visibility
 
 For the lifecycle model, see [docs/runtime-lifecycle.md](docs/runtime-lifecycle.md).
 For the current source of truth, see [docs/current-architecture.md](docs/current-architecture.md).
-For desktop UI integration details, see [docs/desktop-ui-contract.md](docs/desktop-ui-contract.md).
+For the original Tauri/Svelte client contract (historical, superseded by `app/`), see [docs/desktop-ui-contract.md](docs/desktop-ui-contract.md).
 For the migration rationale, see [docs/global-control-plane-rfc.md](docs/global-control-plane-rfc.md).
 
+## Web / Mobile Client (`app/`)
+
+The user-facing browser and native clients live in `app/` as a single Expo Router + React Native project. The same code targets web (browser), iOS, and Android.
+
+For GUI and daemon development, use the isolated `aimux-dev` runtime so your real
+`aimux` daemon and active work sessions keep running:
+
+```bash
+aimux-dev daemon restart
+aimux-dev daemon project-ensure --project /Users/sam/cs/glyde-frontend
+cd app
+yarn dev:web:local
+```
+
+See [docs/dev-runtime.md](docs/dev-runtime.md) for the full local GUI/backend loop.
+
+```bash
+cd app
+yarn install
+yarn dev:web:local        # browser client on http://localhost:8081
+yarn dev:native:local     # Metro for an installed native dev build
+yarn dev:ios:local        # build/install/open iOS simulator dev build, not Expo Go
+yarn dev:android:local    # build/install/open Android emulator dev build
+```
+
+The app talks to two HTTP surfaces:
+
+- the global aimux daemon at `http://localhost:43190` for project discovery
+- per-project metadata servers (port supplied via `/projects` response) for state, agent I/O, plans, and the `/events` SSE stream
+
+For a built local web UI without Cloudflare relay or hosted auth, run:
+
+```bash
+aimux ui --open
+```
+
+`aimux ui` serves the exported first-party web app from the local machine, ensures
+the loopback daemon is running, and injects local runtime config for the daemon
+port. The UI server binds to `127.0.0.1:43192` by default; use `--port` to choose
+a different local UI port.
+
+For simulator-local development, the helper scripts use `http://127.0.0.1:43191`
+for iOS and `http://10.0.2.2:43191` for Android. For mobile use against a remote
+machine, set `EXPO_PUBLIC_AIMUX_DAEMON_URL=http://<machine>:43190` in `app/.env`.
+
+Release pipeline (uses EAS):
+
+```bash
+cd app
+yarn version:bump-build   # new native build
+yarn build:testflight     # EAS build → TestFlight
+yarn update               # OTA JS-only update (testflight channel)
+```
+
 ## Tmux Compatibility
 
 Aimux treats tmux as a managed runtime, not a transparent pass-through. For aimux-owned tmux sessions, aimux applies a fixed compatibility contract instead of inheriting whatever ambient tmux defaults happen to exist on the machine.
@@ -433,6 +524,17 @@ The project-service HTTP API also exposes:
 
 Use `aimux metadata endpoint` to get the local base URL for the current project service.
 
+Teammate agents are first-party aimux agents attached to a parent agent. They stay hidden from the normal dashboard unless the parent agent is focused, but can still be inspected, entered, stopped, restarted, and graveyarded through the parent/team UI. Programmatic teammate lifecycle routes are control-plane internals; agents should use `.aimux/tasks/*.json` handoff records unless the user gives an explicit CLI/API command.
+
+Dashboard navigation exposes only the selected parent's direct team:
+
+- On the dashboard, select a parent agent and press `e` to open its teammate picker.
+- In an attached agent pane, press `Ctrl-A e` to toggle between the parent and its first/active teammate.
+- `Ctrl-A n/p` stays within the current plane: root agent/service panes before `Ctrl-A e`, direct teammates after `Ctrl-A e`.
+- Non-selected parents do not expose their teammates in dashboard rows, details, or footer chips.
+
+Direct teammate teams are capped at 3 agents. Creating a teammate is idempotent by normalized `role` + `label` for the same parent: if that direct teammate already exists, aimux returns it instead of creating a duplicate.
+
 ## Plugins And Watchers
 
 Aimux can load local metadata plugins from:
@@ -515,13 +617,13 @@ aimux records each agent's conversation and makes it available to other agents:
 - **`.aimux/context/{session-id}/summary.checkpoints.jsonl`** — append-only compaction checkpoints
 - **`.aimux/history/{session-id}.jsonl`** — full raw conversation log
 - **`.aimux/plans/{session-id}.md`** — canonical shared plan for that agent
-- **`.aimux/sessions.json`** — all running agents (so agents can discover each other)
+- **`.aimux/tasks/{task-id}.json`** — explicit handoff records when the user asks for delegation
 
 Agents are told about these files in their startup preamble.
 
 These are the canonical agent-facing paths. Runtime-private state stays under `~/.aimux/projects/<project-id>/...` and is not part of the agent contract.
 
-In tmux mode, live terminal state comes from tmux itself. `~/.aimux/projects/<project-id>/state.json` is mainly for offline/resume metadata, not live screen ownership.
+In tmux mode, live terminal state comes from tmux itself. Runtime topology is stored in `~/.aimux/projects/<project-id>/runtime-topology.yaml`; `~/.aimux/projects/<project-id>/state.json` is service/project state and is not the agent session source of truth.
 
 Memory roles are explicit:
 
@@ -547,11 +649,11 @@ Tool behavior differs:
 
 - `Claude`
   - supports clean preamble injection
-  - does **not** support backend-session-id resume in the way aimux originally assumed
-  - so `fork` and fallback `migrate` rely on aimux-owned continuity artifacts
+  - supports exact backend-session-id resume when aimux starts it with `--session-id {id}` and restores it with `--resume {id}`
+  - targeted dashboard restore must use that exact id or fail loudly; it must not fall back to `--continue`
 - `Codex`
   - supports backend-session-id resume, so `migrate` usually takes the native resume path
-  - does **not** currently have a clean startup handoff flag, so `fork` uses seeded files plus an auto-submitted first-turn kickoff
+  - uses `developer_instructions` for clean startup and fork/migration continuity, with seeded files as durable carried-over context
 
 For deeper details, see [docs/tool-integration.md](docs/tool-integration.md).
 
@@ -572,7 +674,7 @@ Each new session gets a stub plan file. Agents are instructed to keep it current
 
 ## Task Delegation
 
-Agents can delegate work to each other through the aimux task system. This is a file-based protocol — agents create task files, aimux dispatches them, and agents report results.
+Agents can coordinate handoffs through `.aimux/tasks/*.json` when the user explicitly asks for delegation or handoff. These files are a shared record format; they are not an alternate live agent lifecycle or persistence layer.
 
 ### How it works
 
@@ -589,37 +691,34 @@ Agents can delegate work to each other through the aimux task system. This is a
    }
    ```
 
-2. **Aimux detects** the pending task (checks every 2s) and finds an idle agent to handle it
+2. **A target agent or user picks it up** through an explicit handoff or manual coordination
 
-3. **The task prompt is injected** into the target agent's stdin — the agent sees it as input and starts working
+3. **The receiving agent works from the task prompt** and treats the task file as durable coordination state
 
 4. **The agent completes the work** and updates the task file with `"status": "done"` and a `"result"` summary
 
-5. **Aimux notifies** the original agent that the task is complete
+5. **The original agent or user reviews** the result from the shared task record
 
 ### Targeting
 
-Tasks can be targeted in three ways:
+Tasks can carry routing metadata:
 
-- **Specific agent**: set `assignedTo` to a session ID from `.aimux/sessions.json`
-- **By tool type**: set `tool` to `"claude"`, `"codex"`, or `"aider"` — dispatched to the first idle agent of that type
-- **Any idle agent**: omit both fields — dispatched to any available idle agent
+- **Specific agent**: set `assignedTo` to the intended aimux session ID
+- **By tool type**: set `tool` to `"claude"`, `"codex"`, or `"aider"` as a preferred tool hint
+- **Untargeted**: omit both fields for a general handoff record
 
 ### Dashboard indicators
 
-- Sessions with active tasks show a purple `⧫` badge with the task description
-- The dashboard footer shows task counts: `[T:2p/1a]` (2 pending, 1 assigned)
-- Flash notifications appear when tasks are assigned, completed, or failed
+The dashboard and metadata APIs expose teammate and task workflow state where those flows are active. The runtime topology remains authoritative for session lifecycle.
 
 ### Using it
 
-Just ask your agent to delegate. The preamble tells agents exactly how the protocol works. For example:
+Ask your agent to delegate or hand off when you want a task file created. For example:
 
 > "Delegate the test writing to another agent"
-
 > "Hand off the CSS cleanup to the codex agent"
 
-The agent will create the task file, and aimux handles the rest. This is separate from any native task system in the underlying tools (like Claude Code's internal tasks).
+The agent creates the task file. Control-plane callers may expose teammate workflow APIs where configured, but agents should not call aimux metadata APIs themselves. This is separate from any native task system in the underlying tools (like Claude Code's internal tasks).
 
 ## Custom Instructions
 
@@ -648,6 +747,13 @@ This creates `.aimux/config.json`. You can also create a global config at `~/.ai
       "sessionPrefix": "aimux"
     }
   },
+  "logging": {
+    "enabled": false,
+    "level": "info",
+    "categories": ["*"],
+    "maxBytes": 10000000,
+    "maxFiles": 5
+  },
   "notifications": {
     "enabled": true,
     "onPrompt": true,
@@ -668,6 +774,15 @@ Tmux runtime:
 
 - `sessionPrefix` — deterministic prefix used for managed per-project tmux sessions
 
+Logging:
+
+- `enabled` — persist structured JSONL runtime logs
+- `level` — `error`, `warn`, `info`, `debug`, or `trace`
+- `categories` — category allowlist, or `["*"]`
+- `maxBytes` / `maxFiles` — simple file rotation limits
+- CLI overrides: `--debug`, `--trace`, `--log-level <level>`, `--log-category <a,b>`
+- Env overrides: `AIMUX_LOG`, `AIMUX_LOG_LEVEL`, `AIMUX_LOG_CATEGORIES`
+
 ### Tool Configuration
 
 All tool behavior is config-driven. No tool-specific code exists in the multiplexer — adding or customizing a tool only requires config:
@@ -683,15 +798,10 @@ All tool behavior is config-driven. No tool-specific code exists in the multiple
       "resumeArgs": ["--resume", "{sessionId}"],
       "resumeFallback": ["--continue"],
       "sessionIdFlag": ["--session-id", "{sessionId}"],
-      "sessionCapture": {
-        "dir": "{home}/.my-tool/sessions/{yyyy}/{mm}/{dd}",
-        "pattern": "([0-9a-f-]+)\\.json$",
-        "delayMs": 2000
-      },
       "promptPatterns": ["^> $", "^\\$ $"],
       "turnPatterns": ["^[>❯]\\s*(.+)"],
       "compactCommand": "claude --print --output-format text",
-      "instructionsFile": "AGENTS.md"
+      "developerInstructionsConfigKey": "developer_instructions"
     }
   }
 }
@@ -701,22 +811,29 @@ All tool behavior is config-driven. No tool-specific code exists in the multiple
 |---|---|
 | `preambleFlag` | Flag to inject system prompt (e.g. `["--append-system-prompt"]`) |
 | `resumeArgs` | Args to resume a session, with `{sessionId}` placeholder |
-| `resumeFallback` | Fallback resume args when session ID is unavailable |
+| `resumeByBackendSessionId` | Whether aimux's stored backend id is safe to pass to `resumeArgs` |
+| `resumeFallback` | Non-specific fallback resume args for explicit latest-session flows; targeted dashboard restore must not use these |
 | `sessionIdFlag` | Flag to set session ID at spawn time |
-| `sessionCapture` | Filesystem-based session ID capture (dir, regex pattern, delay) |
 | `promptPatterns` | Regex patterns for idle/prompt detection in status bar |
 | `turnPatterns` | Regex patterns for extracting conversation turns from output |
 | `compactCommand` | Shell command for LLM-powered history compaction |
-| `instructionsFile` | File to write preamble to (for tools without system prompt flags) |
+| `instructionsFile` | Optional opt-in file to merge aimux's managed standing instructions into; disabled by default so aimux does not create `AGENTS.md` |
+| `developerInstructionsConfigKey` | Codex config key for model-visible standing instructions, normally `developer_instructions`; set to `null` only when you do not want aimux to inject Codex startup instructions |
+
+Codex startup instructions use `-c developer_instructions=...` when configured. Aimux does not create `AGENTS.md` by default; existing user-authored `AGENTS.md` files are still read by Codex itself. Verify the installed Codex CLI exposes the developer-instructions channel with:
+
+```bash
+yarn verify:codex-instructions
+```
 
-## Multi-Instance
+## Multi-Client Runtime
 
-Run aimux in multiple terminal tabs for the same project. Each instance registers in `.aimux/instances.json` with a heartbeat. Agents from other instances appear inline in the dashboard with a `◈` icon.
+Run aimux in multiple terminal tabs or through the dashboard for the same project. Session lifecycle, ownership, graveyard state, and exact resume identity live in runtime topology.
 
-- **Enter** on a remote agent takes it over (resumes in your instance)
-- `--resume` skips agents already owned by another live instance
-- When an instance exits, its agents become offline and visible to other instances
-- Dead instances are auto-pruned via PID checks and heartbeat staleness
+- `.aimux/instances.json` is legacy and is not an active liveness or ownership source.
+- Remote/share presence belongs to relay/share transport state unless explicitly mirrored from topology.
+- `--resume` does not use instance-registry session refs for ownership decisions.
+- When a runtime exits, topology-backed offline rows keep agents visible to other clients.
 
 ## Agent Lifecycle
 
@@ -777,7 +894,7 @@ Relative `baseDir` values are resolved from the main repo root. Absolute paths a
 ## Requirements
 
 - macOS (Linux support planned)
-- Node.js >= 18
+- Node.js >= 24
 - At least one supported AI tool installed: `claude`, `codex`, or `aider`
 - Notifications work out of the box on macOS, Linux, and Windows
 

package/bin/aimux-dev

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+process.env.AIMUX_HOME ||= join(homedir(), ".aimux-dev");
+process.env.AIMUX_DAEMON_PORT ||= "43191";
+process.env.AIMUX_ENV ||= "development";
+process.env.AIMUX_WEB_APP_URL ||= "http://localhost:8081";
+
+import("../dist/main.js");

package/dist/agent-events.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=agent-events.js.map

package/dist/agent-output-parser.js

@@ -226,4 +226,3 @@ function findLastIndex(items, predicate) {
     }
     return -1;
 }
-//# sourceMappingURL=agent-output-parser.js.map

package/dist/agent-prompt-delivery.js

@@ -116,4 +116,3 @@ export async function deliverTmuxPrompt(opts) {
         return true;
     return waitForTmuxPromptSubmit({ tmuxRuntimeManager, target, draft: prompt, isTargetCurrent });
 }
-//# sourceMappingURL=agent-prompt-delivery.js.map

package/dist/agent-tracker.js

@@ -145,4 +145,3 @@ export class AgentTracker {
 export function getDerivedState(metadata) {
     return metadata?.derived;
 }
-//# sourceMappingURL=agent-tracker.js.map

package/dist/agent-watcher.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=agent-watcher.js.map

package/dist/alert-display.d.ts

@@ -0,0 +1,21 @@
+import type { SessionMetadata } from "./metadata-store.js";
+import type { AlertEvent, AlertKind } from "./project-events.js";
+export interface SessionAlertDisplayContext {
+    label?: string;
+    command?: string;
+    worktreePath?: string;
+    worktreeName?: string;
+    branch?: string;
+}
+export type AlertPublishInput = Omit<AlertEvent, "type" | "projectId" | "ts"> & {
+    dedupeKey?: string;
+    cooldownMs?: number;
+    forceNotify?: boolean;
+};
+export declare function compactSessionId(sessionId: string): string;
+export declare function metadataDisplayContext(metadata?: SessionMetadata): SessionAlertDisplayContext;
+export declare function mergeDisplayContext(base: SessionAlertDisplayContext, override: SessionAlertDisplayContext): SessionAlertDisplayContext;
+export declare function displayWorktreeLabel(context: SessionAlertDisplayContext): string | undefined;
+export declare function sessionAlertSubject(sessionId: string | undefined, context: SessionAlertDisplayContext | undefined): string | undefined;
+export declare function sessionAlertTitle(kind: AlertKind, sessionId: string | undefined, fallback: string | undefined, context?: SessionAlertDisplayContext): string;
+export declare function contextualizeAlertInput(input: AlertPublishInput, context?: SessionAlertDisplayContext): AlertPublishInput;

package/dist/alert-display.js

@@ -0,0 +1,85 @@
+import { basename } from "node:path";
+export function compactSessionId(sessionId) {
+    const compact = sessionId.replace(/-[a-z0-9]{4,}$/i, "");
+    return compact || sessionId;
+}
+export function metadataDisplayContext(metadata) {
+    return {
+        worktreePath: metadata?.context?.worktreePath,
+        worktreeName: metadata?.context?.worktreeName,
+        branch: metadata?.context?.branch,
+    };
+}
+export function mergeDisplayContext(base, override) {
+    return {
+        label: override.label ?? base.label,
+        command: override.command ?? base.command,
+        worktreePath: override.worktreePath ?? base.worktreePath,
+        worktreeName: override.worktreeName ?? base.worktreeName,
+        branch: override.branch ?? base.branch,
+    };
+}
+export function displayWorktreeLabel(context) {
+    const worktreeName = context.worktreeName?.trim();
+    const branch = context.branch?.trim();
+    if (worktreeName)
+        return worktreeName;
+    if (branch)
+        return branch;
+    const path = context.worktreePath?.trim();
+    return path ? basename(path) : undefined;
+}
+export function sessionAlertSubject(sessionId, context) {
+    if (!sessionId)
+        return undefined;
+    const label = context?.label?.trim() || context?.command?.trim() || compactSessionId(sessionId);
+    const worktree = context ? displayWorktreeLabel(context) : undefined;
+    return worktree ? `${label} @ ${worktree}` : label;
+}
+export function sessionAlertTitle(kind, sessionId, fallback, context) {
+    const title = fallback?.trim();
+    const subject = sessionAlertSubject(sessionId, context);
+    if (!subject)
+        return title || "aimux";
+    if (kind === "needs_input")
+        return `${subject} needs input`;
+    if (kind === "blocked") {
+        if (!title || (sessionId && title === `${sessionId} is blocked`))
+            return `${subject} is blocked`;
+        return title;
+    }
+    if (kind === "task_failed") {
+        if (!title || (sessionId && (title === `${sessionId} errored` || title === `${sessionId} failed`))) {
+            return `${subject} errored`;
+        }
+        return title;
+    }
+    if (kind === "task_done") {
+        if (!title || (sessionId && title === `${sessionId} finished`))
+            return `${subject} finished`;
+        const genericTitles = new Set([
+            context?.label?.trim(),
+            context?.command?.trim(),
+            compactSessionId(sessionId ?? ""),
+            "service",
+            "shell",
+        ]);
+        if (genericTitles.has(title))
+            return `${subject} finished`;
+        return title;
+    }
+    if (!title)
+        return subject;
+    if (title.includes(subject))
+        return title;
+    if (sessionId && title.includes(sessionId))
+        return title.replace(sessionId, subject);
+    return `${subject}: ${title}`;
+}
+export function contextualizeAlertInput(input, context) {
+    return {
+        ...input,
+        title: sessionAlertTitle(input.kind, input.sessionId, input.title, context),
+        worktreePath: input.worktreePath ?? context?.worktreePath,
+    };
+}

package/dist/atomic-write.js

@@ -6,4 +6,3 @@ export function writeJsonAtomic(path, value) {
     writeFileSync(tmpPath, `${JSON.stringify(value, null, 2)}\n`);
     renameSync(tmpPath, path);
 }
-//# sourceMappingURL=atomic-write.js.map

package/dist/attachment-store.d.ts

@@ -20,16 +20,9 @@ export interface PublicAttachmentRecord {
     source: "path" | "upload";
     contentUrl: string;
 }
-export declare function ingestAttachmentFromPath(path: string): PublicAttachmentRecord;
-export declare function ingestAttachmentFromBase64(input: {
-    contentBase64: string;
-    filename?: string;
-    mimeType?: string;
-}): PublicAttachmentRecord;
 export declare function getAttachment(id: string): PublicAttachmentRecord | null;
 export declare function getAttachmentContent(id: string): {
     attachment: PublicAttachmentRecord;
     contentPath: string;
     buffer: Buffer;
 } | null;
-export declare function resolveAttachmentPath(id: string): string | null;