refactor(lifecycle): normalize operation failures

Author: kushagrchitkar

docs/intentional-architecture-rewrite-2026-06-27/decision-log.md

@@ -57,6 +57,8 @@ Claude and Codex transcript-store scanning, raw transcript snapshot reads, line
 
 Build, Absorb, and Garden operation specs are lifecycle product mechanics, so their provider-neutral construction lives under `src/services/lifecycle/operations/`. CLI commands and peer services call lifecycle workflow contracts instead of importing operation internals.
 
+Lifecycle workflow results expose lifecycle-owned failure contracts. Agent runtime failures are normalized in `src/services/lifecycle/operation-results.ts` before command rendering reads them, so CLI output code does not depend on provider/runtime event types.
+
 ### Absorb source parsing is lifecycle, GitHub mechanics are platform
 
 Absorb owns product input normalization under `src/services/lifecycle/absorb/`: source refs, source input contracts, context rendering, and Absorb run-start shaping. GitHub remote parsing and URL construction are external mechanics, so they live under `src/platform/github/` and return plain typed facts.

docs/intentional-architecture-rewrite-2026-06-27/status.md

@@ -5,9 +5,9 @@ Branch: `codex/intentional-architecture-rewrite`
 
 ## Current State
 
-The branch has 227 committed rewrite commits past `dev`. The worklog records 179 production slices so far.
+The branch has 228 committed rewrite commits past `dev`. The worklog records 180 production slices so far.
 
-The diff is broad: 473 files changed, with 23,659 insertions and 12,875 deletions.
+The diff is broad: 473 files changed, with 23,696 insertions and 12,875 deletions.
 
 This is no longer a small cleanup branch. It is a real ownership rewrite.
 
@@ -32,6 +32,7 @@ This is no longer a small cleanup branch. It is a real ownership rewrite.
 - Moved sync ledger and lock persistence into explicit stores.
 - Moved local Claude/Codex transcript discovery, transcript snapshot reads, and timestamp boundary parsing into `src/platform/transcripts/` and removed the old top-level `src/sync/` source bucket.
 - Moved lifecycle operation construction and Absorb input/source handling into `src/services/lifecycle/` and removed the old top-level `src/operations/` and `src/absorb/` source buckets.
+- Normalized lifecycle operation failures into lifecycle-owned result contracts before command rendering sees them.
 - Moved GitHub source resolution mechanics into `src/platform/github/`.
 - Moved provider execution runtime into `src/agent/runtime/`, especially Claude and Codex app-server mechanics, and made provider runtime environment flow through explicit job/registry contracts.
 - Moved setup, diagnostics, update, automation, jobs, sync, lifecycle, config, and agents workflows behind service-owned contracts.
@@ -55,9 +56,9 @@ This is no longer a small cleanup branch. It is a real ownership rewrite.
 
 ## Latest Checkpoint
 
-The latest slice moved `almanac uninstall` terminal UI from `src/cli/commands/` to `src/edges/cli/`. Uninstall confirmations, output rendering, and edge orchestration now live with CLI edge code, while setup cleanup stays under `src/services/setup/uninstall.ts`.
+The latest slice normalized lifecycle operation failures into `src/services/lifecycle/operation-results.ts`. Operation command rendering now depends on lifecycle-owned failure contracts instead of importing agent runtime failure types directly.
 
-Verification passed: focused uninstall/CLI/boundary tests, `npm run lint`, full `npm test`, `npm run build`, `node dist/codealmanac.js --version`, `node dist/codealmanac.js uninstall --help`, `node dist/codealmanac.js setup --help`, and `node dist/codealmanac.js doctor --help`.
+Verification passed: focused operation-command/boundary tests, `npm run lint`, full `npm test`, `npm run build`, `node dist/codealmanac.js --version`, `node dist/codealmanac.js init --help`, `node dist/codealmanac.js absorb --help`, and `node dist/codealmanac.js garden --help`.
 
 ## Immediate Next Work
 

docs/intentional-architecture-rewrite-2026-06-27/worklog.md

@@ -1221,3 +1221,10 @@ One-hundred-seventy-ninth production slice:
 - Updated setup command registration and uninstall tests to import the edge-owned uninstall runner.
 - Kept `src/services/setup/uninstall.ts` responsible for deterministic cleanup workflow over automation and instruction artifacts.
 - Strengthened boundary coverage so old uninstall command files stay deleted while CLI edge owns confirmations and stdout rendering.
+
+One-hundred-eightieth production slice:
+
+- Added a lifecycle-owned `LifecycleOperationFailure` contract in `src/services/lifecycle/operation-results.ts`.
+- Normalized agent runtime failure objects into lifecycle failures before operation command rendering reads them.
+- Removed the direct `AgentRuntimeFailure` import from `src/cli/commands/operations-render.ts`.
+- Strengthened boundary coverage so lifecycle command rendering cannot re-import agent runtime failure types directly.

