ftown 0.25.2 → 0.26.0

package/dist/coordination/card-store.js

@@ -0,0 +1,188 @@
+import { BLOCKED_ON_KINDS, CARD_LIMITS, CARD_STATES, CardValidationError, } from './contract.js';
+const ALLOWED_PATCH_KEYS = new Set(['state', 'headline', 'progress', 'blockedOn', 'next']);
+const SESSION_REF_PATTERN = /^[A-Za-z0-9_-]{1,200}$/;
+function hasOwn(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+function cleanText(value, field, minLength, maxLength) {
+    if (typeof value !== 'string')
+        throw new CardValidationError(`${field} must be a string`);
+    const withoutControls = [...value].map((char) => {
+        const code = char.codePointAt(0) ?? 0;
+        return code <= 31 || code === 127 ? ' ' : char;
+    }).join('');
+    const cleaned = withoutControls.replace(/\s+/g, ' ').trim();
+    const cleanedLength = [...cleaned].length;
+    if (cleanedLength < minLength)
+        throw new CardValidationError(`${field} must not be empty`);
+    if (cleanedLength > maxLength)
+        throw new CardValidationError(`${field} must be at most ${maxLength} characters`);
+    return cleaned;
+}
+function parseProgress(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new CardValidationError('Progress must be an object');
+    }
+    const record = value;
+    const done = record.done;
+    const total = record.total;
+    if (typeof done !== 'number' || typeof total !== 'number' || !Number.isInteger(done) || !Number.isInteger(total)) {
+        throw new CardValidationError('Progress done and total must be integers');
+    }
+    if (total < 1 || total > CARD_LIMITS.progressTotal) {
+        throw new CardValidationError(`Progress total must be between 1 and ${CARD_LIMITS.progressTotal}`);
+    }
+    if (done < 0 || done > total) {
+        throw new CardValidationError('Progress done must be between 0 and total');
+    }
+    return { done, total };
+}
+function parseBlockedOn(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new CardValidationError('Blocked-on must be an object');
+    }
+    const record = value;
+    const kind = BLOCKED_ON_KINDS.find((candidate) => candidate === record.kind);
+    if (!kind)
+        throw new CardValidationError('Blocked-on kind is invalid');
+    const text = cleanText(record.text, 'Blocked-on text', 1, CARD_LIMITS.blockedText);
+    if (kind === 'session') {
+        const ref = record.ref;
+        if (typeof ref !== 'string' || !SESSION_REF_PATTERN.test(ref)) {
+            throw new CardValidationError('Blocked-on session ref is invalid');
+        }
+        return { kind, ref, text };
+    }
+    if (hasOwn(record, 'ref') && record.ref !== undefined && record.ref !== null) {
+        throw new CardValidationError('Blocked-on ref is only allowed when kind is session');
+    }
+    return { kind, text };
+}
+function parsePatch(patch) {
+    if (typeof patch !== 'object' || patch === null || Array.isArray(patch)) {
+        throw new CardValidationError('Card update must be an object');
+    }
+    const record = patch;
+    const keys = Object.keys(record).filter((key) => record[key] !== undefined);
+    if (keys.length === 0)
+        throw new CardValidationError('Empty card update');
+    for (const key of keys) {
+        if (!ALLOWED_PATCH_KEYS.has(key))
+            throw new CardValidationError(`Unknown card field: ${key}`);
+    }
+    const parsed = {
+        hasState: keys.includes('state'),
+        hasHeadline: keys.includes('headline'),
+        hasProgress: keys.includes('progress'),
+        hasBlockedOn: keys.includes('blockedOn'),
+        hasNext: keys.includes('next'),
+    };
+    if (parsed.hasState) {
+        const state = CARD_STATES.find((candidate) => candidate === record.state);
+        if (!state)
+            throw new CardValidationError('Card state is invalid');
+        parsed.state = state;
+    }
+    if (parsed.hasHeadline) {
+        parsed.headline = cleanText(record.headline, 'Headline', 1, CARD_LIMITS.headline);
+    }
+    if (parsed.hasProgress) {
+        parsed.progress = record.progress === null ? null : parseProgress(record.progress);
+    }
+    if (parsed.hasBlockedOn) {
+        parsed.blockedOn = record.blockedOn === null ? null : parseBlockedOn(record.blockedOn);
+    }
+    if (parsed.hasNext) {
+        if (record.next === null) {
+            parsed.next = null;
+        }
+        else {
+            const cleanedNext = cleanText(record.next, 'Next', 0, CARD_LIMITS.next);
+            parsed.next = cleanedNext === '' ? null : cleanedNext;
+        }
+    }
+    return parsed;
+}
+function applyParsed(existing, parsed, updatedAt) {
+    if (!existing && (!parsed.hasState || !parsed.hasHeadline)) {
+        throw new CardValidationError('First card update must include state and headline');
+    }
+    let state = existing?.state;
+    let headline = existing?.headline;
+    let progress = existing?.progress;
+    let blockedOn = existing?.blockedOn;
+    let next = existing?.next;
+    if (parsed.hasState)
+        state = parsed.state;
+    if (parsed.hasHeadline)
+        headline = parsed.headline;
+    if (parsed.hasProgress)
+        progress = parsed.progress === null ? undefined : parsed.progress;
+    if (parsed.hasBlockedOn)
+        blockedOn = parsed.blockedOn === null ? undefined : parsed.blockedOn;
+    if (parsed.hasNext)
+        next = parsed.next === null ? undefined : parsed.next;
+    if (state !== 'blocked' && !parsed.hasBlockedOn)
+        blockedOn = undefined;
+    if (state === undefined || headline === undefined) {
+        throw new CardValidationError('First card update must include state and headline');
+    }
+    const card = { state, headline, updatedAt };
+    if (progress !== undefined)
+        card.progress = progress;
+    if (blockedOn !== undefined)
+        card.blockedOn = blockedOn;
+    if (next !== undefined)
+        card.next = next;
+    return card;
+}
+export class CardStore {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async get(sessionId) {
+        const session = await this.deps.loadSession(sessionId);
+        return session?.card ?? null;
+    }
+    async set(sessionId, patch) {
+        const session = await this.deps.loadSession(sessionId);
+        if (!session)
+            throw new Error('Session not found');
+        const parsed = parsePatch(patch);
+        const updatedAt = new Date(this.deps.now()).toISOString();
+        const fresh = await this.deps.loadSession(sessionId);
+        if (!fresh)
+            throw new Error('Session not found');
+        const previousCard = fresh.card ?? null;
+        const card = applyParsed(previousCard, parsed, updatedAt);
+        const savedSession = { ...fresh, card };
+        await this.deps.saveSession(savedSession);
+        await this.notify(savedSession, previousCard);
+        return card;
+    }
+    async clear(sessionId) {
+        const session = await this.deps.loadSession(sessionId);
+        if (!session || !session.card)
+            return;
+        const fresh = await this.deps.loadSession(sessionId);
+        if (!fresh || !fresh.card)
+            return;
+        const previousCard = fresh.card;
+        const savedSession = { ...fresh };
+        delete savedSession.card;
+        await this.deps.saveSession(savedSession);
+        await this.notify(savedSession, previousCard);
+    }
+    async notify(session, previous) {
+        if (!this.deps.onChange)
+            return;
+        try {
+            await this.deps.onChange(session, previous);
+        }
+        catch (error) {
+            console.warn('CardStore onChange failed', error);
+        }
+    }
+}
+//# sourceMappingURL=card-store.js.map

