@samuelho-dev/coordinator 0.3.0-beta.2 → 0.3.0-beta.3

package/dist/scripts/install.js

@@ -9,18 +9,19 @@ class InstallError extends Schema.TaggedError()("InstallError", { message: Schem
 const installationFailure = () => new InstallError({ message: "Installation failed; check owner, private paths, installed package and destination permissions. Existing native configuration was not changed." });
 const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
 const packageRoot = new URL("../../", import.meta.url);
-const help = `Usage: coordinator-install --target pi|omp|claude|codex|hermes --destination /absolute/new-directory [--config /absolute/private/inspector.json] [--runtime /absolute/node] [--dry-run]
+const help = `Usage: coordinator-install --target pi|omp|claude|codex|hermes --destination /absolute/new-directory [--config /absolute/private/inspector.json] [--runtime /absolute/node] [--source] [--dry-run]
 
 Run as the native session owner. --destination must be a NEW directory under an existing private owner directory; no existing native files are overwritten.
 --config selects an existing private connector config; otherwise use COORDINATOR_CONNECTOR_CONFIG, the default private file, or COORDINATOR_API_URL/COORDINATOR_API_TOKEN. --runtime defaults to this Node executable.
 --dry-run validates prerequisites and prints activation instructions without writing.
-Printed native install/link commands activate this exact installed package. Generated include artifacts require separate explicit activation; supervise the external coordinator connector separately. API tokens must be inherited from the native owner's environment/secret manager or read from the private config; they are never embedded in artifacts.
+Printed native install commands pin the published package version. --source instead activates this exact local package (for intentional checkout/tarball development, never a managed native node_modules directory). Generated include artifacts require separate explicit activation; supervise the external coordinator connector separately. API tokens must be inherited from the native owner's environment/secret manager or read from the private config; they are never embedded in artifacts.
 No settings/profile/statusLine replacement, exporter activation, remote setup, service management or historical data changes. Claude status-line metrics require optional manual composition; the installer does not configure a status line.`;
 const install = (version) => Command.make("coordinator-install", {
     target: Flag.String("target").pipe(Flag.optional),
     destination: Flag.String("destination").pipe(Flag.optional),
     config: Flag.String("config").pipe(Flag.optional),
     runtime: Flag.String("runtime").pipe(Flag.optional),
+    source: Flag.Boolean("source").pipe(Flag.withDefault(false)),
     dryRun: Flag.Boolean("dry-run").pipe(Flag.withDefault(false)),
 }, (flags) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
@@ -87,13 +88,16 @@ const install = (version) => Command.make("coordinator-install", {
     if (target === "pi" || target === "omp") {
         const bundle = join(root, `dist/plugins/${target}.js`);
         yield* fs.access(bundle, { readable: true }).pipe(Effect.mapError(installationFailure));
-        // ponytail: activate the real package; wrapper absolute entrypoints break native OMP discovery.
+        // Published activation must not self-link a native package manager's node_modules tree.
         if (target === "omp")
             json("mcp.json", { mcpServers: { coordinator: mcp } });
-        activation = `${target === "pi" ? "pi install" : "omp plugin link"} ${quote(root)}\n${target === "pi" ? "The extension provides native coordinator_session_list and coordinator_session_inspect tools; no Pi MCP configuration or adapter is required." : `Merge ONLY the coordinator entry from ${join(destination, "mcp.json")} into ~/.omp/agent/mcp.json; preserve all existing entries.`}\nLaunch the native harness with the same configuration environment${environment ? ` and ${environment}` : ""}.`;
+        const activationCommand = flags.source
+            ? `${target === "pi" ? "pi install" : "omp plugin link"} ${quote(root)}`
+            : `${target === "pi" ? "pi install" : "omp plugin install"} ${quote(`${target === "pi" ? "npm:" : ""}@samuelho-dev/coordinator@${version}`)}`;
+        activation = `${activationCommand}\n${target === "pi" ? "The extension provides native coordinator_session_list and coordinator_session_inspect tools; no Pi MCP configuration or adapter is required." : `Merge ONLY the coordinator entry from ${join(destination, "mcp.json")} into ~/.omp/agent/mcp.json; preserve all existing entries.`}\nLaunch the native harness with the same configuration environment${environment ? ` and ${environment}` : ""}.`;
     }
     else if (target === "claude" || target === "codex") {
-        const events = ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PermissionRequest", "Stop", ...(target === "claude" ? ["PostToolUseFailure", "PostModelSwitch", "PreCompact"] : ["Interrupt"])];
+        const events = ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PermissionRequest", "Stop", ...(target === "claude" ? ["PostToolUseFailure", "PostModelSwitch", "PreCompact", "StopFailure", "Elicitation", "ElicitationResult"] : ["Interrupt"])];
         const hooks = Object.fromEntries(events.map((event) => [event, [{ hooks: [{ type: "command", command: command(`hook ${target}`), timeout: 3 }] }]]));
         json("hooks/hooks.json", { hooks });
         if (target === "claude") {

package/dist/src/inspection.js

@@ -28,6 +28,11 @@ export const ProcessIdentity = Schema.Struct({
     ownership: Schema.Literals(["owned", "shared", "unknown"]),
 });
 const NativeWorkState = Schema.Struct({ id: Id, state: Schema.Literals(["pending", "active", "completed", "cancelled", "unknown"]) });
+const RexText = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(4096), Schema.makeFilter((value) => /[\u0000-\u001f\u007f-\u009f]/u.test(value) ? "Control characters are forbidden" : undefined));
+export const ProgramStatus = Schema.Union([
+    Schema.Struct({ state: Schema.Literals(["idle", "working", "done", "error"]) }),
+    Schema.Struct({ state: Schema.Literal("blocked"), kind: Schema.Literals(["permission", "question", "auth"]) }),
+]);
 export const SessionPresence = Schema.Struct({
     ref: SessionRef,
     observedAt: Timestamp,
@@ -42,7 +47,8 @@ export const SessionPresence = Schema.Struct({
     label: Schema.optional(Label), kind: Schema.optional(Id),
     provider: Schema.optional(Id), model: Schema.optional(Id), profile: Schema.optional(Id), agent: Schema.optional(Id),
     cwd: Schema.optional(Path), repository: Schema.optional(Path),
-    rex: Schema.optional(Schema.Struct({ serverId: Schema.optional(Id), blockId: Schema.optional(Id), sessionId: Schema.optional(Id), windowId: Schema.optional(Id), paneId: Schema.optional(Id), terminalId: Schema.optional(Id) })),
+    rex: Schema.optional(Schema.Struct({ serverAddress: Schema.optional(RexText), blockId: Schema.optional(RexText), sessionId: Schema.optional(RexText) })),
+    programStatus: Schema.optional(ProgramStatus),
     processes: Schema.optional(bounded(ProcessIdentity, 128)),
     activity: Schema.optional(Schema.Struct({
         state: Schema.Literals(["idle", "working", "waiting", "stopped", "unknown"]),

package/dist/src/main.js

@@ -7,6 +7,7 @@ import { Mcp } from "./mcp.js";
 import { Host, cliStdioLayer, serverLayer } from "./platform.js";
 import { InspectorConfig, InspectionTools, SessionInspectInput } from "./inspection.js";
 import { NativeError, connectExternal, loadConnectorConfig, resolveNativeConfig, readConnectorToken, readPrivateFile, projectHook, projectClaudeStatus, projectCodexNotification, writeNativeCache, writeHermesHook } from "./native.js";
+import { runSetup } from "./setup.js";
 const readInput = Effect.gen(function* () {
     const stdio = yield* Stdio.Stdio;
     const bytes = new Uint8Array(65536);
@@ -31,8 +32,10 @@ export const cli = (args) => Effect.scoped(Effect.gen(function* () {
         return yield* Console.log(manifest.version);
     }
     if (mode === "help" || mode === "--help") {
-        return yield* Console.log(JSON.stringify({ commands: ["inspector", "connector", "mcp", "hook claude|codex|hermes", "claude-statusline", "codex-notification", "list", "inspect"], inspectorConfiguration: "COORDINATOR_CONFIG: private inspector server configuration", configuration: "COORDINATOR_API_URL / COORDINATOR_API_TOKEN override COORDINATOR_CONNECTOR_CONFIG or XDG_CONFIG_HOME/coordinator/inspector.json; credentials may also use tokenFile", statusline: "Optional manual composition only; consumes stdin without producing display output", codexNotification: "Version 2 envelope, source attached-app-server, thread/tokenUsage/updated only; does not observe other TUIs" }));
+        return yield* Console.log(JSON.stringify({ commands: ["init [--directory PATH] [--owner ID] [--listen-host IP] [--port 8787]", "connect [--endpoint URL] [--token-file PATH] [--config PATH]", "inspector", "connector", "mcp", "hook claude|codex|hermes", "claude-statusline", "codex-notification", "list", "inspect"], inspectorConfiguration: "COORDINATOR_CONFIG: private inspector server configuration", configuration: "COORDINATOR_API_URL / COORDINATOR_API_TOKEN override COORDINATOR_CONNECTOR_CONFIG or XDG_CONFIG_HOME/coordinator/inspector.json; credentials may also use tokenFile", setup: "Run coordinator init --help or coordinator connect --help. Credentials are accepted only by masked prompt, private file, or environment.", statusline: "Optional manual composition only; consumes stdin without producing display output", codexNotification: "Version 2 envelope, source attached-app-server, thread/tokenUsage/updated only; does not observe other TUIs" }));
     }
+    if (mode === "init" || mode === "connect")
+        return yield* runSetup(args);
     if (mode === "inspector") {
         const file = yield* Config.String("COORDINATOR_CONFIG").pipe(Config.withDefault(""));
         if (!file)

package/dist/src/native.js

@@ -6,6 +6,7 @@ import { Stream } from "effect";
 import { Mcp } from "./mcp.js";
 import { INSPECTION_LIMIT, ConnectorConfig, ConnectorAnnounce, ConnectorAccepted, ConnectorPoll, ConnectorPollResult, ConnectorResult, ConnectorDisconnect, SessionInspection, createInspection, metric, unavailableMetric, sessionRefKey } from "./inspection.js";
 import { identifyProcess, observeResources } from "./resources.js";
+import { readRexContext } from "./rex.js";
 export class NativeError extends Data.TaggedError("NativeError") {
 }
 const json = (text) => Effect.try({ try: () => JSON.parse(text), catch: () => new NativeError({ operation: "Invalid native JSON" }) });
@@ -266,7 +267,8 @@ export const projectHook = (harness, machineId, value, at) => Effect.gen(functio
     const name = event.hook_event_name;
     const activity = name === "PreCompact" || event.source === "compact" ? { state: "working", compacting: true } : name === "SessionEnd" ? { state: "stopped" } : name === "PermissionRequest" ? { state: "waiting", wait: "approval", approval: "pending", ...(event.tool_name ? { currentToolName: event.tool_name } : {}) } : name === "PreToolUse" ? { state: "working", wait: "tool", ...(event.tool_name ? { currentToolName: event.tool_name } : {}) } : name === "Stop" || name === "Interrupt" ? { state: "idle" } : name === "UserPromptSubmit" ? { state: "working", wait: "api" } : { state: "unknown" };
     const model = event.to_model ?? event.model;
-    const presence = { ref: { machineId, harness, nativeSessionId: event.session_id }, observedAt: at, nativeUpdatedAt: at, lastActivityAt: at, activity, ...(event.cwd ? { cwd: event.cwd } : {}), ...(model ? { model } : {}) };
+    const programStatus = name === "PermissionRequest" ? { state: "blocked", kind: "permission" } : harness === "claude" && name === "Elicitation" ? { state: "blocked", kind: "question" } : name === "Interrupt" ? { state: "idle" } : harness === "claude" && name === "StopFailure" ? { state: "error" } : harness === "claude" && name === "Stop" ? { state: "done" } : activity.state === "working" || (harness === "claude" && (name === "PostToolUse" || name === "PostToolUseFailure" || name === "ElicitationResult")) ? { state: "working" } : undefined;
+    const presence = { ref: { machineId, harness, nativeSessionId: event.session_id }, observedAt: at, nativeUpdatedAt: at, lastActivityAt: at, activity, ...(programStatus ? { programStatus } : {}), ...(event.cwd ? { cwd: event.cwd } : {}), ...(model ? { model } : {}) };
     return createInspection(presence, at);
 });
 export const projectClaudeStatus = (machineId, value, at) => Effect.gen(function* () {
@@ -355,6 +357,9 @@ const cacheRecords = (config, hermesIdentities = new Map()) => Effect.gen(functi
     return records;
 }).pipe(sanitizeFileFinalizers("Read private metadata cache"), Effect.catchTag("PlatformError", () => Effect.fail(new NativeError({ operation: "Read private metadata cache" }))));
 export const writeNativeCache = (config, incoming) => Effect.gen(function* () {
+    const rex = yield* readRexContext;
+    if (rex)
+        incoming = { ...incoming, presence: { ...incoming.presence, rex } };
     const records = yield* cacheRecords(config);
     const target = yield* cacheFile(config, incoming.presence.ref);
     if (records.size >= 1024 && !records.has(target))
@@ -364,7 +369,8 @@ export const writeNativeCache = (config, incoming) => Effect.gen(function* () {
     if (previous !== undefined) {
         const old = previous.inspection;
         const metadataOnly = incoming.presence.nativeUpdatedAt !== undefined;
-        inspection = { ...(metadataOnly ? old : incoming), presence: { ...old.presence, ...incoming.presence }, queriedAt: incoming.queriedAt, context: metadataOnly && !incoming.presence.activity?.compacting ? old.context : incoming.context };
+        const { programStatus: previousStatus, ...oldPresence } = old.presence;
+        inspection = { ...(metadataOnly ? old : incoming), presence: { ...oldPresence, ...(!incoming.presence.activity && previousStatus ? { programStatus: previousStatus } : {}), ...incoming.presence }, queriedAt: incoming.queriedAt, context: metadataOnly && !incoming.presence.activity?.compacting ? old.context : incoming.context };
     }
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
@@ -458,7 +464,8 @@ export const claudeRoster = (config) => Effect.scoped(Effect.gen(function* () {
         const identity = yield* identifyProcess(row.pid);
         if (identity.status !== "available")
             continue;
-        sessions.push({ ref: { machineId: config.machineId, harness: "claude", nativeSessionId: id }, observedAt: yield* Clock.currentTimeMillis, ...(row.cwd ? { cwd: row.cwd } : {}), ...(row.kind ? { kind: row.kind } : {}), processes: [{ pid: row.pid, startIdentity: identity.startTime, ownership: "owned" }], activity: { state: row.status === "busy" ? "working" : row.status === "waiting" ? "waiting" : row.status === "idle" ? "idle" : "unknown", ...(row.waitingFor === "permission prompt" ? { wait: "approval", approval: "pending" } : {}) } });
+        const programStatus = row.waitingFor === "permission prompt" ? { state: "blocked", kind: "permission" } : row.status === "busy" ? { state: "working" } : row.status === "idle" ? { state: "idle" } : undefined;
+        sessions.push({ ref: { machineId: config.machineId, harness: "claude", nativeSessionId: id }, observedAt: yield* Clock.currentTimeMillis, ...(row.cwd ? { cwd: row.cwd } : {}), ...(row.kind ? { kind: row.kind } : {}), ...(programStatus ? { programStatus } : {}), processes: [{ pid: row.pid, startIdentity: identity.startTime, ownership: "owned" }], activity: { state: row.status === "busy" ? "working" : row.status === "waiting" ? "waiting" : row.status === "idle" ? "idle" : "unknown", ...(row.waitingFor === "permission prompt" ? { wait: "approval", approval: "pending" } : {}) } });
     }
     return sessions;
 })).pipe(Effect.timeout("5 seconds"));

package/dist/src/plugin.js

@@ -1,10 +1,11 @@
 import { NodeServices } from "@effect/platform-node";
-import { Cause, Clock, Config, Console, Effect, Layer, Logger, ManagedRuntime, Schema } from "effect";
+import { Cause, Clock, Console, Effect, Layer, Logger, ManagedRuntime, Schema } from "effect";
 import { createInspection, HttpError, InspectionTools, metric, sessionRefKey, unavailableMetric } from "./inspection.js";
 import { Mcp } from "./mcp.js";
 import { connectNative, loadConnectorConfig, NativeError, readConnectorToken, resolveNativeConfig, withProcessResources } from "./native.js";
 import { identifyProcess } from "./resources.js";
 import { Host as PlatformHost } from "./platform.js";
+import { createRexReporter, readRexContext } from "./rex.js";
 const provenance = (source, scope, scopeDescription, observedAt, nativeUpdatedAt = null) => ({
     source, scope, scopeDescription, observedAt, nativeUpdatedAt, estimated: false, derived: false, shared: false, partial: false, stale: false,
 });
@@ -12,8 +13,10 @@ const provenance = (source, scope, scopeDescription, observedAt, nativeUpdatedAt
 export const createNativeObserver = (harness, machineId, processes = []) => Effect.gen(function* () {
     const host = yield* PlatformHost;
     const clock = yield* Clock.Clock;
-    const rexSession = yield* Config.String("REX_SESSION").pipe(Config.withDefault(""));
-    const rexBlock = yield* Config.String("REX_BLOCK").pipe(Config.withDefault(""));
+    const rex = yield* readRexContext;
+    let programStatus;
+    let userPrompt;
+    let stopReason;
     let current;
     let identity;
     let lastActivityAt;
@@ -25,6 +28,9 @@ export const createNativeObserver = (harness, machineId, processes = []) => Effe
         const key = JSON.stringify([ctx.sessionManager.getSessionId(), harness === "omp" ? ctx.agent?.id : undefined]);
         if (identity !== key) {
             latest = undefined;
+            programStatus = undefined;
+            userPrompt = undefined;
+            stopReason = undefined;
             activeTools.clear();
             identity = key;
         }
@@ -36,6 +42,33 @@ export const createNativeObserver = (harness, machineId, processes = []) => Effe
             activeTools.delete(event.toolCallId);
         if (event?.type === "agent_end")
             activeTools.clear();
+        if (event?.type === "agent_start") {
+            programStatus = { state: "working" };
+            stopReason = undefined;
+        }
+        if (event?.type === "turn_start") {
+            programStatus = { state: "working" };
+            stopReason = undefined;
+        }
+        if (event?.type === "tool_execution_start")
+            programStatus = { state: "working" };
+        if (event?.message?.role === "assistant" && event.message.stopReason)
+            stopReason = event.message.stopReason;
+        if (event?.type === "agent_end")
+            stopReason = event.messages?.findLast((message) => message.role === "assistant")?.stopReason ?? stopReason;
+        if (harness === "pi" && event?.type === "agent_before_settle")
+            stopReason = event.outcome === "completed" ? "stop" : event.outcome;
+        if (event?.type === "agent_settled" || (harness !== "pi" && event?.type === "agent_end")) {
+            programStatus = event.willContinue ? { state: "working" } : stopReason === "aborted" ? { state: "idle" } : stopReason === "error" ? { state: "error" } : stopReason === "stop" || stopReason === "length" ? { state: "done" } : undefined;
+        }
+        else if (event?.type === "agent_end")
+            programStatus = { state: "working" };
+        if (harness === "pi" && event?.type === "ui_prompt_start")
+            userPrompt = { state: "blocked", kind: "question" };
+        if (harness === "pi" && event?.type === "ui_prompt_end")
+            userPrompt = undefined;
+        if ((event === undefined || event.type === "session_start" || event.type === "session_switch") && programStatus === undefined)
+            programStatus = { state: ctx.isIdle() ? "idle" : "working" };
         const message = event?.message;
         if (message?.role === "assistant" && message.usage) {
             const u = message.usage;
@@ -51,15 +84,18 @@ export const createNativeObserver = (harness, machineId, processes = []) => Effe
         if (!current)
             return undefined;
         const currentToolName = activeTools.values().next().value;
+        const status = userPrompt ?? programStatus;
         return {
             ref: { machineId, harness, nativeSessionId: current.sessionManager.getSessionId(), ...(harness === "omp" && current.agent?.id ? { nativeAgentId: current.agent.id } : {}) },
             observedAt: now, ...(lastActivityAt === undefined ? {} : { lastActivityAt }), cwd: current.cwd, processes,
             machineName, ...(os ? { os } : {}),
-            ...(rexSession || rexBlock ? { rex: { ...(rexSession ? { sessionId: rexSession } : {}), ...(rexBlock ? { blockId: rexBlock } : {}) } } : {}),
+            ...(rex ? { rex } : {}),
+            ...(status ? { programStatus: status } : {}),
             ...(current.model ? { provider: current.model.provider, model: current.model.id } : {}),
             ...(current.agent ? { kind: current.agent.kind, ...(current.agent.name ? { agent: current.agent.name } : {}) } : {}),
-            activity: { state: current.isIdle() ? "idle" : "working", streaming: !current.isIdle(),
-                ...(currentToolName === undefined ? {} : { currentToolName, wait: "tool" }),
+            activity: { state: userPrompt ? "waiting" : current.isIdle() ? "idle" : "working", streaming: !current.isIdle(),
+                ...(currentToolName === undefined ? {} : { currentToolName }),
+                ...(userPrompt ? { wait: "user" } : currentToolName === undefined ? {} : { wait: "tool" }),
             },
         };
     };
@@ -146,7 +182,7 @@ export const createNativeObserver = (harness, machineId, processes = []) => Effe
             },
         };
     };
-    return { update, presence, inspect, clear: () => { current = undefined; identity = undefined; latest = undefined; lastActivityAt = undefined; activeTools.clear(); } };
+    return { update, presence, inspect, clear: () => { current = undefined; identity = undefined; latest = undefined; programStatus = undefined; userPrompt = undefined; stopReason = undefined; lastActivityAt = undefined; activeTools.clear(); } };
 });
 export const isCoordinateInput = (text) => /^coordinate(?:\s|$)/u.test(text);
 export const transformCoordinateInput = (harness, input, snapshot) => {
@@ -161,6 +197,23 @@ export const registerCoordinateKeyword = Effect.gen(function* () {
     // ponytail: native exposes no registry getter/append; only known core keywords can be preserved.
     setMagicKeywords([...MAGIC_KEYWORDS.filter(({ word }) => isMagicKeyword(word)), { word: "coordinate", hue: [190, 260] }]);
 });
+const formatSessionList = (sessions) => {
+    if (sessions.length === 0)
+        return "No sessions are currently visible to this API key.";
+    const lines = [`Coordinator: ${sessions.length} sessions visible to this API key.`, "", "~~~text"];
+    for (const session of sessions) {
+        lines.push(`Machine: ${JSON.stringify(session.machineName ?? "unavailable")} (${JSON.stringify(session.ref.machineId)})`, `Session: ${session.ref.harness} ${JSON.stringify(session.ref.nativeSessionId)}`);
+        if (session.ref.nativeAgentId !== undefined)
+            lines.push(`Agent ID: ${JSON.stringify(session.ref.nativeAgentId)}`);
+        for (const [field, value] of Object.entries(session)) {
+            if (field !== "ref" && field !== "machineName" && value !== undefined)
+                lines.push(`${field}: ${JSON.stringify(value)}`);
+        }
+        lines.push("");
+    }
+    lines.push("~~~");
+    return lines.join("\n");
+};
 export default function plugin(host) {
     const harness = COORDINATOR_HARNESS;
     const runtime = ManagedRuntime.make(Layer.mergeAll(NodeServices.layer, PlatformHost.layer, Mcp.layer, Layer.succeed(Logger.LogToStderr, true)));
@@ -168,6 +221,50 @@ export default function plugin(host) {
     let observer;
     let starting;
     let stopped = false;
+    // Stock OMP owns OSC 7501 (terminal.programStatus); never duplicate or override it.
+    const rexReporter = harness === "pi" ? createRexReporter((sequence) => process.stdout.write(sequence)) : undefined;
+    let terminal = false;
+    host.registerCommand("coordinator", {
+        description: "List visible sessions, their machines, and native metadata",
+        handler: async (args) => {
+            if (args.trim() !== "list") {
+                host.sendMessage({ customType: "coordinator-list", content: "Usage: /coordinator list", display: true }, { triggerTurn: false });
+                return;
+            }
+            const exit = await runtime.runPromiseExit(Effect.gen(function* () {
+                const activeConfig = config ?? (yield* loadConnectorConfig());
+                if (!activeConfig)
+                    return yield* new NativeError({ operation: "Connector configuration required" });
+                const token = yield* readConnectorToken(activeConfig);
+                const mcp = yield* Mcp;
+                const sessions = [];
+                let cursor;
+                do {
+                    const page = yield* mcp.call(activeConfig.inspectorUrl, token, InspectionTools.list, { limit: 100, ...(cursor === undefined ? {} : { cursor }) });
+                    for (const session of page.sessions)
+                        sessions.push(session);
+                    cursor = page.nextCursor ?? undefined;
+                } while (cursor !== undefined);
+                return sessions;
+            }));
+            if (stopped)
+                return;
+            if (exit._tag === "Failure") {
+                const error = Cause.findErrorOption(exit.cause);
+                const reason = error._tag === "Some" ? error.value._tag === "HttpError" ? `HTTP ${error.value.status}` : error.value._tag : "unexpected failure";
+                host.sendMessage({
+                    customType: "coordinator-list",
+                    content: `Coordinator list unavailable (${reason}). Check inspectorUrl, your access token, and API reachability.`,
+                    display: true,
+                }, { triggerTurn: false });
+                return;
+            }
+            host.sendMessage({
+                customType: "coordinator-list", content: formatSessionList(exit.value), display: true,
+                details: { sessions: exit.value },
+            }, { triggerTurn: false });
+        },
+    });
     if (harness === "pi") {
         const register = (descriptor) => {
             const document = Schema.toJsonSchemaDocument(Schema.toCodecJson(descriptor.input), { onExcessProperty: "error" });
@@ -229,6 +326,8 @@ export default function plugin(host) {
         const processIdentity = yield* identifyProcess(host.pid);
         observer = yield* createNativeObserver(harness, nativeConfig.machineId, processIdentity.status === "available" ? [{ pid: host.pid, startIdentity: processIdentity.startTime, ownership: harness === "omp" ? "shared" : "owned" }] : []);
         observer.update(ctx);
+        terminal = ctx.mode === "tui" && ctx.hasUI && process.stdout.isTTY === true;
+        rexReporter?.update(observer.presence()?.programStatus, terminal);
         // Native TUI constructors register core keywords before session_start hooks.
         if (harness === "omp" && ctx.hasUI && ctx.mode === "tui")
             yield* registerCoordinateKeyword;
@@ -253,6 +352,8 @@ export default function plugin(host) {
         }
     });
     const events = ["session_start", "session_switch", "agent_start", "agent_end", "turn_start", "turn_end", "message_end", "tool_execution_start", "tool_execution_end"];
+    if (harness === "pi")
+        events.push("agent_before_settle", "agent_settled", "ui_prompt_start", "ui_prompt_end");
     for (const name of events) {
         host.on(name, async (event, ctx) => {
             if (stopped)
@@ -260,11 +361,18 @@ export default function plugin(host) {
             await start(ctx);
             if (stopped || !observer)
                 return;
-            await runtime.runPromiseExit(Effect.sync(() => observer?.update(ctx, event)).pipe(Effect.tapCause(reportCause(ctx, "native update"))));
+            await runtime.runPromiseExit(Effect.sync(() => {
+                if (name === "session_switch")
+                    rexReporter?.update(undefined, terminal);
+                observer?.update(ctx, event);
+                terminal = ctx.mode === "tui" && ctx.hasUI && process.stdout.isTTY === true;
+                rexReporter?.update(observer?.presence()?.programStatus, terminal);
+            }).pipe(Effect.tapCause(reportCause(ctx, "native update"))));
         });
     }
     host.on("session_shutdown", async () => {
         stopped = true;
+        rexReporter?.close(terminal);
         try {
             await runtime.dispose();
         }

package/dist/src/rex.js

@@ -0,0 +1,36 @@
+import { randomUUID } from "node:crypto";
+import { Config, Effect } from "effect";
+export const readRexContext = Effect.gen(function* () {
+    const serverAddress = yield* Config.String("REX_SERVER").pipe(Config.withDefault(""));
+    const sessionId = yield* Config.String("REX_SESSION").pipe(Config.withDefault(""));
+    const blockId = yield* Config.String("REX_BLOCK").pipe(Config.withDefault(""));
+    return serverAddress || sessionId || blockId ? {
+        ...(serverAddress ? { serverAddress } : {}), ...(sessionId ? { sessionId } : {}), ...(blockId ? { blockId } : {}),
+    } : undefined;
+});
+// ponytail: fixed labels avoid leaking native content and stay below all OSC text limits.
+export const rexSequence = (id, status) => {
+    if (id.length > 128 || id.split("/").length > 8 || !/^[A-Za-z0-9_.+-]{1,32}(?:\/[A-Za-z0-9_.+-]{1,32})*$/u.test(id))
+        return "";
+    return `\u001b]7501;id=${id}:state=${status?.state ?? "clear"}:app=coordinator:title=Q29vcmRpbmF0b3I=${status?.state === "blocked" ? `:kind=${status.kind}` : ""}\u001b\\`;
+};
+export const createRexReporter = (write) => {
+    const id = `coordinator/${randomUUID().replaceAll("-", "")}`;
+    let previous;
+    return {
+        update: (status, terminal) => {
+            if (!terminal)
+                return;
+            const sequence = rexSequence(id, status);
+            if (previous === sequence || (previous === undefined && status === undefined))
+                return;
+            write(sequence);
+            previous = sequence;
+        },
+        close: (terminal) => {
+            if (terminal && previous !== undefined && !/:state=(?:done|error):/u.test(previous))
+                write(rexSequence(id, undefined));
+            previous = undefined;
+        },
+    };
+};

package/dist/src/setup.js

@@ -0,0 +1,134 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, realpath, rmdir, unlink } from "node:fs/promises";
+import { createHash, randomBytes } from "node:crypto";
+import { isIP } from "node:net";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { Config, Console, Effect, Option, Redacted, Schema } from "effect";
+import { Command, Flag, Prompt } from "effect/cli";
+import { ConnectorConfig, InspectionTools, InspectorConfig } from "./inspection.js";
+import { Mcp } from "./mcp.js";
+import { NativeError, readConnectorToken } from "./native.js";
+import { Host } from "./platform.js";
+const failure = (operation) => () => new NativeError({ operation });
+const privateFailure = failure("Setup could not write private files; use a canonical owner-controlled path, mode-0700 directory and new filenames. Existing files are never overwritten");
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+const canonical = (file) => {
+    if (!isAbsolute(file) || resolve(file) !== file || /[\x00-\x1f\x7f-\x9f]/u.test(file))
+        throw new Error("Unsafe path");
+};
+// Exclusive creation is the overwrite fence; remove only files this transaction created.
+const writePrivate = (directory, files, uid) => Effect.tryPromise({
+    try: async () => {
+        canonical(directory);
+        if (uid === undefined)
+            throw new Error("Owner unavailable");
+        const createdDirectories = [], createdFiles = [];
+        const ensure = async (target, privateDirectory) => {
+            try {
+                const info = await lstat(target);
+                if (!info.isDirectory() || info.isSymbolicLink() || await realpath(target) !== target || (privateDirectory && (info.uid !== uid || (info.mode & 0o777) !== 0o700)))
+                    throw new Error("Unsafe directory");
+                // Ancestors must not be replaceable by another owner; sticky /tmp is allowed.
+                if (!privateDirectory && (info.uid !== uid && info.uid !== 0 || (info.mode & 0o022) !== 0 && (info.mode & 0o1000) === 0))
+                    throw new Error("Unsafe ancestor");
+            }
+            catch (error) {
+                if (typeof error !== "object" || error === null || !("code" in error) || error.code !== "ENOENT")
+                    throw error;
+                await ensure(dirname(target), false);
+                await mkdir(target, { mode: 0o700 });
+                createdDirectories.push(target);
+                await chmod(target, 0o700);
+            }
+        };
+        try {
+            await ensure(directory, true);
+            // realpath rejects symlinks anywhere in existing ancestry; validate its writable ancestors too.
+            for (let parent = dirname(directory);; parent = dirname(parent)) {
+                await ensure(parent, false);
+                if (parent === dirname(parent))
+                    break;
+            }
+            for (const [file, content] of files) {
+                canonical(file);
+                if (dirname(file) !== directory)
+                    throw new Error("Unsafe destination");
+                const handle = await open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+                createdFiles.push(file);
+                try {
+                    await handle.chmod(0o600);
+                    await handle.writeFile(content, "utf8");
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+        }
+        catch (error) {
+            for (const file of createdFiles.reverse())
+                await unlink(file).catch(() => undefined);
+            for (const dir of createdDirectories.reverse())
+                await rmdir(dir).catch(() => undefined);
+            throw error;
+        }
+    },
+    catch: privateFailure,
+});
+const configHome = Effect.gen(function* () {
+    const host = yield* Host;
+    const xdg = yield* Config.String("XDG_CONFIG_HOME").pipe(Config.option);
+    return join(Option.getOrUndefined(xdg) ?? join(host.homeDirectory, ".config"), "coordinator");
+});
+export const initializeServer = (options) => Effect.gen(function* () {
+    if ((!isIP(options.host) && options.host !== "localhost") || !Number.isInteger(options.port) || options.port < 1 || options.port > 65535 || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/u.test(options.owner)) {
+        return yield* new NativeError({ operation: "Init requires an IP address or localhost, port 1–65535, and an owner identifier containing only letters, digits, dot, underscore or hyphen" });
+    }
+    const token = yield* Effect.try({ try: () => randomBytes(32).toString("base64url"), catch: failure("Secure credential generation unavailable") });
+    const config = yield* Schema.decodeEffect(InspectorConfig)({ host: options.host, port: options.port, principals: [{ id: options.owner, owner: options.owner, tokenHash: createHash("sha256").update(token).digest("hex") }] }).pipe(Effect.mapError(failure("Invalid server configuration")));
+    const configFile = join(options.directory, "server.json"), tokenFile = join(options.directory, "owner.token");
+    yield* writePrivate(options.directory, [[tokenFile, `${token}\n`], [configFile, `${JSON.stringify(config, null, 2)}\n`]], (yield* Host).uid);
+    return { configFile, tokenFile };
+});
+export const connectClient = (options) => Effect.gen(function* () {
+    const targetToken = options.tokenFile ?? join(dirname(options.configFile), "inspector.token");
+    const config = yield* Schema.decodeEffect(ConnectorConfig)({ inspectorUrl: options.endpoint, apiToken: options.token, tokenFile: targetToken }).pipe(Effect.mapError(failure("Invalid endpoint or credential; use HTTPS except for loopback, without URL credentials, query or fragment")));
+    if (options.tokenFile !== undefined) {
+        const stored = yield* readConnectorToken({ inspectorUrl: options.endpoint, tokenFile: options.tokenFile });
+        if (stored !== options.token)
+            return yield* new NativeError({ operation: "Credential file changed; retry connection setup" });
+    }
+    // This is an authenticated read only: it never resolves/creates a native machine identity.
+    yield* (yield* Mcp).call(config.inspectorUrl, options.token, InspectionTools.list, { limit: 1 }).pipe(Effect.mapError(failure("Connection check failed; verify the endpoint, TLS certificate and owner credential. No client configuration was written")));
+    const files = [];
+    if (options.tokenFile === undefined)
+        files.push([targetToken, `${options.token}\n`]);
+    files.push([options.configFile, `${JSON.stringify({ inspectorUrl: config.inspectorUrl, tokenFile: targetToken }, null, 2)}\n`]);
+    yield* writePrivate(dirname(options.configFile), files, (yield* Host).uid);
+    return { configFile: options.configFile, tokenFile: targetToken };
+});
+const init = Command.make("init", {
+    directory: Flag.String("directory").pipe(Flag.optional),
+    owner: Flag.String("owner").pipe(Flag.withDefault("owner")),
+    host: Flag.String("listen-host").pipe(Flag.withDefault("127.0.0.1")),
+    port: Flag.Int("port").pipe(Flag.withDefault(8787)),
+}, (flags) => Effect.gen(function* () {
+    const directory = Option.getOrUndefined(flags.directory) ?? join(yield* configHome, "server");
+    const result = yield* initializeServer({ ...flags, directory });
+    yield* Console.log(`Created private server configuration: ${result.configFile}\nOwner credential file: ${result.tokenFile}\nStart server:\nCOORDINATOR_CONFIG=${quote(result.configFile)} coordinator inspector\nKeep the credential private. For remote clients, expose this server through HTTPS.`);
+})).pipe(Command.withDescription("Bootstrap a self-hosted server without printing its owner credential. Never overwrites existing files."));
+const connect = Command.make("connect", {
+    endpoint: Flag.String("endpoint").pipe(Flag.optional),
+    tokenFile: Flag.String("token-file").pipe(Flag.optional),
+    config: Flag.String("config").pipe(Flag.optional),
+}, (flags) => Effect.gen(function* () {
+    const selected = yield* Config.String("COORDINATOR_CONNECTOR_CONFIG").pipe(Config.option);
+    const configFile = Option.getOrUndefined(flags.config) ?? Option.getOrUndefined(selected) ?? join(yield* configHome, "inspector.json");
+    const endpoint = Option.getOrUndefined(flags.endpoint) ?? (yield* Prompt.String({ message: "Coordinator endpoint (HTTPS, or loopback HTTP)" }));
+    const tokenFile = Option.getOrUndefined(flags.tokenFile);
+    const environment = yield* Config.String("COORDINATOR_API_TOKEN").pipe(Config.option);
+    const token = tokenFile !== undefined ? yield* readConnectorToken({ inspectorUrl: endpoint, tokenFile })
+        : Option.isSome(environment) ? environment.value : Redacted.value(yield* Prompt.Password({ message: "Owner credential" }));
+    const result = yield* connectClient({ endpoint, token, configFile, ...(tokenFile === undefined ? {} : { tokenFile }) });
+    yield* Console.log(`Authenticated connection saved: ${result.configFile}\nCredential file: ${result.tokenFile}\nClient configuration contains only the endpoint and credential-file pointer. Existing native settings are unchanged.\nCOORDINATOR_API_URL / COORDINATOR_API_TOKEN environment overrides still take precedence at runtime.`);
+})).pipe(Command.withDescription("Authenticate and save a private client configuration. Credentials: --token-file, COORDINATOR_API_TOKEN, or masked prompt; never argv. Existing files are not overwritten."));
+export const runSetup = (args) => Command.runWith(Command.make("coordinator").pipe(Command.withSubcommands([init, connect])), { version: "", renderErrors: false })(args).pipe(Effect.catchTag("ShowHelp", () => Effect.fail(new NativeError({ operation: "Invalid setup flags. Run coordinator init --help or coordinator connect --help. Credentials are never accepted as arguments" }))));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samuelho-dev/coordinator",
-  "version": "0.3.0-beta.2",
+  "version": "0.3.0-beta.3",
   "type": "module",
   "description": "Read-only native agent session inspection across self-hosted machines",
   "license": "MIT",