src/cli/commands/operations-render.ts

@@ -1,5 +1,5 @@
-import type { AgentRuntimeFailure } from "../../agent/runtime/events.js";
 import {
+  type LifecycleOperationFailure,
   type LifecycleOperationRunResult,
   type LifecycleOperationWorkflowResult,
 } from "../../services/lifecycle/index.js";
@@ -90,7 +90,7 @@ function renderOperationFailureMessage(args: {
   operation: string;
   jobId: string;
   error?: string;
-  failure?: AgentRuntimeFailure;
+  failure?: LifecycleOperationFailure;
 }): string {
   const lines = [`${args.operation} failed: ${args.jobId}`];
   if (args.failure !== undefined) {

src/services/lifecycle/index.ts

@@ -22,6 +22,7 @@ export {
 } from "./workflows.js";
 
 export {
+  type LifecycleOperationFailure,
   type LifecycleOperationBackgroundResult,
   type LifecycleOperationForegroundResult,
   type LifecycleOperationJobResult,

src/services/lifecycle/operation-results.ts

@@ -9,17 +9,24 @@ export type LifecycleOperationJobStatus =
   | "failed"
   | "cancelled";
 
+export interface LifecycleOperationFailure {
+  provider: string;
+  message: string;
+  code?: string;
+  fix?: string;
+}
+
 export interface LifecycleOperationJobResult {
   status: LifecycleOperationJobStatus;
   pid: number;
   logPath: string;
-  failure?: AgentRuntimeFailure;
+  failure?: LifecycleOperationFailure;
 }
 
 export interface LifecycleOperationForegroundResult {
   success: boolean;
   error?: string;
-  failure?: AgentRuntimeFailure;
+  failure?: LifecycleOperationFailure;
 }
 
 export interface LifecycleOperationBackgroundResult {
@@ -48,7 +55,9 @@ export function lifecycleOperationRunResultFromOperation(
       status: record.status,
       pid: record.pid,
       logPath: record.logPath,
-      ...(record.failure !== undefined ? { failure: record.failure } : {}),
+      ...(record.failure !== undefined
+        ? { failure: lifecycleFailureFromAgent(record.failure) }
+        : {}),
     },
     ...(result.foreground !== undefined
       ? { foreground: lifecycleForegroundResultFromOperation(result.foreground.result) }
@@ -65,6 +74,19 @@ function lifecycleForegroundResultFromOperation(
   return {
     success: result.success,
     ...(result.error !== undefined ? { error: result.error } : {}),
-    ...(result.failure !== undefined ? { failure: result.failure } : {}),
+    ...(result.failure !== undefined
+      ? { failure: lifecycleFailureFromAgent(result.failure) }
+      : {}),
+  };
+}
+
+function lifecycleFailureFromAgent(
+  failure: AgentRuntimeFailure,
+): LifecycleOperationFailure {
+  return {
+    provider: failure.provider,
+    message: failure.message,
+    ...(failure.code !== undefined ? { code: failure.code } : {}),
+    ...(failure.fix !== undefined ? { fix: failure.fix } : {}),
   };
 }

test/architecture-boundaries.test.ts

@@ -1481,6 +1481,7 @@ describe("architecture boundaries", () => {
     const platformGithubSource = await readSource("src/platform/github/source.ts");
     const syncService = await readSource("src/services/sync/sync.ts");
     const operationsCommand = await readSource("src/cli/commands/operations.ts");
+    const operationsRender = await readSource("src/cli/commands/operations-render.ts");
 
     expect(existsSync(join(ROOT, "src/services/lifecycle/operation-results.ts"))).toBe(true);
     expect(existsSync(join(ROOT, "src/services/lifecycle/workflows.ts"))).toBe(true);
@@ -1519,10 +1520,13 @@ describe("architecture boundaries", () => {
     expect(lifecycleWorkflows).not.toContain("Command context:");
     expect(lifecycleWorkflows).toContain("runPreparedAbsorbOperationWorkflow");
     expect(lifecycleResults).toContain("lifecycleOperationRunResultFromOperation");
+    expect(lifecycleResults).toContain("interface LifecycleOperationFailure");
     expect(platformGithubSource).not.toContain("services/lifecycle");
     expect(syncService).toContain("runPreparedAbsorbOperationWorkflow");
     expect(syncService).not.toContain("services/lifecycle/operations");
     expect(operationsCommand).toContain("services/lifecycle/index.js");
+    expect(operationsRender).not.toContain("../../agent");
+    expect(operationsRender).not.toContain("AgentRuntimeFailure");
     expect(operationsCommand).not.toContain("import type { CommandResult }");
     expect(operationsCommand).not.toContain("extends InitOperationWorkflowOptions");
     expect(operationsCommand).not.toContain("extends AbsorbOperationWorkflowOptions");