package/dist/coordination/card-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-store.js","sourceRoot":"","sources":["../../src/coordination/card-store.ts"],"names":[],"mappings":"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"}

package/dist/coordination/contract.d.ts

@@ -0,0 +1,236 @@
+/**
+ * FROZEN CONTRACT — coordination phase A (session cards, board, tree events,
+ * nudge-once mail, digest). Types, constants and interfaces only; no logic.
+ * Implementers must not modify this file. Changes go through the orchestrator.
+ */
+import type { Activity } from '../attention-events.js';
+import type { PullRequestState } from '../pull-request-status-protocol.js';
+import type { MailMessage, Session, SessionStatus } from '../types.js';
+export declare const CARD_STATES: readonly ["working", "blocked", "waiting_review", "done", "failed"];
+export type CardState = typeof CARD_STATES[number];
+export declare const BLOCKED_ON_KINDS: readonly ["human", "parent", "session", "external"];
+export type BlockedOnKind = typeof BLOCKED_ON_KINDS[number];
+export declare const CARD_LIMITS: {
+    readonly headline: 140;
+    readonly next: 280;
+    readonly blockedText: 280;
+    /** progress.total upper bound; done must be 0..total. */
+    readonly progressTotal: 10000;
+};
+export interface CardProgress {
+    done: number;
+    total: number;
+}
+export interface CardBlockedOn {
+    kind: BlockedOnKind; /** session id when kind==='session' */
+    ref?: string;
+    text: string;
+}
+/** Stored on Session.card (session.json) so it flows to the dashboard via toWireSession. */
+export interface SessionCardDeclared {
+    state: CardState;
+    headline: string;
+    progress?: CardProgress;
+    blockedOn?: CardBlockedOn;
+    next?: string;
+    updatedAt: string;
+}
+/**
+ * Partial update. Omitted field = unchanged; null = remove.
+ * The first write to a session with no card must include state and headline.
+ * Setting state to anything other than 'blocked' clears blockedOn unless blockedOn is also given.
+ */
+export interface CardPatch {
+    state?: CardState;
+    headline?: string;
+    progress?: CardProgress | null;
+    blockedOn?: CardBlockedOn | null;
+    next?: string | null;
+}
+export declare class CardValidationError extends Error {
+    constructor(message: string);
+}
+export interface CardPr {
+    url: string;
+    state: PullRequestState;
+    stale: boolean;
+    checkedAt: string | null;
+}
+export interface CardDerived {
+    status: SessionStatus;
+    activity: Activity['state'];
+    /** activity.lastActivityAt when activity === 'idle'. */
+    idleSince?: string;
+    openAttention: number;
+    /** inbox messages without deliveredAt */
+    unreadMail: number;
+    pr?: CardPr;
+    previews: string[];
+    shellType?: string;
+    model?: string;
+}
+export interface SessionCard {
+    sessionId: string;
+    name: string;
+    parentSessionId?: string;
+    declared: SessionCardDeclared | null;
+    derived: CardDerived;
+    /** declared exists and activity.lastActivityAt is more than CARD_STALE_MS after declared.updatedAt */
+    stale: boolean;
+}
+export declare const CARD_STALE_MS: number;
+export interface CardStoreDeps {
+    loadSession(id: string): Promise<Session | null>;
+    saveSession(session: Session): Promise<void>;
+    /** called after a successful set/clear with the saved session (publish to dashboard + emit tree event) */
+    onChange?(session: Session, previous: SessionCardDeclared | null): void | Promise<void>;
+    now(): number;
+}
+/** Implementation: bridge/src/coordination/card-store.ts → `export class CardStore implements CardStoreApi { constructor(deps: CardStoreDeps) }` */
+export interface CardStoreApi {
+    get(sessionId: string): Promise<SessionCardDeclared | null>;
+    /** validates (CardValidationError), merges, stamps updatedAt, saves. Throws Error('Session not found') if missing. */
+    set(sessionId: string, patch: CardPatch): Promise<SessionCardDeclared>;
+    clear(sessionId: string): Promise<void>;
+}
+/** Root of a tree = session.parentSessionId ?? session.id (tree is one level deep). */
+export declare const TREE_EVENTS_FILE = "tree-events.jsonl";
+export declare const TREE_EVENTS_RETAIN = 5000;
+export declare const TREE_EVENTS_COMPACT_AT = 6000;
+export declare const TREE_EVENTS_MAX_WAIT_MS = 300000;
+export declare const TREE_EVENT_SUMMARY_MAX = 300;
+export declare const TREE_EVENT_KINDS: readonly ["status", "attention", "pr", "preview", "exit", "idle", "result", "mail"];
+export type TreeEventKind = typeof TREE_EVENT_KINDS[number];
+export interface TreeEvent {
+    seq: number;
+    ts: string;
+    sessionId: string;
+    sessionName: string;
+    kind: TreeEventKind;
+    summary: string;
+    ref?: string;
+}
+export type TreeEventInput = Omit<TreeEvent, 'seq' | 'ts'>;
+export interface TreeEventPage {
+    events: TreeEvent[]; /** highest seq returned, or `since` if none */
+    cursor: number;
+    timedOut?: boolean;
+}
+export interface TreeEventLogDeps {
+    sessionDir(id: string): string;
+    now(): number;
+}
+/** Implementation: bridge/src/coordination/tree-events.ts → `export class TreeEventLog implements TreeEventLogApi { constructor(deps: TreeEventLogDeps) }` */
+export interface TreeEventLogApi {
+    append(rootId: string, event: TreeEventInput): Promise<TreeEvent>;
+    /** events with seq > since (default 0), oldest first, at most limit (default 100, max 500) */
+    read(rootId: string, opts?: {
+        since?: number;
+        limit?: number;
+    }): Promise<TreeEventPage>;
+    /** resolves immediately if events exist after since; otherwise on next append or timeout (clamped to TREE_EVENTS_MAX_WAIT_MS) with timedOut: true */
+    wait(rootId: string, since: number, timeoutMs: number, signal?: AbortSignal): Promise<TreeEventPage>;
+    /** highest seq for root (0 if none) */
+    head(rootId: string): Promise<number>;
+}
+export type BoardRollupKey = CardState | 'unset';
+export interface Board {
+    rootId: string;
+    /** tree event head at render time; pass back as `since` */
+    cursor: number;
+    /** children of rootId (not the root itself), ordered by createdAt ascending; filtered when ready/since */
+    cards: SessionCard[];
+    rollup: Record<BoardRollupKey, number>;
+}
+export interface BoardQuery {
+    /** any session id; root is resolved */
+    sessionId: string;
+    /** only children with tree events of seq > since */
+    since?: number;
+    /** only children whose derived.pr.state === 'passed' and declared.state !== 'done' (approval/mergeable not tracked in phase A) */
+    ready?: boolean;
+    /** include archived/completed children; default false = status running|pending only plus any with events after since */
+    all?: boolean;
+}
+export interface BoardDeps {
+    loadSession(id: string): Promise<Session | null>;
+    listSessions(): Promise<Session[]>;
+    attention(id: string): Promise<{
+        activity: Activity;
+        openCount: number;
+    }>;
+    prStatus(url: string): Promise<{
+        state: PullRequestState;
+        stale: boolean;
+        checkedAt: string | null;
+    } | null>;
+    unreadMail(id: string): Promise<number>;
+    events: TreeEventLogApi;
+    now(): number;
+}
+/** Implementation: bridge/src/coordination/board.ts → `export class BoardService implements BoardServiceApi { constructor(deps: BoardDeps) }` */
+export interface BoardServiceApi {
+    card(sessionId: string): Promise<SessionCard | null>;
+    board(query: BoardQuery): Promise<Board>;
+    /** deterministic one-line digest of tree events after sinceSeq for the root of sessionId; null if nothing new */
+    digest(sessionId: string, sinceSeq: number): Promise<{
+        line: string | null;
+        cursor: number;
+    }>;
+}
+/**
+ * Digest line format (exact):
+ *   `[ftown] since HH:MM: <part> | <part> | ...`
+ * Parts, in order, one per child with events (latest event per child wins, max 6 children then `+N more`):
+ *   `<name> <state>` + (headline ? ` "<headline ≤60>"` : '') + (pr ? ` (PR <state>)` : '')
+ * then, if any: `<n> question(s) waiting`. Total line ≤ 500 chars. HH:MM is local time of the first event.
+ */
+export declare const DIGEST_MAX = 500;
+/** Plain `ftown board` row (exact column order, single spaces):
+ *   `<name> <state|-> <activity>[ idle <Nm>]  <headline>[  PR:<state>][  !<openAttention>][  ✉<unreadMail>][  (stale)]`
+ */
+/** Replaces MAIL_TYPES in mail-delivery.ts and wire-types.ts. */
+export declare const MAIL_TYPES_V2: readonly ["message", "task", "result", "escalation", "fyi"];
+export type MailTypeV2 = typeof MAIL_TYPES_V2[number];
+/** fyi never schedules a nudge or wake; collected only at the next natural drain/read. */
+export declare const NON_WAKING_MAIL_TYPES: ReadonlySet<MailTypeV2>;
+/** Max native-wake attempts (codex/muse) for one batch before the batch is stamped and left. */
+export declare const MAX_WAKE_ATTEMPTS = 3;
+/**
+ * Nudge-once rules (MailMessage.nudgedAt):
+ * 1. A nudge/wake fires only if ≥1 undelivered, waking message has no nudgedAt.
+ * 2. On firing (any path: PTY, codex, muse, plugin), stamp nudgedAt on every undelivered waking message → that is the batch.
+ * 3. A stamped message never causes another nudge on any path (new mail, recovery, retry).
+ * 4. Recovery (recoverPendingMail) skips stamped mail.
+ * 5. Nudge text: NUDGE_TEXT(counts, digest).
+ */
+export type MailCounts = Partial<Record<MailTypeV2, number>>;
+export interface DigestProvider {
+    /** one-line digest for the recipient (as tree root), or null. Must not throw; return null on error. */
+    digestFor(recipientSessionId: string): Promise<string | null>;
+}
+/** Event sink so mail-delivery can record child→parent `result` mail on the tree log without importing it. */
+export interface MailEventSink {
+    onAccepted(message: MailMessage, recipient: Session): void | Promise<void>;
+}
+export declare const COORDINATION_ROUTES: {
+    /** GET → SessionCard; PUT body CardPatch → SessionCard (400 on CardValidationError); DELETE → { ok: true } */
+    readonly card: "/api/sessions/:id/card";
+    /** GET ?since=<n>&ready=1&all=1 → Board */
+    readonly board: "/api/sessions/:id/board";
+    /** GET ?since=<n>&limit=<n>&waitSeconds=<0..300> → TreeEventPage (root of :id) */
+    readonly events: "/api/sessions/:id/events";
+};
+/**
+ * ftown status [--json] [--session-id <id>]                       → print own card (SessionCard)
+ * ftown status set [--state <s>] [--headline <t>] [--progress <d>/<t>|--no-progress]
+ *                  [--on human|parent|external|session:<id>] [--text <t>] [--next <t>|--no-next] [--session-id <id>]
+ * ftown status clear [--session-id <id>]
+ * ftown board [--json] [--since <n>] [--ready] [--all] [--session-id <id>]
+ *             [--wait --until any-change|any-done|any-blocked|all-done|any-ready [--timeout <s≤300>]]
+ * ftown events [--json] [--since <n>] [--limit <n>] [--wait [--timeout <s≤300>]] [--session-id <id>]
+ * Exit codes: 0 ok, 1 error, 2 usage, 3 wait timed out with condition unmet.
+ * Default session id: FTOWN_SESSION_ID.
+ */
+export declare const BOARD_WAIT_CONDITIONS: readonly ["any-change", "any-done", "any-blocked", "all-done", "any-ready"];
+export type BoardWaitCondition = typeof BOARD_WAIT_CONDITIONS[number];

