@agentxm/workspace-operations 0.28.5 → 0.28.6

package/dist/src/index.d.ts

@@ -16,7 +16,7 @@ export { AtomicityClassSchema, OperationOutcomeSchema, OperationPhaseSchema, Uni
 export type { AtomicityClass, MakeOperationResolutionArgs, OperationAtomicity, OperationBlock, OperationFootprintEntry, OperationInterruption, OperationOutcome, OperationPhase, OperationRecovery, OperationResolution, ResolvedUnit, UnitDisposition, UnitState, UnitStateCounts, } from "./plan/operation-resolution.js";
 export { OperationJournal, appendResolvedUnit, appendStartedUnit, recordJournalPhase, getOperationJournal, makeOperationJournal, recordOperationJournal, updateOperationJournal, type OperationJournalService, type OperationJournalState, } from "./plan/operation-journal.js";
 export { applyPlan, type ApplyPlanOptions, type OperationHandler } from "./plan/apply-plan.js";
-export { OperationLifecycle, makeOperationLifecycle, publishLifecycleEvent, publishPhaseStarted, subscribeToLifecycle, type OperationLifecycleEvent, type OperationLifecycleService, } from "./plan/operation-events.js";
+export { CurrentOperationUnit, OperationEventSchema, OperationLifecycle, OperationModeSchema, ProgressUnitSchema, SettledOutcomeSchema, awaitDrained, lifecycleEvents, makeOperationLifecycle, makeThrottledUnitProgress, observeUnit, publishOperationEvent, publishPhaseStarted, publishUnitProgress, publishWaitEnded, publishWaiting, settleOperation, subscribeLossless, type ObservedUnit, type OperationEvent, type OperationEventEncoded, type OperationEventInput, type OperationLifecycleService, type OperationMode, type ProgressUnit, type SettledOutcome, } from "./plan/operation-events.js";
 export { ApprovalRecoveryMissing, CandidateFingerprintFailed, OPERATION_ERROR_CATEGORIES, OperationErrorCategorySchema, PlanInteractionFailed, STALE_CANDIDATE_DETAIL, StaleExecutionCandidate, StepFailure, type OperationErrorCategory, } from "./plan/errors.js";
 export { previewOrApplyPlan } from "./plan/resolve-plan.js";
 export { ResolvePlanInteraction, type ApplyConfirmation, type ResolvePlanInteractionService, } from "./plan/resolve-plan-interaction.js";

package/dist/src/index.js

@@ -19,7 +19,8 @@ export { AtomicityClassSchema, OperationOutcomeSchema, OperationPhaseSchema, Uni
 export { OperationJournal, appendResolvedUnit, appendStartedUnit, recordJournalPhase, getOperationJournal, makeOperationJournal, recordOperationJournal, updateOperationJournal, } from "./plan/operation-journal.js";
 // Apply plan + operation handler registry
 export { applyPlan } from "./plan/apply-plan.js";
-export { OperationLifecycle, makeOperationLifecycle, publishLifecycleEvent, publishPhaseStarted, subscribeToLifecycle, } from "./plan/operation-events.js";
+// Operation lifecycle events — the live contract every observer subscribes to.
+export { CurrentOperationUnit, OperationEventSchema, OperationLifecycle, OperationModeSchema, ProgressUnitSchema, SettledOutcomeSchema, awaitDrained, lifecycleEvents, makeOperationLifecycle, makeThrottledUnitProgress, observeUnit, publishOperationEvent, publishPhaseStarted, publishUnitProgress, publishWaitEnded, publishWaiting, settleOperation, subscribeLossless, } from "./plan/operation-events.js";
 // Serialized error vocabulary and the plan-family tagged errors.
 export { ApprovalRecoveryMissing, CandidateFingerprintFailed, OPERATION_ERROR_CATEGORIES, OperationErrorCategorySchema, PlanInteractionFailed, STALE_CANDIDATE_DETAIL, StaleExecutionCandidate, StepFailure, } from "./plan/errors.js";
 // Interactive preview/apply orchestration over the workspace read model.

package/dist/src/plan/operation-events.d.ts

@@ -1,62 +1,272 @@
 /**
- * Operation lifecycle events.
+ * Operation lifecycle events — the one live contract between a running
+ * operation and everything that observes it.
  *
- * Execution publishes typed lifecycle events — phase transitions, unit state
- * transitions, and waiting reasons, each with a monotonic timestamp — to an
- * invocation-scoped broadcast. Observers (renderers, machine progress,
- * telemetry) subscribe; none of them controls execution or keeps a second
- * account of what happened. Publishing is a no-op when no broadcast is
- * provided.
+ * An operation publishes schema-backed, typed lifecycle events (operation and
+ * phase transitions, unit start, progress, and settlement, waiting reasons, and
+ * exactly one terminal settled event) to an invocation-scoped broadcast.
+ * Observers — the human live frame, the machine event writer, telemetry —
+ * subscribe independently; none of them controls execution or keeps a second
+ * account of what happened. Events carry identifiers, labels, counts, and
+ * states, never presentation phrases; wording belongs to the observer.
  *
- * @experimental This API is unstable and may change without notice.
+ * Broadcast policy: the publisher is unbounded and never applies backpressure.
+ * Lifecycle events are discrete state transitions, so their count is bounded
+ * by the planned units; continuous measurements such as downloaded bytes are
+ * throttled at the producer and never published per chunk. Every operation
+ * ends with a settled event, and settled output waits on the drain latch that
+ * lossless subscribers complete. Publishing is a no-op when no broadcast is
+ * provided.
  */
 import * as Effect from "effect/Effect";
+import * as Latch from "effect/Latch";
 import * as PubSub from "effect/PubSub";
+import * as Schema from "effect/Schema";
 import type * as Scope from "effect/Scope";
 import * as ServiceMap from "effect/Context";
-import type { BlockingClass } from "./plan.js";
-import type { OperationPhase, UnitState } from "./operation-resolution.js";
-export type OperationLifecycleEvent = {
-    readonly _tag: "PhaseStarted";
-    readonly phase: OperationPhase;
-    readonly atNanos: bigint;
-} | {
-    readonly _tag: "UnitStarted";
-    readonly unitId: string;
-    readonly label: string;
-    readonly index: number;
-    readonly total: number;
-    readonly atNanos: bigint;
-} | {
-    readonly _tag: "UnitResolved";
-    readonly unitId: string;
-    readonly label: string;
-    readonly state: UnitState;
-    readonly index: number;
-    readonly total: number;
-    readonly atNanos: bigint;
-} | {
-    readonly _tag: "Waiting";
-    readonly blockingClass: BlockingClass;
-    readonly subject: string;
-    readonly detail: string;
-    readonly atNanos: bigint;
-};
+import * as Stream from "effect/Stream";
+import { BlockingClassSchema } from "./plan.js";
+import { OperationPhaseSchema } from "./operation-resolution.js";
+export declare const OperationModeSchema: Schema.Literals<readonly ["preview", "apply"]>;
+export type OperationMode = typeof OperationModeSchema.Type;
+/**
+ * Terminal outcome carried by the settled event: a plan-family outcome, or
+ * `completed` for an operation without a plan-family resolution (a read, an
+ * upgrade step sequence, an authentication flow) that finished successfully.
+ */
+export declare const SettledOutcomeSchema: Schema.Literals<readonly ["previewed", "applied", "no-op", "partial", "failed", "blocked", "cancelled", "interrupted", "completed"]>;
+export type SettledOutcome = typeof SettledOutcomeSchema.Type;
+export declare const ProgressUnitSchema: Schema.Literals<readonly ["bytes", "files", "items"]>;
+export type ProgressUnit = typeof ProgressUnitSchema.Type;
+export declare const OperationStartedEventSchema: Schema.Struct<{
+    readonly _tag: Schema.tag<"OperationStarted">;
+    readonly operationId: Schema.String;
+    readonly name: Schema.String;
+    readonly mode: Schema.Literals<readonly ["preview", "apply"]>;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>;
+export declare const PhaseStartedEventSchema: Schema.Struct<{
+    readonly _tag: Schema.tag<"PhaseStarted">;
+    readonly phase: Schema.Literals<readonly ["resolution", "planning", "preview", "confirmation", "validation", "apply", "restoration"]>;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>;
+export declare const UnitStartedEventSchema: Schema.Struct<{
+    readonly _tag: Schema.tag<"UnitStarted">;
+    readonly unitId: Schema.String;
+    readonly label: Schema.String;
+    readonly index: Schema.Number;
+    readonly total: Schema.optional<Schema.Number>;
+    readonly parentUnitId: Schema.optional<Schema.String>;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>;
+export declare const UnitProgressEventSchema: Schema.Struct<{
+    readonly _tag: Schema.tag<"UnitProgress">;
+    readonly unitId: Schema.String;
+    readonly done: Schema.Number;
+    readonly total: Schema.optional<Schema.Number>;
+    readonly unit: Schema.Literals<readonly ["bytes", "files", "items"]>;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>;
+export declare const UnitResolvedEventSchema: Schema.Struct<{
+    readonly _tag: Schema.tag<"UnitResolved">;
+    readonly unitId: Schema.String;
+    readonly label: Schema.String;
+    readonly state: Schema.Literals<readonly ["planned", "ready", "committed", "unchanged", "failed", "rolled-back", "blocked", "skipped", "cancelled", "interrupted"]>;
+    readonly index: Schema.Number;
+    readonly total: Schema.optional<Schema.Number>;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>;
+export declare const WaitingEventSchema: Schema.Struct<{
+    readonly _tag: Schema.tag<"Waiting">;
+    readonly blockingClass: Schema.Literals<readonly ["approval-required", "override-required", "precondition-unmet", "dependency-failed", "dependency-cycle", "stale-candidate", "policy-excluded", "resource-conflict", "external-blocked", "operation-aborted"]>;
+    readonly subject: Schema.String;
+    readonly detail: Schema.String;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>;
+export declare const WaitEndedEventSchema: Schema.Struct<{
+    readonly _tag: Schema.tag<"WaitEnded">;
+    readonly subject: Schema.String;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>;
+export declare const OperationSettledEventSchema: Schema.Struct<{
+    readonly _tag: Schema.tag<"OperationSettled">;
+    readonly outcome: Schema.Literals<readonly ["previewed", "applied", "no-op", "partial", "failed", "blocked", "cancelled", "interrupted", "completed"]>;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>;
+/**
+ * The published lifecycle event union. `seq` is strictly increasing within one
+ * operation; `atMs` is wall-clock milliseconds. Exactly one `OperationSettled`
+ * event ends every operation.
+ */
+export declare const OperationEventSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly _tag: Schema.tag<"OperationStarted">;
+    readonly operationId: Schema.String;
+    readonly name: Schema.String;
+    readonly mode: Schema.Literals<readonly ["preview", "apply"]>;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"PhaseStarted">;
+    readonly phase: Schema.Literals<readonly ["resolution", "planning", "preview", "confirmation", "validation", "apply", "restoration"]>;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"UnitStarted">;
+    readonly unitId: Schema.String;
+    readonly label: Schema.String;
+    readonly index: Schema.Number;
+    readonly total: Schema.optional<Schema.Number>;
+    readonly parentUnitId: Schema.optional<Schema.String>;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"UnitProgress">;
+    readonly unitId: Schema.String;
+    readonly done: Schema.Number;
+    readonly total: Schema.optional<Schema.Number>;
+    readonly unit: Schema.Literals<readonly ["bytes", "files", "items"]>;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"UnitResolved">;
+    readonly unitId: Schema.String;
+    readonly label: Schema.String;
+    readonly state: Schema.Literals<readonly ["planned", "ready", "committed", "unchanged", "failed", "rolled-back", "blocked", "skipped", "cancelled", "interrupted"]>;
+    readonly index: Schema.Number;
+    readonly total: Schema.optional<Schema.Number>;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"Waiting">;
+    readonly blockingClass: Schema.Literals<readonly ["approval-required", "override-required", "precondition-unmet", "dependency-failed", "dependency-cycle", "stale-candidate", "policy-excluded", "resource-conflict", "external-blocked", "operation-aborted"]>;
+    readonly subject: Schema.String;
+    readonly detail: Schema.String;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"WaitEnded">;
+    readonly subject: Schema.String;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>, Schema.Struct<{
+    readonly _tag: Schema.tag<"OperationSettled">;
+    readonly outcome: Schema.Literals<readonly ["previewed", "applied", "no-op", "partial", "failed", "blocked", "cancelled", "interrupted", "completed"]>;
+    readonly seq: Schema.Number;
+    readonly atMs: Schema.Number;
+}>]>;
+export type OperationEvent = typeof OperationEventSchema.Type;
+export type OperationEventEncoded = typeof OperationEventSchema.Encoded;
+/** Fields the service fills in for every event it publishes. */
+export type OperationEventInput = (seq: number, atMs: number) => OperationEvent;
 export interface OperationLifecycleService {
-    readonly mode: "preview" | "apply";
-    readonly pubsub: PubSub.PubSub<OperationLifecycleEvent>;
+    readonly operationId: string;
+    readonly name: string;
+    readonly mode: OperationMode;
+    /** Unbounded, invocation-scoped broadcast; subscribe before the operation runs. */
+    readonly events: PubSub.PubSub<OperationEvent>;
+    /** Publish one event; the service assigns `seq` and `atMs` atomically. */
+    readonly publish: (make: OperationEventInput) => Effect.Effect<void>;
+    /** Next index for a unit whose caller has no planned index. */
+    readonly nextUnitIndex: Effect.Effect<number>;
+    /** Publish the terminal event once; later calls are no-ops. */
+    readonly settle: (outcome: SettledOutcome) => Effect.Effect<void>;
+    /** Whether the terminal event was published. */
+    readonly settled: Effect.Effect<boolean>;
+    /** Opens when the operation settled and every registered lossless subscriber acknowledged. */
+    readonly drained: Latch.Latch;
+    /**
+     * Register a subscriber that must observe every event through settlement.
+     * Returns the acknowledgement; run it under `Effect.ensuring` so
+     * interruption also acknowledges.
+     */
+    readonly registerLossless: Effect.Effect<Effect.Effect<void>>;
 }
 declare const OperationLifecycle_base: ServiceMap.ServiceClass<OperationLifecycle, "@agentxm/workspace-operations/plan/operation-events/OperationLifecycle", OperationLifecycleService>;
 export declare class OperationLifecycle extends OperationLifecycle_base {
 }
+export declare const makeOperationLifecycle: (args: {
+    readonly name: string;
+    readonly mode: OperationMode;
+}) => Effect.Effect<OperationLifecycleService>;
 /** Publish one lifecycle event. No-op when no broadcast is provided. */
-export declare const publishLifecycleEvent: (make: (atNanos: bigint) => OperationLifecycleEvent) => Effect.Effect<void>;
-export declare const publishPhaseStarted: (phase: OperationPhase) => Effect.Effect<void>;
+export declare const publishOperationEvent: (make: OperationEventInput) => Effect.Effect<void>;
+export declare const publishPhaseStarted: (phase: typeof OperationPhaseSchema.Type) => Effect.Effect<void>;
+export declare const publishWaiting: (wait: {
+    readonly blockingClass: typeof BlockingClassSchema.Type;
+    readonly subject: string;
+    readonly detail: string;
+}) => Effect.Effect<void>;
+export declare const publishWaitEnded: (subject: string) => Effect.Effect<void>;
+declare const CurrentOperationUnit_base: ServiceMap.ServiceClass<CurrentOperationUnit, "@agentxm/workspace-operations/plan/operation-events/CurrentOperationUnit", {
+    readonly unitId: string;
+}>;
+/**
+ * The unit whose run is in progress, so nested producers (a download inside a
+ * step) can attribute continuous progress without threading identifiers.
+ */
+export declare class CurrentOperationUnit extends CurrentOperationUnit_base {
+}
+/**
+ * Publish a continuous measurement for the current unit. Producers throttle
+ * before calling: a download publishes tens of events, never one per chunk.
+ * No-op without a broadcast or without a current unit.
+ */
+export declare const publishUnitProgress: (progress: {
+    readonly done: number;
+    readonly total?: number | undefined;
+    readonly unit: ProgressUnit;
+}) => Effect.Effect<void>;
+/**
+ * Time-gated progress publisher for a producer loop: at most one event per
+ * `intervalMs` of wall clock, plus the final measurement when `done` reaches
+ * `total`. Keeps continuous measurements to tens of events per unit.
+ */
+export declare const makeThrottledUnitProgress: (options: {
+    readonly unit: ProgressUnit;
+    readonly intervalMs?: number | undefined;
+}) => Effect.Effect<(done: number, total?: number | undefined) => Effect.Effect<void>>;
+export interface ObservedUnit {
+    readonly id: string;
+    readonly label: string;
+    /** Planned position; assigned by the service when the caller has none. */
+    readonly index?: number | undefined;
+    readonly total?: number | undefined;
+    readonly parentUnitId?: string | undefined;
+}
+/**
+ * Run one unit of work under the lifecycle: `UnitStarted` before, then
+ * `UnitResolved` with the state the exit proves (`committed`, `failed`, or
+ * `interrupted`). The unit identity is provided to the run so nested producers
+ * can publish progress. No-op wrapper without a broadcast.
+ */
+export declare const observeUnit: <A, E, R>(unit: ObservedUnit, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/** Publish the terminal event once. No-op without a broadcast. */
+export declare const settleOperation: (outcome: SettledOutcome) => Effect.Effect<void>;
+/**
+ * Wait until every lossless subscriber has consumed the terminal event.
+ * Returns immediately when no broadcast is provided or the operation has not
+ * settled, so callers cannot deadlock on an operation that never ends.
+ */
+export declare const awaitDrained: Effect.Effect<void>;
+/**
+ * Subscribe to the broadcast within the current scope. The subscription is
+ * created immediately — before this effect returns — so events published
+ * afterwards are never missed; the stream ends with the terminal event.
+ */
+export declare const lifecycleEvents: (service: OperationLifecycleService) => Effect.Effect<Stream.Stream<OperationEvent>, never, Scope.Scope>;
 /**
- * Fork a subscriber that observes every lifecycle event published while the
- * scope lives. No-op (returns immediately) when no broadcast is provided.
+ * Fork a subscriber that observes every event through settlement and holds
+ * the drain latch until it has processed the terminal event. The subscription
+ * attaches before this effect returns. No-op when no broadcast is provided.
  */
-export declare const subscribeToLifecycle: (observe: (event: OperationLifecycleEvent) => Effect.Effect<void>) => Effect.Effect<void, never, Scope.Scope>;
-export declare const makeOperationLifecycle: (mode: "preview" | "apply") => Effect.Effect<OperationLifecycleService>;
+export declare const subscribeLossless: (service: OperationLifecycleService, observe: (event: OperationEvent) => Effect.Effect<void>) => Effect.Effect<void, never, Scope.Scope>;
 export {};
 //# sourceMappingURL=operation-events.d.ts.map

package/dist/src/plan/operation-events.js

@@ -1,41 +1,296 @@
 /**
- * Operation lifecycle events.
+ * Operation lifecycle events — the one live contract between a running
+ * operation and everything that observes it.
  *
- * Execution publishes typed lifecycle events — phase transitions, unit state
- * transitions, and waiting reasons, each with a monotonic timestamp — to an
- * invocation-scoped broadcast. Observers (renderers, machine progress,
- * telemetry) subscribe; none of them controls execution or keeps a second
- * account of what happened. Publishing is a no-op when no broadcast is
- * provided.
+ * An operation publishes schema-backed, typed lifecycle events (operation and
+ * phase transitions, unit start, progress, and settlement, waiting reasons, and
+ * exactly one terminal settled event) to an invocation-scoped broadcast.
+ * Observers — the human live frame, the machine event writer, telemetry —
+ * subscribe independently; none of them controls execution or keeps a second
+ * account of what happened. Events carry identifiers, labels, counts, and
+ * states, never presentation phrases; wording belongs to the observer.
  *
- * @experimental This API is unstable and may change without notice.
+ * Broadcast policy: the publisher is unbounded and never applies backpressure.
+ * Lifecycle events are discrete state transitions, so their count is bounded
+ * by the planned units; continuous measurements such as downloaded bytes are
+ * throttled at the producer and never published per chunk. Every operation
+ * ends with a settled event, and settled output waits on the drain latch that
+ * lossless subscribers complete. Publishing is a no-op when no broadcast is
+ * provided.
  */
+import * as Cause from "effect/Cause";
 import * as Clock from "effect/Clock";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Latch from "effect/Latch";
+import * as MutableRef from "effect/MutableRef";
 import * as Option from "effect/Option";
 import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
 import * as ServiceMap from "effect/Context";
+import * as Stream from "effect/Stream";
+import { BlockingClassSchema } from "./plan.js";
+import { OperationPhaseSchema, UnitStateSchema } from "./operation-resolution.js";
+// -----------------------------------------------------------------------------
+// Event schema
+// -----------------------------------------------------------------------------
+export const OperationModeSchema = Schema.Literals(["preview", "apply"]).annotate({
+    identifier: "OperationMode",
+    title: "Operation Mode",
+    description: "Whether the operation previews or applies its plan.",
+});
+/**
+ * Terminal outcome carried by the settled event: a plan-family outcome, or
+ * `completed` for an operation without a plan-family resolution (a read, an
+ * upgrade step sequence, an authentication flow) that finished successfully.
+ */
+export const SettledOutcomeSchema = Schema.Literals([
+    "previewed",
+    "applied",
+    "no-op",
+    "partial",
+    "failed",
+    "blocked",
+    "cancelled",
+    "interrupted",
+    "completed",
+]).annotate({
+    identifier: "SettledOutcome",
+    title: "Settled Outcome",
+    description: "Terminal outcome of an observed operation.",
+});
+export const ProgressUnitSchema = Schema.Literals(["bytes", "files", "items"]).annotate({
+    identifier: "ProgressUnit",
+    title: "Progress Unit",
+    description: "Unit of a continuous progress measurement.",
+});
+/** Per-operation monotonic order and wall-clock time, on every event. */
+const EventBase = {
+    seq: Schema.Number,
+    atMs: Schema.Number,
+};
+export const OperationStartedEventSchema = Schema.TaggedStruct("OperationStarted", {
+    ...EventBase,
+    operationId: Schema.String,
+    name: Schema.String,
+    mode: OperationModeSchema,
+}).annotate({ identifier: "OperationStartedEvent" });
+export const PhaseStartedEventSchema = Schema.TaggedStruct("PhaseStarted", {
+    ...EventBase,
+    phase: OperationPhaseSchema,
+}).annotate({ identifier: "PhaseStartedEvent" });
+export const UnitStartedEventSchema = Schema.TaggedStruct("UnitStarted", {
+    ...EventBase,
+    unitId: Schema.String,
+    label: Schema.String,
+    index: Schema.Number,
+    total: Schema.optional(Schema.Number),
+    parentUnitId: Schema.optional(Schema.String),
+}).annotate({ identifier: "UnitStartedEvent" });
+export const UnitProgressEventSchema = Schema.TaggedStruct("UnitProgress", {
+    ...EventBase,
+    unitId: Schema.String,
+    done: Schema.Number,
+    total: Schema.optional(Schema.Number),
+    unit: ProgressUnitSchema,
+}).annotate({ identifier: "UnitProgressEvent" });
+export const UnitResolvedEventSchema = Schema.TaggedStruct("UnitResolved", {
+    ...EventBase,
+    unitId: Schema.String,
+    label: Schema.String,
+    state: UnitStateSchema,
+    index: Schema.Number,
+    total: Schema.optional(Schema.Number),
+}).annotate({ identifier: "UnitResolvedEvent" });
+export const WaitingEventSchema = Schema.TaggedStruct("Waiting", {
+    ...EventBase,
+    blockingClass: BlockingClassSchema,
+    subject: Schema.String,
+    detail: Schema.String,
+}).annotate({ identifier: "WaitingEvent" });
+export const WaitEndedEventSchema = Schema.TaggedStruct("WaitEnded", {
+    ...EventBase,
+    subject: Schema.String,
+}).annotate({ identifier: "WaitEndedEvent" });
+export const OperationSettledEventSchema = Schema.TaggedStruct("OperationSettled", {
+    ...EventBase,
+    outcome: SettledOutcomeSchema,
+}).annotate({ identifier: "OperationSettledEvent" });
+/**
+ * The published lifecycle event union. `seq` is strictly increasing within one
+ * operation; `atMs` is wall-clock milliseconds. Exactly one `OperationSettled`
+ * event ends every operation.
+ */
+export const OperationEventSchema = Schema.Union([
+    OperationStartedEventSchema,
+    PhaseStartedEventSchema,
+    UnitStartedEventSchema,
+    UnitProgressEventSchema,
+    UnitResolvedEventSchema,
+    WaitingEventSchema,
+    WaitEndedEventSchema,
+    OperationSettledEventSchema,
+]).annotate({
+    identifier: "OperationEvent",
+    title: "Operation Lifecycle Event",
+    description: "One typed lifecycle event of a running AXM operation: operation, phase, unit, waiting, or settlement transition.",
+});
 export class OperationLifecycle extends ServiceMap.Service()("@agentxm/workspace-operations/plan/operation-events/OperationLifecycle") {
 }
+const operationCounter = MutableRef.make(0);
+export const makeOperationLifecycle = (args) => Effect.gen(function* () {
+    const events = yield* PubSub.unbounded();
+    const sequence = yield* Ref.make(0);
+    const unitIndex = yield* Ref.make(0);
+    const drain = yield* Ref.make({ settled: false, pending: 0 });
+    const drained = yield* Latch.make(false);
+    const operationId = `operation-${String(MutableRef.incrementAndGet(operationCounter))}`;
+    const openWhenDrained = (state) => state.settled && state.pending === 0 ? Effect.asVoid(drained.open) : Effect.void;
+    const publish = (make) => Effect.gen(function* () {
+        const seq = yield* Ref.modify(sequence, (current) => [current + 1, current + 1]);
+        const atMs = yield* Clock.currentTimeMillis;
+        yield* PubSub.publish(events, make(seq, atMs));
+    });
+    const settle = (outcome) => Effect.gen(function* () {
+        const first = yield* Ref.modify(drain, (state) => state.settled
+            ? [false, state]
+            : [true, { ...state, settled: true }]);
+        if (!first)
+            return;
+        yield* publish((seq, atMs) => ({ _tag: "OperationSettled", seq, atMs, outcome }));
+        yield* Effect.flatMap(Ref.get(drain), openWhenDrained);
+    });
+    const registerLossless = Ref.update(drain, (state) => ({
+        ...state,
+        pending: state.pending + 1,
+    })).pipe(Effect.as(Ref.modify(drain, (state) => {
+        const next = { ...state, pending: Math.max(0, state.pending - 1) };
+        return [next, next];
+    }).pipe(Effect.flatMap(openWhenDrained))));
+    return {
+        operationId,
+        name: args.name,
+        mode: args.mode,
+        events,
+        publish,
+        nextUnitIndex: Ref.modify(unitIndex, (current) => [current, current + 1]),
+        settle,
+        settled: Effect.map(Ref.get(drain), (state) => state.settled),
+        drained,
+        registerLossless,
+    };
+});
+// -----------------------------------------------------------------------------
+// Producers (no-ops without a broadcast)
+// -----------------------------------------------------------------------------
+const withLifecycle = (onSome, onNone) => Effect.flatMap(Effect.serviceOption(OperationLifecycle), (service) => Option.isNone(service) ? onNone() : onSome(service.value));
 /** Publish one lifecycle event. No-op when no broadcast is provided. */
-export const publishLifecycleEvent = (make) => Effect.gen(function* () {
-    const service = yield* Effect.serviceOption(OperationLifecycle);
-    if (Option.isNone(service))
+export const publishOperationEvent = (make) => withLifecycle((service) => service.publish(make), () => Effect.void);
+export const publishPhaseStarted = (phase) => publishOperationEvent((seq, atMs) => ({ _tag: "PhaseStarted", seq, atMs, phase }));
+export const publishWaiting = (wait) => publishOperationEvent((seq, atMs) => ({ _tag: "Waiting", seq, atMs, ...wait }));
+export const publishWaitEnded = (subject) => publishOperationEvent((seq, atMs) => ({ _tag: "WaitEnded", seq, atMs, subject }));
+/**
+ * The unit whose run is in progress, so nested producers (a download inside a
+ * step) can attribute continuous progress without threading identifiers.
+ */
+export class CurrentOperationUnit extends ServiceMap.Service()("@agentxm/workspace-operations/plan/operation-events/CurrentOperationUnit") {
+}
+/**
+ * Publish a continuous measurement for the current unit. Producers throttle
+ * before calling: a download publishes tens of events, never one per chunk.
+ * No-op without a broadcast or without a current unit.
+ */
+export const publishUnitProgress = (progress) => Effect.flatMap(Effect.serviceOption(CurrentOperationUnit), (unit) => Option.isNone(unit)
+    ? Effect.void
+    : publishOperationEvent((seq, atMs) => ({
+        _tag: "UnitProgress",
+        seq,
+        atMs,
+        unitId: unit.value.unitId,
+        done: progress.done,
+        ...(progress.total === undefined ? {} : { total: progress.total }),
+        unit: progress.unit,
+    })));
+/**
+ * Time-gated progress publisher for a producer loop: at most one event per
+ * `intervalMs` of wall clock, plus the final measurement when `done` reaches
+ * `total`. Keeps continuous measurements to tens of events per unit.
+ */
+export const makeThrottledUnitProgress = (options) => Effect.map(Ref.make(-Infinity), (last) => (done, total) => Effect.gen(function* () {
+    const now = yield* Clock.currentTimeMillis;
+    const previous = yield* Ref.get(last);
+    const final = total !== undefined && done >= total;
+    if (!final && now - previous < (options.intervalMs ?? 100))
         return;
-    const atNanos = yield* Clock.currentTimeNanos;
-    yield* PubSub.publish(service.value.pubsub, make(atNanos));
-});
-export const publishPhaseStarted = (phase) => publishLifecycleEvent((atNanos) => ({ _tag: "PhaseStarted", phase, atNanos }));
+    yield* Ref.set(last, now);
+    yield* publishUnitProgress({ done, unit: options.unit, total });
+}));
+const unitStateForExit = (exit) => Exit.isSuccess(exit)
+    ? "committed"
+    : Cause.hasInterruptsOnly(exit.cause)
+        ? "interrupted"
+        : "failed";
 /**
- * Fork a subscriber that observes every lifecycle event published while the
- * scope lives. No-op (returns immediately) when no broadcast is provided.
+ * Run one unit of work under the lifecycle: `UnitStarted` before, then
+ * `UnitResolved` with the state the exit proves (`committed`, `failed`, or
+ * `interrupted`). The unit identity is provided to the run so nested producers
+ * can publish progress. No-op wrapper without a broadcast.
  */
-export const subscribeToLifecycle = (observe) => Effect.gen(function* () {
-    const service = yield* Effect.serviceOption(OperationLifecycle);
+export const observeUnit = (unit, effect) => Effect.flatMap(Effect.serviceOption(OperationLifecycle), (service) => {
     if (Option.isNone(service))
-        return;
-    const subscription = yield* PubSub.subscribe(service.value.pubsub);
-    yield* Effect.forkScoped(Effect.forever(PubSub.take(subscription).pipe(Effect.flatMap(observe))));
+        return effect;
+    const lifecycle = service.value;
+    return Effect.gen(function* () {
+        const index = unit.index ?? (yield* lifecycle.nextUnitIndex);
+        const total = unit.total === undefined ? {} : { total: unit.total };
+        yield* lifecycle.publish((seq, atMs) => ({
+            _tag: "UnitStarted",
+            seq,
+            atMs,
+            unitId: unit.id,
+            label: unit.label,
+            index,
+            ...total,
+            ...(unit.parentUnitId === undefined ? {} : { parentUnitId: unit.parentUnitId }),
+        }));
+        return yield* effect.pipe(Effect.provideService(CurrentOperationUnit, { unitId: unit.id }), Effect.onExit((exit) => lifecycle.publish((seq, atMs) => ({
+            _tag: "UnitResolved",
+            seq,
+            atMs,
+            unitId: unit.id,
+            label: unit.label,
+            state: unitStateForExit(exit),
+            index,
+            ...total,
+        }))));
+    });
+});
+/** Publish the terminal event once. No-op without a broadcast. */
+export const settleOperation = (outcome) => withLifecycle((service) => service.settle(outcome), () => Effect.void);
+/**
+ * Wait until every lossless subscriber has consumed the terminal event.
+ * Returns immediately when no broadcast is provided or the operation has not
+ * settled, so callers cannot deadlock on an operation that never ends.
+ */
+export const awaitDrained = withLifecycle((service) => Effect.flatMap(service.settled, (settled) => (settled ? service.drained.await : Effect.void)), () => Effect.void);
+// -----------------------------------------------------------------------------
+// Subscribers
+// -----------------------------------------------------------------------------
+/**
+ * Subscribe to the broadcast within the current scope. The subscription is
+ * created immediately — before this effect returns — so events published
+ * afterwards are never missed; the stream ends with the terminal event.
+ */
+export const lifecycleEvents = (service) => Effect.map(PubSub.subscribe(service.events), (subscription) => Stream.fromSubscription(subscription).pipe(Stream.takeUntil((event) => event._tag === "OperationSettled")));
+/**
+ * Fork a subscriber that observes every event through settlement and holds
+ * the drain latch until it has processed the terminal event. The subscription
+ * attaches before this effect returns. No-op when no broadcast is provided.
+ */
+export const subscribeLossless = (service, observe) => Effect.gen(function* () {
+    const ack = yield* service.registerLossless;
+    const stream = yield* lifecycleEvents(service);
+    yield* stream.pipe(Stream.runForEach(observe), Effect.ensuring(ack), Effect.forkScoped);
 });
-export const makeOperationLifecycle = (mode) => PubSub.unbounded().pipe(Effect.map((pubsub) => ({ mode, pubsub })));
 //# sourceMappingURL=operation-events.js.map

package/dist/src/plan/operation-resolution.d.ts

@@ -27,7 +27,7 @@ import type { ConfiguredAgentOutcome } from "@agentxm/workspace-state";
 export declare const UnitStateSchema: Schema.Literals<readonly ["planned", "ready", "committed", "unchanged", "failed", "rolled-back", "blocked", "skipped", "cancelled", "interrupted"]>;
 export type UnitState = typeof UnitStateSchema.Type;
 /** Lifecycle phase in which an operation event (blocking, waiting) occurred. */
-export declare const OperationPhaseSchema: Schema.Literals<readonly ["planning", "preview", "confirmation", "validation", "apply", "restoration"]>;
+export declare const OperationPhaseSchema: Schema.Literals<readonly ["resolution", "planning", "preview", "confirmation", "validation", "apply", "restoration"]>;
 export type OperationPhase = typeof OperationPhaseSchema.Type;
 /** Canonical operation terminal outcomes. */
 export declare const OperationOutcomeSchema: Schema.Literals<readonly ["previewed", "applied", "no-op", "partial", "failed", "blocked", "cancelled", "interrupted"]>;

package/dist/src/plan/operation-resolution.js

@@ -41,6 +41,8 @@ export const UnitStateSchema = Schema.Literals([
 });
 /** Lifecycle phase in which an operation event (blocking, waiting) occurred. */
 export const OperationPhaseSchema = Schema.Literals([
+    // Resolving requested sources into concrete packages, before planning.
+    "resolution",
     "planning",
     "preview",
     "confirmation",

package/dist/src/plan/resolve-plan-interaction.d.ts

@@ -1,17 +1,17 @@
 /**
  * Plan-resolution interaction port.
  *
- * `previewOrApplyPlan` presents candidates, reports progress, and obtains the
- * apply confirmation exclusively through this service. The CLI runtime
- * provides the renderer- and prompt-backed implementation; wording, verbosity
- * gating, and progress presentation belong to that implementation, never to
- * the kernel.
+ * `previewOrApplyPlan` presents candidates and obtains the apply confirmation
+ * exclusively through this service. The CLI runtime provides the renderer- and
+ * prompt-backed implementation; wording and verbosity gating belong to that
+ * implementation, never to the kernel. Progress is not an interaction: the
+ * kernel publishes typed lifecycle events (`plan/operation-events`) that
+ * observers render.
  *
  * @experimental This API is unstable and may change without notice.
  */
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as Option from "effect/Option";
 import * as ServiceMap from "effect/Context";
 import type { PlanInteractionFailed } from "./errors.js";
 import type { ConfirmationRecovery } from "./plan-execution.js";
@@ -34,19 +34,6 @@ export interface ResolvePlanInteractionService {
     readonly presentPlan: (plan: Plan<unknown, unknown>, options: {
         readonly mode: "preview" | "apply";
     }) => Effect.Effect<void>;
-    /** Progress envelope for lockfile reconciliation. */
-    readonly withPlanningProgress: <A, E, R>(planName: string, run: () => Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
-    /**
-     * Progress envelope for apply. The implementation subscribes to the
-     * operation lifecycle stream itself (`plan/operation-events`) and maps unit
-     * and restoration events to progress updates.
-     */
-    readonly withApplyProgress: <A, E, R>(planName: string, run: () => Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
-    /** Transition-lock contention notice. */
-    readonly noteTransitionWait: (holder: Option.Option<{
-        readonly command: string;
-        readonly pid: number;
-    }>) => Effect.Effect<void>;
 }
 declare const ResolvePlanInteraction_base: ServiceMap.ServiceClass<ResolvePlanInteraction, "@agentxm/workspace-operations/plan/resolve-plan-interaction/ResolvePlanInteraction", ResolvePlanInteractionService>;
 export declare class ResolvePlanInteraction extends ResolvePlanInteraction_base {
@@ -57,9 +44,6 @@ export interface ResolvePlanInteractionTestState {
         readonly planName: string;
         readonly mode: "preview" | "apply";
     }>;
-    readonly planningProgress: Array<string>;
-    readonly applyProgress: Array<string>;
-    transitionWaits: number;
 }
 export declare const ResolvePlanInteractionTest: (overrides?: {
     readonly isConfirmationAvailable?: boolean;
@@ -67,10 +51,6 @@ export declare const ResolvePlanInteractionTest: (overrides?: {
     readonly presentPlan?: (plan: Plan<unknown, unknown>, options: {
         readonly mode: "preview" | "apply";
     }) => Effect.Effect<void>;
-    readonly noteTransitionWait?: (holder: Option.Option<{
-        readonly command: string;
-        readonly pid: number;
-    }>) => Effect.Effect<void>;
 }) => {
     layer: Layer.Layer<ResolvePlanInteraction, never, never>;
     state: ResolvePlanInteractionTestState;

package/dist/src/plan/resolve-plan-interaction.js

@@ -1,17 +1,17 @@
 /**
  * Plan-resolution interaction port.
  *
- * `previewOrApplyPlan` presents candidates, reports progress, and obtains the
- * apply confirmation exclusively through this service. The CLI runtime
- * provides the renderer- and prompt-backed implementation; wording, verbosity
- * gating, and progress presentation belong to that implementation, never to
- * the kernel.
+ * `previewOrApplyPlan` presents candidates and obtains the apply confirmation
+ * exclusively through this service. The CLI runtime provides the renderer- and
+ * prompt-backed implementation; wording and verbosity gating belong to that
+ * implementation, never to the kernel. Progress is not an interaction: the
+ * kernel publishes typed lifecycle events (`plan/operation-events`) that
+ * observers render.
  *
  * @experimental This API is unstable and may change without notice.
  */
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as Option from "effect/Option";
 import * as ServiceMap from "effect/Context";
 export class ResolvePlanInteraction extends ServiceMap.Service()("@agentxm/workspace-operations/plan/resolve-plan-interaction/ResolvePlanInteraction") {
 }
@@ -19,9 +19,6 @@ export const ResolvePlanInteractionTest = (overrides) => {
     const state = {
         confirmApplyChangesCalls: [],
         presentPlanCalls: [],
-        planningProgress: [],
-        applyProgress: [],
-        transitionWaits: 0,
     };
     const layer = Layer.succeed(ResolvePlanInteraction, {
         isConfirmationAvailable: Effect.succeed(overrides?.isConfirmationAvailable ?? false),
@@ -34,18 +31,6 @@ export const ResolvePlanInteractionTest = (overrides) => {
             state.presentPlanCalls.push({ planName: plan.name, mode: options.mode });
             yield* overrides?.presentPlan?.(plan, options) ?? Effect.void;
         }),
-        withPlanningProgress: (planName, run) => Effect.suspend(() => {
-            state.planningProgress.push(planName);
-            return run();
-        }),
-        withApplyProgress: (planName, run) => Effect.suspend(() => {
-            state.applyProgress.push(planName);
-            return run();
-        }),
-        noteTransitionWait: (holder) => Effect.gen(function* () {
-            state.transitionWaits += 1;
-            yield* overrides?.noteTransitionWait?.(holder) ?? Effect.void;
-        }),
     });
     return { layer, state };
 };

package/dist/src/plan/resolve-plan.js

@@ -18,6 +18,7 @@ import * as Path from "effect/Path";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
 import { ApprovalRecoveryMissing, STALE_CANDIDATE_DETAIL, StaleExecutionCandidate, StepFailure, } from "./errors.js";
 import { applyPlan } from "./apply-plan.js";
 import { isExecutionCandidateFresh, makeExecutionCandidate, } from "./execution-candidate.js";
@@ -25,7 +26,7 @@ import { augmentPlanWithReconciliation } from "../operations/augment-plan.js";
 import { scanPlanReadiness } from "../operations/scan-plan-readiness.js";
 import { declaredAtomicity, executedUnits, makeOperationResolution, plannedUnits, unitIdOf, } from "./operation-resolution.js";
 import { appendResolvedUnit, appendStartedUnit, recordJournalPhase, recordOperationJournal, } from "./operation-journal.js";
-import { publishLifecycleEvent, publishPhaseStarted } from "./operation-events.js";
+import { CurrentOperationUnit, observeUnit, publishOperationEvent, publishPhaseStarted, publishWaitEnded, publishWaiting, } from "./operation-events.js";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
 import { readPendingClosureRestorationFailures, WorkspaceRestorationIncomplete, } from "@agentxm/workspace-state";
 import { rollbackWorkspaceClosure, settleWorkspaceClosure, withWorkspaceClosure, } from "../operations/transaction.js";
@@ -34,7 +35,6 @@ import { InterruptionSignalSource } from "./interruption-signal.js";
 import { ResolvePlanInteraction } from "./resolve-plan-interaction.js";
 import { confirmationRecoverySuggestions, namedPolicyRecoverySuggestions, } from "./plan-execution.js";
 import { ConfiguredAgentOutcomesProvider } from "@agentxm/workspace-state";
-import { isMcpServerApplicableToAgent } from "@agentxm/workspace-state";
 import { configuredAgentLifecycleOutcomes } from "@agentxm/workspace-state";
 import { candidateFingerprintFailedToStepFailure, configuredAgentOutcomesUnavailableToStepFailure, restorationIncompleteToStepFailure, workspaceStateReadFailureToStepFailure, workspaceTransactionFailureToStepFailure, } from "./step-failure-conversions.js";
 /** Publish a phase transition to the lifecycle stream and the journal. */
@@ -107,19 +107,15 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
     const fsLayer = Layer.mergeAll(Layer.succeed(FileSystem.FileSystem, fs), Layer.succeed(Path.Path, path));
     const mode = options.execution.request.mode;
     yield* publishPhaseStarted("planning");
-    // Step 1: Lockfile reconciliation
-    const augmented = yield* interaction.withPlanningProgress(plan.name, () => augmentPlanWithReconciliation(plan, () => ws.getLockfileState()));
+    // Step 1: Lockfile reconciliation, observed as one planning unit.
+    const augmented = yield* observeUnit({ id: "lockfile-reconciliation", label: "lockfile reconciliation" }, augmentPlanWithReconciliation(plan, () => ws.getLockfileState()));
     const operations = options.execution.configuredAgentOperations ?? [];
     const configuredAgents = operations.length === 0 ? [] : yield* ws.getConfiguredAgents();
-    const configuredMcpServers = operations.some(({ extensionType }) => extensionType === "mcp-server")
-        ? yield* ws.getConfiguredMcpServerEntries()
-        : {};
     const outcomesProvider = yield* Effect.serviceOption(ConfiguredAgentOutcomesProvider);
     const outcomesOverrideFor = (extensionType) => Option.isSome(outcomesProvider)
         ? outcomesProvider.value.byExtensionType[extensionType]
         : undefined;
     const outcomesFor = (operation, state) => {
-        const mcpEntry = operation.extensionType === "mcp-server" ? configuredMcpServers[operation.name] : undefined;
         const generic = configuredAgentLifecycleOutcomes({
             type: operation.extensionType,
             name: operation.name,
@@ -129,11 +125,6 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
             targetState: operation.plannedState,
             installed: state === "projected",
             observedAgentIds: state === "projected" ? configuredAgents : [],
-            ...(mcpEntry === undefined
-                ? {}
-                : {
-                    applicableAgentIds: configuredAgents.filter((agentId) => isMcpServerApplicableToAgent(mcpEntry, agentId)),
-                }),
         });
         const override = outcomesOverrideFor(operation.extensionType);
         if (operation.plannedState === "enabled" && override !== undefined) {
@@ -350,19 +341,23 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
                 ...job,
                 steps: job.steps.map((step) => step.readiness === "error"
                     ? step
-                    : { ...step, run: withWorkspaceClosure(unitIdOf(step))(step.run) }),
+                    : {
+                        ...step,
+                        run: withWorkspaceClosure(unitIdOf(step))(step.run).pipe(Effect.provideService(CurrentOperationUnit, { unitId: unitIdOf(step) })),
+                    }),
             })),
         };
         return yield* applyPlan(closureScopedPlan, {
             // The started fact is journaled before the run's first effect, so an
             // interruption mid-run reports the unit in flight, never not attempted.
-            onStepStarted: (step) => appendStartedUnit(unitIdOf(step)).pipe(Effect.andThen(publishLifecycleEvent((atNanos) => ({
+            onStepStarted: (step) => appendStartedUnit(unitIdOf(step)).pipe(Effect.andThen(publishOperationEvent((seq, atMs) => ({
                 _tag: "UnitStarted",
+                seq,
+                atMs,
                 unitId: unitIdOf(step),
                 label: step.label,
                 index: startedUnits++,
                 total: totalUnits,
-                atNanos,
             })))),
             // Settlement runs before the next interruptible boundary: the journal
             // fact and the closure's snapshot disposition are recorded together —
@@ -370,14 +365,15 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
             // itself, and later ready closures continue.
             onStepCompleted: (step) => appendResolvedUnit(step).pipe(Effect.andThen(step.result.result === "error"
                 ? rollbackWorkspaceClosure(unitIdOf(step))
-                : settleWorkspaceClosure(unitIdOf(step))), Effect.andThen(publishLifecycleEvent((atNanos) => ({
+                : settleWorkspaceClosure(unitIdOf(step))), Effect.andThen(publishOperationEvent((seq, atMs) => ({
                 _tag: "UnitResolved",
+                seq,
+                atMs,
                 unitId: unitIdOf(step),
                 label: step.label,
                 state: resolvedUnitState(step),
                 index: resolvedUnits++,
                 total: totalUnits,
-                atNanos,
             })))),
         });
     });
@@ -504,19 +500,32 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
             ? failure
             : { error: workspaceTransactionFailureToStepFailure(failure) };
     }));
+    const transitionSubject = "workspace-transition";
     const applyResult = yield* Effect.scoped(Effect.gen(function* () {
+        const waited = yield* Ref.make(false);
         const contention = yield* ws.acquireTransition({
             command: applyExecution.approvalRecovery.command.join(" "),
             candidateId: candidate.id,
-            onWaiting: (holder) => interaction.noteTransitionWait(holder),
+            // Contention is a first-class lifecycle fact: observers render the
+            // wait and its holder; nothing here decides how it is worded.
+            onWaiting: (holder) => Ref.set(waited, true).pipe(Effect.andThen(publishWaiting({
+                blockingClass: "resource-conflict",
+                subject: transitionSubject,
+                detail: Option.match(holder, {
+                    onNone: () => "another operation",
+                    onSome: (value) => `${value.command} (pid ${String(value.pid)})`,
+                }),
+            }))),
         });
+        if (yield* Ref.get(waited))
+            yield* publishWaitEnded(transitionSubject);
         if (Option.isSome(contention)) {
             return { type: "contention", contention: contention.value };
         }
-        return yield* interaction.withApplyProgress(candidatePlan.name, () => guardedApply.pipe(Effect.match({
+        return yield* guardedApply.pipe(Effect.match({
             onFailure: (error) => ({ type: "failure", error }),
             onSuccess: (value) => ({ type: "success", value }),
-        })));
+        }));
     }));
     if (applyResult.type === "contention") {
         const reference = Option.match(applyResult.contention.holder, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentxm/workspace-operations",
-  "version": "0.28.5",
+  "version": "0.28.6",
   "description": "AXM workspace operations kernel: plans, execution candidates, operation resolutions, and workspace transactions for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
   "type": "module",
   "license": "FSL-1.1-MIT",
@@ -48,9 +48,9 @@
   "dependencies": {
     "effect": "4.0.0-rc.112",
     "proper-lockfile": "^4.1.2",
-    "@agentxm/extension-model": "^0.28.5",
-    "@agentxm/registry-protocol": "^0.28.5",
-    "@agentxm/workspace-state": "^0.28.5"
+    "@agentxm/extension-model": "^0.28.6",
+    "@agentxm/workspace-state": "^0.28.6",
+    "@agentxm/registry-protocol": "^0.28.6"
   },
   "devDependencies": {
     "@effect/platform-node": "4.0.0-rc.112",