refactor(automation): split launchd plist ownership

Author: kushagrchitkar

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

@@ -209,6 +209,8 @@ Viewer read models are route-payload owners, not one API bucket. `src/edges/view
 
 Bare-`codealmanac` bootstrap is a flow coordinator, not a package-manager bucket. `src/platform/install/global.ts` owns the high-level bootstrap sequence. `bootstrap-process.ts` owns child-process spawn/capture mechanics. `bootstrap-package.ts` owns package-root detection, package version reads, root equality, and version comparison. `bootstrap-npm.ts` owns npm global-root discovery, global install execution, and npm failure text.
 
+Launchd action mechanics and launchd plist XML are separate platform owners. `src/platform/automation/launchd.ts` owns launchctl target construction, PATH construction, plist file writes/removals, directory creation, bootstrap/bootout, and loaded-state checks. `src/platform/automation/launchd-plist.ts` owns XML rendering, XML escaping/unescaping, StartInterval parsing, and ProgramArguments parsing. `src/platform/automation/paths.ts` owns plist and log path construction.
+
 Codex app-server runtime has two layers. `app-server.ts` coordinates provider runtime state: request/config setup, JSON-RPC transport wiring, notification mapping, root-turn completion, turn watchdogs, and final result projection. `app-server-process.ts` owns child-process mechanics: spawning the Codex app-server, decoding stdout JSONL into protocol messages, collecting stderr for close failures, registering signal handlers, writing JSON-RPC messages to stdin, and terminating the managed child.
 
 Codex app-server notifications are routed by notification kind. `app-notifications.ts` owns the top-level method router and generic notification categories. `app-agent-messages.ts` owns agent-message semantics: text deltas, root result capture, structured output parsing, invalid structured-output failure state, and helper-agent completion events. `app-terminal-events.ts` owns terminal event semantics: turn completion, warnings, app-server error notifications, terminal run-state success/failure mutation, and `classifyCodexFailure` calls. Tool display, usage parsing, actor tracing, root-turn detection, and process mechanics stay in their existing named files.

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

@@ -5,7 +5,7 @@ Branch: `codex/intentional-architecture-rewrite`
 
 ## Current State
 
-The branch has more than 340 committed rewrite commits past `dev`. The worklog records 289 production slices so far.
+The branch has more than 340 committed rewrite commits past `dev`. The worklog records 290 production slices so far.
 
 The diff is broad: more than 680 files changed, with tens of thousands of lines reshaped.
 
@@ -148,6 +148,7 @@ This is no longer a small cleanup branch. It is a real ownership rewrite.
 - Split setup input controls into line prompts, single-choice select, raw input capability, multi-select, and interruption handling.
 - Split viewer read-model route payloads into overview, page, topic, search/file, DB freshness, and type owners.
 - Split bare-`codealmanac` install bootstrap into flow coordination, package-root/version, npm global install, and process-spawn owners.
+- Split launchd plist XML mechanics from launchctl action mechanics in the automation platform adapter.
 - Moved repeated store atomic-write temp-file mechanics into `src/stores/atomic-write.ts`, removing process-PID temp names from job and sync stores.
 - Split most command rendering into command-private render files.
 - Added architecture-boundary tests to stop old dependency leaks from returning.
@@ -164,12 +165,12 @@ This is no longer a small cleanup branch. It is a real ownership rewrite.
 
 ## Latest Checkpoint
 
-The latest slice split the bare-`codealmanac` install bootstrap bucket. `global.ts` now coordinates the bootstrap flow, while `bootstrap-package.ts`, `bootstrap-npm.ts`, and `bootstrap-process.ts` own package-root/version mechanics, npm mechanics, and child-process mechanics.
+The latest slice split launchd plist XML mechanics from launchctl action mechanics. `launchd.ts` now owns launchctl/file/action mechanics, while `launchd-plist.ts` owns XML rendering, escaping, and parsing.
 
 Verification passed:
 
 - `npm run lint`
-- `npx vitest run test/global-bootstrap.test.ts test/architecture-setup-boundaries.test.ts`
+- `npx vitest run test/automation.test.ts test/architecture-automation-update-boundaries.test.ts`
 - `npx vitest run test/architecture-*-boundaries.test.ts`
 - `git diff --check`
 - `npm test`

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

@@ -2076,3 +2076,12 @@ Two-hundred-eighty-ninth production slice:
 - Added `src/platform/install/bootstrap-npm.ts` for npm global-root discovery, global package install execution, and npm-install failure text.
 - Kept `global.ts` focused on the bare-`codealmanac` bootstrap flow: local setup bypass, global-root resolution, global install decision, and rerun through the global launcher.
 - Strengthened setup architecture tests so process spawning, package-root/version probing, and npm install mechanics stay in separate install-platform owners.
+
+Two-hundred-ninetieth production slice:
+
+- Split launchd plist XML mechanics out of `src/platform/automation/launchd.ts`.
+- Added `src/platform/automation/launchd-plist.ts` for plist XML rendering, XML escaping/unescaping, StartInterval parsing, and ProgramArguments parsing.
+- Kept `launchd.ts` focused on launchctl target construction, launch PATH construction, plist file writes/removals, directory creation, bootstrap/bootout, and loaded-state checks.
+- Updated the launchd scheduler adapter to consume `readLaunchdProgramArguments()` from the plist owner instead of parsing plist XML locally.
+- Removed the unused `automationLogsDir()` helper because automation log path ownership already lives in `src/platform/automation/paths.ts`.
+- Strengthened automation boundary tests so launchd action mechanics and plist XML mechanics stay separate.

src/platform/automation/launchd-plist.ts

@@ -0,0 +1,79 @@
+export interface LaunchdPlistDefinition {
+  label: string;
+  programArguments: string[];
+  intervalSeconds: number;
+  environmentVariables: Record<string, string>;
+  stdoutPath: string;
+  stderrPath: string;
+  workingDirectory?: string;
+}
+
+export function renderLaunchdPlist(args: LaunchdPlistDefinition): string {
+  const programArguments = args.programArguments
+    .map((arg) => `    <string>${escapeXml(arg)}</string>`)
+    .join("\n");
+  const environmentVariables = Object.entries(args.environmentVariables)
+    .map(
+      ([key, value]) =>
+        `    <key>${escapeXml(key)}</key>\n    <string>${escapeXml(value)}</string>`,
+    )
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(args.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${programArguments}
+  </array>
+  <key>StartInterval</key>
+  <integer>${args.intervalSeconds}</integer>
+${args.workingDirectory !== undefined
+    ? `  <key>WorkingDirectory</key>\n  <string>${escapeXml(args.workingDirectory)}</string>\n`
+    : ""}  <key>EnvironmentVariables</key>
+  <dict>
+${environmentVariables}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(args.stdoutPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(args.stderrPath)}</string>
+</dict>
+</plist>
+`;
+}
+
+export function readLaunchdStartInterval(contents: string): number | null {
+  const value = contents.match(
+    /<key>StartInterval<\/key>\s*<integer>(\d+)<\/integer>/,
+  )?.[1];
+  return value === undefined ? null : Number(value);
+}
+
+export function readLaunchdProgramArguments(contents: string): string[] {
+  return [...contents.matchAll(/<string>([^<]*)<\/string>/g)]
+    .map((match) => unescapeXml(match[1] ?? ""));
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+function unescapeXml(value: string): string {
+  return value
+    .replaceAll("&apos;", "'")
+    .replaceAll("&quot;", '"')
+    .replaceAll("&gt;", ">")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&amp;", "&");
+}

src/platform/automation/launchd.ts

@@ -1,10 +1,16 @@
 import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { homedir, userInfo } from "node:os";
+import { userInfo } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 
+import {
+  readLaunchdStartInterval,
+  renderLaunchdPlist,
+  type LaunchdPlistDefinition,
+} from "./launchd-plist.js";
+
 const execFileAsync = promisify(execFile);
 
 const LAUNCHD_FALLBACK_PATHS = [
@@ -16,15 +22,9 @@ const LAUNCHD_FALLBACK_PATHS = [
   "/sbin",
 ];
 
-export interface LaunchdJobDefinition {
+export interface LaunchdJobDefinition extends LaunchdPlistDefinition {
   label: string;
   plistPath: string;
-  programArguments: string[];
-  intervalSeconds: number;
-  environmentVariables: Record<string, string>;
-  stdoutPath: string;
-  stderrPath: string;
-  workingDirectory?: string;
 }
 
 export type ExecFn = (
@@ -47,10 +47,6 @@ export function launchdTarget(): string {
   return `gui/${userInfo().uid}`;
 }
 
-export function automationLogsDir(home: string = homedir()): string {
-  return path.join(home, ".almanac", "logs");
-}
-
 export function buildLaunchPath(home: string, envPath: string | undefined): string {
   const installPaths = (envPath ?? "")
     .split(":")
@@ -60,13 +56,19 @@ export function buildLaunchPath(home: string, envPath: string | undefined): stri
     path.join(home, ".local", "bin"),
     path.join(home, ".bun", "bin"),
   ];
-  return unique([...installPaths, ...userPaths, ...LAUNCHD_FALLBACK_PATHS]).join(":");
+  return unique([...installPaths, ...userPaths, ...LAUNCHD_FALLBACK_PATHS])
+    .join(":");
 }
 
 export async function ensureLaunchdDirs(jobs: LaunchdJobDefinition[]): Promise<void> {
   await Promise.all([
     ...jobs.map((job) => mkdir(path.dirname(job.plistPath), { recursive: true })),
-    ...unique(jobs.flatMap((job) => [path.dirname(job.stdoutPath), path.dirname(job.stderrPath)]))
+    ...unique(
+      jobs.flatMap((job) => [
+        path.dirname(job.stdoutPath),
+        path.dirname(job.stderrPath),
+      ]),
+    )
       .map((dir) => mkdir(dir, { recursive: true })),
   ]);
 }
@@ -113,7 +115,7 @@ export async function readLaunchdPlistStatus(
     installed: true,
     plistPath,
     contents,
-    intervalSeconds: readStartInterval(contents),
+    intervalSeconds: readLaunchdStartInterval(contents),
   };
 }
 
@@ -141,57 +143,6 @@ async function isLaunchdJobLoaded(
   }
 }
 
-function renderLaunchdPlist(args: LaunchdJobDefinition): string {
-  const programArguments = args.programArguments
-    .map((arg) => `    <string>${escapeXml(arg)}</string>`)
-    .join("\n");
-  const environmentVariables = Object.entries(args.environmentVariables)
-    .map(([key, value]) => `    <key>${escapeXml(key)}</key>\n    <string>${escapeXml(value)}</string>`)
-    .join("\n");
-  return `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
-  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>${escapeXml(args.label)}</string>
-  <key>ProgramArguments</key>
-  <array>
-${programArguments}
-  </array>
-  <key>StartInterval</key>
-  <integer>${args.intervalSeconds}</integer>
-${args.workingDirectory !== undefined
-    ? `  <key>WorkingDirectory</key>\n  <string>${escapeXml(args.workingDirectory)}</string>\n`
-    : ""}  <key>EnvironmentVariables</key>
-  <dict>
-${environmentVariables}
-  </dict>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>StandardOutPath</key>
-  <string>${escapeXml(args.stdoutPath)}</string>
-  <key>StandardErrorPath</key>
-  <string>${escapeXml(args.stderrPath)}</string>
-</dict>
-</plist>
-`;
-}
-
-function readStartInterval(contents: string): number | null {
-  const value = contents.match(/<key>StartInterval<\/key>\s*<integer>(\d+)<\/integer>/)?.[1];
-  return value === undefined ? null : Number(value);
-}
-
-function escapeXml(value: string): string {
-  return value
-    .replaceAll("&", "&amp;")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;")
-    .replaceAll("'", "&apos;");
-}
-
 function unique(values: string[]): string[] {
   return [...new Set(values)];
 }

src/platform/automation/scheduler.ts

@@ -7,6 +7,7 @@ import {
   writeLaunchdPlist,
   type ExecFn,
 } from "./launchd.js";
+import { readLaunchdProgramArguments } from "./launchd-plist.js";
 import { detectLegacyCaptureSweepAutomation } from "./legacy-capture.js";
 import { cleanupLegacyHooks } from "./legacy-hooks.js";
 import { automationLogPaths, launchAgentPlistPath } from "./paths.js";
@@ -88,17 +89,3 @@ function buildLaunchdAutomationJob(
     stderrPath: logs.stderrPath,
   };
 }
