yarramate 0.18.0 → 0.20.0

package/dist/adapters/visual/session-store.d.ts

@@ -1,6 +1,7 @@
-import { type VisualAuthority, type VisualDiagnostic, type VisualEvent, type VisualFreezeReason, type VisualHandoff, type VisualModel, type VisualResponse, type VisualSessionDescriptor, type VisualSessionRequest, type VisualTerminationReason } from './protocol.js';
+import { type VisualAuthority, type VisualDiagnostic, type VisualEvent, type VisualFreezeReason, type VisualHandoff, type VisualResponse, type VisualSessionDescriptor, type VisualSessionRequest, type VisualTerminationReason } from './protocol.js';
+import { type WorkspaceSource } from '../../compiler.js';
+import { type CanvasGraph } from '../../graph-projection.js';
 export declare const VISUAL_SESSION_MARKER_FORMAT: 'yarramate/visual-session-marker/v1';
-export declare const VISUAL_ACTIVE_MODEL_FORMAT: 'yarramate/visual-active-model/v1';
 /**
  * Upper bound on how many orphaned sessions one `start` prunes. Cleanup runs on
  * the critical path of a new session, so a directory full of orphans must cost
@@ -19,8 +20,6 @@ export interface VisualSessionPaths {
     readonly marker: string;
     readonly descriptor: string;
     readonly journal: string;
-    readonly candidates: string;
-    readonly activeModel: string;
 }
 export interface SessionDependencies {
     readonly baseDir: string;
@@ -45,17 +44,6 @@ export interface VisualSessionMarker {
     readonly createdAt: string;
     readonly authority: VisualAuthority;
 }
-/**
- * Last-good rendering pointer. It names a staged candidate directory instead of
- * embedding the model so the swap is a single rename of a small file.
- */
-export interface VisualActiveModel {
-    readonly format: typeof VISUAL_ACTIVE_MODEL_FORMAT;
-    readonly candidate: string;
-    readonly authority: VisualAuthority;
-    readonly initialView: string;
-    readonly promotedAt: string;
-}
 export interface VisualSessionCreated {
     readonly paths: VisualSessionPaths;
     readonly browserToken: string;
@@ -73,17 +61,6 @@ export interface VisualAppendRejected {
     readonly diagnostics: readonly VisualDiagnostic[];
 }
 export type VisualAppendResult = VisualAppendAccepted | VisualAppendRejected;
-export interface ModelPromotion {
-    readonly model: VisualModel;
-    readonly now: () => Date;
-    readonly compile: (candidateDir: string) => Promise<readonly VisualDiagnostic[]>;
-}
-export interface ModelPromotionResult {
-    readonly promoted: boolean;
-    readonly candidate: string;
-    readonly candidateDir: string;
-    readonly diagnostics: readonly VisualDiagnostic[];
-}
 export declare const visualSessionPaths: (root: string) => VisualSessionPaths;
 export declare const createVisualSession: (request: VisualSessionRequest, deps: SessionDependencies) => Promise<VisualSessionCreated>;
 /**
@@ -105,12 +82,37 @@ export declare const appendVisualResponse: (paths: VisualSessionPaths, response:
 export declare const appendTerminalEvent: (paths: VisualSessionPaths, reason: VisualTerminationReason, deps: TerminalEventDependencies) => Promise<VisualEvent>;
 export declare const readActionableEventsAfter: (paths: VisualSessionPaths, sequence: number) => Promise<readonly VisualEvent[]>;
 export declare const recoverVisualSession: (paths: VisualSessionPaths, includeTranscript?: boolean) => Promise<VisualHandoff>;
-export declare const readActiveVisualModel: (paths: VisualSessionPaths) => Promise<VisualActiveModel | undefined>;
-export declare const promoteCompiledModel: (paths: VisualSessionPaths, promotion: ModelPromotion) => Promise<ModelPromotionResult>;
+export type VisualModelGraphResult = {
+    readonly ok: true;
+    readonly graph: CanvasGraph;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly VisualDiagnostic[];
+};
+/**
+ * Builds the `graph` a session's `VisualModel` renders, from the workspace's
+ * own source documents. This is the whole construction step a visual session
+ * needs at start: no subprocess, no staged candidate directory, no on-disk
+ * pointer file — `compileWorkspaceWithProfileContext` and
+ * `projectGraphForCanvas` are both pure, synchronous functions over this
+ * repo's native compiler, so the caller assembles the result directly into
+ * the full `VisualModel` (format, authority, initialView, sourceDigests,
+ * graph) without any session-store I/O.
+ *
+ * A compile failure here is not a runtime defect — it is exactly the
+ * diagnostic-shaped rejection the browser already expects, so the workspace
+ * compiler's own diagnostics are returned unchanged rather than resynthesised.
+ * `Diagnostic` (compiler.ts) and `VisualDiagnostic` (protocol-contract.ts)
+ * already share one shape: severity, code, message, path, pointer, line,
+ * column.
+ */
+export declare const buildVisualModelGraph: (sources: readonly WorkspaceSource[]) => VisualModelGraphResult;
 /**
  * Recovers the handoff and only then deletes the session, so cleanup can never
  * be the step that loses confirmed state. Returns `undefined` when the session
- * is already gone, which makes a repeated stop idempotent.
+ * is already gone, which makes a repeated stop idempotent, and when a previous
+ * cleanup already took the journal: there is no handoff left to recover, and
+ * refusing would strand a marked directory that only this call will remove.
  */
 export declare const removeVisualSession: (paths: VisualSessionPaths, includeTranscript?: boolean) => Promise<VisualHandoff | undefined>;
 /**

package/dist/adapters/visual/session-store.js

@@ -1,16 +1,16 @@
 import { constants } from 'node:fs';
 import { lstat, mkdir, open, readFile, readdir, rename, rm, stat, truncate, writeFile, } from 'node:fs/promises';
-import { basename, dirname, join, resolve, sep } from 'node:path';
-import { VISUAL_LIMITS, parseVisualEvent, parseVisualHandoff, parseVisualModel, parseVisualResponse, parseVisualSessionDescriptor, parseVisualSessionRequest, } from './protocol.js';
+import { basename, dirname, join, resolve } from 'node:path';
+import { VISUAL_LIMITS, parseVisualEvent, parseVisualHandoff, parseVisualResponse, parseVisualSessionDescriptor, parseVisualSessionRequest, } from './protocol.js';
+import { compileWorkspaceWithProfileContext, } from '../../compiler.js';
+import { projectGraphForCanvas } from '../../graph-projection.js';
 export const VISUAL_SESSION_MARKER_FORMAT = 'yarramate/visual-session-marker/v1';
-export const VISUAL_ACTIVE_MODEL_FORMAT = 'yarramate/visual-active-model/v1';
 /**
  * Upper bound on how many orphaned sessions one `start` prunes. Cleanup runs on
  * the critical path of a new session, so a directory full of orphans must cost
  * a bounded amount of work; the remainder is collected by the next start.
  */
 export const VISUAL_SESSION_PRUNE_LIMIT = 64;
-const CANDIDATE_NAME = /^[0-9]{6}$/;
 const IDENTIFIER = /^[0-9a-f]{32}$/;
 const TIMESTAMP = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$/;
 const NEWLINE = 0x0a;
@@ -58,7 +58,6 @@ const serialize = (key, action) => {
 const forget = (paths) => {
     states.delete(paths.journal);
     queues.delete(paths.journal);
-    queues.delete(paths.candidates);
 };
 const drawHex = (randomBytes, size) => {
     const drawn = randomBytes(size);
@@ -113,8 +112,6 @@ export const visualSessionPaths = (root) => {
         marker: join(base, 'session.json'),
         descriptor: join(base, 'descriptor.json'),
         journal: join(base, 'journal.jsonl'),
-        candidates: join(base, 'candidates'),
-        activeModel: join(base, 'active-model.json'),
     };
 };
 const readSessionMarker = async (paths) => {
@@ -141,7 +138,7 @@ const readSessionMarker = async (paths) => {
         !IDENTIFIER.test(id) ||
         typeof createdAt !== 'string' ||
         !TIMESTAMP.test(createdAt) ||
-        (authority !== 'canonical' && authority !== 'ad-hoc')) {
+        authority !== 'canonical') {
         throw storeError('YMVS124', `Session marker "${paths.marker}" is not ${VISUAL_SESSION_MARKER_FORMAT}`);
     }
     // A marker that names another directory cannot authorise destructive work on
@@ -277,7 +274,6 @@ export const createVisualSession = async (request, deps) => {
         createdAt: deps.now().toISOString(),
         authority: validated.value.authority,
     });
-    await mkdir(paths.candidates, { recursive: false, mode: 0o700 });
     await writeFile(paths.journal, '', { mode: 0o600 });
     await syncDirectory(root);
     return {
@@ -559,91 +555,93 @@ export const recoverVisualSession = async (paths, includeTranscript = false) =>
     }
     return handoff;
 };
-export const readActiveVisualModel = async (paths) => {
-    let raw = '';
-    try {
-        raw = await readFile(paths.activeModel, 'utf8');
-    }
-    catch {
-        return undefined;
+/**
+ * Builds the `graph` a session's `VisualModel` renders, from the workspace's
+ * own source documents. This is the whole construction step a visual session
+ * needs at start: no subprocess, no staged candidate directory, no on-disk
+ * pointer file — `compileWorkspaceWithProfileContext` and
+ * `projectGraphForCanvas` are both pure, synchronous functions over this
+ * repo's native compiler, so the caller assembles the result directly into
+ * the full `VisualModel` (format, authority, initialView, sourceDigests,
+ * graph) without any session-store I/O.
+ *
+ * A compile failure here is not a runtime defect — it is exactly the
+ * diagnostic-shaped rejection the browser already expects, so the workspace
+ * compiler's own diagnostics are returned unchanged rather than resynthesised.
+ * `Diagnostic` (compiler.ts) and `VisualDiagnostic` (protocol-contract.ts)
+ * already share one shape: severity, code, message, path, pointer, line,
+ * column.
+ */
+export const buildVisualModelGraph = (sources) => {
+    const compiled = compileWorkspaceWithProfileContext(sources);
+    if (!compiled.ok) {
+        return { ok: false, diagnostics: compiled.diagnostics };
     }
-    let parsed;
+    return {
+        ok: true,
+        graph: projectGraphForCanvas(compiled.graph, compiled.profileContext),
+    };
+};
+/**
+ * Whether a journal is still on disk. A cleanup that failed partway can leave
+ * a marked session without one, and that is a question about the filesystem
+ * rather than a corruption to report.
+ */
+const journalExists = async (paths) => {
     try {
-        parsed = JSON.parse(raw);
+        await lstat(paths.journal);
+        return true;
     }
     catch {
-        throw storeError('YMVS128', `Active model pointer "${paths.activeModel}" is not JSON`);
+        return false;
     }
-    const fields = documentFields(parsed);
-    const candidate = fields.candidate;
-    const authority = fields.authority;
-    const initialView = fields.initialView;
-    const promotedAt = fields.promotedAt;
-    if (fields.format !== VISUAL_ACTIVE_MODEL_FORMAT ||
-        typeof candidate !== 'string' ||
-        !CANDIDATE_NAME.test(candidate) ||
-        (authority !== 'canonical' && authority !== 'ad-hoc') ||
-        typeof initialView !== 'string' ||
-        typeof promotedAt !== 'string' ||
-        !TIMESTAMP.test(promotedAt)) {
-        throw storeError('YMVS128', `Active model pointer "${paths.activeModel}" is not ${VISUAL_ACTIVE_MODEL_FORMAT}`);
-    }
-    return {
-        format: VISUAL_ACTIVE_MODEL_FORMAT,
-        candidate,
-        authority,
-        initialView,
-        promotedAt,
-    };
 };
-export const promoteCompiledModel = async (paths, promotion) => {
-    // The runtime has already parsed the `model.replace` response that carried
-    // this model, so a violation here is a runtime defect rather than untrusted
-    // input, and must not be reported to the browser as a candidate diagnostic.
-    const validated = parseVisualModel(promotion.model);
-    if (!validated.ok) {
-        const first = validated.diagnostics[0];
-        throw storeError(first?.code ?? 'YMVS106', `Candidate model is invalid: ${first?.message ?? 'unknown violation'}`);
-    }
-    const model = validated.value;
-    return serialize(paths.candidates, async () => {
-        await readSessionMarker(paths);
-        const existing = await readdir(paths.candidates);
-        const highest = existing
-            .filter((entry) => CANDIDATE_NAME.test(entry))
-            .reduce((max, entry) => Math.max(max, Number(entry)), 0);
-        const candidate = String(highest + 1).padStart(6, '0');
-        const candidateDir = join(paths.candidates, candidate);
-        await mkdir(candidateDir, { recursive: false, mode: 0o700 });
-        for (const [file, contents] of Object.entries(model.files)) {
-            const target = resolve(candidateDir, file);
-            // Confinement is already enforced by the model schema and by the protocol
-            // path check; re-checking the resolved path means neither of those alone
-            // is load-bearing for a write outside the candidate directory.
-            if (!target.startsWith(`${candidateDir}${sep}`)) {
-                throw storeError('YMVS125', `Candidate file "${file}" resolves outside "${candidateDir}"`);
-            }
-            await mkdir(dirname(target), { recursive: true, mode: 0o700 });
-            await writePrivateFile(target, contents);
-        }
-        const diagnostics = await promotion.compile(candidateDir);
-        if (diagnostics.length > 0) {
-            return { promoted: false, candidate, candidateDir, diagnostics };
+/**
+ * Deletes a session directory one entry at a time, journal and marker last.
+ *
+ * `rm(..., { recursive: true })` rejects the moment one entry fails while the
+ * sibling removals it already started are still in flight; those stragglers go
+ * on deleting after the caller has already seen the rejection. A cleanup that
+ * failed could therefore still take the journal with it, leaving the retry that
+ * follows nothing to recover from. Removing entries in a decided order, and
+ * awaiting each one, keeps the two files a retry depends on - the journal it
+ * recovers from, and the marker that authorises deleting this directory at all
+ * - on disk for as long as any other trace of the session is. The marker goes
+ * last of the two: a directory that outlives its marker is one no later pass
+ * would agree to remove.
+ */
+const removeSessionDirectory = async (paths) => {
+    let entries;
+    try {
+        entries = await readdir(paths.root, { withFileTypes: true });
+    }
+    catch (cause) {
+        // A session already gone is a completed cleanup, not a failed one.
+        if (typeof cause === 'object' &&
+            cause !== null &&
+            'code' in cause &&
+            cause.code === 'ENOENT') {
+            return;
         }
-        await writePrivateJson(paths.activeModel, {
-            format: VISUAL_ACTIVE_MODEL_FORMAT,
-            candidate,
-            authority: model.authority,
-            initialView: model.initialView,
-            promotedAt: promotion.now().toISOString(),
-        });
-        return { promoted: true, candidate, candidateDir, diagnostics: [] };
-    });
+        throw cause;
+    }
+    const journal = basename(paths.journal);
+    const marker = basename(paths.marker);
+    for (const entry of entries) {
+        if (entry.name === journal || entry.name === marker)
+            continue;
+        await rm(join(paths.root, entry.name), { recursive: true, force: true });
+    }
+    await rm(paths.journal, { force: true });
+    await rm(paths.marker, { force: true });
+    await rm(paths.root, { recursive: true, force: true });
 };
 /**
  * Recovers the handoff and only then deletes the session, so cleanup can never
  * be the step that loses confirmed state. Returns `undefined` when the session
- * is already gone, which makes a repeated stop idempotent.
+ * is already gone, which makes a repeated stop idempotent, and when a previous
+ * cleanup already took the journal: there is no handoff left to recover, and
+ * refusing would strand a marked directory that only this call will remove.
  */
 export const removeVisualSession = async (paths, includeTranscript = false) => {
     let entry;
@@ -657,8 +655,12 @@ export const removeVisualSession = async (paths, includeTranscript = false) => {
     if (!entry.isDirectory()) {
         throw storeError('YMVS125', `Session root "${paths.root}" is not a directory`);
     }
-    const handoff = await recoverVisualSession(paths, includeTranscript);
-    await rm(paths.root, { recursive: true, force: true });
+    // The marker authorises the deletion whether or not a journal survived it.
+    await readSessionMarker(paths);
+    const handoff = (await journalExists(paths))
+        ? await recoverVisualSession(paths, includeTranscript)
+        : undefined;
+    await removeSessionDirectory(paths);
     await syncDirectory(dirname(paths.root));
     forget(paths);
     return handoff;
@@ -668,11 +670,10 @@ export const removeVisualSession = async (paths, includeTranscript = false) => {
  * none of them could be measured.
  *
  * POSIX updates a directory's modification time only when its own entries
- * change, so the session root records nothing about an appended journal, and
- * the candidates directory records nothing about a promoted pointer. Every
- * artefact that can carry activity is therefore measured directly; the
- * optional ones are simply absent until a session produces them. `lstat`
- * keeps a symlinked artefact from reporting some other file's activity.
+ * change, so the session root records nothing about an appended journal.
+ * Every artefact that can carry activity is therefore measured directly;
+ * `lstat` keeps a symlinked artefact from reporting some other file's
+ * activity.
  */
 const lastActivityMs = async (paths) => {
     let newest;
@@ -681,8 +682,6 @@ const lastActivityMs = async (paths) => {
         paths.marker,
         paths.descriptor,
         paths.journal,
-        paths.candidates,
-        paths.activeModel,
     ]) {
         let entry;
         try {
@@ -744,8 +743,9 @@ export const pruneStaleVisualSessions = async (baseDir, now, limit = VISUAL_SESS
     stale.sort((left, right) => left.activeAt - right.activeAt || left.root.localeCompare(right.root));
     const removed = [];
     for (const candidate of stale.slice(0, Math.max(0, limit))) {
-        await rm(candidate.root, { recursive: true, force: true });
-        forget(visualSessionPaths(candidate.root));
+        const paths = visualSessionPaths(candidate.root);
+        await removeSessionDirectory(paths);
+        forget(paths);
         removed.push(candidate.root);
     }
     if (removed.length > 0) {

package/dist/adapters/visual/wire.d.ts

@@ -1,4 +1,5 @@
-import type { VISUAL_PROTOCOL_VERSION, VisualAuthority, VisualCapabilities, VisualChoicePresentPayload, VisualDiagnostic, VisualFreezeReason, VisualResponse, VisualTerminationReason } from './protocol-contract.js';
+import type { CanvasGraph } from '../../graph-projection.js';
+import type { VISUAL_PROTOCOL_VERSION, VisualApplyResultPayload, VisualAuthority, VisualBrowserInput, VisualCapabilities, VisualChoicePresentPayload, VisualDiagnostic, VisualFilterResultPayload, VisualFreezeReason, VisualKindOption, VisualLayoutPositions, VisualLayoutSaveResultPayload, VisualResponse, VisualTerminationReason, VisualViewSaveResultPayload, VisualViewSummary } from './protocol-contract.js';
 /**
  * Transport shapes the session server and the browser application both speak.
  *
@@ -9,18 +10,21 @@ import type { VISUAL_PROTOCOL_VERSION, VisualAuthority, VisualCapabilities, Visu
  * that serves it — this module holds types only, and every dependency it has on
  * the protocol is type-only too.
  */
-/** One promoted candidate as the browser receives it. */
+/** The resolved graph a session renders, as the browser receives it. */
 export interface VisualRenderedModel {
-    readonly candidate: string;
     readonly authority: VisualAuthority;
     readonly initialView: string;
-    readonly views: readonly string[];
-    /**
-     * The trusted compiler's own LikeC4 export for this candidate, the document
-     * `createLikeC4Model` consumes. Its internals belong to LikeC4, so the
-     * transport carries it verbatim instead of restating a shape it does not own.
-     */
-    readonly compiled: unknown;
+    readonly graph: CanvasGraph;
+    /** Manifest-relative document paths — the add-concept target dropdown. */
+    readonly documents: readonly string[];
+    readonly vocabulary: {
+        readonly conceptKinds: readonly VisualKindOption[];
+        readonly relationshipKinds: readonly VisualKindOption[];
+    };
+    /** Every saved layout sidecar, keyed by projection id (Plan-level decision 1). */
+    readonly layouts: {
+        readonly [projectionId: string]: VisualLayoutPositions;
+    };
 }
 /**
  * One line of the conversation, as plain text.
@@ -47,6 +51,8 @@ export interface VisualSessionSnapshot {
     readonly webSocketUrl: string;
     readonly model: VisualRenderedModel;
     readonly transcript: readonly VisualTranscriptRecord[];
+    /** The saved views the reviewer can switch this session's diagram to. */
+    readonly views: readonly VisualViewSummary[];
     /**
      * Whether the agent still owes an answer to something the reviewer sent. A
      * browser that reconnects mid-turn reads this rather than inferring the turn
@@ -79,6 +85,14 @@ export type VisualServerFrame = {
     readonly eventId: string;
 } | {
     readonly kind: 'rejected';
+    /**
+     * The input this refusal is about, as the frame that carried it named
+     * itself. A browser with a commit or a save in flight can only retire
+     * the right control if the refusal says which one died, and a refusal
+     * that never got as far as reading a type - a binary frame, a document
+     * that is not JSON - names nothing rather than guessing.
+     */
+    readonly refused?: VisualBrowserInput['type'];
     readonly diagnostics: readonly VisualDiagnostic[];
     readonly frozen?: VisualFreezeReason;
 } | {
@@ -87,6 +101,18 @@ export type VisualServerFrame = {
 } | {
     readonly kind: 'model';
     readonly model: VisualRenderedModel;
+} | {
+    readonly kind: 'filter-result';
+    readonly result: VisualFilterResultPayload;
+} | {
+    readonly kind: 'view-save-result';
+    readonly result: VisualViewSaveResultPayload;
+} | {
+    readonly kind: 'apply-result';
+    readonly result: VisualApplyResultPayload;
+} | {
+    readonly kind: 'layout-save-result';
+    readonly result: VisualLayoutSaveResultPayload;
 } | {
     readonly kind: 'closing';
     readonly reason: VisualTerminationReason;

package/dist/adapters/visual-cli.d.ts

@@ -10,6 +10,9 @@ export declare const VISUAL_SESSION_DIRECTORY: string;
 /**
  * Every command an agent can run to completion. `start` is not one of them: it
  * blocks for the life of the session and is dispatched by `runVisualCli`.
+ *
+ * `request` is the one verb that takes no descriptor - it runs before any
+ * session exists - so it is dispatched ahead of the descriptor requirement.
  */
 export declare function runVisualClientCli(args: readonly string[], cwd?: string): Promise<CliResult>;
 /** Where a foreground session publishes, and where it observes its signals. */

package/dist/adapters/visual-cli.js

@@ -3,9 +3,12 @@ import { join } from 'node:path';
 import { isMainModule, versionResult } from '../cli-support.js';
 import { fetchVisualStatus, readVisualJsonDocument, readVisualSessionDescriptor, recoverVisualSessionClient, sendVisualResponse, stopVisualSessionClient, visualClientDiagnostic, visualFailureDiagnostics, visualSessionAlreadyStopped, waitForVisualEvent, } from './visual/client.js';
 import { parseVisualResponse, parseVisualSessionRequest, } from './visual/protocol.js';
+import { buildVisualSessionRequest } from './visual/request.js';
 import { startVisualServer } from './visual/session-server.js';
 import { pruneStaleVisualSessions } from './visual/session-store.js';
 export const visualUsage = 'Usage:\n' +
+    '  yarramate-visual request [--view <id>] [--title <text>]\n' +
+    '                           [--description <text>] [--chat]\n' +
     '  yarramate-visual start <request.json>\n' +
     '  yarramate-visual wait <descriptor.json> [--after <sequence>]\n' +
     '  yarramate-visual respond <descriptor.json> <response.json>\n' +
@@ -66,6 +69,63 @@ const transcriptFlag = (rest) => rest.length === 0
     : rest.length === 1 && rest[0] === '--transcript'
         ? true
         : undefined;
+/**
+ * Strict because the document this builds is a session's whole input: a
+ * misspelled flag that was silently ignored would open a session on the wrong
+ * view, or with chat off when the caller asked for it. A repeated flag is a
+ * caller that means two things at once, and a value beginning with `--` is a
+ * missing value rather than a title, so both refuse with usage.
+ */
+const requestFlags = (rest) => {
+    let view;
+    let title;
+    let description;
+    let chatEnabled = false;
+    for (let index = 0; index < rest.length; index += 1) {
+        const flag = rest[index];
+        if (flag === '--chat') {
+            if (chatEnabled)
+                return undefined;
+            chatEnabled = true;
+            continue;
+        }
+        const value = rest[index + 1];
+        if (value === undefined || value.startsWith('--'))
+            return undefined;
+        index += 1;
+        if (flag === '--view' && view === undefined)
+            view = value;
+        else if (flag === '--title' && title === undefined)
+            title = value;
+        else if (flag === '--description' && description === undefined) {
+            description = value;
+        }
+        else
+            return undefined;
+    }
+    return { view, title, description, chatEnabled };
+};
+/**
+ * Transcribes the workspace into the request document `start` consumes. It is
+ * the only visual command that reads the repository rather than a session:
+ * every other one addresses a descriptor, and this one runs before a session
+ * exists.
+ */
+const requestCliCommand = (rest, cwd) => {
+    const flags = requestFlags(rest);
+    if (flags === undefined)
+        return usageResult;
+    const built = buildVisualSessionRequest({
+        cwd,
+        initialView: flags.view,
+        title: flags.title,
+        description: flags.description,
+        chatEnabled: flags.chatEnabled,
+    });
+    if (!built.ok)
+        return refusalResult(built.diagnostics);
+    return { exitCode: 0, stdout: documentLine(built.request), stderr: '' };
+};
 const waitCliCommand = async (descriptorPath, rest, cwd) => {
     const after = sequenceFlag(rest);
     if (after === undefined)
@@ -164,11 +224,16 @@ const stopCliCommand = async (descriptorPath, rest, cwd) => {
 /**
  * Every command an agent can run to completion. `start` is not one of them: it
  * blocks for the life of the session and is dispatched by `runVisualCli`.
+ *
+ * `request` is the one verb that takes no descriptor - it runs before any
+ * session exists - so it is dispatched ahead of the descriptor requirement.
  */
 export async function runVisualClientCli(args, cwd = process.cwd()) {
     const [command, descriptor, ...rest] = args;
     if (command === '--version')
         return versionResult('yarramate-visual');
+    if (command === 'request')
+        return requestCliCommand(args.slice(1), cwd);
     if (descriptor === undefined)
         return usageResult;
     switch (command) {
@@ -215,7 +280,7 @@ export const runVisualStart = async (requestPath, cwd = process.cwd(), io = proc
         // A previous runtime's orphans are collected on the critical path of a new
         // session, bounded per pass so a full directory cannot stall this one.
         await pruneStaleVisualSessions(baseDir, new Date());
-        handle = await startVisualServer({ request: request.value, baseDir });
+        handle = await startVisualServer({ request: request.value, baseDir, cwd });
     }
     catch (cause) {
         // A failed start has already recovered and removed whatever it created.

package/dist/apply-command.d.ts

@@ -1,2 +1,12 @@
 import { type CliResult } from './cli-support.js';
+import { type Diagnostic, type WorkspaceSource } from './compiler.js';
+import type { YarramateApplyResult } from './operations.js';
+export type ApplyOutcome = {
+    readonly ok: true;
+    readonly result: YarramateApplyResult;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export declare const applyOperations: (operations: WorkspaceSource, workspace: WorkspaceSource, cwd: string) => ApplyOutcome;
 export declare function runApplyCommand(options: readonly string[], cwd: string): CliResult;