Skip to content

transcendr/slopware-skills / plugins/t3-app-link/skills/t3-app-link

t3-app-link

Verified

Monitor Codex and Claude work threads inside T3 through a read-only CLI, with formal questions, RESULT detection, settling, stalls and resumable multi-thread watches. Use when managing T3 threads; use native T3 tools to dispatch or answer them.

FileKindSize
SKILL.mdskill md13.1 KB
references/companions.mdmarkdown1.1 KB
references/operational.mdmarkdown7.7 KB
references/strategic.mdmarkdown1.5 KB
scripts/t3-thread.mjsexecutablescript64.0 KB

scripts/t3-thread.mjs

View on GitHub
#!/usr/bin/env node
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { randomUUID, createHash } from 'node:crypto';
import { spawnSync } from 'node:child_process';
import { fileURLToPath } from 'node:url';

// Protocol-2 transport adapted from Jevpact's t3-rpc.js; credentials never enter errors.
export const t3Error = (code, ambiguous = false) => Object.assign(new Error(code), { code, ambiguous });
const maintenanceCodes = new Set(['maintenance-unavailable', 'maintenance-stale-target', 'maintenance-direction-changed',
  'maintenance-thread-unavailable', 'maintenance-busy', 'maintenance-unsupported', 'maintenance-invalid-continuation',
  'maintenance-ambiguous-delivery', 'maintenance-invalid-input']);

function rejection(cause, mutation) {
  const pending = [cause];
  while (pending.length) {
    const item = pending.pop();
    if (Array.isArray(item)) { pending.push(...item); continue; }
    if (!item || typeof item !== 'object') continue;
    if (maintenanceCodes.has(item.code)) return t3Error(item.code, item.code === 'maintenance-ambiguous-delivery');
    if (item._tag === 'EnvironmentAuthorizationError') return t3Error('t3-authorization-failed');
    for (const key of ['cause', 'error', 'reason']) if (item[key]) pending.push(item[key]);
    if (Array.isArray(item.reasons)) pending.push(...item.reasons);
  }
  return t3Error('t3-rpc-rejected', mutation);
}

/** Protocol-2 RPC connection. Native errors and credential-bearing URLs never enter errors. */
export class T3Rpc {
  #token;
  constructor({ origin, token, fetch = globalThis.fetch, WebSocket = globalThis.WebSocket }) {
    let url;
    try { url = new URL(origin); } catch { throw t3Error('t3-invalid-origin'); }
    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw t3Error('t3-invalid-origin');
    this.origin = url.origin; this.#token = token; this.fetch = fetch; this.WebSocket = WebSocket;
    this.pending = new Map(); this.streams = new Map(); this.closed = false;
  }

  async credential() {
    const token = typeof this.#token === 'function' ? await this.#token() : this.#token;
    if (typeof token !== 'string' || !token) throw t3Error('t3-missing-token');
    return token;
  }

  connect() {
    if (this.closed) return Promise.reject(t3Error('t3-rpc-closed'));
    if (this.socket?.readyState === 1) return Promise.resolve();
    if (this.connecting) return this.connecting;
    this.connecting = this.open().finally(() => { this.connecting = null; });
    return this.connecting;
  }

  async open() {
    try {
      const token = await this.credential();
      const response = await this.fetch(new URL('/api/auth/websocket-ticket/rpc', this.origin), {
        method: 'POST', headers: { Authorization: `Bearer ${token}` },
      });
      if (!response.ok) throw t3Error('t3-authentication-failed');
      const { ticket } = await response.json();
      if (!ticket) throw t3Error('t3-invalid-ticket');
      if (this.closed) throw t3Error('t3-rpc-closed');
      const url = new URL('/ws', this.origin); url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
      url.searchParams.set('orchestrationProtocol', '2'); url.searchParams.set('wsTicket', ticket);
      await this.listen(url);
    } catch (error) { throw t3Error(error.code?.startsWith('t3-') ? error.code : 't3-connection-failed'); }
  }

  listen(url) {
    return new Promise((resolve, reject) => {
      const socket = this.socket = new this.WebSocket(url.href);
      const ended = () => { reject(t3Error('t3-disconnected')); this.fail(socket); };
      socket.addEventListener('open', () => { if (this.closed) { socket.close(); ended(); } else resolve(); });
      socket.addEventListener('error', ended); socket.addEventListener('close', ended);
      socket.addEventListener('message', event => {
        if (this.socket !== socket) return;
        try { for (const line of String(event.data).split('\n').filter(Boolean)) this.handle(JSON.parse(line), socket); }
        catch { this.fail(socket, 't3-invalid-frame'); socket.close(); }
      });
    });
  }

  fail(socket, code = 't3-disconnected') {
    if (this.socket !== socket) return;
    this.socket = null;
    for (const request of this.pending.values()) request.reject(t3Error(code, request.mutation && request.sent));
    this.pending.clear();
    const streams = [...this.streams.values()]; this.streams.clear();
    for (const stream of streams) { stream.reject(t3Error(code)); stream.onDisconnect(t3Error(code)); }
  }

  handle(message, socket) {
    if (message._tag === 'Ping') { socket.send(JSON.stringify({ _tag: 'Pong' })); return; }
    if (message._tag === 'Defect') { this.fail(socket, 't3-protocol-failed'); socket.close(); return; }
    const stream = this.streams.get(String(message.requestId));
    if (stream) {
      if (message._tag !== 'Chunk' || !Array.isArray(message.values)) throw t3Error('t3-subscription-ended');
      for (const frame of message.values) { stream.onFrame(frame); if (frame.kind === 'synchronized') stream.resolve(); }
      socket.send(JSON.stringify({ _tag: 'Ack', requestId: message.requestId })); return;
    }
    const request = this.pending.get(String(message.requestId));
    if (!request) return;
    if (message._tag !== 'Exit') throw t3Error('t3-invalid-frame');
    this.pending.delete(String(message.requestId));
    if (message.exit?._tag === 'Success') request.resolve(message.exit.value);
    else request.reject(rejection(message.exit?.cause, request.mutation));
  }

  async request(tag, payload, { mutation = false, isCurrent } = {}) {
    if (!['server.getConfig'].includes(tag)) throw t3Error('t3-read-only');
    await this.connect();
    if (isCurrent && !isCurrent()) throw t3Error('stale-action');
    const id = randomUUID();
    return new Promise((resolve, reject) => {
      const request = { resolve, reject, mutation, sent: false }; this.pending.set(id, request);
      try {
        request.sent = true;
        this.socket.send(JSON.stringify({ _tag: 'Request', id, tag, payload, headers: [] }));
      } catch { this.pending.delete(id); reject(t3Error('t3-send-failed', mutation)); }
    });
  }

  async subscribe(tag, payload, { onFrame, onDisconnect }) {
    if (!['orchestration.subscribeShell', 'orchestration.subscribeThread'].includes(tag)) throw t3Error('t3-read-only');
    await this.connect();
    const id = randomUUID();
    const ready = new Promise((resolve, reject) => this.streams.set(id, { resolve, reject, onFrame, onDisconnect }));
    try {
      this.socket.send(JSON.stringify({ _tag: 'Request', id, tag, payload, headers: [] }));
      await ready;
    } catch { this.streams.delete(id); throw t3Error('t3-subscription-failed'); }
    return () => {
      if (!this.streams.delete(id)) return;
      this.socket?.send(JSON.stringify({ _tag: 'Interrupt', requestId: id }));
    };
  }

  async history(threadId, cursor) {
    const url = new URL(`/api/orchestration/threads/${encodeURIComponent(threadId)}/history`, this.origin);
    url.searchParams.set('cursor', cursor);
    const token = await this.credential();
    try {
      const response = await this.fetch(url, { headers: { Authorization: `Bearer ${token}`, 'x-t3-orchestration-protocol': '2' } });
      if (!response.ok) throw t3Error('t3-history-unavailable');
      return await response.json();
    } catch { throw t3Error('t3-history-unavailable'); }
  }

  close() {
    this.closed = true;
    const socket = this.socket;
    this.fail(socket, 't3-rpc-closed'); socket?.close();
  }
}

