termdock 1.4.309 → 1.4.311

package/dist/server/agent/collaborationTmuxDelivery.js

@@ -1,5 +1,5 @@
 import { plainCollaborationSnapshot } from './collaborationText.js';
-import { normalizePromptForPaste } from './promptDelivery.js';
+import { normalizePromptForPaste, waitForPromptSubmit } from './promptDelivery.js';
 const TMUX_KEY_NAMES = {
     enter: 'Enter', escape: 'Escape', space: 'Space', left: 'Left', right: 'Right', up: 'Up', down: 'Down',
 };
@@ -19,26 +19,9 @@ const APPROVAL_DIALOG_PATTERNS = [
     /\b1\.\s*是\b/,
     /允许.*执行|确认.*执行/i,
 ];
-/** Agent TUIs collapse pasted input in the input box to a marker line like
- * "[Pasted text #3 +42 lines]". While the paste sits unsubmitted the marker
- * stays on screen; a submitted paste clears the box and only the transcript
- * holds the content. Session-unique #N lets us diff screen captures. */
-const PASTE_MARKER_PATTERN = /\[Pasted text #(\d+)/g;
 export function detectApprovalDialog(content) {
     return APPROVAL_DIALOG_PATTERNS.some((pattern) => pattern.test(content));
 }
-/** Paste marker sequence numbers visible in a screen capture. */
-export function extractPasteMarkerNumbers(content) {
-    return new Set([...content.matchAll(PASTE_MARKER_PATTERN)].map((match) => Number(match[1])));
-}
-/** True when `after` shows a paste marker that was not in `before`. Diffing
- * prevents a recovery Enter from submitting a stale paste that predates this
- * delivery (or someone else's draft): we only ever submit what we just put
- * there, at most once per delivery. */
-export function hasNewPasteMarker(after, before) {
-    const beforeNumbers = extractPasteMarkerNumbers(before);
-    return [...extractPasteMarkerNumbers(after)].some((number) => !beforeNumbers.has(number));
-}
 async function assertSamePane(run, pane) {
     const identity = (await run(['display-message', '-p', '-t', pane.paneId,
         '#{pid}:#{session_id}:#{pane_id}:#{pane_pid}'])).trim();
@@ -48,15 +31,19 @@ async function assertSamePane(run, pane) {
 /** Unique-per-process buffer name so concurrent deliveries to different panes
  *  never share (or clobber) a buffer. */
 let bufferSequence = 0;
-export async function writeCollaborationTmuxPane(run, pane, prompt, 
-/** Sends `input` to the tmux client's stdin. The steps below are one `\;`
- *  chain (see the comment inside), and a chain is argv, so the body must not
- *  ride in argv: tmux treats an element that is exactly `;` as a separator
- *  even after `--`, and its backslash unescaping is version-dependent
- *  (`\\` survives verbatim while `\;` collapses to `;`). Reading the body
- *  from stdin sidesteps both — every byte round-trips unchanged. Required,
- *  not optional: a run() that ignored the payload would load an empty buffer
- *  and fail the delivery rather than deliver the wrong thing. */
+const paneWrites = new Map();
+/** Serialize TD paste/submit pairs for this exact runtime pane. */
+export function writeCollaborationTmuxPane(run, pane, prompt, stdin) {
+    const key = `${pane.serverPid}:${pane.sessionId}:${pane.paneId}:${pane.panePid}`;
+    const previous = paneWrites.get(key) ?? Promise.resolve();
+    const operation = previous.catch(() => undefined).then(() => writeTmuxPrompt(run, pane, prompt, stdin))
+        .finally(() => { if (paneWrites.get(key) === operation)
+        paneWrites.delete(key); });
+    paneWrites.set(key, operation);
+    return operation;
+}
+async function writeTmuxPrompt(run, pane, prompt, 
+/** Body travels on stdin so tmux cannot parse its semicolons/backslashes. */
 stdin) {
     await assertSamePane(run, pane);
     // A fixed pane target is independent of the current window, keyboard focus
@@ -77,13 +64,8 @@ stdin) {
     // every tmux version.
     const buffer = `termdock-collab-${process.pid}-${bufferSequence++}`;
     try {
-        // The four steps ride one client invocation joined by tmux's `\;`: the
-        // server runs them back to back in a single queue item, so no other
-        // client's paste can interleave between our text and our submit CR
-        // (measured: one contiguous block, 0ms apart, versus two invocations
-        // ~14ms apart). A failing step stops the rest — verified on 3.4 and 3.7 —
-        // which is the safe direction: a failed text paste is never followed by a
-        // bare CR into whatever the input box already held.
+        // Paste once, then send one unbracketed CR after 50ms. No screen parsing,
+        // Agent-specific recovery, consumption confirmation or additional Enter.
         await stdin([
             // The body arrives on stdin, not argv: it is user content, and in a
             // `\;` chain argv is a language where `;` and `\` mean something.
@@ -91,13 +73,17 @@ stdin) {
             // -r keeps LF as LF rather than the separator default of CR. The
             // normalizer already folded every line break to CR, so no LF is left
             // for it to rewrite — the flag is insurance, not the mechanism.
-            'paste-buffer', '-p', '-r', '-d', '-b', buffer, '-t', pane.paneId, ';',
+            'paste-buffer', '-p', '-r', '-d', '-b', buffer, '-t', pane.paneId,
+        ], normalizePromptForPaste(prompt));
+        await waitForPromptSubmit();
+        await assertSamePane(run, pane);
+        await run([
             // The submit key rides outside the paste block: inside it, an editor
             // inserts a pasted CR as text instead of acting on it. Pasting the bare
             // CR (no -p) keeps the key in the same mode-proof channel as the text.
             'set-buffer', '-b', buffer, '--', '\r', ';',
             'paste-buffer', '-d', '-b', buffer, '-t', pane.paneId,
-        ], normalizePromptForPaste(prompt));
+        ]);
     }
     finally {
         // -d consumed the buffer on the happy path; this sweeps up after a failed
@@ -139,21 +125,7 @@ export async function approveCollaborationDialog(run, pane) {
     await sendTmuxPaneKey(run, pane, 'enter');
     return true;
 }
-/** Submit a paste that arrived while the agent was finishing its previous
- *  turn and is still sitting unsubmitted in the input box. Only acts on
- *  differential evidence — a paste marker that appeared after the write —
- *  never on pre-existing stale markers, and returns whether Enter was sent.
- *  Committing the whole input buffer is safe: each delivery is written once,
- *  so each marker's content enters the transcript exactly once. */
-export async function recoverStuckPaste(run, pane, baseline) {
-    const viewport = await captureTmuxPaneText(run, pane);
-    if (!hasNewPasteMarker(viewport, baseline))
-        return false;
-    await sendTmuxPaneKey(run, pane, 'enter');
-    return true;
-}
-/** History-inclusive pane text (scrollback + viewport) used to confirm a
- *  delivery was actually rendered by the agent, not wiped by a boot clear. */
+/** History-inclusive terminal observation, without inferring consumption. */
 export async function captureTmuxPaneHistory(run, pane, lines = 800, rawOutput = false) {
     await assertSamePane(run, pane);
     if (!Number.isInteger(lines) || lines < 1 || lines > 10000)

package/dist/server/agent/integrationCli.js

@@ -8,6 +8,17 @@ import { COLLAB_HELP, executeCollaborationCommand, duration } from './collaborat
 import { getTermdockVersion } from '../utils/version.js';
 export const INTEGRATION_HELP = `td integration — local scoped integration administration
   groups | list
+  clear-startup-input <TD-session-id> --generation <N>
+    Administrator removes this session's saved screen conditions and disables
+    inheritance on later restores; original identity/launch/history are preserved.
+    Pending messages may then use the ordinary delivery worker; delivered bodies
+    are never replayed. No Agent restart, resize, RPC or readiness claim.
+    The generation increments once; read session get for the new generation and
+    startup_input_disabled=true. Repeating with the old generation is rejected.
+    Minimum CLI/running service 1.4.310; session_startup_input_clear=true.
+    Errors: SESSION_STARTUP_INPUT_CLEAR_UNSUPPORTED, INVALID_SESSION_GENERATION,
+    SESSION_GENERATION_MISMATCH, SESSION_OPERATION_IN_PROGRESS,
+    INTEGRATION_SESSION_NOT_FOUND. Profile policy update alone keeps old snapshots.
   resume-configuration <TD-session-id> (read current/recorded fingerprints; no mutation)
   confirm-resume <TD-session-id> --generation <N> --fingerprint <sha256>
     Administrator explicitly authorizes the current launcher/plugin recovery semantics.
@@ -72,6 +83,18 @@ export async function runIntegrationAdmin(argv, port, adminToken, write) {
             return 0;
         }
         const socketPath = integrationSocketPath(port);
+        if (action === 'clear-startup-input') {
+            const id = argv[1];
+            if (argv.length !== 4 || !id || !/^[a-zA-Z0-9._-]{1,80}$/.test(id) || argv[2] !== '--generation'
+                || !/^[1-9][0-9]*$/.test(argv[3]) || !Number.isSafeInteger(Number(argv[3]))) {
+                throw new Error('Usage: td integration clear-startup-input <TD-session-id> --generation <positive integer>');
+            }
+            const capabilities = parsed(await request(socketPath, 'GET', '/admin/capabilities', undefined, headers(undefined, adminToken)));
+            if (capabilities.session_startup_input_clear !== true)
+                throw new CollaborationError('SESSION_STARTUP_INPUT_CLEAR_UNSUPPORTED', 'CLI and running service must be at least 1.4.310', 409);
+            write(JSON.stringify(parsed(await request(socketPath, 'POST', `/admin/sessions/${encodeURIComponent(id)}/startup-input/clear`, { generation: Number(argv[3]) }, headers(undefined, adminToken)))));
+            return 0;
+        }
         if (action === 'resume-configuration' || action === 'confirm-resume') {
             const id = argv[1];
             if (!id || !/^[a-zA-Z0-9._-]{1,80}$/.test(id))

package/dist/server/agent/integrationServer.js

@@ -73,6 +73,12 @@ export class IntegrationRuntime {
         app.get('/admin/sessions/:id/restore-diagnostics', run(req => { admin(req); return this.sessions.restoreDiagnostics(req.params.id); }));
         app.get('/admin/sessions/:id/resume-configuration', run(async (req) => { admin(req); return this.sessions.resumeConfiguration(req.params.id); }));
         app.post('/admin/sessions/:id/resume-configuration', run(async (req) => { admin(req); return { session: publicIntegrationSession(await this.sessions.confirmResumeConfiguration(req.params.id, req.body?.generation, req.body?.fingerprint)) }; }));
+        app.post('/admin/sessions/:id/startup-input/clear', run(async (req) => {
+            admin(req);
+            const session = await this.sessions.clearStartupInput(req.params.id, req.body?.generation);
+            this.sync();
+            return { session: publicIntegrationSession(session) };
+        }));
         app.get('/admin/principals', run(req => { admin(req); return { integrations: this.store.policies() }; }));
         app.post('/admin/principals', run(req => { admin(req); this.group(req.body?.groupId); const provisioned = this.store.provision(req.body); try {
             this.sync();
@@ -217,6 +223,7 @@ export class IntegrationRuntime {
             idempotent_session_create: true, exact_session_restore: true, external_validation: false,
             startup_input_conditions: true, session_runtime_release: true, stable_session_identity: true, session_lifecycle_generation: true,
             session_resume_configuration: true, session_lifecycle_min_version: '1.4.309',
+            session_startup_input_clear: true, session_startup_input_clear_min_version: '1.4.310',
             integration_policy_update: true,
             session_restore_diagnostics: true,
             native_identity_linux_flock_owner: process.platform === 'linux',

package/dist/server/agent/integrationSessions.js

@@ -14,6 +14,8 @@ export function integrationLaunchCommand(record, restore) {
     return `cd -- ${quote(record.cwd)} && ${[record.profile.executable, ...args].map(quote).join(' ')}`;
 }
 function startupInput(record, now) {
+    if (record.startup_input_disabled)
+        return undefined;
     const condition = record.startup_condition ?? record.profile.startupInput;
     return condition ? { state: 'pending', deadline: now + (condition.timeoutMs ?? 120000), matched_since: null, observed_at: null } : undefined;
 }
@@ -308,7 +310,7 @@ export class IntegrationSessions {
             record.deadline = Date.now() + this.bindingTimeout;
             record.updated_at = Date.now();
             record.restore_diagnostics = undefined;
-            if (!record.profile.startupInput && !record.startup_condition)
+            if (!record.startup_input_disabled && !record.profile.startupInput && !record.startup_condition)
                 record.startup_condition = structuredClone(principal.launchProfiles.find(profile => profile.id === record.launch_profile)?.startupInput);
             record.startup_input = startupInput(record, Date.now());
             this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id, operationId: record.operation_id, generation: record.generation };
@@ -332,6 +334,27 @@ export class IntegrationSessions {
         return { session_id: id, generation: record.generation ?? 1, recorded_fingerprint: record.resume_configuration_fingerprint ?? null,
             current_fingerprint: await resumeConfigurationFingerprint(record, this.adapter), confirmation_required: !record.resume_configuration_fingerprint };
     }
+    async clearStartupInput(id, generation) {
+        return this.lifecycle.run(id, async () => {
+            const record = structuredClone(this.doc.sessions.find(s => s.session_id === id));
+            if (!record)
+                return integrationError('INTEGRATION_SESSION_NOT_FOUND', 'Recovery record does not exist', 404);
+            assertReleaseGeneration(record, generation);
+            if (this.pending.has(id) || record.operation_uncertain || ['starting', 'restoring', 'binding_pending', 'releasing'].includes(record.state)) {
+                integrationError('SESSION_OPERATION_IN_PROGRESS', 'Resolve the current lifecycle operation before clearing startup input conditions', 409);
+            }
+            if (record.startup_input_disabled && !record.profile.startupInput && !record.startup_condition && !record.startup_input)
+                return record;
+            delete record.profile.startupInput;
+            delete record.startup_condition;
+            delete record.startup_input;
+            record.startup_input_disabled = true;
+            record.generation = generation + 1;
+            record.updated_at = Date.now();
+            this.saveRecord(record);
+            return record;
+        });
+    }
     async confirmResumeConfiguration(id, generation, fingerprint) {
         return this.lifecycle.run(id, async () => {
             const record = structuredClone(this.doc.sessions.find(s => s.session_id === id));

package/dist/server/agent/promptDelivery.js

@@ -8,13 +8,26 @@
 export function normalizePromptForPaste(prompt) {
     return prompt.replace(/\r\n|\r|\n/g, '\r').replace(/\x1b/g, '␛');
 }
-/**
- * Encode a prompt as one bracketed-paste block followed by one real Enter.
- * Agent TUIs then keep embedded newlines inside the editor instead of treating
- * each line as a separate submission.
- */
-export function buildBracketedSubmitBytes(prompt) {
-    return `\x1b[200~${normalizePromptForPaste(prompt)}\x1b[201~\r`;
+/** Separate the paste and its single unbracketed CR by 50ms. */
+export const PROMPT_SUBMIT_DELAY_MS = 50;
+export function waitForPromptSubmit() {
+    return new Promise((resolve) => setTimeout(resolve, PROMPT_SUBMIT_DELAY_MS));
+}
+export function buildBracketedPasteBytes(prompt) {
+    return `\x1b[200~${normalizePromptForPaste(prompt)}\x1b[201~`;
+}
+const promptWrites = new WeakMap();
+/** Serialize TD prompt pairs per PTY. Success only records terminal writes. */
+export function writeBracketedPrompt(target, prompt) {
+    const previous = promptWrites.get(target) ?? Promise.resolve();
+    const operation = previous.catch(() => undefined).then(async () => {
+        target.write(buildBracketedPasteBytes(prompt));
+        await waitForPromptSubmit();
+        target.write('\r');
+    }).finally(() => { if (promptWrites.get(target) === operation)
+        promptWrites.delete(target); });
+    promptWrites.set(target, operation);
+    return operation;
 }
 /**
  * Process detection and hook events are independent Agent signals. A target is

package/dist/server/agent/sessionLifecycle.js

@@ -33,9 +33,9 @@ export class SessionLifecycleCoordinator {
 }
 export function assertReleaseGeneration(record, generation) {
     if (!Number.isSafeInteger(generation) || Number(generation) < 1)
-        fail('INVALID_SESSION_GENERATION', 'release requires the generation returned by session get');
+        fail('INVALID_SESSION_GENERATION', 'Operation requires the generation returned by session get');
     if (generation !== (record.generation ?? 1))
-        fail('SESSION_GENERATION_MISMATCH', 'Session generation changed; read its current state before releasing');
+        fail('SESSION_GENERATION_MISMATCH', 'Session generation changed; read its current state before retrying');
 }
 export function assertReleaseFacts(record, facts) {
     if (!record.agent_native_session_id)

package/dist/server/architecture/cli.js

@@ -0,0 +1,320 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { updateArchitectureField } from './fieldMutation.js';
+import { ARCHITECTURE_FIELDS, ARCHITECTURE_FILE, analysisFile, architectureSourceDiagram, buildArchitecturePrompt, buildOmmScanPrompt, parseArchitecture } from './document.js';
+import { ArchitectureStore } from './store.js';
+import { parseFlowchart } from './flowchart.js';
+import { diffMermaid } from './mermaidDiff.js';
+import { diffArchitecture } from './documentDiff.js';
+export const ARCHITECTURE_HELP = `Termdock architecture — recursive code architecture documents
+Usage: td architecture <command> [--project <directory>] [--file <map.json>] [--format native|omm]
+  prompt [--language en|zh]         Print the recursive analysis instructions
+  setup [claude|codex|cursor|openclaw|antigravity] [--teardown]
+  init | list | status             Initialize or inspect project maps
+  tree [perspective/element]       Browse the recursive document tree
+  read <element> <field>           Read a field
+  write <element> <field> <text|->  Write a field (stdin with -)
+  show <element>                   Read all fields and metadata
+  delete <element>                 Delete that element and descendants
+  save <json|->                    Validate and atomically save a native map, retaining history
+  validate [element]               Check diagrams, documents and references
+  refs <element>                   Show incoming/outgoing and cross-perspective references
+  diff [element] | history         Show changes and previous versions
+  config language [en|zh|...]       Read/write the .omm content language
+  export [--format omm]            Export native JSON or a portable .omm file bundle
+  import <json|->                  Import a native map or a .omm file bundle
+  view                            Print the native Termdock viewer link
+Fields: description, diagram, context, constraint, concern, todo, note.
+Examples: td architecture prompt --project .
+          td architecture write --format omm overall-architecture/auth description -
+          td architecture save --file .termdock/architecture.json -`;
+function elementPath(view, node) {
+    if (!node)
+        return view.id;
+    if (node.documentPath)
+        return node.documentPath;
+    const parts = [node.id];
+    let parent = node.parentId;
+    while (parent) {
+        parts.unshift(parent);
+        parent = view.nodes.find(item => item.id === parent)?.parentId;
+    }
+    return [view.id, ...parts].join('/');
+}
+function target(document, element) {
+    const [perspective, ...parts] = element.split('/');
+    const view = document.perspectives.find(view => view.id === perspective);
+    if (!view)
+        throw new Error(`Perspective not found: ${perspective}`);
+    let node;
+    for (const [index, part] of parts.entries()) {
+        const id = document.origin === 'omm' ? `e_${createHash('sha256').update([perspective, ...parts.slice(0, index + 1)].join('/')).digest('hex').slice(0, 20)}` : part;
+        const next = view.nodes.find(item => item.id === id && item.parentId === node?.id);
+        if (!next)
+            throw new Error(`Element not found: ${element}`);
+        node = next;
+    }
+    return { view, node, value: node ?? view };
+}
+export async function runArchitectureCli(args, io = { write: value => process.stdout.write(`${value}\n`), stdin: async () => { let text = ''; for await (const chunk of process.stdin) {
+        text += String(chunk);
+        if (text.length > 5_000_000)
+            throw new Error('Input exceeds the architecture limit');
+    } return text; } }) {
+    try {
+        const positional = [], options = {};
+        for (let index = 0; index < args.length; index++) {
+            const arg = args[index];
+            if (['--project', '--file', '--format', '--language'].includes(arg)) {
+                if (!args[index + 1] || args[index + 1].startsWith('--'))
+                    throw new Error(`Missing value for ${arg}`);
+                options[arg.slice(2)] = args[++index];
+            }
+            else if (['--teardown', '--list', '--help'].includes(arg))
+                options[arg.slice(2)] = 'true';
+            else if (arg.startsWith('--'))
+                throw new Error(`Unknown option: ${arg}`);
+            else
+                positional.push(arg);
+        }
+        const [command = 'help', element, field, ...content] = positional;
+        if (command === 'help' || options.help) {
+            io.write(ARCHITECTURE_HELP);
+            return 0;
+        }
+        const root = await fs.realpath(path.resolve(options.project ?? process.cwd()));
+        if (!(await fs.stat(root)).isDirectory())
+            throw new Error('Project root must be a directory');
+        const store = new ArchitectureStore(root);
+        const omm = options.format === 'omm' || options.file === '.omm';
+        if (options.format && !['native', 'omm'].includes(options.format))
+            throw new Error('Format must be native or omm');
+        const file = options.file ?? (omm ? '.omm' : ARCHITECTURE_FILE);
+        const instructions = async () => {
+            const language = options.language ?? (omm ? (await store.config()).language : 'en');
+            return omm ? buildOmmScanPrompt(root, language) : buildArchitecturePrompt(root, language === 'zh' ? 'zh' : 'en');
+        };
+        const input = async (values) => values[0] === '-' ? io.stdin() : values.join(' ');
+        const json = (value) => io.write(JSON.stringify(value, null, 2));
+        if (command === 'prompt' || command === 'scan') {
+            io.write(await instructions());
+            return 0;
+        }
+        if (command === 'setup') {
+            const platforms = { claude: '.claude/skills', codex: '.agents/skills', cursor: '.cursor/skills', openclaw: '.openclaw/skills', antigravity: '.agent/skills' };
+            if (options.list) {
+                json(Object.keys(platforms));
+                return 0;
+            }
+            const selected = element ? [element] : Object.keys(platforms);
+            if (selected.some(platform => !platforms[platform]))
+                throw new Error('Unknown AI platform');
+            const marker = '<!-- Termdock architecture skill -->';
+            for (const platform of selected) {
+                const relative = `${platforms[platform]}/termdock-architecture/SKILL.md`, destination = await store.bounded(relative, true);
+                let existing = '';
+                try {
+                    existing = await fs.readFile(destination, 'utf8');
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                if (existing && !existing.includes(marker))
+                    throw new Error(`Refusing to overwrite an unrelated skill: ${relative}`);
+                if (options.teardown) {
+                    if (existing.includes(marker))
+                        await fs.unlink(destination);
+                    io.write(`Removed ${relative}`);
+                    continue;
+                }
+                const prompt = await instructions();
+                await fs.writeFile(destination, `---\nname: termdock-architecture\ndescription: Recursively analyze or update this project's Termdock code architecture.\n---\n${marker}\n\n${prompt}\n`, { mode: 0o600 });
+                io.write(`Installed ${relative}`);
+            }
+            return 0;
+        }
+        if (command === 'config') {
+            if (element !== 'language')
+                throw new Error('Use config language [code]');
+            json(await store.config(field));
+            return 0;
+        }
+        if (command === 'init') {
+            await store.config();
+            if (omm)
+                await store.config(options.language ?? 'en');
+            io.write('Ready. Use td architecture prompt, or Generate in the Architecture panel.');
+            return 0;
+        }
+        if (command === 'list') {
+            json(await store.list());
+            return 0;
+        }
+        if (command === 'save' || command === 'import') {
+            const raw = await input(positional.slice(1));
+            if (!raw)
+                throw new Error('Supply JSON or - for stdin');
+            const value = JSON.parse(raw);
+            if (value?.format === 'termdock-omm-bundle') {
+                await store.importOmmBundle(value);
+                json(await store.read('.omm'));
+            }
+            else {
+                const document = parseArchitecture(raw);
+                json(await store.save(options.file ?? (document.analysis ? analysisFile(document.analysis) : ARCHITECTURE_FILE), document));
+            }
+            return 0;
+        }
+        if (command === 'export' && omm) {
+            const source = options.file && options.file !== '.omm' ? (await store.read(options.file)).document : undefined;
+            if (source === null)
+                throw new Error('Architecture not found');
+            json(await store.exportOmmBundle(source));
+            return 0;
+        }
+        if (command === 'delete' && omm) {
+            if (!element)
+                throw new Error('Supply an element path');
+            await store.deleteOmmElement(element);
+            io.write(`Deleted ${element}`);
+            return 0;
+        }
+        if (command === 'write' && omm) {
+            if (!element || !ARCHITECTURE_FIELDS.includes(field))
+                throw new Error('Supply an element and valid field');
+            await store.writeOmmField(element, field, await input(content));
+            io.write(`Updated ${element}/${field}`);
+            return 0;
+        }
+        const loaded = await store.read(file), document = loaded.document;
+        if (!document)
+            throw new Error('No saved architecture. Generate one first, or select --format omm.');
+        if (command === 'export') {
+            json(document);
+            return 0;
+        }
+        if (command === 'status') {
+            json({ file, generatedAt: document.generatedAt, meta: document.meta, perspectives: document.perspectives.map(view => ({ id: view.id, nodes: view.nodes.length, edges: view.edges.length })) });
+            return 0;
+        }
+        if (command === 'history') {
+            json(await store.history(file));
+            return 0;
+        }
+        if (command === 'tree' && document.origin === 'omm') {
+            for (const entry of await store.ommElements())
+                if (!element || entry === element || entry.startsWith(`${element}/`))
+                    io.write(`${'  '.repeat(entry.split('/').length - 1)}${entry.split('/').pop()}`);
+            return 0;
+        }
+        if (command === 'tree') {
+            const views = element ? [target(document, element).view] : document.perspectives;
+            for (const view of views) {
+                io.write(view.id);
+                const walk = (parent, prefix) => { for (const node of view.nodes.filter(node => node.parentId === parent)) {
+                    io.write(`${prefix}${node.id} — ${node.title}`);
+                    walk(node.id, `${prefix}  `);
+                } };
+                walk(element ? target(document, element).node?.id : undefined, '  ');
+            }
+            return 0;
+        }
+        if (command === 'validate') {
+            const issues = [];
+            if (element)
+                target(document, element);
+            for (const view of document.perspectives) {
+                for (const item of [view, ...view.nodes]) {
+                    const key = elementPath(view, item === view ? undefined : item);
+                    if (element && key !== element && !key.startsWith(`${element}/`))
+                        continue;
+                    if (!item.description && !item.summary)
+                        issues.push({ element: key, message: 'Missing description' });
+                    if (item.diagram) {
+                        const diagram = parseFlowchart(item.diagram);
+                        for (const issue of diagram.issues)
+                            issues.push({ element: key, message: issue });
+                        for (const node of diagram.nodes)
+                            if (node.ref && (!document.perspectives.some(other => other.id === node.ref) || node.ref === view.id))
+                                issues.push({ element: key, message: `Unresolved or self-referencing perspective: ${node.ref}` });
+                    }
+                }
+            }
+            json({ valid: !issues.length, issues });
+            return issues.length ? 1 : 0;
+        }
+        if (command === 'diff' && !element) {
+            json(await store.history(file));
+            return 0;
+        }
+        if (command === 'view') {
+            io.write(`Open Termdock → this project → Architecture, or https://localhost:9834/?architecture=${encodeURIComponent(JSON.stringify({ root, file }))}`);
+            return 0;
+        }
+        if (!element)
+            throw new Error('Element path is required');
+        const selected = target(document, element);
+        if (command === 'delete') {
+            const removed = new Set();
+            if (!selected.node)
+                document.perspectives = document.perspectives.filter(view => view.id !== selected.view.id);
+            else {
+                removed.add(selected.node.id);
+                for (let index = 0; index < selected.view.nodes.length; index++)
+                    for (const node of selected.view.nodes)
+                        if (node.parentId && removed.has(node.parentId))
+                            removed.add(node.id);
+                selected.view.nodes = selected.view.nodes.filter(node => !removed.has(node.id));
+                selected.view.edges = selected.view.edges.filter(edge => !removed.has(edge.from) && !removed.has(edge.to));
+            }
+            // Validation refuses dangling references and an empty document.
+            await store.save(file, document, loaded.revision);
+            io.write(`Deleted ${element}`);
+            return 0;
+        }
+        if (command === 'show') {
+            json(selected.value);
+            return 0;
+        }
+        if (command === 'read') {
+            if (!ARCHITECTURE_FIELDS.includes(field))
+                throw new Error('Invalid field');
+            io.write(selected.value[field] ?? (field === 'description' ? selected.value.summary : field === 'diagram' ? architectureSourceDiagram(selected.view, selected.node?.id) : ''));
+            return 0;
+        }
+        if (command === 'write') {
+            if (!ARCHITECTURE_FIELDS.includes(field))
+                throw new Error('Invalid field');
+            const updated = updateArchitectureField(document, selected.view.id, selected.node?.id, field, await input(content));
+            await store.save(file, updated, loaded.revision);
+            io.write(`Updated ${element}/${field}`);
+            return 0;
+        }
+        if (command === 'refs') {
+            const reference = (perspective, id) => {
+                const view = document.perspectives.find(view => view.id === perspective);
+                const node = id ? view.nodes.find(node => node.id === id) : undefined;
+                return { perspective, ...(id ? { node: id } : {}), element: elementPath(view, node), title: node?.title ?? view.title };
+            };
+            const connections = (selected.node ? selected.view.edges.filter(edge => edge.from === selected.node.id || edge.to === selected.node.id) : selected.view.edges).map(edge => ({ ...edge, fromElement: elementPath(selected.view, selected.view.nodes.find(node => node.id === edge.from)), toElement: elementPath(selected.view, selected.view.nodes.find(node => node.id === edge.to)) }));
+            json({ outgoing: (selected.node?.references ?? []).map(ref => reference(ref.perspective, ref.node)), incoming: document.perspectives.flatMap(view => view.nodes.filter(node => node.references?.some(ref => ref.perspective === selected.view.id && (!ref.node || ref.node === selected.node?.id))).map(node => reference(view.id, node.id))), connections });
+            return 0;
+        }
+        if (command === 'diff') {
+            if (selected.value.meta?.previousDiagram && selected.value.diagram)
+                json(diffMermaid(selected.value.meta.previousDiagram, selected.value.diagram));
+            else {
+                const versions = await store.history(file);
+                json(versions[0] ? diffArchitecture(await store.historical(file, versions[0].id), document).filter(change => change.perspective === selected.view.id && (!selected.node || change.node === selected.node.id)) : []);
+            }
+            return 0;
+        }
+        throw new Error(`Unknown architecture command: ${command}`);
+    }
+    catch (error) {
+        io.write(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}