@ours.network/fleet 0.15.7 → 0.16.0

package/dist/web/topology-draft-store.js

@@ -0,0 +1,337 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
+import { stateRoot } from '../paths.js';
+import { FleetError } from '../application/errors.js';
+/**
+ * Durable storage for *sketches*: nodes the owner has drawn but not yet added to
+ * the fleet, and where every node sits on the canvas.
+ *
+ * This file is deliberately invisible to `loadConfig`. An incomplete agent in
+ * `roles:` would be started by `ours-fleet up`, and an incomplete watchdog or
+ * loop is a hard `ConfigError` that makes the entire fleet unloadable — so a
+ * draft cannot live in fleet.yaml at all. Being outside the config also makes
+ * "visible but not launchable" true at the daemon level rather than in the UI.
+ *
+ * Nothing here is authoritative and nothing here is a secret: the schema admits
+ * only presentational coordinates and a small allowlist of plain draft fields,
+ * so `env:`/`vars:` values can never reach it.
+ */
+export const TOPOLOGY_DRAFT_VERSION = 1;
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_NODES = 500;
+const MAX_EDGES = 2000;
+const MAX_POSITIONS = 2000;
+const MAX_COORDINATE = 100_000;
+const MAX_FIELDS_PER_NODE = 32;
+const MAX_FIELD_LENGTH = 16 * 1024;
+const MAX_TUTORIAL_STEP = 32;
+const NODE_ID_RE = /^(agent|watchdog|loop):[A-Za-z0-9_-]{1,64}$/;
+const NODE_KINDS = ['agent', 'watchdog', 'loop'];
+/** `spawned` is runtime provenance, never a drawn edge. */
+const EDGE_KINDS = ['oversees', 'watches', 'targets'];
+/**
+ * Draft fields the console may persist. An allowlist rather than a denylist so
+ * secret-bearing keys (`env`, `vars`, `harness_options`) are excluded by
+ * construction; extend it deliberately when the inspector grows a field.
+ *
+ * Every entry is a plain scalar that promotion can write straight into a role,
+ * watchdog or loop mapping. Nested settings (`permissions:`, `harness_options:`,
+ * `isolation:`) are deliberately absent: they are edited through the reviewed
+ * configuration editor once the node is real, not sketched.
+ */
+const FIELD_KEYS = [
+    'mission', 'bio', 'persona', 'coordinator', 'prompt',
+    'interval', 'initial_delay', 'jitter', 'enabled',
+    'harness', 'session', 'model', 'identity', 'cwd',
+];
+export const emptyDraft = () => ({
+    version: TOPOLOGY_DRAFT_VERSION,
+    positions: {},
+    drafts: { nodes: [], edges: [] },
+    tutorial: { step: 0, dismissed: false },
+});
+export class TopologyDraftStore {
+    path;
+    dir;
+    constructor(options = {}) {
+        this.dir = options.dir ?? join(stateRoot(), 'web');
+        this.path = join(this.dir, 'topology.json');
+    }
+    /**
+     * Never throws. A missing, unreadable, oversized, malformed or future-version
+     * sidecar degrades to an empty draft plus a `problem` the console can show as
+     * a banner — losing sketches is bad, but blocking the console on them is worse.
+     */
+    read() {
+        const raw = this.readRaw();
+        const revision = digest(raw.text);
+        if (raw.problem)
+            return { draft: emptyDraft(), revision, problem: raw.problem, writable: true };
+        if (raw.text === '')
+            return { draft: emptyDraft(), revision, writable: true };
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.text);
+        }
+        catch (error) {
+            return {
+                draft: emptyDraft(), revision, writable: true,
+                problem: problem('draft_corrupt', `topology drafts are unreadable and were ignored: ${error.message}`),
+            };
+        }
+        const version = parsed?.version;
+        if (typeof version === 'number' && version > TOPOLOGY_DRAFT_VERSION)
+            return {
+                draft: emptyDraft(), revision, writable: false,
+                problem: problem('draft_version_unsupported', `topology drafts were written by a newer console (version ${version}); update ours-fleet to edit them`),
+            };
+        return { draft: coerceDraft(parsed), revision, writable: true };
+    }
+    /**
+     * Revision-guarded, atomic, 0600. Strict on the way in: an out-of-bounds
+     * coordinate, an unknown field or an unparseable id is refused with a reason
+     * rather than silently dropped, because the caller is the console's own
+     * editor and a silent drop would look like data loss.
+     */
+    async write(baseRevision, next) {
+        const draft = validateDraft(next);
+        const text = `${JSON.stringify(draft, null, 2)}\n`;
+        if (Buffer.byteLength(text) > MAX_FILE_BYTES)
+            throw new FleetError('invalid_request', `topology drafts exceed ${MAX_FILE_BYTES} bytes`);
+        return withFileLock(`${this.path}.lock`, () => {
+            const current = this.read();
+            if (!current.writable)
+                throw new FleetError('incompatible_version', current.problem?.detail ?? 'topology drafts are not writable');
+            if (!baseRevision || baseRevision !== current.revision)
+                throw new FleetError('stale_state', 'topology drafts changed since they were opened; reload before saving');
+            mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+            chmodSync(this.dir, 0o700);
+            replaceFileAtomically(this.path, text, 0o600);
+            return { draft, revision: digest(text) };
+        });
+    }
+    readRaw() {
+        if (!existsSync(this.path))
+            return { text: '' };
+        try {
+            const stat = lstatSync(this.path);
+            if (!stat.isFile() || stat.isSymbolicLink())
+                return { text: '', problem: problem('draft_unreadable', 'topology drafts must be a regular non-symlink file') };
+            if (stat.size > MAX_FILE_BYTES)
+                return { text: '', problem: problem('draft_unreadable', `topology drafts exceed ${MAX_FILE_BYTES} bytes and were ignored`) };
+            const uid = process.getuid?.();
+            if (uid !== undefined && stat.uid !== uid)
+                return { text: '', problem: problem('draft_unreadable', 'topology drafts are not owned by the current user') };
+            return { text: readFileSync(this.path, 'utf8') };
+        }
+        catch (error) {
+            return { text: '', problem: problem('draft_unreadable', `topology drafts could not be read: ${error.message}`) };
+        }
+    }
+}
+const problem = (code, detail) => ({ code, severity: 'warning', detail, source: 'topology.json' });
+const digest = (text) => createHash('sha256').update(text).digest('hex');
+/* ------------------------------------------------------------------ *
+ * Lenient read coercion — drop what does not fit, keep the rest.
+ * ------------------------------------------------------------------ */
+function coerceDraft(value) {
+    const draft = emptyDraft();
+    if (!isRecord(value))
+        return draft;
+    const positions = value.positions;
+    if (isRecord(positions))
+        for (const [id, raw] of Object.entries(positions).slice(0, MAX_POSITIONS)) {
+            if (!NODE_ID_RE.test(id) || !isRecord(raw))
+                continue;
+            if (!isCoordinate(raw.x) || !isCoordinate(raw.y))
+                continue;
+            draft.positions[id] = { x: raw.x, y: raw.y };
+        }
+    const drafts = isRecord(value.drafts) ? value.drafts : {};
+    const seenNodes = new Set();
+    if (Array.isArray(drafts.nodes))
+        for (const raw of drafts.nodes) {
+            if (draft.drafts.nodes.length >= MAX_NODES)
+                break;
+            const node = coerceNode(raw);
+            if (!node || seenNodes.has(node.id))
+                continue;
+            seenNodes.add(node.id);
+            draft.drafts.nodes.push(node);
+        }
+    const seenEdges = new Set();
+    if (Array.isArray(drafts.edges))
+        for (const raw of drafts.edges) {
+            if (draft.drafts.edges.length >= MAX_EDGES)
+                break;
+            const edge = coerceEdge(raw);
+            if (!edge)
+                continue;
+            const key = `${edge.kind}:${edge.from}:${edge.to}`;
+            if (seenEdges.has(key))
+                continue;
+            seenEdges.add(key);
+            draft.drafts.edges.push(edge);
+        }
+    if (isRecord(value.tutorial)) {
+        const { step, dismissed } = value.tutorial;
+        if (typeof step === 'number' && Number.isInteger(step) && step >= 0 && step <= MAX_TUTORIAL_STEP)
+            draft.tutorial.step = step;
+        draft.tutorial.dismissed = dismissed === true;
+    }
+    return draft;
+}
+function coerceNode(value) {
+    if (!isRecord(value))
+        return undefined;
+    const { id, kind } = value;
+    if (typeof id !== 'string' || !NODE_ID_RE.test(id))
+        return undefined;
+    if (typeof kind !== 'string' || !NODE_KINDS.includes(kind))
+        return undefined;
+    if (!id.startsWith(`${kind}:`))
+        return undefined;
+    const fields = {};
+    if (isRecord(value.fields))
+        for (const [key, raw] of Object.entries(value.fields)) {
+            if (Object.keys(fields).length >= MAX_FIELDS_PER_NODE)
+                break;
+            if (!FIELD_KEYS.includes(key) || !isFieldValue(raw))
+                continue;
+            fields[key] = raw;
+        }
+    return { id, kind: kind, fields };
+}
+function coerceEdge(value) {
+    if (!isRecord(value))
+        return undefined;
+    const { kind, from, to } = value;
+    if (typeof kind !== 'string' || !EDGE_KINDS.includes(kind))
+        return undefined;
+    if (typeof from !== 'string' || !NODE_ID_RE.test(from))
+        return undefined;
+    if (typeof to !== 'string' || !NODE_ID_RE.test(to) || from === to)
+        return undefined;
+    return { kind: kind, from, to };
+}
+/* ------------------------------------------------------------------ *
+ * Strict write validation — refuse with a reason.
+ * ------------------------------------------------------------------ */
+function validateDraft(value) {
+    if (!isRecord(value))
+        throw invalid('topology draft must be a JSON object');
+    const version = value.version ?? TOPOLOGY_DRAFT_VERSION;
+    if (version !== TOPOLOGY_DRAFT_VERSION)
+        throw invalid(`unsupported topology draft version ${String(version)}`);
+    const draft = emptyDraft();
+    const positions = value.positions ?? {};
+    if (!isRecord(positions))
+        throw invalid('positions must be an object');
+    const positionIds = Object.keys(positions);
+    if (positionIds.length > MAX_POSITIONS)
+        throw invalid(`at most ${MAX_POSITIONS} node positions are supported`);
+    for (const id of positionIds) {
+        if (!NODE_ID_RE.test(id))
+            throw invalid(`invalid node id in positions: ${id}`);
+        const raw = positions[id];
+        if (!isRecord(raw) || !isCoordinate(raw.x) || !isCoordinate(raw.y))
+            throw invalid(`position for ${id} must be finite x/y within ±${MAX_COORDINATE}`);
+        draft.positions[id] = { x: raw.x, y: raw.y };
+    }
+    const drafts = value.drafts ?? {};
+    if (!isRecord(drafts))
+        throw invalid('drafts must be an object');
+    const nodes = drafts.nodes ?? [];
+    const edges = drafts.edges ?? [];
+    if (!Array.isArray(nodes))
+        throw invalid('drafts.nodes must be an array');
+    if (!Array.isArray(edges))
+        throw invalid('drafts.edges must be an array');
+    if (nodes.length > MAX_NODES)
+        throw invalid(`at most ${MAX_NODES} draft nodes are supported`);
+    if (edges.length > MAX_EDGES)
+        throw invalid(`at most ${MAX_EDGES} draft edges are supported`);
+    const seenNodes = new Set();
+    for (const raw of nodes) {
+        const node = validateNode(raw);
+        if (seenNodes.has(node.id))
+            throw invalid(`duplicate draft node ${node.id}`);
+        seenNodes.add(node.id);
+        draft.drafts.nodes.push(node);
+    }
+    const seenEdges = new Set();
+    for (const raw of edges) {
+        const edge = validateEdge(raw);
+        const key = `${edge.kind}:${edge.from}:${edge.to}`;
+        if (seenEdges.has(key))
+            continue;
+        seenEdges.add(key);
+        draft.drafts.edges.push(edge);
+    }
+    const tutorial = value.tutorial ?? {};
+    if (!isRecord(tutorial))
+        throw invalid('tutorial must be an object');
+    const step = tutorial.step ?? 0;
+    if (typeof step !== 'number' || !Number.isInteger(step) || step < 0 || step > MAX_TUTORIAL_STEP)
+        throw invalid(`tutorial.step must be an integer between 0 and ${MAX_TUTORIAL_STEP}`);
+    draft.tutorial = { step, dismissed: tutorial.dismissed === true };
+    return draft;
+}
+function validateNode(value) {
+    if (!isRecord(value))
+        throw invalid('each draft node must be an object');
+    const { id, kind } = value;
+    if (typeof id !== 'string' || !NODE_ID_RE.test(id))
+        throw invalid(`draft node id must look like agent:<Name>: ${JSON.stringify(id)}`);
+    if (typeof kind !== 'string' || !NODE_KINDS.includes(kind))
+        throw invalid(`draft node ${id} has an unknown kind ${JSON.stringify(kind)}`);
+    if (!id.startsWith(`${kind}:`))
+        throw invalid(`draft node ${id} does not match kind ${kind}`);
+    const rawFields = value.fields ?? {};
+    if (!isRecord(rawFields))
+        throw invalid(`draft node ${id} fields must be an object`);
+    const keys = Object.keys(rawFields);
+    if (keys.length > MAX_FIELDS_PER_NODE)
+        throw invalid(`draft node ${id} has more than ${MAX_FIELDS_PER_NODE} fields`);
+    const fields = {};
+    for (const key of keys) {
+        if (!FIELD_KEYS.includes(key))
+            throw invalid(`draft node ${id} may not store field ${JSON.stringify(key)}`);
+        const raw = rawFields[key];
+        if (!isFieldValue(raw))
+            throw invalid(`draft node ${id} field ${key} must be a string under ${MAX_FIELD_LENGTH} characters, a finite number, or a boolean`);
+        fields[key] = raw;
+    }
+    return { id, kind: kind, fields };
+}
+function validateEdge(value) {
+    if (!isRecord(value))
+        throw invalid('each draft edge must be an object');
+    const { kind, from, to } = value;
+    if (typeof kind !== 'string' || !EDGE_KINDS.includes(kind))
+        throw invalid(`draft edge has an unknown kind ${JSON.stringify(kind)}`);
+    if (typeof from !== 'string' || !NODE_ID_RE.test(from))
+        throw invalid(`invalid draft edge source ${JSON.stringify(from)}`);
+    if (typeof to !== 'string' || !NODE_ID_RE.test(to))
+        throw invalid(`invalid draft edge target ${JSON.stringify(to)}`);
+    if (from === to)
+        throw invalid(`draft edge ${from} cannot point at itself`);
+    return { kind: kind, from, to };
+}
+const invalid = (message) => new FleetError('invalid_request', message);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isCoordinate(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        && value >= -MAX_COORDINATE && value <= MAX_COORDINATE;
+}
+function isFieldValue(value) {
+    if (typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    return typeof value === 'string' && value.length <= MAX_FIELD_LENGTH;
+}

package/dist/web/topology-model.d.ts

@@ -0,0 +1,62 @@
+import type { FleetConfig } from '../config.js';
+import type { Problem } from '../application/types.js';
+import { type RuntimeRoleItem, type TopologyEdge, type TopologyNode } from './topology.js';
+import type { DraftFieldValue, DraftPosition, TopologyDraftRead } from './topology-draft-store.js';
+/**
+ * The console's read model: authoritative configuration overlaid with the
+ * sketches and canvas positions from the draft sidecar.
+ *
+ * `deriveTopology` stays a pure function of resolved config plus the runtime
+ * role list — this layer calls it and annotates the result, so the derivation
+ * and its tests keep their meaning. Everything drafts add is additive.
+ */
+export type NodeOrigin = 'draft' | 'config';
+/** One actionable reason a node is not yet ready, phrased for the owner. */
+export interface MissingRequirement {
+    field: string;
+    why: string;
+    fix: string;
+}
+export interface MergedTopologyNode extends TopologyNode {
+    origin: NodeOrigin;
+    /** Would `loadConfig` accept this node's name today. */
+    valid: boolean;
+    /** Meets the bar for being added to the fleet. */
+    complete: boolean;
+    /**
+     * Whether a process may be started for this node. A draft is never launchable,
+     * and not because the UI hides a button: a draft is in no file the supervisor
+     * or `ours-fleet up` reads.
+     */
+    launchable: boolean;
+    missing: MissingRequirement[];
+    position?: DraftPosition;
+    enabled?: boolean;
+    /** Sketched values, on draft nodes only — what promotion writes. */
+    fields?: Record<string, DraftFieldValue>;
+}
+export interface MergedTopologyEdge extends TopologyEdge {
+    origin: NodeOrigin;
+    /** A watchdog with no `watch:` list watches every agent, including later ones. */
+    implicit: boolean;
+    /** An endpoint that no longer exists — kept visible rather than swallowed. */
+    dangling: boolean;
+}
+export interface MergedTopology {
+    nodes: MergedTopologyNode[];
+    edges: MergedTopologyEdge[];
+    unknownLineage: string[];
+    problems: Problem[];
+    draftRevision: string;
+    draftWritable: boolean;
+}
+export declare const IMPLICIT_WATCH_LABEL = "watches all agents (default)";
+/**
+ * Merge configuration and drafts into the graph the console renders.
+ *
+ * Drift is surfaced, never silently repaired: a draft whose name is now taken
+ * by real configuration is reported as a problem rather than shadowing it, a
+ * draft edge to a vanished node is kept and marked dangling, and a position for
+ * a node that no longer exists is simply dropped.
+ */
+export declare function mergeTopology(config: FleetConfig, roles: RuntimeRoleItem[], draft: TopologyDraftRead): MergedTopology;

package/dist/web/topology-model.js

@@ -0,0 +1,220 @@
+import { deriveTopology, } from './topology.js';
+export const IMPLICIT_WATCH_LABEL = 'watches all agents (default)';
+const AGENT_MISSION = {
+    field: 'mission',
+    why: 'An agent without a mission has nothing to do and reads as noise on the canvas.',
+    fix: 'Write one sentence about this agent\'s job.',
+};
+const WATCHDOG_COORDINATOR = {
+    field: 'coordinator',
+    why: 'A watchdog reports to exactly one coordinator; the fleet refuses to load without it.',
+    fix: 'Name the agent this watchdog reports to.',
+};
+const LOOP_PROMPT = {
+    field: 'prompt',
+    why: 'An interval delivers a prompt on a schedule; there is nothing to deliver yet.',
+    fix: 'Write the prompt this interval should send.',
+};
+const LOOP_TARGET = {
+    field: 'roles',
+    why: 'An interval needs at least one agent to deliver its prompt to.',
+    fix: 'Connect this interval to an agent.',
+};
+/**
+ * Merge configuration and drafts into the graph the console renders.
+ *
+ * Drift is surfaced, never silently repaired: a draft whose name is now taken
+ * by real configuration is reported as a problem rather than shadowing it, a
+ * draft edge to a vanished node is kept and marked dangling, and a position for
+ * a node that no longer exists is simply dropped.
+ */
+export function mergeTopology(config, roles, draft) {
+    const snapshot = deriveTopology(config, roles);
+    const problems = draft.problem ? [draft.problem] : [];
+    const configIds = new Set(snapshot.nodes.map(node => node.id));
+    const shadowed = draft.draft.drafts.nodes.filter(node => configIds.has(node.id));
+    if (shadowed.length)
+        problems.push({
+            code: 'draft_conflicts_with_config',
+            severity: 'warning',
+            source: 'topology.json',
+            detail: `${shadowed.map(node => node.id).join(', ')} now exist${shadowed.length === 1 ? 's' : ''} in the fleet configuration; rename the draft to keep sketching it`,
+        });
+    const draftNodes = draft.draft.drafts.nodes.filter(node => !configIds.has(node.id));
+    const draftEdges = draft.draft.drafts.edges;
+    const nodes = [
+        ...snapshot.nodes.map(node => configNode(node, config)),
+        ...draftNodes.map(node => draftNode(node, draftEdges, draftNodes, config)),
+    ];
+    const known = new Map(nodes.map(node => [node.id, node]));
+    const implicitConfigWatchdogs = new Set(config.watchdogs.filter(watchdog => !watchdog.watchExplicit).map(watchdog => `watchdog:${watchdog.name}`));
+    const edges = [
+        ...snapshot.edges.map(edge => annotate(edge, 'config', edge.kind === 'watches' && implicitConfigWatchdogs.has(edge.from), known)),
+        ...draftEdges.map(edge => annotate({
+            id: `${edge.kind}:${edge.from}:${edge.to}`, kind: edge.kind,
+            from: edge.from, to: edge.to, label: edgeLabel(edge.kind),
+        }, 'draft', false, known)),
+        ...implicitDraftWatchEdges(draftNodes, draftEdges, nodes, known),
+    ];
+    for (const node of nodes) {
+        const position = draft.draft.positions[node.id];
+        if (position)
+            node.position = position;
+    }
+    return {
+        nodes,
+        edges,
+        unknownLineage: snapshot.unknownLineage,
+        problems,
+        draftRevision: draft.revision,
+        draftWritable: draft.writable,
+    };
+}
+/* ------------------------------------------------------------------ *
+ * Configured nodes
+ * ------------------------------------------------------------------ */
+function configNode(node, config) {
+    const name = node.id.slice(node.kind.length + 1);
+    const missing = [];
+    let enabled;
+    if (node.kind === 'agent') {
+        const role = config.roles.find(candidate => candidate.name === name);
+        // A role reachable only through its on-disk state directory is running
+        // configuration we cannot inspect; do not invent a gap for it.
+        if (role && !nonBlank(role.mission))
+            missing.push(AGENT_MISSION);
+    }
+    else if (node.kind === 'watchdog') {
+        enabled = config.watchdogs.find(candidate => candidate.name === name)?.enabled;
+    }
+    else {
+        enabled = config.loops.find(candidate => candidate.name === name)?.enabled;
+    }
+    const complete = missing.length === 0;
+    return { ...node, origin: 'config', valid: true, complete, launchable: complete, missing, enabled };
+}
+/* ------------------------------------------------------------------ *
+ * Draft nodes
+ * ------------------------------------------------------------------ */
+function draftNode(node, edges, draftNodes, config) {
+    const name = node.id.slice(node.kind.length + 1);
+    const missing = [];
+    const collision = nameConflict(node.kind, name, config);
+    if (collision)
+        missing.push({
+            field: 'name',
+            why: `The fleet already uses the name "${name}" for ${collision}.`,
+            fix: 'Rename this draft before adding it to the fleet.',
+        });
+    const draftIds = new Set(draftNodes.map(other => other.id));
+    const outgoing = edges.filter(edge => edge.from === node.id);
+    const stillDraft = (kind) => outgoing
+        .filter(edge => edge.kind === kind && draftIds.has(edge.to))
+        .map(edge => edge.to.slice('agent:'.length));
+    if (node.kind === 'agent') {
+        if (!nonBlank(node.fields.mission))
+            missing.push(AGENT_MISSION);
+    }
+    else if (node.kind === 'watchdog') {
+        if (!nonBlank(node.fields.coordinator))
+            missing.push(WATCHDOG_COORDINATOR);
+        pushPendingTargets(missing, 'watch', stillDraft('watches'), 'A watchdog may only watch agents that are already in the fleet.');
+    }
+    else {
+        if (!outgoing.some(edge => edge.kind === 'targets'))
+            missing.push(LOOP_TARGET);
+        if (!nonBlank(node.fields.prompt))
+            missing.push(LOOP_PROMPT);
+        pushPendingTargets(missing, 'roles', stillDraft('targets'), 'An interval may only deliver to agents that are already in the fleet.');
+    }
+    return {
+        id: node.id,
+        kind: node.kind,
+        label: name,
+        status: 'draft',
+        detail: draftDetail(node),
+        origin: 'draft',
+        valid: !collision,
+        complete: missing.length === 0,
+        launchable: false, // a draft is in no file the supervisor reads
+        missing,
+        fields: node.fields,
+        enabled: node.fields.enabled === undefined ? undefined : node.fields.enabled !== false,
+    };
+}
+function pushPendingTargets(missing, field, pending, why) {
+    if (!pending.length)
+        return;
+    missing.push({
+        field, why,
+        fix: `Add ${pending.join(', ')} to the fleet first, or remove the connection.`,
+    });
+}
+function draftDetail(node) {
+    const value = node.kind === 'agent' ? node.fields.mission
+        : node.kind === 'watchdog' ? node.fields.coordinator && `Reports to ${node.fields.coordinator}`
+            : node.fields.prompt;
+    return nonBlank(value) ? String(value) : undefined;
+}
+/* ------------------------------------------------------------------ *
+ * Edges
+ * ------------------------------------------------------------------ */
+function annotate(edge, origin, implicit, known) {
+    return {
+        ...edge,
+        label: implicit ? IMPLICIT_WATCH_LABEL : edge.label,
+        origin,
+        implicit,
+        dangling: !known.has(edge.from) || !known.has(edge.to),
+    };
+}
+/**
+ * A draft watchdog nobody scoped to a single agent is a *standalone* watchdog:
+ * promoting it omits `watch:`, which the config layer reads as "every role".
+ * Draw that so the owner sees the coverage before adding it, and so an agent
+ * added later is visibly covered with no edit at all.
+ */
+function implicitDraftWatchEdges(draftNodes, draftEdges, nodes, known) {
+    const persistentAgents = nodes.filter(node => node.kind === 'agent' && node.lifetime !== 'temporary');
+    return draftNodes
+        .filter(node => node.kind === 'watchdog'
+        && !draftEdges.some(edge => edge.kind === 'watches' && edge.from === node.id))
+        .flatMap(watchdog => persistentAgents.map(agent => annotate({
+        id: `watches:${watchdog.id}:${agent.id}`, kind: 'watches',
+        from: watchdog.id, to: agent.id, label: IMPLICIT_WATCH_LABEL,
+    }, 'draft', true, known)));
+}
+const edgeLabel = (kind) => (kind === 'watches' ? 'watches' : kind === 'targets' ? 'delivers to' : 'oversees');
+/* ------------------------------------------------------------------ *
+ * Shared
+ * ------------------------------------------------------------------ */
+/**
+ * What already owns `name`, or undefined when a draft of this kind may use it.
+ *
+ * Deliberately mirrors the collisions the config layer actually rejects and no
+ * others: a watchdog name may not equal a role name, and a watchdog identity
+ * (`Watchdog-<name>` by default) may not equal a role name, a role identity or
+ * another watchdog identity. Loop names share no namespace with anything, so a
+ * loop is only ever blocked by another loop of the same name.
+ */
+function nameConflict(kind, name, config) {
+    if (kind === 'loop')
+        return undefined;
+    if (kind === 'agent') {
+        // Adding a role named N breaks any watchdog already using N as its identity.
+        if (config.watchdogs.some(watchdog => watchdog.name === name))
+            return 'a watchdog';
+        const identity = config.watchdogs.find(watchdog => watchdog.identity === name);
+        return identity ? `watchdog ${identity.name}'s identity` : undefined;
+    }
+    if (config.roles.some(role => role.name === name))
+        return 'a role';
+    const identity = `Watchdog-${name}`;
+    if (config.roles.some(role => role.name === identity))
+        return `a role, which this watchdog's identity "${identity}" would collide with`;
+    if (config.roles.some(role => role.identity === identity))
+        return `a role identity, which this watchdog's identity "${identity}" would collide with`;
+    const other = config.watchdogs.find(watchdog => watchdog.identity === identity);
+    return other ? `watchdog ${other.name}'s identity "${identity}"` : undefined;
+}
+const nonBlank = (value) => typeof value === 'string' ? value.trim() !== '' : value !== undefined && value !== null;

package/dist/web/topology-promote.d.ts

@@ -0,0 +1,31 @@
+import type { ConfigPreviewResult, ConfigWriteResult, FleetConfigService } from './fleet-config-service.js';
+import type { TopologyDraftStore } from './topology-draft-store.js';
+import type { MergedTopology } from './topology-model.js';
+export interface PromoteRequest {
+    ids: string[];
+    configRevision: string;
+    draftRevision?: string;
+}
+export interface PromotePreview extends ConfigPreviewResult {
+    promoted: string[];
+}
+export interface PromoteResult extends ConfigWriteResult {
+    promoted: string[];
+    /** False when the config landed but the sketches could not be cleared. */
+    draftsCleared: boolean;
+    draftRevision: string;
+}
+export interface TopologyPromoteOptions {
+    drafts: TopologyDraftStore;
+    configuration: FleetConfigService;
+    topology(): Promise<MergedTopology>;
+}
+export declare class TopologyPromoteService {
+    private readonly options;
+    constructor(options: TopologyPromoteOptions);
+    preview(request: PromoteRequest): Promise<PromotePreview>;
+    promote(request: PromoteRequest): Promise<PromoteResult>;
+    private clearDrafts;
+    /** Build the configuration model that adding `ids` produces. */
+    private build;
+}