export const RULES = {
  start: 'new turn: one handoff or follow-up per turn; the RESULT ends it. New work for a busy thread: t3_thread_send mode queue.',
  steer: "t3_thread_send mode steer is input for THIS turn's work only. Answer formal questions with t3_pending_request respond; queue new follow-up work with t3_thread_send mode queue.",
  queued: 'queued: delivered as a new turn when the running turn ends; t3_queue action list shows it and action cancel removes a queuedRunId.',
  active: 'active turn: queue new work with t3_thread_send mode queue; use mode steer only to correct this turn. Answer formal questions with t3_pending_request respond. Past its timebox: act on it now.',
  questions: 'run questions <thread> for the full requestId, state and answer keys; answer pending input with t3_pending_request respond.',
  approvals: 'the user reviews this permission request in T3; a monitoring lead cannot approve it.',
  done: 'read the full reply and RESULT before acting, and check its claims against the evidence.',
  stalled: "stalled: inspect and act in this turn; don't just wait again.",
  created: 'new thread: track it with a name, and give it one handoff with its timebox.',
  result: 'read the full RESULT before acting and check its claims against the evidence; then send new work with t3_thread_send mode queue.',
  idle: 'turn ended: read the reply in full; send the next work with t3_thread_send mode queue.',
};

const KEY_START = /\s+(?=[A-Za-z_][\w.-]*=)/;