package/dist/coordination/contract.js

@@ -0,0 +1,63 @@
+// ───────────────────────── Session card (declared by the agent) ─────────────────────────
+export const CARD_STATES = ['working', 'blocked', 'waiting_review', 'done', 'failed'];
+export const BLOCKED_ON_KINDS = ['human', 'parent', 'session', 'external'];
+export const CARD_LIMITS = {
+    headline: 140,
+    next: 280,
+    blockedText: 280,
+    /** progress.total upper bound; done must be 0..total. */
+    progressTotal: 10_000,
+};
+export class CardValidationError extends Error {
+    constructor(message) { super(message); this.name = 'CardValidationError'; }
+}
+export const CARD_STALE_MS = 10 * 60_000;
+// ───────────────────────── Tree event log ─────────────────────────
+/** Root of a tree = session.parentSessionId ?? session.id (tree is one level deep). */
+export const TREE_EVENTS_FILE = 'tree-events.jsonl'; // in sessionDir(rootId)
+export const TREE_EVENTS_RETAIN = 5_000; // keep newest N on compaction
+export const TREE_EVENTS_COMPACT_AT = 6_000;
+export const TREE_EVENTS_MAX_WAIT_MS = 300_000;
+export const TREE_EVENT_SUMMARY_MAX = 300;
+export const TREE_EVENT_KINDS = ['status', 'attention', 'pr', 'preview', 'exit', 'idle', 'result', 'mail'];
+/**
+ * Digest line format (exact):
+ *   `[ftown] since HH:MM: <part> | <part> | ...`
+ * Parts, in order, one per child with events (latest event per child wins, max 6 children then `+N more`):
+ *   `<name> <state>` + (headline ? ` "<headline ≤60>"` : '') + (pr ? ` (PR <state>)` : '')
+ * then, if any: `<n> question(s) waiting`. Total line ≤ 500 chars. HH:MM is local time of the first event.
+ */
+export const DIGEST_MAX = 500;
+/** Plain `ftown board` row (exact column order, single spaces):
+ *   `<name> <state|-> <activity>[ idle <Nm>]  <headline>[  PR:<state>][  !<openAttention>][  ✉<unreadMail>][  (stale)]`
+ */
+// ───────────────────────── Mail: nudge once + fyi ─────────────────────────
+/** Replaces MAIL_TYPES in mail-delivery.ts and wire-types.ts. */
+export const MAIL_TYPES_V2 = ['message', 'task', 'result', 'escalation', 'fyi'];
+/** fyi never schedules a nudge or wake; collected only at the next natural drain/read. */
+export const NON_WAKING_MAIL_TYPES = new Set(['fyi']);
+/** Max native-wake attempts (codex/muse) for one batch before the batch is stamped and left. */
+export const MAX_WAKE_ATTEMPTS = 3;
+// ───────────────────────── Local API (all via dispatchSecure, :id = target session) ─────────────────────────
+export const COORDINATION_ROUTES = {
+    /** GET → SessionCard; PUT body CardPatch → SessionCard (400 on CardValidationError); DELETE → { ok: true } */
+    card: '/api/sessions/:id/card',
+    /** GET ?since=<n>&ready=1&all=1 → Board */
+    board: '/api/sessions/:id/board',
+    /** GET ?since=<n>&limit=<n>&waitSeconds=<0..300> → TreeEventPage (root of :id) */
+    events: '/api/sessions/:id/events',
+};
+// ───────────────────────── CLI (new top-level groups in ftown-cli.ts) ─────────────────────────
+/**
+ * ftown status [--json] [--session-id <id>]                       → print own card (SessionCard)
+ * ftown status set [--state <s>] [--headline <t>] [--progress <d>/<t>|--no-progress]
+ *                  [--on human|parent|external|session:<id>] [--text <t>] [--next <t>|--no-next] [--session-id <id>]
+ * ftown status clear [--session-id <id>]
+ * ftown board [--json] [--since <n>] [--ready] [--all] [--session-id <id>]
+ *             [--wait --until any-change|any-done|any-blocked|all-done|any-ready [--timeout <s≤300>]]
+ * ftown events [--json] [--since <n>] [--limit <n>] [--wait [--timeout <s≤300>]] [--session-id <id>]
+ * Exit codes: 0 ok, 1 error, 2 usage, 3 wait timed out with condition unmet.
+ * Default session id: FTOWN_SESSION_ID.
+ */
+export const BOARD_WAIT_CONDITIONS = ['any-change', 'any-done', 'any-blocked', 'all-done', 'any-ready'];
+//# sourceMappingURL=contract.js.map

