@ours.network/fleet 0.15.7 → 0.17.0

package/dist/session/acp.js

@@ -13,6 +13,9 @@ const CANCEL_SETTLE_GRACE_MS = 15_000;
 const PERMISSION_TIMEOUT_MS = 10 * 60_000;
 /** Spec §4.3: 10-15 s before a vanished controller triggers the unattended policy. */
 const CONTROLLER_GRACE_MS = 12_000;
+/** Bound safe-boundary waiting without turning a hung tool into cancellation. */
+export const AFTER_TOOL_BOUNDARY_TIMEOUT_MS = 120_000;
+const TERMINAL_TOOL_STATUSES = new Set(['completed', 'failed']);
 const SCHEDULED_LOOP_REDACTION = '[scheduled-loop content redacted]';
 const OWNER_COMMENTARY_REDACTION = '[assistant commentary redacted]';
 const scheduledTurn = (turn) => turn?.origin?.kind === 'scheduled-loop';
@@ -95,9 +98,13 @@ export class AcpSession {
     runtimeModel;
     reasoningEffort;
     controllerCount = 0;
+    closing = false;
     /** Armed when the last controller detaches; unattended policy applies on fire. */
     controllerGrace;
     cancelEscalation;
+    /** ACP-authenticated in-flight calls, including independently reserved permissions. */
+    activeToolCalls = new Map();
+    toolBoundaryWaiters = new Set();
     activeTurn;
     constructor(options, child, connection) {
         this.options = options;
@@ -215,6 +222,142 @@ export class AcpSession {
             permissionMode: this.options.permissionMode,
         };
     }
+    toolCall(toolCallId) {
+        const existing = this.activeToolCalls.get(toolCallId);
+        if (existing)
+            return existing;
+        const created = { lifecycle: false, permissions: new Map() };
+        this.activeToolCalls.set(toolCallId, created);
+        return created;
+    }
+    reserveTool(toolCallId) {
+        if (toolCallId)
+            this.toolCall(toolCallId).lifecycle = true;
+    }
+    reservePermission(toolCallId, permissionId) {
+        if (toolCallId)
+            this.toolCall(toolCallId).permissions.set(permissionId, 'pending');
+    }
+    allowPermission(toolCallId, permissionId) {
+        if (!toolCallId)
+            return;
+        const permission = this.activeToolCalls.get(toolCallId)?.permissions;
+        if (permission?.has(permissionId))
+            permission.set(permissionId, 'allowed');
+    }
+    releasePermission(toolCallId, permissionId) {
+        const call = toolCallId && this.activeToolCalls.get(toolCallId);
+        if (!call || !call.permissions.delete(permissionId))
+            return;
+        this.releaseToolIfIdle(toolCallId, call);
+    }
+    releaseTool(toolCallId) {
+        const call = toolCallId && this.activeToolCalls.get(toolCallId);
+        if (!call)
+            return;
+        call.lifecycle = false;
+        // Terminal tool evidence consumes permissions already granted for this
+        // call, but never a separate request that is still awaiting a decision.
+        for (const [permissionId, state] of call.permissions)
+            if (state === 'allowed')
+                call.permissions.delete(permissionId);
+        this.releaseToolIfIdle(toolCallId, call);
+    }
+    releaseToolIfIdle(toolCallId, call) {
+        if (call.lifecycle || call.permissions.size > 0)
+            return;
+        if (!this.activeToolCalls.delete(toolCallId) || this.activeToolCalls.size > 0)
+            return;
+        for (const notify of [...this.toolBoundaryWaiters])
+            notify();
+    }
+    releaseAllTools() {
+        if (this.activeToolCalls.size === 0)
+            return;
+        this.activeToolCalls.clear();
+        for (const notify of [...this.toolBoundaryWaiters])
+            notify();
+    }
+    waitForToolBoundary(timeoutMs) {
+        if (this.activeToolCalls.size === 0)
+            return Promise.resolve(true);
+        return new Promise(resolve => {
+            let settled = false;
+            const finish = (atBoundary) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.toolBoundaryWaiters.delete(check);
+                resolve(atBoundary);
+            };
+            const check = () => {
+                if (this.activeToolCalls.size === 0 || !this.isAlive())
+                    finish(this.activeToolCalls.size === 0);
+            };
+            const timer = setTimeout(() => finish(false), Math.max(0, timeoutMs));
+            timer.unref?.();
+            this.toolBoundaryWaiters.add(check);
+            // Close the subscribe/check race without guessing about elapsed time.
+            check();
+        });
+    }
+    recordAfterToolDelivery(state, activeToolCount, waitedMs) {
+        this.events.emit('monitor_delivery', {
+            status: state, monitorPolicy: 'after_tool', activeToolCount, waitedMs,
+        });
+        this.conversation.appendSafe({
+            kind: 'monitor.delivery', sessionGeneration: this.sessionGeneration,
+            acpSessionId: this.sessionId, source: 'fleet_monitor',
+            payload: { policy: 'after_tool', state, activeToolCount, waitedMs },
+        });
+    }
+    /**
+     * Monitor-only safe-boundary delivery. Steering is the interruption: this
+     * path never calls session/cancel and never resolves a pending permission.
+     */
+    async submitPromptAfterTool(text, options = {}) {
+        if (this.closing || !this.isAlive())
+            return turnResult(false, 'failed', this.lastError ?? 'ACP session is closing');
+        const startedAt = Date.now();
+        const initialToolCount = this.activeToolCalls.size;
+        if (!this.steeringSupported) {
+            this.recordAfterToolDelivery('unsupported', initialToolCount, 0);
+            const result = await this.submitPrompt(text, { ...options, interrupt: false, steer: false });
+            return {
+                ...result,
+                safeBoundary: { state: 'unsupported', waitedMs: 0, activeToolCount: initialToolCount },
+            };
+        }
+        if (initialToolCount === 0) {
+            this.recordAfterToolDelivery('direct', 0, 0);
+            const result = await this.steerPrompt(text);
+            return { ...result, safeBoundary: { state: 'direct', waitedMs: 0, activeToolCount: 0 } };
+        }
+        this.recordAfterToolDelivery('deferred', initialToolCount, 0);
+        const timeoutMs = this.options.afterToolBoundaryTimeoutMs ?? AFTER_TOOL_BOUNDARY_TIMEOUT_MS;
+        const deadline = startedAt + timeoutMs;
+        let atBoundary = false;
+        // Re-check after every wake: another authenticated tool event may have
+        // arrived before this continuation ran. Only an empty tracked set is safe.
+        while (this.activeToolCalls.size > 0) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0 || !(await this.waitForToolBoundary(remaining)))
+                break;
+        }
+        atBoundary = this.activeToolCalls.size === 0;
+        if (this.closing || !this.isAlive())
+            return turnResult(false, 'failed', this.lastError ?? 'ACP session closed during after_tool wait');
+        const waitedMs = Math.max(0, Date.now() - startedAt);
+        const state = atBoundary ? 'after_tool' : 'timeout';
+        const remainingToolCount = this.activeToolCalls.size;
+        this.recordAfterToolDelivery(state, remainingToolCount, waitedMs);
+        const result = await this.steerPrompt(text);
+        return {
+            ...result,
+            safeBoundary: { state, waitedMs, activeToolCount: remainingToolCount },
+        };
+    }
     /**
      * Accept responsibility for a prompt, then return. The turn itself may run
      * for minutes behind other queued turns; making an interactive caller wait
@@ -365,6 +508,10 @@ export class AcpSession {
             clearTimeout(pending.expiry);
         pending.resolve({ outcome: { outcome: 'selected', optionId } });
         const decision = chosen.kind.startsWith('reject') ? 'denied' : 'allowed';
+        if (decision === 'allowed')
+            this.allowPermission(pending.toolCallId, permissionId);
+        else
+            this.releasePermission(pending.toolCallId, permissionId);
         this.events.emit('permission', {
             turnId: this.activeTurn?.id,
             origin: this.activeTurn?.origin,
@@ -381,7 +528,7 @@ export class AcpSession {
             promptId: this.activeTurn?.id, turnId: this.activeTurn?.id,
             payload: { decision, decisionSource: 'manual', optionId },
         });
-        this.readiness = 'running';
+        this.readiness = this.pendingPermissions.size > 0 ? 'awaiting_permission' : 'running';
         return true;
     }
     /**
@@ -446,11 +593,12 @@ export class AcpSession {
             ? { outcome: { outcome: 'selected', optionId: rejectOption.optionId } }
             : { outcome: { outcome: 'cancelled' } });
         const settled = decision === 'denied' && !rejectOption ? 'cancelled' : decision;
+        this.releasePermission(pending.toolCallId, permissionId);
         this.events.emit('permission', {
             turnId: this.activeTurn?.id,
             origin: this.activeTurn?.origin,
             permissionId,
-            toolCallId: pending.toolCallId,
+            toolCallId: pending.eventToolCallId,
             status: 'completed',
             decision: settled === 'expired' ? 'cancelled' : settled,
             decisionSource: 'automatic',
@@ -462,7 +610,7 @@ export class AcpSession {
             kind: 'permission.resolved', sessionGeneration: this.sessionGeneration,
             acpSessionId: this.sessionId, permissionId,
             promptId: this.activeTurn?.id, turnId: this.activeTurn?.id,
-            toolCallId: pending.toolCallId,
+            toolCallId: pending.eventToolCallId,
             payload: {
                 decision: settled, decisionSource: 'automatic',
                 ...(policy ? { policy } : {}), reason,
@@ -476,6 +624,7 @@ export class AcpSession {
         return this.exit;
     }
     async close() {
+        this.closing = true;
         if (this.cancelEscalation)
             clearTimeout(this.cancelEscalation);
         this.cancelEscalation = undefined;
@@ -484,6 +633,7 @@ export class AcpSession {
         this.controllerGrace = undefined;
         for (const [permissionId, pending] of [...this.pendingPermissions])
             this.settlePendingAutomatically(permissionId, pending, 'cancelled', undefined, 'the session closed while this request was pending');
+        this.releaseAllTools();
         if (this.sessionId && this.capabilities?.sessionCapabilities?.close != null) {
             await this.connection.agent.request(acp.methods.agent.session.close, { sessionId: this.sessionId }).catch(() => undefined);
         }
@@ -627,6 +777,7 @@ export class AcpSession {
             return turnResult(false, 'failed', this.lastError, this.activeTurn?.id === turnId ? this.activeTurn.output : undefined);
         }
         finally {
+            this.releaseAllTools();
             if (this.activeTurn?.id === turnId) {
                 if (this.cancelEscalation)
                     clearTimeout(this.cancelEscalation);
@@ -667,9 +818,19 @@ export class AcpSession {
             }
             return undefined;
         };
+        const toolCallId = params.toolCall.toolCallId;
+        const permissionId = randomUUID();
+        // Permission is part of the tool lifecycle. Reserve before any policy or
+        // human decision so a monitor wake cannot slip between request and answer.
+        this.reservePermission(toolCallId, permissionId);
         if (this.options.permissions.approval === 'allow' && this.withinAutomaticBoundary(params)) {
             const option = choose(['allow_always', 'allow_once']);
-            return Promise.resolve(this.settleAutomatically(params, option, 'allowed', 'permissions.approval=allow', `the request is inside the ${this.options.permissions.filesystem} boundary`));
+            const response = this.settleAutomatically(params, option, 'allowed', 'permissions.approval=allow', `the request is inside the ${this.options.permissions.filesystem} boundary`);
+            if (option)
+                this.allowPermission(toolCallId, permissionId);
+            else
+                this.releasePermission(toolCallId, permissionId);
+            return Promise.resolve(response);
         }
         // A live grace window still counts as attended: the controller may be
         // mid-reconnect, and denying instantly is exactly what the grace prevents.
@@ -680,11 +841,12 @@ export class AcpSession {
             // a decision no human made, so one unattended denial would silently disable
             // the tool for the rest of the session.
             const option = choose(['reject_once', 'reject_always']);
-            return Promise.resolve(this.settleAutomatically(params, option, 'denied', unattended ? 'permissions.unattended=deny' : 'permissions.approval=deny', unattended
+            const response = this.settleAutomatically(params, option, 'denied', unattended ? 'permissions.unattended=deny' : 'permissions.approval=deny', unattended
                 ? 'no controller is attached, so the request cannot be shown to anyone'
-                : 'the role denies every permission request by policy'));
+                : 'the role denies every permission request by policy');
+            this.releasePermission(toolCallId, permissionId);
+            return Promise.resolve(response);
         }
-        const permissionId = randomUUID();
         const timeoutMs = this.options.permissionTimeoutMs ?? PERMISSION_TIMEOUT_MS;
         const expiresAt = new Date(Date.now() + timeoutMs).toISOString();
         this.readiness = 'awaiting_permission';
@@ -723,8 +885,8 @@ export class AcpSession {
         return new Promise(resolve => {
             const pending = {
                 options: params.options, resolve,
-                toolCallId: scheduledTurn(this.activeTurn)
-                    ? 'scheduled-loop-tool' : params.toolCall.toolCallId,
+                toolCallId,
+                eventToolCallId: scheduledTurn(this.activeTurn) ? 'scheduled-loop-tool' : toolCallId,
             };
             pending.expiry = setTimeout(() => {
                 this.settlePendingAutomatically(permissionId, pending, 'expired', undefined, `no decision arrived within ${Math.round(timeoutMs / 1000)}s`);
@@ -832,6 +994,10 @@ export class AcpSession {
                     title: scheduled ? 'scheduled-loop tool' : update.title,
                     status: update.status,
                 });
+                if (TERMINAL_TOOL_STATUSES.has(update.status ?? ''))
+                    this.releaseTool(update.toolCallId);
+                else
+                    this.reserveTool(update.toolCallId);
                 break;
             case 'tool_call_update':
                 this.events.emit('tool_update', {
@@ -841,6 +1007,10 @@ export class AcpSession {
                     title: scheduled ? 'scheduled-loop tool' : update.title ?? undefined,
                     status: update.status ?? undefined,
                 });
+                if (TERMINAL_TOOL_STATUSES.has(update.status ?? ''))
+                    this.releaseTool(update.toolCallId);
+                else if (update.status !== undefined)
+                    this.reserveTool(update.toolCallId);
                 break;
             default:
                 break;
@@ -864,7 +1034,10 @@ export class AcpSession {
     }
     /** Normalize every ACP update losslessly into the durable ledger. */
     recordConversationUpdate(update, scheduled, commentary = false) {
-        const normalized = normalizeSessionUpdate(update, scheduled ? { redactText: SCHEDULED_LOOP_REDACTION }
+        const normalized = normalizeSessionUpdate(update, scheduled ? {
+            redactText: SCHEDULED_LOOP_REDACTION,
+            redactToolCallId: 'scheduled-loop-tool',
+        }
             : commentary ? { redactText: OWNER_COMMENTARY_REDACTION } : {});
         this.conversation.appendSafe({
             kind: normalized.kind,

package/dist/session/arbiter.d.ts

@@ -27,6 +27,11 @@ export declare class RoleTurnArbiter implements SessionHandle {
     private track;
     queuePrompt(text: string, options?: SubmitPromptOptions): Promise<QueuedPrompt>;
     submitPrompt(text: string, options?: SubmitPromptOptions): Promise<TurnResult>;
+    /**
+     * Do not hold `exclusive` while ACP waits for a tool boundary: permission
+     * answers and explicit interrupts must remain able to pass immediately.
+     */
+    submitPromptAfterTool(text: string, options?: SubmitPromptOptions): Promise<TurnResult>;
     tryScheduled(text: string, origin: Extract<PromptOrigin, {
         kind: 'scheduled-loop';
     }>, beforeQueue?: () => void | Promise<void>): Promise<ScheduledAttempt>;

package/dist/session/arbiter.js

@@ -32,6 +32,14 @@ export class RoleTurnArbiter {
     async submitPrompt(text, options = {}) {
         return (await this.queuePrompt(text, options)).completion;
     }
+    /**
+     * Do not hold `exclusive` while ACP waits for a tool boundary: permission
+     * answers and explicit interrupts must remain able to pass immediately.
+     */
+    submitPromptAfterTool(text, options = {}) {
+        return this.session.submitPromptAfterTool?.(text, options)
+            ?? this.session.submitPrompt(text, { ...options, interrupt: false, steer: false });
+    }
     async tryScheduled(text, origin, beforeQueue) {
         // Give owner/console/I/O callbacks already ready in this event-loop turn a
         // chance to claim the arbiter first. Scheduled work is best-effort; humans

package/dist/session/conversation-normalizer.d.ts

@@ -23,6 +23,12 @@ export interface NormalizeOptions {
      * digest. Used for scheduled-loop turns whose output must not be retained.
      */
     redactText?: string;
+    /**
+     * Replace ACP tool-call IDs in both the normalized event correlation field
+     * and payload. The caller may still use the original update for in-memory
+     * lifecycle tracking without persisting its private identifier.
+     */
+    redactToolCallId?: string;
 }
 export interface NormalizedUpdate {
     kind: ConversationEventKind;

package/dist/session/conversation-normalizer.js

@@ -203,9 +203,10 @@ function normalizeToolContent(raw, redact) {
         }
     });
 }
-function toolUpsert(update, snapshot, redact) {
+function toolUpsert(update, snapshot, options) {
+    const redact = options.redactText;
     const payload = {
-        toolCallId: asString(update.toolCallId) ?? '',
+        toolCallId: options.redactToolCallId ?? asString(update.toolCallId) ?? '',
         snapshot,
     };
     if (asString(update.title) !== undefined)
@@ -271,7 +272,7 @@ export function normalizeSessionUpdate(update, options = {}) {
         }
         case 'tool_call':
         case 'tool_call_update': {
-            const payload = toolUpsert(raw, raw.sessionUpdate === 'tool_call', redact);
+            const payload = toolUpsert(raw, raw.sessionUpdate === 'tool_call', options);
             return withMeta({
                 kind: 'tool.upsert', payload,
                 ...(payload.toolCallId ? { toolCallId: payload.toolCallId } : {}),

package/dist/session/conversation-types.d.ts

@@ -7,7 +7,7 @@ import type { PromptOrigin, TurnCancellationSource, TurnOutcome } from './types.
  * file touches the wire: ACP updates are reduced into these shapes by the
  * normalizer, and the store (phase 1) assigns `seq`/`eventId`/timestamps.
  */
-export type ConversationEventKind = 'prompt.admitted' | 'prompt.started' | 'prompt.interrupt_requested' | 'message.chunk' | 'message.replace' | 'thought.chunk' | 'thought.replace' | 'plan.replace' | 'tool.upsert' | 'tool.content_chunk' | 'permission.requested' | 'permission.resolved' | 'usage.updated' | 'turn.state' | 'turn.completed' | 'session.state' | 'session.info' | 'capabilities.updated' | 'error'
+export type ConversationEventKind = 'prompt.admitted' | 'prompt.started' | 'prompt.interrupt_requested' | 'message.chunk' | 'message.replace' | 'thought.chunk' | 'thought.replace' | 'plan.replace' | 'tool.upsert' | 'tool.content_chunk' | 'permission.requested' | 'permission.resolved' | 'monitor.delivery' | 'usage.updated' | 'turn.state' | 'turn.completed' | 'session.state' | 'session.info' | 'capabilities.updated' | 'error'
 /** A well-formed ACP update this version cannot represent. Bounded, never a crash. */
  | 'unsupported';
 /** Where a conversation record came from. Typed provenance, never prompt text. */
@@ -178,6 +178,13 @@ export interface PermissionResolvedPayload {
     policy?: string;
     reason?: string;
 }
+/** Body-free monitor evidence. Tool ids, titles, output, and wake text are never stored. */
+export interface MonitorDeliveryPayload {
+    policy: 'after_tool';
+    state: 'deferred' | 'direct' | 'after_tool' | 'timeout' | 'unsupported';
+    activeToolCount: number;
+    waitedMs: number;
+}
 export interface TurnStatePayload {
     state: 'queued' | 'running' | 'awaiting_permission' | 'interrupt_requested';
 }
@@ -201,7 +208,7 @@ export interface BoundedJson {
     digest?: string;
     redacted?: true;
 }
-export type ConversationPayload = MessageChunkPayload | ThoughtChunkPayload | PlanReplacePayload | ToolUpsertPayload | UsageUpdatedPayload | SessionStatePayload | SessionInfoPayload | CapabilitiesUpdatedPayload | UnsupportedPayload | PromptAdmittedPayload | PromptStartedPayload | PromptInterruptRequestedPayload | PermissionRequestedPayload | PermissionResolvedPayload | TurnStatePayload | TurnCompletedPayload | SessionLifecyclePayload | ErrorPayload;
+export type ConversationPayload = MessageChunkPayload | ThoughtChunkPayload | PlanReplacePayload | ToolUpsertPayload | UsageUpdatedPayload | SessionStatePayload | SessionInfoPayload | CapabilitiesUpdatedPayload | UnsupportedPayload | PromptAdmittedPayload | PromptStartedPayload | PromptInterruptRequestedPayload | PermissionRequestedPayload | PermissionResolvedPayload | TurnStatePayload | TurnCompletedPayload | MonitorDeliveryPayload | SessionLifecyclePayload | ErrorPayload;
 export interface ConversationEventV1 {
     schemaVersion: 1;
     roleId: string;

package/dist/session/types.d.ts

@@ -49,6 +49,12 @@ export interface TurnResult {
     cancellationSource?: TurnCancellationSource;
     /** Final assistant text captured structurally by a backend, when available. */
     output?: string;
+    /** Body-free monitor safe-boundary disposition, when this was an after_tool wake. */
+    safeBoundary?: {
+        state: 'direct' | 'after_tool' | 'timeout' | 'unsupported';
+        waitedMs: number;
+        activeToolCount: number;
+    };
 }
 /**
  * Why a control operation failed. The distinctions exist because collapsing
@@ -137,7 +143,7 @@ export interface SessionSnapshot {
         nativeMode: string;
     };
 }
-export type SessionEventKind = 'state' | 'agent_text' | 'thought' | 'tool_call' | 'tool_update' | 'permission' | 'turn_stop' | 'error';
+export type SessionEventKind = 'state' | 'agent_text' | 'thought' | 'tool_call' | 'tool_update' | 'permission' | 'monitor_delivery' | 'turn_stop' | 'error';
 /** What a settled permission request resolved to. */
 export type PermissionDecision = 'allowed' | 'denied' | 'cancelled';
 export interface SessionEvent {
@@ -178,6 +184,10 @@ export interface SessionEvent {
     reason?: string;
     /** The option actually selected, when one was. */
     optionId?: string;
+    /** Body-free evidence for monitor safe-boundary delivery. */
+    monitorPolicy?: 'after_tool';
+    activeToolCount?: number;
+    waitedMs?: number;
 }
 export interface ConversationHandlePage {
     events: ConversationEventV1[];
@@ -206,6 +216,8 @@ export interface SessionHandle {
     queuePrompt(text: string, options?: SubmitPromptOptions): Promise<QueuedPrompt>;
     /** Queue a prompt and wait for its terminal result. */
     submitPrompt(text: string, options?: SubmitPromptOptions): Promise<TurnResult>;
+    /** Monitor-only ACP safe-boundary delivery. Never implies human/control cancellation. */
+    submitPromptAfterTool?(text: string, options?: SubmitPromptOptions): Promise<TurnResult>;
     interrupt(source?: TurnCancellationSource): Promise<void>;
     respondPermission(permissionId: string, optionId: string): boolean;
     /** Generation-bound browser decision; stale/settled/invalid all fail closed. */

package/dist/web/fleet-config-service.js

@@ -1,14 +1,15 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { chmodSync, existsSync, lstatSync, readFileSync, rmSync, } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { stringify } from 'yaml';
 import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
 import { loadConfig } from '../config.js';
 import { parseFleetDocument } from '../config-yaml.js';
 import { defaultConfigPath } from '../paths.js';
 import { FleetError } from '../application/errors.js';
+import { redactSourceSecrets, renderModelOntoSource } from './yaml-document-edit.js';
 export const REDACTED_ENV_VALUE = '__OURS_FLEET_SECRET_REDACTED__';
 const MAX_CONFIG_BYTES = 256 * 1024;
+const DIFF_CONTEXT_LINES = 3;
 const emptyReport = () => ({ ok: true, checks: [] });
 export class FleetConfigService {
     path;
@@ -32,13 +33,13 @@ export class FleetConfigService {
         this.assertRevision(baseRevision, currentSource);
         const current = parseFleetDocument(this.path, currentSource, 'strict').value;
         const restored = restoreRedactions(assertModel(model), current);
-        const source = serialize(restored);
-        const candidate = this.validateCandidate(source);
-        const [redactedCurrent, redactedNext] = [redactModel(current), redactModel(restored)];
+        const nextSource = render(currentSource, restored);
+        const candidate = this.validateCandidate(nextSource);
+        const redactedNext = redactModel(restored);
         const preflight = await this.preflight(candidate.path).finally(candidate.remove);
         return {
             valid: true, revision: digest(currentSource), normalizedModel: redactedNext.model,
-            diff: exactDiff(serialize(redactedCurrent.model), serialize(redactedNext.model)),
+            diff: sourceDiff(currentSource, nextSource),
             redactions: redactedNext.paths,
             impact: restartImpact(current, restored), preflight,
         };
@@ -49,13 +50,12 @@ export class FleetConfigService {
             this.assertRevision(baseRevision, currentSource);
             const current = parseFleetDocument(this.path, currentSource, 'strict').value;
             const restored = restoreRedactions(assertModel(model), current);
-            const nextSource = serialize(restored);
+            const nextSource = render(currentSource, restored);
             const candidate = this.validateCandidate(nextSource);
             const preflight = await this.preflight(candidate.path).finally(candidate.remove);
             // The lock coordinates trusted web/agent writers. An operator's editor does
             // not take it, so re-check immediately before replacement as well.
             this.assertRevision(baseRevision, this.readSource());
-            const redactedCurrent = redactModel(current);
             const redactedNext = redactModel(restored);
             let backup;
             if (existsSync(this.path)) {
@@ -67,7 +67,7 @@ export class FleetConfigService {
             return {
                 saved: true, valid: true, revision: digest(currentSource), newRevision: digest(nextSource),
                 normalizedModel: redactedNext.model,
-                diff: exactDiff(serialize(redactedCurrent.model), serialize(redactedNext.model)),
+                diff: sourceDiff(currentSource, nextSource),
                 redactions: redactedNext.paths, impact: restartImpact(current, restored), preflight,
                 backup,
             };
@@ -110,8 +110,17 @@ function assertModel(value) {
         throw new FleetError('invalid_request', 'model must be a JSON object');
     return structuredClone(value);
 }
-function serialize(model) {
-    return stringify(model, { lineWidth: 0, sortMapEntries: false });
+/**
+ * Apply the edited model onto the user's own document rather than re-serializing
+ * it, so comments, key order and formatting outside the edit survive the save.
+ */
+function render(currentSource, model) {
+    try {
+        return renderModelOntoSource(currentSource, model);
+    }
+    catch (error) {
+        throw new FleetError('invalid_request', error.message);
+    }
 }
 function digest(source) {
     return createHash('sha256').update(source).digest('hex');
@@ -173,12 +182,39 @@ function restoreRedactions(next, current) {
         }
     return next;
 }
-function exactDiff(before, after) {
-    if (before === after)
+/**
+ * Unified-style diff of the real file text with env secrets masked. Common
+ * leading/trailing lines are trimmed, so a surgical edit reviews as a small
+ * hunk instead of the whole configuration twice.
+ */
+function sourceDiff(beforeSource, afterSource) {
+    const before = splitLines(redactSourceSecrets(beforeSource, REDACTED_ENV_VALUE));
+    const after = splitLines(redactSourceSecrets(afterSource, REDACTED_ENV_VALUE));
+    let head = 0;
+    while (head < before.length && head < after.length && before[head] === after[head])
+        head += 1;
+    let tail = 0;
+    while (tail < before.length - head && tail < after.length - head
+        && before[before.length - 1 - tail] === after[after.length - 1 - tail])
+        tail += 1;
+    if (head === before.length && head === after.length)
         return '';
-    return ['--- fleet.yaml (current)', '+++ fleet.yaml (proposed)',
-        ...before.trimEnd().split('\n').map(line => `-${line}`),
-        ...after.trimEnd().split('\n').map(line => `+${line}`), ''].join('\n');
+    const start = Math.max(0, head - DIFF_CONTEXT_LINES);
+    const trailing = Math.min(DIFF_CONTEXT_LINES, tail);
+    const beforeSpan = before.length - tail + trailing - start;
+    const afterSpan = after.length - tail + trailing - start;
+    return [
+        '--- fleet.yaml (current)', '+++ fleet.yaml (proposed)',
+        `@@ -${start + 1},${beforeSpan} +${start + 1},${afterSpan} @@`,
+        ...before.slice(start, head).map(line => ` ${line}`),
+        ...before.slice(head, before.length - tail).map(line => `-${line}`),
+        ...after.slice(head, after.length - tail).map(line => `+${line}`),
+        ...before.slice(before.length - tail, before.length - tail + trailing).map(line => ` ${line}`),
+        '',
+    ].join('\n');
+}
+function splitLines(source) {
+    return source.replace(/\n$/, '').split('\n');
 }
 function objectKeys(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? Object.keys(value) : [];

package/dist/web/runtime.js

@@ -19,7 +19,9 @@ import { AuditSink } from './audit.js';
 import { FleetEventBus } from './events.js';
 import { buildWebServer } from './server.js';
 import { FleetConfigService } from './fleet-config-service.js';
-import { deriveTopology } from './topology.js';
+import { mergeTopology } from './topology-model.js';
+import { TopologyDraftStore } from './topology-draft-store.js';
+import { TopologyPromoteService } from './topology-promote.js';
 import { doctor } from '../doctor.js';
 import { TerminalBridgeManager } from './terminal/bridge.js';
 import { acquireWebServerLock } from './lock.js';
@@ -148,11 +150,16 @@ export async function startWebConsole(options) {
         configPath: options.configPath,
         preflight: path => doctor({ configPath: path, yamlMode: 'strict' }),
     });
+    const topologyDrafts = new TopologyDraftStore({ dir: webDir });
+    const readTopology = async () => mergeTopology(loadConfig(options.configPath), await query.list(), topologyDrafts.read());
+    const topologyPromote = new TopologyPromoteService({
+        drafts: topologyDrafts, configuration, topology: readTopology,
+    });
     let server;
     try {
         server = await buildWebServer({
             query, repository, logs, commands, creation, removal, audit, events, watchdogs, configuration,
-            topology: async () => deriveTopology(loadConfig(options.configPath), await query.list()),
+            topology: readTopology, topologyDrafts, topologyPromote,
             terminalUpgrade: terminalAvailable
                 ? async (socket, _request, roleId, _ticket, hello) => terminals.connect(socket, roleId, hello)
                 : undefined,

package/dist/web/server.d.ts

@@ -11,7 +11,9 @@ import { AuditSink } from './audit.js';
 import { WebAuth } from './auth.js';
 import { FleetEventBus } from './events.js';
 import type { FleetConfigService } from './fleet-config-service.js';
-import type { TopologySnapshot } from './topology.js';
+import type { MergedTopology } from './topology-model.js';
+import type { TopologyDraftStore } from './topology-draft-store.js';
+import type { TopologyPromoteService } from './topology-promote.js';
 import type { RoleRemovalService } from '../application/role-removal-service.js';
 export interface WebServices {
     query: FleetQueryService;
@@ -24,7 +26,9 @@ export interface WebServices {
     events?: FleetEventBus;
     watchdogs?: WatchdogQueryService;
     configuration?: FleetConfigService;
-    topology?: () => Promise<TopologySnapshot>;
+    topology?: () => Promise<MergedTopology>;
+    topologyDrafts?: TopologyDraftStore;
+    topologyPromote?: TopologyPromoteService;
     removal?: RoleRemovalService;
     terminalUpgrade?: (socket: WebSocket, request: FastifyRequest, roleId: string, ticket: string, hello: Record<string, unknown>) => Promise<void>;
 }