-
-function readLaunchdProgramArguments(contents: string): string[] {
-  return [...contents.matchAll(/<string>([^<]*)<\/string>/g)]
-    .map((match) => unescapeXml(match[1] ?? ""));
-}
-
-function unescapeXml(value: string): string {
-  return value
-    .replaceAll("&apos;", "'")
-    .replaceAll("&quot;", '"')
-    .replaceAll("&gt;", ">")
-    .replaceAll("&lt;", "<")
-    .replaceAll("&amp;", "&");
-}

test/architecture-automation-update-boundaries.test.ts

@@ -39,6 +39,10 @@ describe("architecture boundaries: automation, update, config, and agents", () =
     const setupAutoUpdateStep = await readSource("src/edges/cli/setup/auto-update-step.ts");
     const uninstallEdge = await readSource("src/edges/cli/uninstall.ts");
     const launchdAutomationScheduler = await readSource("src/platform/automation/scheduler.ts");
+    const launchd = await readSource("src/platform/automation/launchd.ts");
+    const launchdPlist = await readSource(
+      "src/platform/automation/launchd-plist.ts",
+    );
     const automationPaths = await readSource("src/platform/automation/paths.ts");
     const automationInstallCommand = await readSource(
       "src/edges/cli/commands/automation/install.ts",
@@ -155,6 +159,20 @@ describe("architecture boundaries: automation, update, config, and agents", () =
     expect(launchdAutomationScheduler).toContain("automationLogPaths");
     expect(launchdAutomationScheduler).toContain("launchAgentPlistPath");
     expect(launchdAutomationScheduler).toContain("readLaunchdProgramArguments");
+    expect(launchdAutomationScheduler).toContain("launchd-plist.js");
+    expect(existsSync(join(ROOT, "src/platform/automation/launchd-plist.ts")))
+      .toBe(true);
+    expect(launchd).toContain("renderLaunchdPlist");
+    expect(launchd).toContain("readLaunchdStartInterval");
+    expect(launchd).not.toContain("function renderLaunchdPlist");
+    expect(launchd).not.toContain("function escapeXml");
+    expect(launchd).not.toContain("function readLaunchdStartInterval");
+    expect(launchd).not.toContain("automationLogsDir");
+    expect(launchdPlist).toContain("renderLaunchdPlist");
+    expect(launchdPlist).toContain("readLaunchdStartInterval");
+    expect(launchdPlist).toContain("readLaunchdProgramArguments");
+    expect(launchdPlist).toContain("function escapeXml");
+    expect(launchdPlist).toContain("function unescapeXml");
     expect(existsSync(join(ROOT, "src/platform/automation/job-plan.ts"))).toBe(
       false,
     );