package/dist/coordination/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/coordination/contract.ts"],"names":[],"mappings":"AASA,2FAA2F;AAE3F,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC;AAG/F,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AAGpF,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,QAAQ,EAAE,GAAG;IACb,IAAI,EAAE,GAAG;IACT,WAAW,EAAE,GAAG;IAChB,yDAAyD;IACzD,aAAa,EAAE,MAAM;CACb,CAAC;AA4BX,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAe,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC,CAAC,CAAC;CACpF;AA8BD,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,GAAG,MAAM,CAAC;AAoBzC,qEAAqE;AAErE,uFAAuF;AACvF,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,CAAC,wBAAwB;AAC7E,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC,CAAG,8BAA8B;AACzE,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,CAAC;AAC5C,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;AAC/C,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAwEpH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,CAAC;AAE9B;;GAEG;AAEH,6EAA6E;AAE7E,iEAAiE;AACjE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAU,CAAC;AAEzF,0FAA0F;AAC1F,MAAM,CAAC,MAAM,qBAAqB,GAA4B,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AAC/E,gGAAgG;AAChG,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAsBnC,+GAA+G;AAE/G,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,8GAA8G;IAC9G,IAAI,EAAE,wBAAwB;IAC9B,2CAA2C;IAC3C,KAAK,EAAE,yBAAyB;IAChC,kFAAkF;IAClF,MAAM,EAAE,0BAA0B;CAC1B,CAAC;AAEX,iGAAiG;AACjG;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,CAAU,CAAC"}

package/dist/coordination/format.d.ts

@@ -0,0 +1,5 @@
+import { type Board, type SessionCard, type TreeEvent } from './contract.js';
+export declare function formatLocalHHMM(iso: string): string;
+export declare function formatBoardRow(card: SessionCard, nowMs: number): string;
+export declare function formatBoard(board: Board, nowMs: number): string;
+export declare function formatEvent(e: TreeEvent): string;

package/dist/coordination/format.js

@@ -0,0 +1,60 @@
+import { CARD_STATES, } from './contract.js';
+const ROLLUP_ORDER = [...CARD_STATES, 'unset'];
+function pad2(n) {
+    return String(n).padStart(2, '0');
+}
+export function formatLocalHHMM(iso) {
+    const d = new Date(iso);
+    return `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}
+export function formatBoardRow(card, nowMs) {
+    const state = card.declared?.state ?? '-';
+    const activity = card.derived.activity;
+    let idlePart = '';
+    if (activity === 'idle') {
+        const idleSinceMs = card.derived.idleSince !== undefined
+            ? Date.parse(card.derived.idleSince)
+            : NaN;
+        const idleMin = Number.isNaN(idleSinceMs)
+            ? 0
+            : Math.max(0, Math.floor((nowMs - idleSinceMs) / 60_000));
+        idlePart = ` idle ${idleMin}m`;
+    }
+    const headline = card.declared?.headline || '-';
+    let suffix = '';
+    if (card.derived.pr) {
+        suffix += `  PR:${card.derived.pr.state}`;
+    }
+    if (card.derived.openAttention > 0) {
+        suffix += `  !${card.derived.openAttention}`;
+    }
+    if (card.derived.unreadMail > 0) {
+        suffix += `  ✉${card.derived.unreadMail}`;
+    }
+    if (card.stale) {
+        suffix += '  (stale)';
+    }
+    return `${card.name} ${state} ${activity}${idlePart}  ${headline}${suffix}`;
+}
+export function formatBoard(board, nowMs) {
+    if (board.cards.length === 0) {
+        return 'no child sessions';
+    }
+    const rows = board.cards.map((card) => formatBoardRow(card, nowMs));
+    const rollupParts = [];
+    for (const key of ROLLUP_ORDER) {
+        const count = board.rollup[key] ?? 0;
+        if (count > 0) {
+            rollupParts.push(`${count} ${key}`);
+        }
+    }
+    if (rollupParts.length > 0) {
+        rows.push(rollupParts.join(', '));
+    }
+    return rows.join('\n');
+}
+export function formatEvent(e) {
+    const hhmm = formatLocalHHMM(e.ts);
+    return `#${e.seq} ${hhmm} ${e.sessionName} ${e.kind}: ${e.summary}`;
+}
+//# sourceMappingURL=format.js.map