export function extractResult(text, marker = 'RESULT') {
  if (!text) return null;
  const lines = String(text).split('\n');
  const starts = l => { const t = l.trim(); return t === marker || t.startsWith(`${marker} `); };
  let start = -1;
  for (let i = lines.length - 1; i >= 0; i--) if (starts(lines[i])) { start = i; break; }
  if (start < 0) return null;
  const block = [];
  for (let i = start; i < lines.length; i++) {
    const l = lines[i];
    if (/^\s*```/.test(l)) break;
    if (i > start && !l.trim()) {
      if (/^\s*[A-Za-z_][\w.-]*=/.test(lines[i + 1] || '')) continue;
      break;
    }
    block.push(l);
  }
  const fields = {};
  let last = null;
  const add = (k, v) => { fields[k] = fields[k] === undefined ? v : `${fields[k]}\n${v}`; last = k; };
  block.forEach((l, n) => {
    const body = n === 0 ? l.trim().slice(marker.length).trim() : l;
    if (n > 0 && !/^\s*[A-Za-z_][\w.-]*=/.test(body)) {
      if (last && body.trim()) fields[last] += `\n${body.trim()}`;
      return;
    }
    for (const part of body.trim().split(KEY_START)) {
      const eq = part.indexOf('=');
      if (eq > 0) add(part.slice(0, eq), part.slice(eq + 1).trim());
    }
  });
  return { raw: block.join('\n'), fields };
}


const OMIT = new Set(['rolloutPath', 'title', 'cwd', 'model', 'archived', 'ownerClientId', 'threadId']);
const TEXT_FIELDS = ['lastAgentMessage', 'finalMessage', 'message'];
export function toText(out) {
  if (Array.isArray(out)) return out.map(r => toText(r)).join('\n');
  if (out === null || typeof out !== 'object') return String(out);
  const kv = [], texts = [];
  for (const [k, v] of Object.entries(out)) {
    if (k === 'rule' || OMIT.has(k) || v === null || v === undefined || v === '') continue;
    if (TEXT_FIELDS.includes(k)) { texts.push(String(v)); continue; }
    if (Array.isArray(v)) { texts.push(v.map(x => (typeof x === 'object' ? toText(x) : String(x))).join('\n---\n')); continue; }
    kv.push(`${k}=${typeof v === 'object' ? JSON.stringify(v) : v}`);
  }
  return [kv.join(' '), ...texts, out.rule ? `rule: ${out.rule}` : null].filter(Boolean).join('\n');
}


const ACTIVE = new Set(['queued', 'preparing', 'starting', 'running', 'waiting']);
const ACTIONABLE = new Set(['QUESTION', 'APPROVAL', 'RESULT', 'PAUSED', 'STALLED', 'OVERFLOW']);
const COLLECTIONS = { 'run.created': 'runs', 'run.updated': 'runs', 'message.updated': 'messages',
  'runtime-request.updated': 'runtimeRequests', 'turn-item.updated': 'turnItems',
  'node.updated': 'nodes', 'provider-thread.updated': 'providerThreads', 'provider-turn.updated': 'providerTurns',
  'subagent.updated': 'subagents', 'run-attempt.created': 'attempts', 'run-attempt.updated': 'attempts', 'provider-session.attached': 'providerSessions', 'provider-session.updated': 'providerSessions', 'checkpoint-scope.created': 'checkpointScopes', 'plan.updated': 'plans',
  'checkpoint.updated': 'checkpoints', 'checkpoint.captured': 'checkpoints',
  'context-handoff.updated': 'contextHandoffs', 'context-transfer.created': 'contextTransfers',
  'context-transfer.updated': 'contextTransfers' };
const MESSAGE_LIMIT = 2000; // Matches codex-app-link and codex-progress.
export const requestHandle = id => 'q:' + createHash('sha256').update(String(id)).digest('base64url');
const hash = value => createHash('sha256').update(String(value)).digest('hex');
const fail = (code, message = code) => Object.assign(new Error(message), { code });
const ordered = records => Object.values(records ?? {}).sort((a, b) =>
  (a.ordinal ?? Date.parse(a.createdAt ?? a.startedAt) ?? 0) - (b.ordinal ?? Date.parse(b.createdAt ?? b.startedAt) ?? 0));

// Cursor bounds, per thread. Records hold only fields read later; text is limited by RECORD_TEXT_LIMIT.
export const CURSOR_VERSION = 2;
export const LIMITS = Object.freeze({ runs: 16, messages: 8, runtimeRequests: 16, turnItems: 32, nodes: 32,
  providerThreads: 8, providerSessions: 8, reported: 256, anchors: 64, pending: 64, idleThreads: 16 });
const RECORD_TEXT_LIMIT = 4096;
const FIELDS = {
  runs: ['id', 'ordinal', 'status', 'requestedAt', 'startedAt', 'completedAt'],
  messages: ['id', 'runId', 'role', 'ordinal', 'text', 'streaming', 'matched', 'createdAt', 'startedAt', 'updatedAt'],
  runtimeRequests: ['id', 'runId', 'nodeId', 'kind', 'status', 'answers', 'createdAt', 'resolvedAt'],
  turnItems: ['id', 'runId', 'nodeId', 'ordinal', 'status', 'type', 'toolName', 'requestId', 'questions', 'prompt', 'reason', 'questionAnswer', 'startedAt', 'completedAt', 'updatedAt'],
  nodes: ['id', 'runId'],
  providerThreads: ['id', 'pendingBackgroundTasks', 'updatedAt'],
  providerSessions: ['id', 'status', 'updatedAt'],
};
const THREAD_FIELDS = ['id', 'activeRunId', 'worktreePath'];
const SHELL_FIELDS = [...THREAD_FIELDS, 'activityRunStatus', 'pendingBackgroundTasks', 'archivedAt', 'deletedAt'];
const pick = (value, fields) => value && Object.fromEntries(fields.filter(key => value[key] !== undefined).map(key => [key, value[key]]));
/** Shares one text budget across a value, so a record's size has a hard limit. */
function clip(value, budget = { left: RECORD_TEXT_LIMIT }) {
  if (typeof value === 'string') {
    const text = value.slice(0, budget.left); budget.left -= text.length; return text;
  }
  if (Array.isArray(value)) return value.slice(0, 32).map(entry => clip(entry, budget));
  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).slice(0, 32).map(([key, entry]) => [key, clip(entry, budget)]));
  return value;
}
const recordTime = record => Math.max(0, ...[record?.updatedAt, record?.completedAt, record?.resolvedAt, record?.startedAt, record?.requestedAt, record?.createdAt]
  .map(time => Date.parse(time) || 0));
/** Evicts first-listed records first; pinned ones go only if the limit still requires it. */
function evict(records, limit, list, pinned = () => false) {
  const over = list.length - limit;
  if (over > 0) for (const record of [...list.filter(r => !pinned(r)), ...list.filter(pinned)].slice(0, over)) delete records[record.id];
}

export function freshState(id) {
  return { id, version: CURSOR_VERSION, sequence: null, records: {}, anchors: [], reported: {}, reportedFloor: 0, pending: [], overflow: 0, idleSince: null,
    lastEventAt: Date.now(), initialized: false, missing: false };
}

/** Version 1 cursors held every record. All were processed, so the newest one sets the floor. */
export function migrateState(state, expect = null) {
  if (state.version === CURSOR_VERSION) return false;
  const old = state.records ?? {}, nodes = old.nodes ?? {};
  const held = [...Object.values(old.turnItems ?? {}), ...Object.values(old.messages ?? {})].sort((a, b) => recordTime(a) - recordTime(b));
  state.reportedFloor = Math.max(0, ...Object.values(old).flatMap(records => Object.values(records)).map(recordTime));
  state.anchors = [...new Set(held.flatMap(item => [item.id, item.messageId]).filter(Boolean))].slice(-LIMITS.anchors);
  state.records = {};
  for (const [collection, fields] of Object.entries(FIELDS)) for (const record of Object.values(old[collection] ?? {})) {
    if (collection === 'messages' && record.role !== 'assistant') continue;
    const shaped = collection === 'runtimeRequests' ? { ...record, runId: record.runId ?? nodes[record.nodeId]?.runId }
      : collection === 'messages' && expect ? { ...record, matched: expect.test(record.text ?? '') } : record;
    (state.records[collection] ??= {})[record.id] = clip(pick(shaped, fields));
  }
  for (const key of Object.keys(state.reported ?? {})) state.reported[key] = 0;
  state.reported ??= {}; state.pending ??= []; state.deferredRequests ??= {};
  state.thread = pick(state.thread, THREAD_FIELDS); state.shell = clip(pick(state.shell, SHELL_FIELDS));
  delete state.lastAgentMessage; state.version = CURSOR_VERSION;
  return true;
}

/** Limits what a cursor keeps for threads the current watch does not follow. */
export function compactCursor(saved, ids) {
  const others = Object.values(saved.threads ?? {}).filter(state => !ids.includes(state.id));
  evict(saved.threads, LIMITS.idleThreads, others.sort((a, b) => (a.lastEventAt ?? 0) - (b.lastEventAt ?? 0)));
  for (const state of others) if (saved.threads[state.id]) new Reducer(state);
}

export function requestStatus(state, request) {
  if (request.status !== 'pending') return request.status;
  const item = Object.values(state.records.turnItems ?? {}).find(i => i.requestId === request.id);
  const node = state.records.nodes?.[request.nodeId];
  const runId = request.runId ?? item?.runId ?? node?.runId;
  const run = state.records.runs?.[runId];
  return run && !ACTIVE.has(run.status) ? 'stale' : request.status;
}

export class Reducer {
  constructor(state, { expect, progress = false, silentMs = 240000, questionDelayMs = 5000, complete = false } = {}) {
    delete state.position; // Discard the obsolete page-relative offset in older cursors.
    this.complete = complete; this.state = state; this.expect = expect == null ? null : new RegExp(expect, 'm'); this.progress = progress; this.silentMs = silentMs; this.questionDelayMs = questionDelayMs;
    state.deferredRequests ??= {};
    if (!complete && migrateState(state, this.expect)) this.prune();
  }
  /** Runs after each frame or tick, never during recovery: history rows are not in time order. */
  prune() {
    const s = this.state, r = s.records;
    if (this.complete) return;
    for (const request of Object.values(r.runtimeRequests ?? {})) if (requestStatus(s, request) === 'stale') request.status = 'stale';
    const settled = item => !['running', 'pending', 'waiting'].includes(item.status);
    for (const item of Object.values(r.turnItems ?? {})) {
      const run = r.runs?.[item.runId];
      if (settled(item) ? !item.requestId : run && !ACTIVE.has(run.status)) delete r.turnItems[item.id];
    }
    const lists = { runs: ordered, messages: ordered };
    const pins = { runs: run => ACTIVE.has(run.status), runtimeRequests: request => request.status === 'pending', turnItems: item => !settled(item) };
    for (const collection of Object.keys(FIELDS)) {
      if (r[collection]) evict(r[collection], LIMITS[collection], (lists[collection] ?? Object.values)(r[collection]), pins[collection]);
    }
    const keys = Object.keys(s.reported);
    for (const key of keys.slice(0, Math.max(0, keys.length - LIMITS.reported))) {
      s.reportedFloor = Math.max(s.reportedFloor, s.reported[key] || 0); delete s.reported[key];
    }
  }
  /** Applies only to events that stay in the cursor; a running watch prints them first. */
  capPending() {
    const s = this.state, overflow = s.pending.find(event => event.event === 'OVERFLOW');
    const held = s.pending.filter(event => event !== overflow), excess = held.length - LIMITS.pending;
    if (excess <= 0) return;
    const dropped = new Set([...held.filter(event => !ACTIONABLE.has(event.event)), ...held.filter(event => ACTIONABLE.has(event.event))].slice(0, excess));
    const count = excess + (overflow?.dropped ?? 0);
    s.pending = [{ event: 'OVERFLOW', threadId: s.id, at: new Date().toISOString(), dropped: count,
      message: `${count} held events were dropped to keep the cursor bounded; read the thread for what they covered.` }, ...held.filter(event => !dropped.has(event))];
  }
  emit(event, key, data = {}, at = 0) {
    const s = this.state;
    if (this.complete) return; // One-shot inspection reads state; it reports no events.
    if (key in s.reported) { const held = s.reported[key]; delete s.reported[key]; s.reported[key] = Math.max(Number(held) || 0, at); return; }
    if (at && at <= s.reportedFloor) return;
    s.reported[key] = at;
    if (this.baselining) return;
    const rule = ({ QUESTION: RULES.questions, APPROVAL: RULES.approvals, STALLED: RULES.stalled, PAUSED: RULES.done, DONE: RULES.done })[event];
    s.pending.push({ event, threadId: s.id, at: new Date().toISOString(), ...clip(data), ...(rule ? { rule } : {}) });
  }
  hold(collection, record) {
    if (this.complete) { (this.state.records[collection] ??= {})[record.id] = record; return; }
    if (!FIELDS[collection] || (collection === 'messages' && record.role !== 'assistant')) return;
    const records = this.state.records[collection] ??= {};
    delete records[record.id]; // Reinsert, so key order is least recently updated first.
    records[record.id] = clip(pick(record, FIELDS[collection]));
    if (collection === 'turnItems' || collection === 'messages') this.anchor(record);
  }
  anchor(item) {
    const s = this.state;
    for (const id of [item.id, item.messageId]) {
      if (!id) continue;
      const known = s.anchors.indexOf(id);
      if (known >= 0) s.anchors.splice(known, 1);
      s.anchors.push(id);
    }
    if (s.anchors.length > LIMITS.anchors) s.anchors.splice(0, s.anchors.length - LIMITS.anchors);
  }
  store(collection, record) {
    if (!record?.id) throw fail('t3-invalid-record');
    const s = this.state, at = recordTime(record);
    if (collection === 'runtimeRequests') record = { ...record, runId: record.runId ?? s.records.nodes?.[record.nodeId]?.runId };
    if (collection === 'messages' && this.expect) record = { ...record, matched: new RegExp(this.expect.source, 'm').test(record.text ?? '') };
    this.hold(collection, record);
    if (collection === 'runs') {
      this.emit('STARTED', `run:${record.id}`, { turnId: record.id, status: record.status }, at);
      if (this.progress && !ACTIVE.has(record.status)) this.emit('TURN_END', `end:${record.id}`, { turnId: record.id, status: record.status }, at);
    } else if (collection === 'messages') {
      if (record.maintenance) this.emit('MAINTENANCE', `maintenance:${record.id}`, { maintenance: record.maintenance }, at);
      if (record.role === 'assistant') this.message(record, at);
    } else if (collection === 'runtimeRequests') {
      if (record.status === 'pending') this.request(record);
      else delete s.deferredRequests[record.id];
    } else if (collection === 'turnItems') {
      if (record.type === 'approval_request') {
        const request = s.records.runtimeRequests?.[record.requestId];
        if (request?.status === 'pending') this.request(request);
      }
      if (record.type === 'compaction' && record.status === 'completed')
        this.emit('COMPACTED', `compaction:${record.id}`, { itemId: record.id }, at);
      if (record.type === 'user_input_request') {
        const request = s.records.runtimeRequests?.[record.requestId];
        if (request || ['pending', 'running', 'waiting'].includes(record.status) || record.questionAnswer)
          this.request({ ...record, ...request, id: record.requestId, kind: 'user_input',
            status: request?.status ?? (record.questionAnswer ? 'resolved' : 'pending'),
            resolvedAt: request?.resolvedAt ?? record.completedAt, questions: record.questions });
      }
    }
  }
  request(record, fallback = false, unreported = false) {
    if (requestStatus(this.state, record) === 'stale') { delete this.state.deferredRequests[record.id]; return; }
    const s = this.state, item = Object.values(s.records.turnItems ?? {}).find(i => i.requestId === record.id);
    const questions = record.questions ?? item?.questions ?? [];
    const approvalText = item?.prompt ?? item?.reason ?? record.prompt;
    if ((record.kind === 'user_input' ? !questions.length : !approvalText) && !fallback && !this.baselining) {
      s.deferredRequests[record.id] ??= { record: this.complete ? record : clip(record), at: this.now ?? Date.now() };
      return;
    }
    unreported ||= record.id in s.deferredRequests; // Never reported, so the floor must not hide it.
    delete s.deferredRequests[record.id];
    this.emit(record.kind === 'user_input' ? 'QUESTION' : 'APPROVAL', `request:${record.id}`,
      { requestId: record.id, handle: requestHandle(record.id), kind: record.kind, questions, status: record.status, answeredAt: record.resolvedAt ?? item?.completedAt ?? null,
        message: record.kind === 'user_input' ? (questions.length ? '' : 'Question text unavailable; run questions for the full request.') : approvalText ?? 'The user must review this approval in T3.', ...(record.kind !== 'user_input' ? { approval: item ?? null } : {}) }, unreported ? 0 : recordTime(record));
  }
  flushQuestions(now = Date.now()) {
    for (const deferred of Object.values(this.state.deferredRequests))
      if (now - deferred.at >= this.questionDelayMs) this.request(deferred.record, true);
  }
  message(record, at = 0) {
    const text = record.text ?? '';
    if (this.expect && !record.streaming) {
      for (const line of text.split('\n')) if (new RegExp(this.expect.source, this.expect.flags).test(line))
        this.emit('RESULT', `result:${record.id}:${hash(line)}`, { messageId: record.id, turnId: record.runId, message: line }, at);
    }
    const note = text.split('\n').filter(line => !this.expect?.test(line)).join('\n').trim();
    if (this.progress && !record.streaming && note)
      this.emit('NOTE', `note:${record.id}:${hash(note)}`, { messageId: record.id, message: note }, at);
  }
  baseline(frame, now = Date.now()) {
    this.baselining = true;
    try { this.accept(frame, now); } finally { this.baselining = false; }
    this.state.settleArmed = this.active();
    for (const request of Object.values(this.state.records.runtimeRequests ?? {})) {
      if (request.status !== 'pending') continue;
      delete this.state.reported[`request:${request.id}`];
      this.request(request, false, true);
    }
  }
  accept(frame, now = Date.now()) {
    const s = this.state; this.now = now;
    if (frame.kind === 'synchronized') { s.initialized = true; return; }
    if (frame.kind === 'snapshot') {
      if (frame.projection?.thread?.id !== s.id) throw fail('t3-thread-identity-mismatch');
      s.lastEventAt ??= now;
      s.thread = pick(frame.projection.thread, THREAD_FIELDS);
      // A bounded snapshot supersedes liveness; evicted runs must not stay active.
      s.records.runs = {};
      const currentRequests = new Set((frame.projection.runtimeRequests ?? []).map(r => r.id));
      for (const [id, request] of Object.entries(s.records.runtimeRequests ?? {}))
        if (request.status === 'pending' && !currentRequests.has(id)) delete s.records.runtimeRequests[id];
      // Merge, rather than discard, records restored by history paging.
      for (const [name, records] of Object.entries(frame.projection)) {
        if (Array.isArray(records) && name !== 'visibleTurnItems') for (const record of records) this.store(name, record);
      }
      for (const row of frame.projection.visibleTurnItems ?? []) this.historyItem(row);
      s.sequence = frame.snapshotSequence;
    } else if (frame.kind === 'event') {
      if (frame.sequence <= (s.sequence ?? -1)) return;
      if (frame.event.threadId && frame.event.threadId !== s.id) throw fail('t3-thread-identity-mismatch');
      const { type, payload } = frame.event;
      if (type === 'thread.visited') {
        const id = payload?.id ?? payload?.threadId;
        if (id !== s.id) throw fail('t3-thread-identity-mismatch');
        if (payload.id) s.thread = pick(payload, THREAD_FIELDS);
        s.sequence = frame.sequence;
        return;
      }
      if (type.startsWith('provider-') || type.startsWith('run.') || type.startsWith('run-attempt.') ||
          ['runtime-request.updated', 'node.updated', 'subagent.updated', 'plan.updated'].includes(type) ||
          (type === 'message.updated' && payload?.role === 'assistant') ||
          (type === 'turn-item.updated' && !['user_message', 'notification'].includes(payload?.type))) s.lastEventAt = now;
      if (type === 'run.created' || type === 'run.updated') {
        const previous = s.records.runs?.[payload?.id];
        if (!previous || ACTIVE.has(previous.status) || ACTIVE.has(payload?.status)) s.settleArmed = true;
      }
      if (COLLECTIONS[type]) this.store(COLLECTIONS[type], payload);
      else if (type.startsWith('thread.') && payload?.id === s.id) s.thread = pick(payload, THREAD_FIELDS);
      else if (!['thread.pull-request-link-updated', 'provider-session.detached', 'run.background-work-cancelled', 'checkpoint.rollback-requested'].includes(type)) this.emit('UNPARSED', `unknown:${frame.sequence}`, { type });
      s.sequence = frame.sequence;
    } else this.emit('UNPARSED', `unknown:${frame.sequence ?? hash(JSON.stringify(frame))}`, { type: frame.eventType ?? frame.kind });
    if (this.active()) { s.idleSince = null; s.classified = null; }
    else {
      s.idleSince ??= now;
      const completedAt = Math.max(0, ...Object.values(s.records.runs ?? {}).map(r => Date.parse(r.completedAt) || 0));
      s.idleSince = Math.max(s.idleSince, completedAt);
    }
    this.prune();
  }
  historyItem(row) {
    const item = row.item ?? row;
    if (row.visibility === 'inherited') return;
    if (item.runId) this.emit('STARTED', `run:${item.runId}`, { turnId: item.runId, recovered: true });
    if (item.type === 'assistant_message') this.store('messages', { ...item, id: item.messageId ?? item.id, role: 'assistant' });
    else this.store('turnItems', item);
  }
  active() {
    const s = this.state;
    if (s.thread?.activeRunId || s.shell?.activeRunId || s.shell?.activityRunStatus || s.shell?.pendingBackgroundTasks?.length) return true;
    return Object.values(s.records.runs ?? {}).some(run => ACTIVE.has(run.status));
  }
  status() {
    const s = this.state, run = ordered(s.records.runs).at(-1);
    const messages = ordered(s.records.messages).filter(m => m.role === 'assistant');
    return { threadId: s.id, status: this.active() ? 'active' : 'idle', workspace: s.thread?.worktreePath ?? s.shell?.worktreePath ?? null, turnId: run?.id ?? null,
      lastTurnStatus: run?.status ?? null, lastAgentMessage: messages.at(-1)?.text ?? '',
      pending: Object.values(s.records.runtimeRequests ?? {}).filter(r => requestStatus(s, r) === 'pending').length,
      rule: this.active() ? RULES.active : null };
  }
  liveness() {
    const s = this.state;
    const running = Object.values(s.records.turnItems ?? {}).filter(i => ['running', 'pending', 'waiting'].includes(i.status));
    return { runningCommands: running.filter(i => i.type === 'command_execution').map(i => ({ id: i.id, status: i.status })),
      runningTools: running.filter(i => i.type === 'dynamic_tool').map(i => ({ id: i.id, name: i.toolName, status: i.status })),
      backgroundTasks: Object.values(s.records.providerThreads ?? {}).flatMap(p => p.pendingBackgroundTasks ?? []),
      providerStates: Object.values(s.records.providerSessions ?? {}).map(p => ({ id: p.id, status: p.status })),
      pendingRequests: Object.values(s.records.runtimeRequests ?? {}).filter(r => requestStatus(s, r) === 'pending').map(r => ({ kind: r.kind, id: r.id })) };
  }
  quietMessage() {
    if (!this.active()) return 'thread is idle; no active run';
    const l = this.liveness();
    if (l.runningCommands.length) return 'T3 reports a command as running; verify the command before treating the run as dead';
    if (l.runningTools.length) return 'T3 reports a tool as running; verify it before treating the run as dead';
    if (l.pendingRequests.length) return 'T3 is awaiting a question or permission response';
    if (l.backgroundTasks.length) return 'T3 reports background work; verify it before treating the run as dead';
    return 'active run has no observable progress; may be reasoning or hung; inspect T3';
  }
  tick(now, settleMs, stallMs) {
    const s = this.state; this.flushQuestions(now);
    if (!s.initialized || s.missing) return;
    if (this.progress && now - s.lastEventAt >= this.silentMs)
      this.emit('SILENT', `silent:${s.lastEventAt}`, { seconds: Math.floor((now - s.lastEventAt) / 1000), message: this.quietMessage() });
    if (this.active()) {
      if (now - s.lastEventAt >= stallMs) this.emit('STALLED', `stall:${s.lastEventAt}`, { message: this.quietMessage(), liveness: this.liveness(), seconds: Math.floor((now - s.lastEventAt) / 1000) });
    } else if (s.settleArmed !== false && s.idleSince != null && now - s.idleSince >= settleMs) {
      const run = ordered(s.records.runs).at(-1), key = run?.id ?? 'idle';
      const messages = ordered(s.records.messages).filter(m => m.role === 'assistant' && (!run || m.runId === run.id));
      const matched = this.expect && (messages.at(-1)?.matched || new RegExp(this.expect.source, 'm').test(messages.at(-1)?.text ?? ''));
      const event = this.expect && !matched ? 'PAUSED' : 'DONE';
      this.emit(event, `settled:${key}`, { turnId: run?.id ?? null, lastAgentMessage: this.status().lastAgentMessage });
      s.classified = event;
    }
  }
}

const EVENT_ROWS = new Set(['assistant_message', 'compaction', 'user_input_request', 'approval_request']);
// History pages are chronological windows with page-relative positions. Only item identities resume them.
export async function recoverHistory(rpc, reducer, frame, { replies = Infinity, since = 0 } = {}) {
  let cursor = frame.historyCursor, found = false, limited = false;
  const newer = [], visited = new Set(), runs = new Set(), replyRuns = new Set();
  const held = new Set(reducer.state.anchors ?? []);
  const scan = rows => {
    for (let i = rows.length - 1; i >= 0; i--) {
      const item = rows[i].item ?? rows[i];
      if (held.has(item.id) || held.has(item.messageId)) return i;
      // A row with no event and an already-counted run changes nothing when replayed.
      if (EVENT_ROWS.has(item.type) || !runs.has(item.runId)) newer.push(rows[i]);
      runs.add(item.runId);
      if (item.type === 'assistant_message' && !item.streaming) replyRuns.add(item.runId);
      if (replyRuns.size > replies || (since && recordTime(item) && recordTime(item) < since)) { limited = true; return -1; }
    }
    return -1;
  };
  const snapshotRows = frame.projection?.visibleTurnItems ?? [];
  const snapshotBoundary = scan(snapshotRows);
  found = snapshotBoundary >= 0;
  while (!found && !limited && cursor && frame.hasMoreHistory !== false) {
    if (visited.has(cursor)) throw fail('t3-history-cursor-loop');
    visited.add(cursor);
    const page = await rpc.history(reducer.state.id, cursor);
    if (!Array.isArray(page.items)) throw fail('t3-invalid-history');
    found = scan(page.items) >= 0;
    if (found || limited || !page.hasMoreHistory) break;
    if (!page.nextCursor) throw fail('t3-history-incomplete');
    cursor = page.nextCursor;
  }
  if (found && snapshotBoundary >= 0) {
    // Hydration below must not report pre-baseline rows from the same snapshot window.
    reducer.baselining = true;
    try {
      const messages = new Map((frame.projection.messages ?? []).map(message => [message.id, message]));
      for (const row of snapshotRows.slice(0, snapshotBoundary)) {
        reducer.historyItem(row);
        const message = messages.get(row.item?.messageId);
        if (message) reducer.store('messages', message);
      }
    } finally { reducer.baselining = false; }
  }
  if (!found && !limited) reducer.emit('HISTORY_START', `history-start:${frame.snapshotSequence ?? reducer.state.sequence}`,
    { message: 'No held history item found; recovered to the start of available history.' });
  for (const row of newer.reverse()) reducer.historyItem(row);
}

function parse(args) {
  const opt = {}, pos = [];
  const booleans = new Set(['json', 'tracked', 'progress', 'until-event', 'until-question', 'all', 'queue', 'steer', 'wait', 'stdin', 'no-open']);
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    if (!arg.startsWith('--')) { pos.push(arg); continue; }
    const [key, inline] = arg.slice(2).split(/=(.*)/s);
    if (booleans.has(key)) opt[key] = true;
    else { const value = inline ?? args[++i]; if (value == null || value.startsWith('--')) throw fail('missing-option-value', arg); opt[key] = value; }
  }
  return { opt, pos };
}
const jsonFile = (file, fallback) => {
  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { if (e.code === 'ENOENT') return fallback; throw e; }
};
function atomicJson(file, value) {
  fs.mkdirSync(path.dirname(file), { recursive: true });
  const temp = `${file}.${process.pid}.tmp`;
  try { fs.writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 }); fs.renameSync(temp, file); }
  catch (error) { fs.rmSync(temp, { force: true }); throw error; }
}
function registryPath(opt) {
  if (opt.registry || process.env.T3_APP_LINK_REGISTRY) return path.resolve(opt.registry ?? process.env.T3_APP_LINK_REGISTRY);
  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
  return path.join(r.status === 0 ? r.stdout.trim() : process.cwd(), '.t3-app-link.json');
}
export function resolveRef(ref, reg) {
  if (!ref) throw fail('missing-thread', 'pass a thread ID or tracked name');
  return reg.threads.find(t => t.name.toLowerCase() === ref.toLowerCase())?.id ?? ref;
}
function refuseSelf(id) {
  const own = [process.env.T3CODE_THREAD_ID, process.env.T3_THREAD_ID, process.env.T3_APP_LINK_SELF];
  if (own.includes(id)) throw fail('self-tracking', 'Do not track the lead thread.');
}
const TOKEN_FILE = path.join(os.homedir(), 'Library/Application Support/T3-App-Link/token');
const runtimePath = () => path.join(process.env.T3CODE_HOME ?? path.join(os.homedir(), '.t3'), 'userdata/server-runtime.json');
function privateToken(file = TOKEN_FILE) {
  const stat = fs.lstatSync(file);
  if (!stat.isFile() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid())) throw fail('unsafe-token-file');
  if (stat.mode & 0o077) fs.chmodSync(file, 0o600);
  return fs.readFileSync(file, 'utf8').trim();
}
export async function setup({ tokenFile = TOKEN_FILE, app = process.env.T3_APP_LINK_APP ?? '/Applications/T3 Code (Beta).app', run = spawnSync, fetch = globalThis.fetch, origin } = {}) {
  if (fs.existsSync(tokenFile)) {
    const token = privateToken(tokenFile);
    let response, session;
    try {
      origin ??= jsonFile(runtimePath()).origin;
      response = await fetch(new URL('/api/auth/session', origin), { headers: { Authorization: `Bearer ${token}` } });
      session = await response.json();
    } catch { throw fail('token-validation-failed', 'Could not validate the existing monitoring session with T3.'); }
    if (response.ok && session.authenticated && Date.parse(session.expiresAt) > Date.now()) {
      if (JSON.stringify(session.scopes) !== JSON.stringify(['orchestration:read'])) throw fail('token-scope-mismatch', 'The monitoring token must have only orchestration:read.');
      atomicJson(`${tokenFile}.json`, { expiresAt: session.expiresAt });
      return { setup: 'ready', scope: 'orchestration:read', reused: true };
    }
    if (response.status !== 401 && response.status !== 403 && session.authenticated !== false && !(Date.parse(session.expiresAt) <= Date.now())) throw fail('token-validation-failed');
  }
  const plist = run('/usr/libexec/PlistBuddy', ['-c', 'Print :CFBundleExecutable', path.join(app, 'Contents/Info.plist')], { encoding: 'utf8' });
  if (plist.status !== 0) throw fail('bundled-cli-unavailable');
  const executable = path.join(app, 'Contents/MacOS', plist.stdout.trim());
  const entry = path.join(app, 'Contents/Resources/app.asar/apps/server/dist/bin.mjs');
  const env = { ...process.env, ELECTRON_RUN_AS_NODE: '1' };
  for (const key of ['T3_SERVICE_LAUNCHER_CONTEXT', 'T3_BOOT_SERVICE_UNIT', 'VITE_DEV_SERVER_URL', 'T3CODE_DEV_AUTH_TOKEN']) delete env[key];
  const result = run(executable, [entry, 'auth', 'session', 'issue', '--base-dir', path.dirname(path.dirname(runtimePath())),
    '--json', '--scope', 'orchestration:read', '--label', 'T3 App Link', '--subject', 't3-app-link'], { encoding: 'utf8', env });
  if (result.status !== 0) throw fail('token-issue-failed', 'Bundled auth CLI failed; output withheld to protect credentials.');
  let issued;
  try { issued = JSON.parse(result.stdout); } catch { throw fail('token-issue-invalid'); }
  if (typeof issued.token !== 'string' || !issued.token || !issued.sessionId || !Number.isFinite(Date.parse(issued.expiresAt)) || JSON.stringify(issued.scopes) !== JSON.stringify(['orchestration:read'])) throw fail('token-issue-invalid');
  fs.mkdirSync(path.dirname(tokenFile), { recursive: true, mode: 0o700 });
  const temporary = `${tokenFile}.${process.pid}.tmp`;
  try { fs.writeFileSync(temporary, issued.token + '\n', { mode: 0o600, flag: 'wx' }); fs.renameSync(temporary, tokenFile); }
  catch (error) { fs.rmSync(temporary, { force: true }); throw error; }
  atomicJson(`${tokenFile}.json`, { expiresAt: issued.expiresAt, sessionId: issued.sessionId });
  return { setup: 'ready', scope: 'orchestration:read', reused: false };
}

export function lockCursor(file) {
  if (!file) return () => {};
  fs.mkdirSync(path.dirname(file), { recursive: true });
  const lock = `${file}.lock`;
  for (;;) {
    try { fs.writeFileSync(lock, String(process.pid), { flag: 'wx', mode: 0o600 }); break; }
    catch (e) {
      if (e.code !== 'EEXIST') throw e;
      const pid = Number(fs.readFileSync(lock, 'utf8'));
      if (!Number.isSafeInteger(pid) || pid <= 0) throw fail('cursor-in-use');
      try { process.kill(pid, 0); throw fail('cursor-in-use'); }
      catch (error) { if (error.code !== 'ESRCH') throw error; fs.unlinkSync(lock); }
    }
  }
  return () => { if (fs.existsSync(lock) && fs.readFileSync(lock, 'utf8') === String(process.pid)) fs.unlinkSync(lock); };
}

export class Monitor {
  constructor(ids, saved, options, reg) {
    this.options = options; this.reg = reg; this.saved = saved; this.ids = ids;
    saved.threads ??= {}; this.reducers = new Map(ids.map(id => {
      saved.threads[id] ??= freshState(id); return [id, new Reducer(saved.threads[id], options)];
    }));
    this.shellIds = new Set([...ids, process.env.T3CODE_THREAD_ID, process.env.T3_APP_LINK_SELF]);
    this.shells = new Map(); this.work = Promise.resolve(); this.subscriptions = new Set(); this.connected = false;
  }
  enqueue(fn) { this.work = this.work.then(fn).then(() => { this.scheduleQuestions(); this.changed?.(); }).catch(e => { this.error = e; this.changed?.(); }); }
  scheduleQuestions() {
    clearTimeout(this.questionTimer);
    const due = [...this.reducers.values()].flatMap(r => Object.values(r.state.deferredRequests).map(q => q.at + r.questionDelayMs));
    if (!this.closed && due.length) this.questionTimer = setTimeout(() => this.enqueue(() => { for (const r of this.reducers.values()) r.flushQuestions(); }), Math.max(0, Math.min(...due) - Date.now()));
  }
  async open() {
    const runtime = jsonFile(runtimePath());
    this.rpc = (this.options.rpcFactory ?? (options => new T3Rpc(options)))({ origin: this.options.origin ?? runtime.origin, token: privateToken(this.options['token-file'] ?? TOKEN_FILE) });
    const config = await this.rpc.request('server.getConfig', {});
    this.codexInstances = new Set((config.providers ?? []).filter(p => p.driver === 'codex').map(p => p.instanceId));
    const environmentId = config.environment?.environmentId;
    const expected = this.options.environment ?? this.reg.environmentId;
    if (expected && expected !== environmentId) throw fail('t3-environment-mismatch');
    if (this.saved.environmentId && this.saved.environmentId !== environmentId) throw fail('cursor-environment-mismatch');
    this.saved.environmentId = environmentId;
    await this.rpc.subscribe('orchestration.subscribeShell', { requestCompletionMarker: true, omitIdleSubagents: false, omitOlderSettled: false }, {
      onFrame: frame => this.enqueue(() => this.shell(frame)), onDisconnect: error => this.disconnect(error),
    });
    await this.work;
    for (const id of this.ids) if (this.options.inspecting || (this.shells.has(id) && !this.reducers.get(id).state.missing)) await this.subscribe(id);
    await this.work; this.connected = true;
  }
  shellKept(id) { return this.options.allShells || this.shellIds.has(id); }
  shell(frame) {
    if (frame.resolvedRepositoryIdentityRoots !== undefined) return;
    if (frame.kind === 'snapshot' && frame.snapshot?.threads) {
      this.shellReady = true;
      this.shells = new Map([...frame.snapshot.threads, ...(frame.snapshot.archivedThreads ?? [])].filter(t => this.shellKept(t.id)).map(t => [t.id, t]));
      for (const [id, reducer] of this.reducers) this.updateShell(reducer, this.shells.get(id));
    } else if (frame.kind === 'thread.updated') {
      if (this.shellKept(frame.thread.id)) this.shells.set(frame.thread.id, frame.thread);
      const reducer = this.reducers.get(frame.thread.id);
      if (reducer) {
        this.updateShell(reducer, frame.thread);
        if (this.connected && !reducer.state.missing) return this.subscribe(frame.thread.id);
      }
    } else if (frame.kind === 'thread.removed') {
      this.shells.delete(frame.threadId); const reducer = this.reducers.get(frame.threadId); if (reducer) this.updateShell(reducer, null);
    }
  }
  updateShell(reducer, shell) {
    const s = reducer.state; s.shell = shell ? clip(pick(shell, SHELL_FIELDS)) : null;
    const missing = !shell || !!shell.deletedAt || !!shell.archivedAt;
    if (missing && !s.missing) { reducer.emit('MISSING', `missing:${Date.now()}`); s.missing = true; }
    else if (!missing && s.missing) { reducer.emit('FOUND', `found:${Date.now()}`); s.missing = false; }
    if (reducer.active()) { s.idleSince = null; s.classified = null; } else s.idleSince ??= Date.now();
  }
  async subscribe(id) {
    if (this.subscriptions.has(id)) return;
    const reducer = this.reducers.get(id), s = reducer.state;
    this.subscriptions.add(id);
    await this.rpc.subscribe('orchestration.subscribeThread', { threadId: id, acceptBoundedSnapshot: true, requestCompletionMarker: true,
      ...(s.sequence != null ? { afterSequence: s.sequence } : {}) }, {
      onFrame: frame => this.enqueue(async () => {
        if (frame.kind === 'snapshot' && this.options.inspecting) s.missing = false;
        if (frame.kind === 'snapshot' && this.options.watching && s.sequence == null) {
          reducer.baseline(frame);
        } else {
          if (frame.kind === 'snapshot' && this.options.history !== false) await recoverHistory(this.rpc, reducer, frame, this.options.historyLimit);
          reducer.accept(frame);
        }
      }), onDisconnect: error => this.disconnect(error),
    });
  }
  disconnect(error) {
    if (error && !['t3-disconnected', 't3-connection-failed', 't3-rpc-closed'].includes(error.code)) { this.error = error; this.changed?.(); return; }
    if (this.closed || this.disconnected) return;
    this.disconnected = true; this.connected = false;
    for (const reducer of this.reducers.values()) {
      const s = reducer.state; if (!s.missing) { reducer.emit('MISSING', `disconnect:${Date.now()}`); s.missing = true; }
    }
    this.changed?.();
  }
  close() { this.closed = true; clearTimeout(this.questionTimer); this.rpc?.close(); }
}

function seconds(opt, key, fallback) {
  const n = opt[key] == null ? fallback : Number(opt[key]);
  if (!Number.isFinite(n) || n < 0) throw fail('invalid-duration', key);
  return n * 1000;
}
const exitFor = event => ({ STALLED: 3, QUESTION: 5, PAUSED: 6 })[event] ?? 0;
const oneLine = text => String(text ?? '').replace(/\s+/g, ' ').trim();
const optionLabels = question => (question.options ?? []).map(option => typeof option === 'string' ? option : option.label ?? String(option));
export function eventText(event, reg) {
  const name = reg.threads.find(t => t.id === event.threadId)?.name ?? event.threadId;
  let detail = '';
  switch (event.event) {
    case 'QUESTION': detail = (event.questions ?? []).map(q => `${q.question ?? q.title ?? ''}${optionLabels(q).length ? ` [options: ${optionLabels(q).join(' | ')}]` : ''}`).join(' ; ') || event.message;
      if (event.status && !['pending','waiting'].includes(event.status)) detail += ` status=${event.status}`;
      detail += ` request=${event.handle ?? requestHandle(event.requestId)}`; break;
    case 'APPROVAL': detail = `${event.kind ?? 'permission'} ${event.message ?? 'The user must review this approval in T3.'} request=${event.handle ?? requestHandle(event.requestId)}`; break;
    case 'STARTED': case 'TURN_END': detail = event.status ? `status=${event.status}` : ''; break;
    case 'RESULT': case 'NOTE': detail = event.message; break;
    case 'PAUSED': case 'DONE': detail = event.lastAgentMessage; break;
    case 'STALLED': detail = event.message ?? 'no provider or run activity; verify the thread before acting'; break;
    case 'SILENT': detail = `${event.seconds}s: ${event.message}`; break;
    case 'MISSING': detail = event.message ?? 'T3 thread unavailable or connection lost; inspect T3'; break;
    case 'FOUND': detail = event.message ?? 'T3 thread available again; cursor recovery resumed'; break;
    case 'MAINTENANCE': detail = typeof event.maintenance === 'object' ? JSON.stringify(event.maintenance) : event.maintenance; break;
    case 'COMPACTED': break;
    default: detail = event.message ?? event.type ?? '';
  }
  const rule = event.rule ? ` | rule: ${event.rule}` : '';
  return `${String(event.at ?? new Date().toISOString()).slice(11,19)} ${event.event}${name ? ` ${name}` : ''}${detail ? ` ${oneLine(detail).slice(0,MESSAGE_LIMIT)}` : ''}${rule}`;
}

export function questionRecords(state) {
  return Object.values(state.records.runtimeRequests ?? {}).filter(r => r.kind === 'user_input' || requestStatus(state, r) === 'stale').map(r => {
    const item = Object.values(state.records.turnItems ?? {}).find(i => i.requestId === r.id);
    const asyncAnswer = Object.values(state.records.messages ?? {}).find(m => m.id === `async-answer:${r.id}`);
    const answers = r.answers ?? item?.questionAnswer?.answers;
    return { ...r, status: requestStatus(state, r), handle: requestHandle(r.id), askedAt: r.createdAt ?? item?.startedAt,
      answeredAt: r.resolvedAt ?? item?.completedAt ?? null, questions: item?.questions ?? (item?.prompt ? [{ question: item.prompt }] : []),
      answers: answers ?? null, answer: answers ? JSON.stringify(answers) : asyncAnswer?.text ?? null,
      answerSource: answers ? (r.answers ? 'runtime-request' : 'question-item') : asyncAnswer ? 'async-answer-message' : null,
      answerUnavailable: r.status === 'resolved' && !answers && !asyncAnswer ? 'T3 retained no answer in the request, question item, or async-answer message.' : null };
  });
}
export function formatQuestions(list) {
  return list.map(q => {
    const head = `[${q.askedAt}${q.status === 'stale' ? ' STALE' : q.answeredAt ? ` answered ${q.answeredAt}` : ' PENDING'}]`;
    const body = q.questions.map(x => `Q: ${x.question ?? x.title ?? ''}${optionLabels(x).length ? `\n  options: ${optionLabels(x).join(' | ')}` : ''}\n  answer key: ${JSON.stringify(x.id ?? x.question)}`).join('\n');
    const shape = Object.fromEntries(q.questions.map(x => [x.id ?? x.question, { answers: ['<selected option>'] }]));
    return `${head}\nrequestId: ${q.id}\nhandle: ${q.handle}\n${body || 'Q: text not retained by T3'}${q.answer ? `\n  answer: ${oneLine(q.answer).slice(0,MESSAGE_LIMIT)}` : q.answerUnavailable ? `\n  answer unavailable: ${q.answerUnavailable}` : ''}${q.kind === 'user_input' ? `\nanswers: ${JSON.stringify(shape)}` : '\nThis approval belongs to a terminal run; it is not open input.'}`;
  }).join('\n---\n');
}

export async function runMonitor(ids, opt, reg, waiting = false) {
  const cursorFile = opt.cursor ? path.resolve(opt.cursor) : null;
  let monitor, timer, deadline, retry, finish;
  const saved = cursorFile ? jsonFile(cursorFile, { threads: {} }) : { threads: {} };
  const settle = seconds(opt, 'settle', 45), stall = seconds(opt, 'stall', 2700), timeout = seconds(opt, 'timeout', 10800);
  const options = { ...opt, inspecting: waiting || opt.inspecting, progress: !!opt.progress, watching: !waiting, history: !waiting, silentMs: seconds(opt, 'silent', 240), questionDelayMs: seconds(opt, 'poll', 5) };
  const release = lockCursor(cursorFile);
  compactCursor(saved, ids);
  const write = () => { if (cursorFile) atomicJson(cursorFile, saved); };
  const save = () => { for (const reducer of monitor?.reducers.values() ?? []) reducer.capPending(); write(); };
  let done = false, holdInitialized = false, startingLeadRun = null, holding = false;
  const self = !waiting && opt['until-event'] && (process.env.T3CODE_THREAD_ID || process.env.T3_APP_LINK_SELF);
  if (!waiting && opt['until-event'] && !self)
    console.error('T3 App Link: no T3CODE_THREAD_ID or T3_APP_LINK_SELF; until-event exits immediately without a lead-run exit hold.');
  const holdingLeadRun = () => {
    if (!self || !monitor?.shellReady) return false;
    const lead = monitor.shells.get(self);
    if (!holdInitialized) {
      holdInitialized = true;
      if (lead && (lead.providerInstanceId === 'codex' || monitor.codexInstances.has(lead.providerInstanceId))) startingLeadRun = lead.activeRunId;
    }
    return !!startingLeadRun && lead?.activeRunId === startingLeadRun;
  };
  const output = value => console.log(opt.json ? JSON.stringify(value) : waiting ? toText(value) : eventText(value, reg));
  const stop = code => { if (done) return; done = true; process.exitCode = code; finish?.(); };
  const drain = () => {
    if (done) return;
    if (monitor?.error) { stop(1); return; }
    holding = false; holdingLeadRun();
    for (const id of ids) {
      const reducer = monitor.reducers.get(id), s = reducer.state;
      while (s.pending.length) {
        const event = s.pending[0];
        if (event.requestId && requestStatus(s, s.records.runtimeRequests?.[event.requestId] ?? event) === 'stale') { s.pending.shift(); continue; }
        if (!waiting && opt['until-event'] && ACTIONABLE.has(event.event) && holdingLeadRun()) { holding = true; save(); return; }
        holding = false; s.pending.shift();
        if (waiting) {
          const terminal = ['DONE', 'PAUSED', 'STALLED'].includes(event.event) || (opt['until-question'] && event.event === 'QUESTION');
          if (!terminal) continue;
          const result = ({ DONE: 'done', PAUSED: 'paused', STALLED: 'stalled', QUESTION: 'question' })[event.event];
          output({ ...reducer.status(), result, rule: event.rule }); save(); stop(exitFor(event.event)); return;
        }
        if (event.event === 'DONE' && opt.expect) continue;
        output(event); write();
        if (opt['until-event'] && ACTIONABLE.has(event.event)) { save(); stop(exitFor(event.event)); return; }
      }
    }
    save();
  };
  const tick = () => {
    if (done || !monitor.connected) return;
    for (const reducer of monitor.reducers.values()) { reducer.tick(Date.now(), settle, stall); reducer.prune(); }
    drain();
  };
  const signal = () => { save(); stop(0); };
  try {
    await new Promise((resolve, reject) => {
      finish = resolve;
      const connect = async () => {
        if (done) return;
        monitor?.close(); monitor = new Monitor(ids, saved, options, reg);
        monitor.changed = () => {
          drain();
          if (monitor.disconnected && !done && !retry) {
            // T3's connection supervisor uses a one-second reconnect base.
            retry = setTimeout(() => { retry = null; connect(); }, 1000);
          }
        };
        try { await monitor.open(); drain(); tick(); }
        catch (e) {
          if (['t3-connection-failed', 't3-disconnected'].includes(e.code) && !done) {
            monitor.disconnect();
            if (!retry) retry = setTimeout(() => { retry = null; connect(); }, 1000);
          } else reject(e);
        }
      };
      process.once('SIGINT', signal); process.once('SIGTERM', signal);
      // Timer cadence is the manager kit's existing five-second watch default.
      timer = setInterval(tick, seconds(opt, 'poll', waiting ? 15 : 5));
      deadline = setTimeout(() => {
        if (holding) return; // A selected event waits for its launching lead run, even past the search timeout.
        output(waiting ? { ...monitor.reducers.get(ids[0]).status(), result: 'timeout' } : { event: 'TIMEOUT' });
        save(); stop(4);
      }, timeout);
      connect();
    });
    if (monitor?.error) throw monitor.error;
  } finally {
    clearInterval(timer); clearTimeout(deadline); clearTimeout(retry);
    monitor?.close(); process.removeListener('SIGINT', signal); process.removeListener('SIGTERM', signal); release();
  }
}

export function completedReplies(state) {
  const active = new Set(Object.values(state.records.runs ?? {}).filter(r => ACTIVE.has(r.status)).map(r => r.id));
  const replies = new Map();
  for (const message of ordered(state.records.messages))
    if (message.role === 'assistant' && !message.streaming && !active.has(message.runId)) replies.set(message.runId, message);
  return [...replies.values()];
}

// One-shot commands fetch only the history their answer needs, then exit.
function historyNeeds(cmd, opt) {
  if (cmd === 'status') return { history: false };
  if (cmd === 'read') return { historyLimit: { replies: Number(opt.last ?? 1) + 1 } };
  if (cmd === 'result') return { historyLimit: { replies: Number(opt.turns ?? 10) + 1 } };
  return { historyLimit: { since: opt.since ? Date.parse(opt.since) : 0 } };
}
async function inspect(ids, opt, reg, cmd) {
  const monitor = new Monitor(ids, { threads: {} }, { ...opt, inspecting: true, complete: true, ...historyNeeds(cmd, opt) }, reg);
  try { await monitor.open(); if (monitor.error) throw monitor.error; return monitor; }
  finally { monitor.close(); }
}
function redirects(cmd, pos, opt, reg) {
  const id = pos[0] ? resolveRef(pos[0], reg) : '<threadId>';
  const message = opt.text ?? (opt.file ? '<contents of --file>' : '<message>');
  const calls = {
    send: ['t3_thread_send', { threadId: id, message, mode: opt.queue ? 'queue' : opt.steer ? 'steer' : 'auto' }],
    new: ['t3_thread_launch', { title: '<title>', message }],
    queue: ['t3_queue', { threadId: id, action: pos[1] === 'rm' ? 'cancel' : 'list', ...(pos[2] ? { queuedRunId: pos[2] } : {}) }],
    interrupt: ['t3_thread_interrupt', { threadId: id }],
    access: ['t3_thread_configure', { threadId: id }],
  };
  const [tool, args] = calls[cmd];
  return `Use ${tool}(${JSON.stringify(args)})${cmd === 'access' ? '; runtime permissions must be set in T3.' : ''}`;
}
const USAGE = `t3-thread setup|status|read|list|wait|questions|result|watch|track|rules|version
status|read|wait|questions|result <thread ID or tracked name> [--json]
read --last N=1; result --marker RESULT --turns N=10; questions --all --since ISO
wait --settle SEC=45 --stall SEC=2700 --timeout SEC=10800 --until-question --expect REGEX
watch (<id>... | --tracked) --expect REGEX --cursor FILE --progress [--silent SEC=240] --until-event
track add <id> --name NAME [--role ROLE] [--note TEXT] [--environment ID] | rm <name> | prune | list
list --limit N=10 --cwd DIR; --registry FILE selects .t3-app-link.json
send|new|queue|interrupt|access redirect to native T3 tools and exit 2.`;

export async function main(args = process.argv.slice(2)) {
  const [cmd, ...rest] = args, { opt, pos } = parse(rest);
  const file = registryPath(opt), reg = jsonFile(file, { threads: [] }); reg.threads ??= [];
  const print = value => console.log(opt.json ? JSON.stringify(value) : toText(value));
  if (['send', 'new', 'queue', 'interrupt', 'access'].includes(cmd)) {
    console.error(redirects(cmd, pos, opt, reg)); process.exitCode = 2; return;
  }
  if (cmd === 'setup') { print(await setup({tokenFile:opt['token-file'] ?? TOKEN_FILE,origin:opt.origin})); return; }
  if (cmd === 'version') {
    const script = fileURLToPath(import.meta.url), manifest = jsonFile(path.resolve(path.dirname(script), '../../../.claude-plugin/plugin.json'), {});
    print({ version: manifest.version ?? 'unknown', script, registry: file }); return;
  }
  if (cmd === 'rules') { print(opt.json ? RULES : Object.entries(RULES).map(([key, value]) => `${key}: ${value}`).join('\n')); return; }
  if (cmd === 'track') {
    if (pos[0] === 'add') {
      if (!pos[1] || !opt.name) throw fail('missing-name', 'track add <id> --name NAME');
      refuseSelf(pos[1]);
      const entry = { id: pos[1], name: opt.name, role: opt.role ?? null, note: opt.note ?? null,
        environmentId: opt.environment ?? reg.environmentId ?? null, added: new Date().toISOString() };
      reg.threads = reg.threads.filter(t => t.id !== entry.id && t.name.toLowerCase() !== entry.name.toLowerCase());
      reg.threads.push(entry);
    } else if (pos[0] === 'rm') {
      const id = resolveRef(pos[1], reg); const before = reg.threads.length; reg.threads = reg.threads.filter(t => t.id !== id);
      if (reg.threads.length === before) throw fail('unknown-thread-name');
    } else if (pos[0] === 'prune') {
      const monitor = new Monitor([], { threads: {} }, { ...opt, allShells: true }, reg);
      try { await monitor.open(); } finally { monitor.close(); }
      reg.threads = reg.threads.filter(t => { const shell = monitor.shells.get(t.id); return shell && !shell.archivedAt && !shell.deletedAt; });
    } else if (pos[0] !== 'list') throw fail('invalid-track-action');
    if (pos[0] !== 'list') atomicJson(file, reg);
    print(reg.threads); return;
  }
  if (cmd === 'list') {
    const monitor = new Monitor([], { threads: {} }, { ...opt, allShells: true }, reg);
    try {
      await monitor.open();
      const limit = Number(opt.limit ?? 10);
      print([...monitor.shells.values()].filter(t => !t.archivedAt && !t.deletedAt && (!opt.cwd || t.worktreePath === opt.cwd))
        .sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt)).slice(0, limit)
        .map(t => ({ id: t.id, name: t.title, updated: t.updatedAt, status: t.status })));
    } finally { monitor.close(); } return;
  }
  if (!['watch', 'wait', 'read', 'status', 'questions', 'result'].includes(cmd)) { console.error(USAGE); process.exitCode = 2; return; }
  const ids = [...new Set(opt.tracked ? reg.threads.map(t => t.id) : pos.map(ref => resolveRef(ref, reg)))];
  if (!ids.length) throw fail('missing-thread');
  for (const id of ids) {
    refuseSelf(id);
    const environment = reg.threads.find(t => t.id === id)?.environmentId;
    if (environment && reg.environmentId && environment !== reg.environmentId) throw fail('mixed-environments');
    if (environment && !opt.environment) opt.environment = environment;
    else if (environment && environment !== opt.environment) throw fail('mixed-environments');
  }
  if (cmd === 'watch' || cmd === 'wait') { await runMonitor(ids, opt, reg, cmd === 'wait'); return; }
  const monitor = await inspect(ids, opt, reg, cmd), reducer = monitor.reducers.get(ids[0]), s = reducer.state;
  if (cmd === 'status') print(reducer.status());
  const replies = completedReplies(s);
  if (cmd === 'read') {
    print({ threadId: ids[0], turns: replies.slice(-Number(opt.last ?? 1)).map(m => ({ turnId: m.runId, message: m.text })) });
  }
  if (cmd === 'result') {
    const result = replies.slice(-Number(opt.turns ?? 10)).map(m => extractResult(m.text, opt.marker ?? 'RESULT')).findLast(Boolean);
    if (!result) { print({ result: 'none', marker: opt.marker ?? 'RESULT' }); process.exitCode = 6; }
    else print(opt.json ? result : `${Object.entries(result.fields).map(([k, v]) => `${k}=${v}`).join('\n')}\nrule: ${RULES.done}`);
  }
  if (cmd === 'questions') {
    const since = opt.since ? Date.parse(opt.since) : 0;
    if (Number.isNaN(since)) throw fail('invalid-since');
    const questions = questionRecords(s).filter(q => Date.parse(q.askedAt) >= since);
    const pending = questions.filter(r => requestStatus(s, r) === 'pending').length;
    const shown = opt.all ? questions : questions.filter(r => r.status === 'pending');
    print(opt.json ? { threadId: ids[0], pending, asked: questions.length, questions: shown } :
      { pending, asked: questions.length, message: shown.length ? formatQuestions(shown) : null, rule: pending ? RULES.questions : null });
    process.exitCode = pending ? 5 : 0;
  }
}
// Compare real paths: a symlinked install or macOS /tmp would otherwise exit 0 having done nothing.
if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
  main().catch(error => { console.error(JSON.stringify({ error: error.code ?? 'error', message: error.code ? error.message : 'T3 App Link failed; inspect local configuration and protocol compatibility.' })); process.exitCode = 1; });
}
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall