@stage-labs/metro 0.1.0-beta.28 → 0.1.0-beta.281

package/dist/native-recovery-scan.js

@@ -0,0 +1,246 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRecord } from './background.js';
+import { nativeId, nativeToken, NATIVE_CURSOR_MAX, NATIVE_FILE_MAX } from './native-recovery-state.js';
+export const NATIVE_SCAN_BYTES = 256 * 1024;
+export const NATIVE_LINE_BYTES = 64 * 1024;
+const RECORD_MAX = 2048;
+function decodeRows(buffer, start, end, read) {
+    const lines = buffer.subarray(start, end).toString('utf8').split('\n');
+    for (const line of lines.slice(0, RECORD_MAX)) {
+        if (line === '')
+            continue;
+        if (Buffer.byteLength(line) > NATIVE_LINE_BYTES) {
+            read.incomplete = true;
+            continue;
+        }
+        try {
+            read.rows.push(JSON.parse(line));
+        }
+        catch {
+            read.incomplete = true;
+        }
+    }
+    read.incomplete ||= lines.length > RECORD_MAX;
+    return read;
+}
+function readRows(path, offset) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile())
+            throw new Error('Native transcript is not a regular file');
+        if (offset > stat.size)
+            return { rows: [], offset, incomplete: true };
+        const from = Math.max(offset, stat.size - NATIVE_SCAN_BYTES);
+        const buffer = Buffer.alloc(Math.min(stat.size - from, NATIVE_SCAN_BYTES));
+        const count = readSync(fd, buffer, 0, buffer.length, from);
+        const end = buffer.lastIndexOf(10, count - 1);
+        const incomplete = from > offset || count < buffer.length || end !== count - 1;
+        if (count === 0)
+            return { rows: [], offset: from, incomplete };
+        if (end < 0)
+            return { rows: [], offset: from, incomplete: true };
+        const start = from > offset ? buffer.indexOf(10) + 1 : 0;
+        return decodeRows(buffer, start, end, { rows: [], offset: from + end + 1, incomplete });
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function contentOf(row) {
+    return isRecord(row.message) ? row.message.content : undefined;
+}
+function textOf(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content) || content.length !== 1)
+        return null;
+    const block = content[0];
+    return isRecord(block) && block.type === 'text' && typeof block.text === 'string' ? block.text : null;
+}
+function resultOf(value) {
+    if (isRecord(value))
+        return value;
+    if (typeof value !== 'string' || value.length > NATIVE_LINE_BYTES)
+        return null;
+    try {
+        const raw = JSON.parse(value);
+        return isRecord(raw) ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+function tag(text, name) {
+    const matches = [...text.matchAll(new RegExp(`<${name}>([^<]*)</${name}>`, 'g'))];
+    return matches.length > 1 ? undefined : matches[0]?.[1] ?? null;
+}
+function terminal(value, reason) {
+    if (value === 'stopped' && reason === 'worker_restart')
+        return 'restarted';
+    return value === 'completed' || value === 'failed' || value === 'stopped' ? value : null;
+}
+const queued = (row) => isRecord(row.attachment) && row.attachment.type === 'queued_command' ? row.attachment : null;
+function textNotification(row) {
+    const attachment = queued(row);
+    const origin = attachment?.origin ?? row.origin;
+    if (!isRecord(origin) || origin.kind !== 'task-notification')
+        return null;
+    if (row.type !== 'user' && row.type !== 'attachment')
+        return null;
+    const text = textOf(attachment?.value ?? contentOf(row));
+    return text === null ? null : notificationTags(text.trim());
+}
+function notificationOf(agent, tool, status, reason) {
+    const state = terminal(status, reason);
+    if (!nativeToken(agent) || state === null)
+        return null;
+    if (tool != null && !nativeToken(tool))
+        return null;
+    return { agent, state, tool: nativeToken(tool) ? tool : null };
+}
+function notificationTags(text) {
+    const open = '<task-notification>';
+    const close = '</task-notification>';
+    if (!text.startsWith(open) || !text.endsWith(close))
+        return null;
+    if (text.includes(open, 1) || text.indexOf(close) !== text.length - close.length)
+        return null;
+    const fields = ['task-id', 'tool-use-id', 'status', 'reason'].map((name) => tag(text, name));
+    if (fields.some((field) => field === undefined))
+        return null;
+    return notificationOf(fields[0], fields[1], fields[2], fields[3]);
+}
+function notification(row) {
+    if (row.type !== 'system' || row.subtype !== 'task_notification')
+        return textNotification(row);
+    return notificationOf(row.task_id, row.tool_use_id, row.status, row.reason);
+}
+function ackOf(block, base) {
+    if (block.type !== 'text' || typeof block.text !== 'string')
+        return null;
+    const match = /^METRO_RECOVERY_ACK ([a-f0-9]{64})$/.exec(block.text.trim());
+    return nativeId(match?.[1]) ? { ...base, type: 'ack', id: match[1] } : null;
+}
+function callOf(block, base) {
+    if (block.type !== 'tool_use' || !nativeToken(block.id))
+        return null;
+    return block.name === 'Agent' || block.name === 'SendMessage' ? { ...base, type: 'call', tool: block.id, kind: block.name } : null;
+}
+const rootAssistant = (row, base) => base.source === null && row.aborted !== true && row.parent_tool_use_id == null && row.parent_agent_id == null;
+function blockEvent(block, row, base, single) {
+    if (!isRecord(block))
+        return null;
+    if (row.type === 'assistant') {
+        const ack = rootAssistant(row, base) ? ackOf(block, base) : null;
+        return ack ?? callOf(block, base);
+    }
+    if (row.type !== 'user' || block.type !== 'tool_result' || !nativeToken(block.tool_use_id))
+        return null;
+    return { ...base, type: 'result', tool: block.tool_use_id, failed: block.is_error === true, outcome: resultOf(single ? row.toolUseResult : null) ?? resultOf(block.content) };
+}
+const sidechain = (row, source) => source === null && (row.isSidechain === true || typeof row.agentId === 'string');
+function eventsOf(row, source) {
+    if (sidechain(row, source))
+        return [];
+    const at = typeof row.timestamp === 'string' ? Date.parse(row.timestamp) : NaN;
+    if (!Number.isSafeInteger(at) || at < 0 || !nativeToken(row.uuid))
+        return [];
+    const base = { source, at, receipt: row.uuid };
+    const end = notification(row);
+    if (end !== null)
+        return [{ ...base, type: 'notification', ...end }];
+    const content = contentOf(row);
+    const blocks = typeof content === 'string' ? [{ type: 'text', text: content }] : Array.isArray(content) ? content : [];
+    return blocks.flatMap((block) => { const event = blockEvent(block, row, base, blocks.length === 1); return event === null ? [] : [event]; });
+}
+function resultChild(kind, outcome) {
+    if (kind === 'Agent' && (outcome.status === 'async_launched' || outcome.status === 'completed'))
+        return nativeToken(outcome.agentId) ? outcome.agentId : null;
+    return kind === 'SendMessage' && outcome.success === true && nativeToken(outcome.resumedAgentId) ? outcome.resumedAgentId : null;
+}
+function childOf(event, calls) {
+    if (event.type === 'ack')
+        return null;
+    const key = `${event.source ?? ''}/${event.tool ?? ''}`;
+    if (event.type === 'call')
+        calls.set(key, event.kind);
+    if (event.type === 'notification')
+        return calls.has(key) ? event.agent : null;
+    if (event.type !== 'result' || event.failed || event.outcome === null)
+        return null;
+    return resultChild(calls.get(key), event.outcome);
+}
+function missingEnvelope(row) {
+    const message = row.type === 'assistant' || row.type === 'user' || row.type === 'attachment' || row.subtype === 'task_notification';
+    if (!message)
+        return false;
+    return !nativeToken(row.uuid) || typeof row.timestamp !== 'string' || !Number.isSafeInteger(Date.parse(row.timestamp));
+}
+function rowsOf(read, agent, owner) {
+    const events = [];
+    for (const row of read.rows) {
+        if (!isRecord(row)) {
+            read.incomplete = true;
+            continue;
+        }
+        if (agent === null && typeof row.sessionId === 'string' && row.sessionId !== owner) {
+            read.incomplete = true;
+            continue;
+        }
+        read.incomplete ||= missingEnvelope(row);
+        events.push(...eventsOf(row, agent));
+    }
+    return events;
+}
+function discover(context, event, index) {
+    const child = childOf(event, context.calls);
+    if (child === null || context.pending.includes(child))
+        return;
+    if (context.files.size >= NATIVE_CURSOR_MAX) {
+        context.scan.gaps.push('file-capacity');
+        return;
+    }
+    context.files.set(child, { agent: child, offset: 0 });
+    context.pending.splice(index + 1, 0, child);
+}
+function scanFile(context, agent, index) {
+    const { root, owner, files, scan } = context;
+    const before = files.get(agent)?.offset ?? 0;
+    const path = agent === null ? join(root, `${owner}.jsonl`) : join(root, owner, 'subagents', `agent-${agent}.jsonl`);
+    files.delete(agent);
+    try {
+        const read = readRows(path, before);
+        const events = rowsOf(read, agent, owner);
+        files.set(agent, { agent, offset: read.offset });
+        if (read.incomplete)
+            scan.gaps.push(`${agent ?? 'root'}:${String(before)}`);
+        for (const event of events) {
+            discover(context, event, index);
+            if (scan.events.length < RECORD_MAX)
+                scan.events.push(event);
+            else
+                scan.gaps.push('event-capacity');
+        }
+    }
+    catch {
+        scan.gaps.push(`${agent ?? 'root'}:${String(before)}`);
+        files.set(agent, { agent, offset: before });
+    }
+}
+export function scanNative(root, owner, previous, knownCalls) {
+    const pending = [null, ...previous.flatMap((file) => file.agent === null ? [] : [file.agent])];
+    const files = new Map(previous.map((file) => [file.agent, file]));
+    const calls = new Map(knownCalls.map((call) => [`${call.source ?? ''}/${call.tool}`, call.kind]));
+    const scan = { events: [], files: [], gaps: [] };
+    const context = { root, owner, calls, pending, files, scan };
+    for (let i = 0; i < pending.length && i < NATIVE_FILE_MAX; i += 1)
+        scanFile(context, pending[i] ?? null, i);
+    if (pending.length > NATIVE_FILE_MAX)
+        scan.gaps.push('file-budget');
+    scan.files = [...files.values()];
+    scan.gaps = [...new Set(scan.gaps)];
+    scan.events.sort((a, b) => a.at - b.at);
+    return scan;
+}

package/dist/native-recovery-state.js

@@ -0,0 +1,154 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, opendirSync, openSync, readSync, renameSync, rmdirSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { isRecord, processAlive } from './background.js';
+export const NATIVE_TASK_MAX = 256;
+export const NATIVE_FILE_MAX = 16;
+export const NATIVE_CURSOR_MAX = 256;
+export const NATIVE_NOTICE_MAX = 512;
+export const NATIVE_STATE_BYTES = 512 * 1024;
+export const nativeToken = (value) => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value);
+export const nativeId = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const integer = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+const nullable = (value, valid) => value === null || valid(value);
+const keys = (value, fields) => Object.keys(value).length === fields.length && fields.every((key) => Object.hasOwn(value, key));
+const statuses = new Set(['started', 'completed', 'failed', 'stopped', 'restarted']);
+const reasons = new Set(['interrupted', 'failed', 'restarted', 'incomplete']);
+function taskFields(value) {
+    return nullable(value.source, nativeToken) && nativeToken(value.tool) && (value.kind === 'Agent' || value.kind === 'SendMessage')
+        && nullable(value.agent, nativeToken) && statuses.has(value.state) && nativeToken(value.receipt);
+}
+function task(value) {
+    return isRecord(value) && keys(value, ['id', 'source', 'tool', 'kind', 'agent', 'at', 'updatedAt', 'state', 'receipt']) && nativeId(value.id)
+        && integer(value.at) && integer(value.updatedAt) && value.updatedAt >= value.at && taskFields(value);
+}
+function noticeTimes(value) {
+    if (!nullable(value.deliveredAt, integer) || !nullable(value.acknowledgedAt, integer))
+        return false;
+    if (value.attempts === 0)
+        return value.deliveredAt === null && value.acknowledgedAt === null;
+    if (typeof value.deliveredAt !== 'number')
+        return false;
+    return value.acknowledgedAt === null || (typeof value.acknowledgedAt === 'number' && value.acknowledgedAt >= value.deliveredAt);
+}
+function notice(value) {
+    return isRecord(value) && keys(value, ['id', 'task', 'reason', 'attempts', 'deliveredAt', 'acknowledgedAt']) && nativeId(value.id)
+        && nullable(value.task, nativeId) && reasons.has(value.reason) && integer(value.attempts) && value.attempts <= 3 && noticeTimes(value);
+}
+function cursor(value) {
+    return isRecord(value) && keys(value, ['agent', 'offset']) && nullable(value.agent, nativeToken) && integer(value.offset);
+}
+function rows(value, max, valid, key) {
+    return Array.isArray(value) && value.length <= max && value.every(valid) && new Set(value.map(key)).size === value.length;
+}
+function validState(value, owner) {
+    if (!isRecord(value) || !keys(value, ['version', 'owner', 'tasks', 'notices', 'files']) || value.version !== 1 || value.owner !== owner)
+        return false;
+    const { tasks, notices, files } = value;
+    return rows(tasks, NATIVE_TASK_MAX, task, (v) => v.id) && rows(notices, NATIVE_NOTICE_MAX, notice, (v) => v.id)
+        && rows(files, NATIVE_CURSOR_MAX, cursor, (v) => v.agent)
+        && notices.every((row) => row.task === null || tasks.some((entry) => entry.id === row.task));
+}
+function readStateBytes(path) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > NATIVE_STATE_BYTES)
+            throw new Error('state exceeds its size bound');
+        const buffer = Buffer.alloc(NATIVE_STATE_BYTES + 1);
+        const count = readSync(fd, buffer, 0, buffer.length, 0);
+        if (count !== stat.size || fstatSync(fd).size !== stat.size)
+            throw new Error('state changed while reading');
+        return buffer.subarray(0, count).toString('utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function readNativeState(path, owner) {
+    try {
+        const raw = JSON.parse(readStateBytes(path));
+        if (!validState(raw, owner))
+            throw new Error('state does not match its schema');
+        return raw;
+    }
+    catch (err) {
+        if (isRecord(err) && err.code === 'ENOENT')
+            return { version: 1, owner, tasks: [], notices: [], files: [] };
+        throw new Error('Native recovery state cannot be read safely. Restore it before resuming; it has not been overwritten.', { cause: err });
+    }
+}
+function retireLock(path) {
+    if (!lstatSync(path).isDirectory())
+        throw new Error('Native recovery lock is not a directory');
+    const dir = opendirSync(path);
+    let name;
+    try {
+        name = dir.readSync()?.name;
+        if (dir.readSync() !== null)
+            throw new Error('Native recovery lock has unexpected entries');
+    }
+    finally {
+        dir.closeSync();
+    }
+    const pid = /^(\d{1,10})-[a-f0-9-]{36}$/.exec(name ?? '')?.[1];
+    if (pid === undefined || Number(pid) < 1 || processAlive(Number(pid)))
+        throw new Error('Native recovery preparation is locked. Restore an unreadable lock before resuming.');
+    unlinkSync(join(path, name ?? ''));
+    rmdirSync(path);
+}
+export function withNativeStateLock(path, work) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const lock = `${path}.lock`;
+    try {
+        mkdirSync(lock, { mode: 0o700 });
+    }
+    catch (err) {
+        if (!isRecord(err) || err.code !== 'EEXIST')
+            throw err;
+        retireLock(lock);
+        mkdirSync(lock, { mode: 0o700 });
+    }
+    const owner = join(lock, `${String(process.pid)}-${randomUUID()}`);
+    writeFileSync(owner, '', { flag: 'wx', mode: 0o600 });
+    try {
+        return work();
+    }
+    finally {
+        unlinkSync(owner);
+        rmdirSync(lock);
+    }
+}
+function syncDirectory(path) {
+    if (process.platform === 'win32')
+        return;
+    const fd = openSync(path, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function saveNativeState(path, state) {
+    const text = JSON.stringify(state);
+    if (!validState(state, state.owner) || Buffer.byteLength(text) > NATIVE_STATE_BYTES)
+        throw new Error('Native recovery state exceeds its bounds; it has not been overwritten.');
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${randomUUID()}.tmp`;
+    try {
+        const fd = openSync(tmp, 'wx', 0o600);
+        try {
+            writeFileSync(fd, text);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, path);
+        syncDirectory(dirname(path));
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}

package/dist/native-recovery.js

@@ -0,0 +1,164 @@
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { claudeDir, projectDir, resumeSessionId } from './background.js';
+import { scanNative } from './native-recovery-scan.js';
+import { nativeToken, NATIVE_NOTICE_MAX, NATIVE_TASK_MAX, readNativeState, saveNativeState, withNativeStateLock } from './native-recovery-state.js';
+const hash = (...parts) => createHash('sha256').update(JSON.stringify(parts)).digest('hex');
+const taskId = (owner, source, tool) => hash(owner, source ?? '', tool);
+const RETRY_MS = [0, 60_000, 10 * 60_000];
+const PROMPT_NOTICES = 8;
+const taskReason = (task) => task.state === 'started' ? 'interrupted' : task.state === 'failed' ? 'failed' : task.state === 'restarted' ? 'restarted' : null;
+function agentResult(task, outcome) {
+    if (nativeToken(outcome.agentId))
+        task.agent = outcome.agentId;
+    if (outcome.status === 'completed')
+        task.state = 'completed';
+    else if (outcome.status === 'async_launched')
+        task.state = 'started';
+}
+function messageResult(task, outcome) {
+    if (outcome.success === true && nativeToken(outcome.resumedAgentId)) {
+        task.agent = outcome.resumedAgentId;
+        task.state = 'started';
+    }
+    else if (outcome.success === true && outcome.resumedAgentId === undefined)
+        task.state = 'completed';
+    else if (outcome.success === false)
+        task.state = 'failed';
+}
+function result(task, event) {
+    if (event.at < task.updatedAt || event.receipt === task.receipt)
+        return;
+    if (event.failed)
+        task.state = 'failed';
+    else if (event.outcome !== null) {
+        if (task.kind === 'Agent')
+            agentResult(task, event.outcome);
+        else
+            messageResult(task, event.outcome);
+    }
+    task.receipt = event.receipt;
+    task.updatedAt = event.at;
+}
+function acknowledge(state, event) {
+    const notice = state.notices.find((row) => row.id === event.id);
+    if (notice !== undefined && notice.deliveredAt !== null && event.at >= notice.deliveredAt)
+        notice.acknowledgedAt = event.at;
+}
+function notification(state, event) {
+    const candidates = state.tasks.filter((row) => row.source === event.source && row.at <= event.at
+        && (event.tool === null ? row.agent === event.agent : row.tool === event.tool && (row.agent === null || row.agent === event.agent)));
+    if (candidates.length > 1)
+        return false;
+    const task = candidates[0];
+    if (task !== undefined && event.at >= task.updatedAt) {
+        task.agent = event.agent;
+        task.state = event.state;
+        task.receipt = event.receipt;
+        task.updatedAt = event.at;
+    }
+    return true;
+}
+function applyEvent(state, event) {
+    if (event.type === 'ack') {
+        acknowledge(state, event);
+        return true;
+    }
+    if (event.type === 'notification')
+        return notification(state, event);
+    const id = taskId(state.owner, event.source, event.tool);
+    const task = state.tasks.find((row) => row.id === id);
+    if (event.type === 'result') {
+        if (task !== undefined)
+            result(task, event);
+        return true;
+    }
+    if (task !== undefined)
+        return true;
+    if (state.tasks.length >= NATIVE_TASK_MAX)
+        prune(state);
+    if (state.tasks.length >= NATIVE_TASK_MAX)
+        return false;
+    state.tasks.push({ id, source: event.source, tool: event.tool, kind: event.kind, agent: null, at: event.at, updatedAt: event.at, state: 'started', receipt: event.receipt });
+    return true;
+}
+function addNotice(state, task, reason, gap = 'incomplete') {
+    const id = hash(state.owner, task?.id ?? 'scan', task?.receipt ?? gap, reason);
+    if (state.notices.some((row) => row.id === id))
+        return;
+    if (state.notices.length >= NATIVE_NOTICE_MAX)
+        throw new Error('Native recovery has too many retained notices. Saved state has not been overwritten.');
+    state.notices.push({ id, task: task?.id ?? null, reason, attempts: 0, deliveredAt: null, acknowledgedAt: null });
+}
+function prune(state) {
+    const pending = new Set(state.notices.filter((row) => row.acknowledgedAt === null).map((row) => row.task));
+    const acknowledged = new Set(state.notices.filter((row) => row.acknowledgedAt !== null).map((row) => row.id));
+    const removable = state.tasks.filter((row) => !pending.has(row.id) && (taskReason(row) === null || acknowledged.has(hash(state.owner, row.id, row.receipt, taskReason(row) ?? ''))))
+        .sort((a, b) => a.updatedAt - b.updatedAt);
+    const removed = new Set(removable.slice(0, Math.max(0, state.tasks.length - NATIVE_TASK_MAX / 2)).map((row) => row.id));
+    state.tasks = state.tasks.filter((row) => !removed.has(row.id));
+    state.notices = state.notices.filter((row) => row.task === null || !removed.has(row.task));
+}
+function noticeLine(state, notice) {
+    const task = state.tasks.find((row) => row.id === notice.task);
+    const subject = task === undefined ? 'Native task history' : `${task.kind} receipt ${task.tool}${task.agent === null ? '' : `, worker ${task.agent}`}`;
+    const facts = {
+        interrupted: 'has no terminal receipt. Work may have run before interruption; its outcome is unknown.',
+        failed: 'reported failure. Earlier side effects may already have happened.',
+        restarted: 'was stopped by worker restart, not explicit user cancellation.',
+        incomplete: 'could not be fully checked within the bounded local scan. Other unfinished work may exist.',
+    };
+    return `${subject} ${facts[notice.reason]}\nAfter taking responsibility for this notice, emit a standalone assistant text block exactly: METRO_RECOVERY_ACK ${notice.id}`;
+}
+function promptFor(state, notices) {
+    return [
+        'Metro native recovery notice. This is recovery bookkeeping, not a new user task or permission to repeat actions.',
+        `Owner conversation: ${state.owner}. Native worker routing may have lost ownership metadata; this notice does not repair it.`,
+        'Review the affected work and current evidence, using a read-only worker if needed. Do not blindly rerun a task, resend a message, or repeat another side effect. Acknowledge awareness only; acknowledgment is not proof of successful completion. Do not post these bookkeeping markers to chat.',
+        ...notices.map((notice) => noticeLine(state, notice)),
+    ].join('\n\n');
+}
+function prepare(state, root) {
+    const scan = scanNative(root, state.owner, state.files, state.tasks);
+    prune(state);
+    for (const event of scan.events)
+        if (!applyEvent(state, event))
+            scan.gaps.push('unresolved-receipts');
+    state.files = scan.files;
+    for (const task of state.tasks) {
+        const reason = taskReason(task);
+        if (reason !== null)
+            addNotice(state, task, reason);
+    }
+    for (const gap of scan.gaps)
+        addNotice(state, null, 'incomplete', gap);
+}
+function isDue(notice, now) {
+    return notice.acknowledgedAt === null && notice.attempts < RETRY_MS.length
+        && (notice.deliveredAt === null || now - notice.deliveredAt >= (RETRY_MS[notice.attempts] ?? Infinity));
+}
+function locations(owner, deps) {
+    const env = deps.env ?? process.env;
+    const given = env.HOME?.trim();
+    const home = resolve(given === '' ? homedir() : given ?? homedir());
+    return { path: join(home, '.metro', 'native-recovery', `${owner}.json`), root: projectDir(claudeDir(env), deps.cwd ?? process.cwd()) };
+}
+export function nativeRecoveryArgs(extra, deps = {}) {
+    const owner = resumeSessionId(extra);
+    if (extra.length !== 2 || owner === undefined || (extra[0] !== '--resume' && extra[0] !== '-r'))
+        return extra;
+    const { path, root } = locations(owner, deps);
+    return withNativeStateLock(path, () => {
+        const state = readNativeState(path, owner);
+        prepare(state, root);
+        const now = deps.now ?? Date.now();
+        const due = state.notices.filter((row) => isDue(row, now)).slice(0, PROMPT_NOTICES);
+        for (const notice of due) {
+            notice.attempts += 1;
+            notice.deliveredAt = now;
+        }
+        saveNativeState(path, state);
+        return due.length === 0 ? extra : [...extra, promptFor(state, due)];
+    });
+}

package/dist/node-name.js

@@ -0,0 +1,71 @@
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentsDir } from './local.js';
+const NODE_FILE = '.node';
+const ALPHABET = 'abcdefghjkmnpqrstuvwxyz23456789';
+const NAME_RE = /^metro-[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
+const RENAME_WAIT_MS = 30_000;
+const RENAME_POLL_MS = 500;
+const renameWaitMs = () => Number(process.env.METRO_NODE_RENAME_WAIT_MS) || RENAME_WAIT_MS;
+const pause = (ms) => {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+const stderrLine = (line) => {
+    process.stderr.write(`${line}\n`);
+};
+export function newNodeName() {
+    const bytes = randomBytes(6);
+    return `metro-${[...bytes].map((b) => ALPHABET[b % ALPHABET.length] ?? 'x').join('')}`;
+}
+export function nodeName(dir = agentsDir()) {
+    const path = join(dir, NODE_FILE);
+    if (existsSync(path)) {
+        const held = readFileSync(path, 'utf8').trim();
+        if (NAME_RE.test(held))
+            return held;
+    }
+    const name = newNodeName();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${name}\n`, { mode: 0o600 });
+    return name;
+}
+export function currentNodeLabel(bin) {
+    const run = spawnSync(bin, ['status', '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    if (run.error !== undefined || run.status !== 0)
+        return null;
+    try {
+        const parsed = JSON.parse(run.stdout);
+        const dns = typeof parsed.Self?.DNSName === 'string' ? parsed.Self.DNSName : '';
+        const label = dns.split('.')[0] ?? '';
+        return label === '' ? null : label.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+function awaitRename(bin, wanted, warn) {
+    const wait = renameWaitMs();
+    const until = Date.now() + wait;
+    while (Date.now() < until) {
+        if (currentNodeLabel(bin) === wanted)
+            return;
+        pause(RENAME_POLL_MS);
+    }
+    warn(`tailscale still reports the old machine name after ${String(Math.round(wait / 1000))}s; the Funnel address may come up under it until the next restart`);
+}
+export function ensureNodeName(bin, dir = agentsDir(), warn = stderrLine) {
+    const wanted = nodeName(dir);
+    if (currentNodeLabel(bin) === wanted)
+        return wanted;
+    const run = spawnSync(bin, ['set', '--hostname', wanted], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    if (run.error !== undefined || run.status !== 0) {
+        const said = run.stderr.trim();
+        const reason = said === '' ? (run.error?.message ?? `exit ${String(run.status)}`) : said;
+        throw new Error(`could not name this machine ${wanted} on your tailnet (${reason}).\n` +
+            `Run it once yourself, then start again:  sudo tailscale set --hostname ${wanted}`);
+    }
+    awaitRename(bin, wanted, warn);
+    return wanted;
+}

package/dist/onboarding.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const FILE = '.claude.json';
+const FLAG = 'hasCompletedOnboarding';
+const given = (value) => value !== undefined && value.trim() !== '' ? value.trim() : undefined;
+export function claudeConfigPath(env = process.env) {
+    return join(given(env.CLAUDE_CONFIG_DIR) ?? given(env.HOME) ?? homedir(), FILE);
+}
+function readConfig(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function markOnboardingDone(path = claudeConfigPath()) {
+    const config = readConfig(path);
+    if (config === null)
+        return 'unreadable';
+    if (config[FLAG] === true)
+        return 'already';
+    writeFileSync(path, `${JSON.stringify({ ...config, [FLAG]: true }, null, 2)}\n`, { mode: 0o600 });
+    return 'marked';
+}
+const FEATURES = 'cachedGrowthBookFeatures';
+const CHANNEL_FLAGS = ['tengu_harbor', 'tengu_harbor_permissions'];
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export function seedChannels(path = claudeConfigPath()) {
+    const config = readConfig(path);
+    if (config === null)
+        return 'unreadable';
+    const features = isRecord(config[FEATURES]) ? config[FEATURES] : {};
+    if (CHANNEL_FLAGS.every((flag) => features[flag] === true))
+        return 'already';
+    const seeded = Object.fromEntries(CHANNEL_FLAGS.map((flag) => [flag, true]));
+    const next = { ...config, [FEATURES]: { ...features, ...seeded } };
+    writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    return 'marked';
+}