package/dist/coordination/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/coordination/format.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,GAKZ,MAAM,eAAe,CAAC;AAEvB,MAAM,YAAY,GAA8B,CAAC,GAAG,WAAW,EAAE,OAAO,CAAC,CAAC;AAE1E,SAAS,IAAI,CAAC,CAAS;IACrB,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAiB,EAAE,KAAa;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,IAAI,GAAG,CAAC;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;IAEvC,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,MAAM,WAAW,GACf,IAAI,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS;YAClC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;YACpC,CAAC,CAAC,GAAG,CAAC;QACV,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC;YACvC,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;QAC5D,QAAQ,GAAG,SAAS,OAAO,GAAG,CAAC;IACjC,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,IAAI,GAAG,CAAC;IAEhD,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;QACpB,MAAM,IAAI,QAAQ,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAC5C,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,CAAC,aAAa,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;IAC/C,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;IAC5C,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,WAAW,CAAC;IACxB,CAAC;IAED,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,KAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,QAAQ,GAAG,MAAM,EAAE,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAY,EAAE,KAAa;IACrD,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,mBAAmB,CAAC;IAC7B,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IACpE,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,WAAW,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IACD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAY;IACtC,MAAM,IAAI,GAAG,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;AACtE,CAAC"}

package/dist/coordination/tree-events.d.ts

@@ -0,0 +1,31 @@
+import { type TreeEvent, type TreeEventInput, type TreeEventLogApi, type TreeEventLogDeps, type TreeEventPage } from './contract.js';
+/** Per-root JSONL log of tree events (one JSON object per line, seq survives compaction). */
+export declare class TreeEventLog implements TreeEventLogApi {
+    private deps;
+    private locks;
+    /** Highest seq seen per root, cached after the first file read. */
+    private heads;
+    /** Valid event lines per root, cached alongside the head to trigger compaction without recounting. */
+    private counts;
+    /** Wake callbacks of long-poll waiters, keyed by root. */
+    private waiters;
+    constructor(deps: TreeEventLogDeps);
+    private file;
+    private requireValidId;
+    private withLock;
+    /** Parses the log, keeping only well-formed events; a truncated/corrupt tail is tolerated. */
+    private events;
+    /** Cold-fills the head cache. Must run while holding the per-root lock, so it can never
+     *  overwrite a newer head written by a concurrent append. */
+    private stateLocked;
+    private cleaned;
+    append(rootId: string, input: TreeEventInput): Promise<TreeEvent>;
+    /** Rewrites the log down to the newest TREE_EVENTS_RETAIN events via tmp file + rename. Seqs are preserved. */
+    private compact;
+    read(rootId: string, opts?: {
+        since?: number;
+        limit?: number;
+    }): Promise<TreeEventPage>;
+    wait(rootId: string, since: number, timeoutMs: number, signal?: AbortSignal): Promise<TreeEventPage>;
+    head(rootId: string): Promise<number>;
+}