@moretea-labs/forge 1.7.2 → 1.8.1

package/src/cli/controller/operational-plan.ts

@@ -18,13 +18,13 @@ export interface ControllerOperationalPlan {
     reviewRequired: boolean;
   };
   validationStrategy: {
-    source: "task-targeted-validation-policy";
+    source: "declared-check-projection";
     policy: "minimal" | "task-targeted" | "release-gate";
     checks: string[];
     reason: string;
   };
   recipeSystem: {
-    source: "controller-recipe-system";
+    source: "legacy-recipe-projection";
     recipes: Array<{
       id: string;
       label: string;
@@ -34,7 +34,7 @@ export interface ControllerOperationalPlan {
     }>;
   };
   workerAbstraction: {
-    source: "worker-routing-abstraction";
+    source: "execution-capability-projection";
     workers: Array<{
       id: string;
       role: string;
@@ -107,11 +107,9 @@ export function buildControllerOperationalPlan(repoRoot: string, ledger: TaskLed
   const dirty = changedFiles.length > 0;
   const blocked = ledger.status.kind === "blocked" || ledger.status.kind === "needs_retry_decision";
   const needsAttention = blocked || ledger.status.severity === "action" || ledger.status.severity === "warning" || dirty;
-  const policy = checks.some((check) => check.includes("release") || check.includes("ci"))
-    ? "release-gate" as const
-    : checks.length > 0
-      ? "task-targeted" as const
-      : "minimal" as const;
+  // Compatibility projection only. Declared checks are facts the model may use;
+  // this projection does not choose a validation method or release gate.
+  const policy = "minimal" as const;
 
   return {
     schemaVersion: OPERATIONAL_PLAN_SCHEMA_VERSION,
@@ -122,70 +120,45 @@ export function buildControllerOperationalPlan(repoRoot: string, ledger: TaskLed
       "task-ledger",
       "context-pack",
       "diff-projection",
-      "validation-strategy",
-      "recipe-system",
-      "worker-abstraction",
+      "declared-check-projection",
+      "legacy-recipe-projection",
+      "execution-capability-projection",
       "gui-interaction-model",
       "mcp-tool-schema-convergence",
       "controller-home-runtime-storage-policy",
       "branch-worktree-cleanup-policy",
       "task-recovery-loop",
     ],
-    remainingDecisionPoints: dirty
-      ? ["Review and commit or discard current diff before dispatching unrelated work."]
-      : [],
+    remainingDecisionPoints: [],
     diffProjection: {
       source: "live-git-diff-projection",
       dirty,
       changedFiles,
       diffStat: diffStat.ok ? diffStat.stdout.trim() : diffStat.error || diffStat.stderr.trim(),
-      reviewRequired: dirty,
+      // Legacy field retained for UI ABI only. Dirty state is a fact, not an
+      // automatic review lifecycle decision.
+      reviewRequired: false,
     },
     validationStrategy: {
-      source: "task-targeted-validation-policy",
+      source: "declared-check-projection",
       policy,
       checks,
-      reason: policy === "release-gate"
-        ? "Release or CI checks are declared by the focused work."
-        : policy === "task-targeted"
-          ? "Use checks declared on the focused task or ready queue; do not expand validation scope by default."
-          : "No task-specific checks were found; keep validation minimal and explicit.",
+      reason: checks.length > 0
+        ? "These checks are declared context only; the model decides whether, when, and how to validate."
+        : "No declared checks were found; Forge does not invent a validation strategy.",
     },
     recipeSystem: {
-      source: "controller-recipe-system",
-      recipes: [
-        {
-          id: "scoped-direct-edit",
-          label: "Scoped direct edit",
-          when: "Known files and low/medium-risk bounded changes.",
-          steps: ["build context pack", "read exact ranges", "apply bounded patch", "review diff projection", "run task-targeted checks"],
-          requiredEvidence: ["contextPack", "diffProjection", "validationStrategy"],
-        },
-        {
-          id: "isolated-worker-run",
-          label: "Isolated worker run",
-          when: "Large, risky, or long-running implementation requiring agent execution.",
-          steps: ["derive worker scope", "dispatch isolated run", "inspect run diff", "integrate through edit session", "verify exact revision"],
-          requiredEvidence: ["run", "task diff", "integration session", "checks"],
-        },
-        {
-          id: "recovery-resume",
-          label: "Fresh-session recovery",
-          when: "A controller session restarts or loses conversation state.",
-          steps: ["load task ledger", "read operational plan", "select continuation state", "expand only needed context", "resume or ask for the one missing decision"],
-          requiredEvidence: ["taskLedger", "operationalPlan", "recoveryArtifacts"],
-        },
-      ],
+      source: "legacy-recipe-projection",
+      recipes: [],
     },
     workerAbstraction: {
-      source: "worker-routing-abstraction",
+      source: "execution-capability-projection",
       workers: [
-        { id: "direct_edit", role: "transactional patch executor", preferredFor: ["small scoped edits", "known paths"], avoidWhen: ["unknown architecture", "long-running generation"] },
-        { id: "quick_agent", role: "bounded investigation or small implementation", preferredFor: ["uncertain file discovery", "medium-risk changes"], avoidWhen: ["dirty main workspace", "release-critical changes"] },
-        { id: "isolated_task_run", role: "durable worker with worktree", preferredFor: ["parallel tasks", "risky implementation"], avoidWhen: ["single-line fixes"] },
-        { id: "github_copilot", role: "visible cloud coding session", preferredFor: ["remote reviewable work", "GitHub issue flow"], avoidWhen: ["secret-local context", "offline tasks"] },
+        { id: "direct_capability", role: "direct domain capability execution", preferredFor: [], avoidWhen: [] },
+        { id: "isolated_process", role: "isolated process/workspace capability when explicitly useful", preferredFor: [], avoidWhen: [] },
+        { id: "external_provider", role: "optional external model/provider capability", preferredFor: [], avoidWhen: [] },
       ],
-      recommendedWorker: dirty ? "direct_edit" : ledger.status.kind === "ready_to_dispatch" ? "isolated_task_run" : "direct_edit",
+      recommendedWorker: "model_selected",
     },
     guiInteraction: {
       source: "controller-console-interaction-model",

package/src/cli/controller/runtime-config.ts

@@ -6,7 +6,11 @@ export { FORGE_VERSION } from '../../version';
 /** Product identity exposed by every Forge runtime surface. */
 export const FORGE_TOOL_SURFACE = FORGE_PRODUCT_ID;
 /** Payload schema for MCP health/config records; this is not a product/component version. */
-export const FORGE_MCP_SCHEMA_VERSION = 10;
+// 12: autonomous continuation is addressed by Workflow Supervisor task identity
+// rather than optional Work identity. Tool names stay bounded; the served input
+// schema changes and therefore must fence stale Connector schema snapshots.
+// A served-schema change must be visible to connector freshness checks.
+export const FORGE_MCP_SCHEMA_VERSION = 12;
 
 type ToolSurfaceDefinition = {
   name: string;

package/src/cli/controller/stuck-state-migration.ts

@@ -3,7 +3,7 @@ import { spawnSync } from 'child_process';
 import { createHash } from 'crypto';
 import { inspectCompletionBacklog, type CompletionBacklogItem } from './completion-backlog';
 import { getIssue, listIssues, updateIssue, updateTask } from './issue-store';
-import { completionEvidenceComplete, taskExecutionPolicy, verificationEvidencePassed } from './execution-policy';
+import { completionEvidenceComplete, verificationEvidencePassed } from './execution-policy';
 import type { CompletionReceipt, ControllerIssue, ControllerTask } from './types';
 import { resolveCompletionTargetBranch } from './completion-target';
 import { legacyIssueAuthorityRetired } from './legacy-issue-cutover';
@@ -174,8 +174,7 @@ function reachable(repoRoot: string, revision: string, branch: string): boolean
 
 function historicalCompletionReceipt(repoRoot: string, issue: ControllerIssue, task: ControllerTask): CompletionReceipt | undefined {
   if (!task.verification) return undefined;
-  const policy = taskExecutionPolicy(task);
-  const outcome = verificationEvidencePassed(task, task.verification, policy);
+  const outcome = verificationEvidencePassed(task, task.verification);
   if (!outcome.ok) return undefined;
   const target = currentTarget(repoRoot);
   if (!target) return undefined;

package/src/cli/controller/systemd-user.ts

@@ -0,0 +1,148 @@
+import { spawnSync, type SpawnSyncReturns } from 'child_process';
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+
+export interface SystemdUserUnitInput {
+  description?: string;
+  executable: string;
+  args: string[];
+  environment: Record<string, string>;
+  restart?: 'no' | 'on-failure' | 'always';
+  restartSec?: number;
+}
+
+function atomicWrite(path: string, content: string, mode = 0o644): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, content, { encoding: 'utf8', mode });
+  renameSync(temporary, path);
+}
+
+export function systemdEscape(value: string): string {
+  return `"${value.replaceAll('%', '%%').replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+
+export function renderSystemdUserUnit(input: SystemdUserUnitInput): string {
+  const environment = Object.entries(input.environment)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, value]) => `Environment=${systemdEscape(`${key}=${value}`)}`)
+    .join('\n');
+  return [
+    '[Unit]',
+    `Description=${input.description ?? 'Forge service'}`,
+    'After=network-online.target',
+    '',
+    '[Service]',
+    'Type=simple',
+    `ExecStart=${[input.executable, ...input.args].map(systemdEscape).join(' ')}`,
+    ...(environment ? [environment] : []),
+    `Restart=${input.restart ?? 'on-failure'}`,
+    `RestartSec=${Math.max(1, Math.trunc(input.restartSec ?? 5))}`,
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+}
+
+function commandSucceeded(command: string, args: string[], env: NodeJS.ProcessEnv): SpawnSyncReturns<string> {
+  return spawnSync(command, args, { encoding: 'utf8', env, timeout: 30_000 });
+}
+
+export function systemdUserAvailable(env: NodeJS.ProcessEnv = process.env): boolean {
+  return commandSucceeded('systemctl', ['--user', 'show-environment'], env).status === 0;
+}
+
+export function systemdUserUnitName(label: string): string {
+  const normalized = label.trim();
+  if (!normalized) throw new Error('SYSTEMD_USER_UNIT_LABEL_REQUIRED');
+  return normalized.endsWith('.service') ? normalized : `${normalized}.service`;
+}
+
+export function systemdUserUnitPath(unitName: string, env: NodeJS.ProcessEnv = process.env): string {
+  return join(env.HOME ?? homedir(), '.config', 'systemd', 'user', systemdUserUnitName(unitName));
+}
+
+export function systemdUserInstallCommands(unitName: string): string[][] {
+  const unit = systemdUserUnitName(unitName);
+  return [
+    ['--user', 'daemon-reload'],
+    ['--user', 'enable', unit],
+    ['--user', 'restart', unit],
+  ];
+}
+
+export function writeSystemdUserUnit(
+  unitName: string,
+  input: SystemdUserUnitInput,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const unitPath = systemdUserUnitPath(unitName, env);
+  atomicWrite(unitPath, renderSystemdUserUnit(input), 0o644);
+  return unitPath;
+}
+
+export function installSystemdUserUnit(input: {
+  unitName: string;
+  unit: SystemdUserUnitInput;
+  env?: NodeJS.ProcessEnv;
+  errorPrefix?: string;
+}): string {
+  const env = input.env ?? process.env;
+  const unit = systemdUserUnitName(input.unitName);
+  const unitPath = writeSystemdUserUnit(unit, input.unit, env);
+  for (const args of systemdUserInstallCommands(unit)) {
+    const result = commandSucceeded('systemctl', args, env);
+    if (result.status !== 0) {
+      const prefix = input.errorPrefix?.trim() || 'SYSTEMD_USER_INSTALL_FAILED';
+      throw new Error(`${prefix}: systemctl ${args.join(' ')}: ${(result.stderr || result.stdout || '').trim()}`);
+    }
+  }
+  return unitPath;
+}
+
+export function systemdUserServicePid(unitName: string, env: NodeJS.ProcessEnv = process.env): number | undefined {
+  const result = commandSucceeded('systemctl', ['--user', 'show', '--property', 'MainPID', '--value', systemdUserUnitName(unitName)], env);
+  if (result.status !== 0) return undefined;
+  const pid = Number(result.stdout.trim());
+  return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+
+export interface ExactSystemdUserUnitRetirementResult {
+  unitName: string;
+  unitPath: string;
+  serviceWasPresent: boolean;
+  unitFileWasPresent: boolean;
+  absentAfter: boolean;
+}
+
+function systemdUnitLoaded(unitName: string, env: NodeJS.ProcessEnv): boolean {
+  const result = commandSucceeded('systemctl', ['--user', 'show', '--property', 'LoadState', '--value', systemdUserUnitName(unitName)], env);
+  return result.status === 0 && result.stdout.trim() !== '' && result.stdout.trim() !== 'not-found';
+}
+
+export function retireSystemdUserUnitExact(
+  input: { unitName: string; env?: NodeJS.ProcessEnv },
+): ExactSystemdUserUnitRetirementResult {
+  const env = input.env ?? process.env;
+  const unitName = systemdUserUnitName(input.unitName);
+  const unitPath = systemdUserUnitPath(unitName, env);
+  const serviceWasPresent = systemdUnitLoaded(unitName, env);
+  const unitFileWasPresent = existsSync(unitPath);
+  if (serviceWasPresent || unitFileWasPresent) {
+    const disabled = commandSucceeded('systemctl', ['--user', 'disable', '--now', unitName], env);
+    const detail = `${disabled.stderr ?? ''}\n${disabled.stdout ?? ''}`;
+    if (disabled.status !== 0 && !/not loaded|not found|does not exist|not enabled|no files found/i.test(detail)) {
+      throw new Error(`SYSTEMD_USER_EXACT_RETIRE_FAILED: ${unitName}: ${detail.trim()}`);
+    }
+  }
+  rmSync(unitPath, { force: true });
+  const reload = commandSucceeded('systemctl', ['--user', 'daemon-reload'], env);
+  if (reload.status !== 0) {
+    throw new Error(`SYSTEMD_USER_EXACT_RETIRE_RELOAD_FAILED: ${unitName}: ${(reload.stderr || reload.stdout || '').trim()}`);
+  }
+  const absentAfter = !systemdUnitLoaded(unitName, env) && !existsSync(unitPath);
+  if (!absentAfter) throw new Error(`SYSTEMD_USER_EXACT_RETIRE_VERIFY_FAILED: ${unitName}`);
+  return { unitName, unitPath, serviceWasPresent, unitFileWasPresent, absentAfter };
+}

package/src/cli/controller/types.ts

@@ -1,4 +1,14 @@
 import type { ProcessCheckReceiptEvidence } from '../../runtime/evidence/process-check-receipt';
+import type { CompletionMaintenanceWarning, CompletionReceipt, CompletionResourceBlocker } from '../../../packages/kernel/work/api/index';
+export type {
+  CompletionMaintenanceWarning,
+  CompletionReceipt,
+  CompletionReceiptCleanupStatus,
+  CompletionReceiptDeliveryKind,
+  CompletionReceiptDeliveryStatus,
+  CompletionReceiptSource,
+  CompletionResourceBlocker,
+} from '../../../packages/kernel/work/api/index';
 
 export type IssueKind = 'bug' | 'feature' | 'governance' | 'investigation';
 export type IssueStatus = 'backlog' | 'analysis' | 'planned' | 'launch_blocked' | 'in_progress' | 'review' | 'done' | 'cancelled';
@@ -59,76 +69,6 @@ export interface CleanupEvidence {
   recordedAt: string;
 }
 
-export type CompletionReceiptSource =
-  | 'direct_edit'
-  | 'controller_work'
-  | 'isolated_agent_run'
-  | 'workspace_run'
-  | 'remote_no_change_execution';
-
-export type CompletionReceiptDeliveryKind = 'commit' | 'no_change' | 'remote' | 'superseded';
-export type CompletionReceiptDeliveryStatus = 'integrated' | 'blocked';
-export type CompletionReceiptCleanupStatus = 'complete' | 'maintenance_warning' | 'blocked';
-
-export interface CompletionMaintenanceWarning {
-  code:
-    | 'worktree_cleanup_failed'
-    | 'branch_cleanup_failed'
-    | 'edit_session_backup_retained'
-    | 'cleanup_retained_by_request';
-  message: string;
-  resourceKind?: 'worktree' | 'branch' | 'edit_session' | 'lease' | 'process' | 'workspace';
-  resourceId?: string;
-  recordedAt: string;
-}
-
-export interface CompletionResourceBlocker {
-  code:
-    | 'unintegrated_changes'
-    | 'active_write_process'
-    | 'unknown_resource_ownership'
-    | 'dirty_owned_paths'
-    | 'edit_session_open'
-    | 'lease_active'
-    | 'run_not_terminal'
-    | 'target_revision_unreachable';
-  message: string;
-  resourceKind?: 'worktree' | 'branch' | 'edit_session' | 'lease' | 'process' | 'workspace';
-  resourceId?: string;
-  recordedAt: string;
-}
-
-export interface CompletionReceipt {
-  schemaVersion: 1;
-  receiptId: string;
-  source: CompletionReceiptSource;
-  issueId: string;
-  taskId: string;
-  runId?: string;
-  workId?: string;
-  editSessionId?: string;
-  targetBranch: string;
-  targetRevision: string;
-  sourceRevision?: string;
-  baseRevision?: string;
-  changedPaths: string[];
-  delivery: {
-    kind: CompletionReceiptDeliveryKind;
-    status: CompletionReceiptDeliveryStatus;
-    strategy: 'edit_session_commit' | 'already_integrated' | 'no_change' | 'remote';
-    reachable: boolean;
-    recordedAt: string;
-  };
-  cleanup: {
-    status: CompletionReceiptCleanupStatus;
-    warnings: CompletionMaintenanceWarning[];
-    blockers: CompletionResourceBlocker[];
-    recordedAt: string;
-  };
-  verifiedAt: string;
-  recordedAt: string;
-}
-
 export type TaskAcceptanceOutcome = 'passed' | 'failed' | 'not_evaluated';
 export type TaskAcceptanceSource = 'human_review' | 'controller_check' | 'run_completion' | 'reported' | 'legacy';
 

package/src/cli/controller/worklog.ts

@@ -7,8 +7,10 @@ import {
   writeFileSync,
 } from "fs";
 import { dirname, isAbsolute, join, relative, resolve } from "path";
+import { durableControllerHome, repositoryControllerRoot } from "../repositories/controller-home";
+import { findRegisteredRepositoryByCheckoutRoot } from "../repositories/registry";
 
-const WORKLOG_PATH = ".ai/harness/controller/worklog.jsonl";
+const WORKLOG_CONTROLLER_RELATIVE_PATH = "controller/worklog.jsonl";
 
 export const WORKLOG_CATEGORIES = [
   "issue",
@@ -61,8 +63,56 @@ export interface WorklogFilter {
   limit?: number;
 }
 
-function worklogPath(repoRoot: string): string {
-  return join(repoRoot, WORKLOG_PATH);
+export interface ControllerWorklogStorageAuthority {
+  controllerHome: string;
+  repoId: string;
+}
+
+export interface ResolvedControllerWorklogStorage extends ControllerWorklogStorageAuthority {
+  repoRoot: string;
+  physicalPath: string;
+}
+
+function resolveControllerWorklogStorageIfKnown(
+  repoRoot: string,
+  explicit?: ControllerWorklogStorageAuthority,
+): ResolvedControllerWorklogStorage | undefined {
+  const root = resolve(repoRoot);
+  if (explicit) {
+    const controllerHome = durableControllerHome(explicit.controllerHome);
+    const repoId = explicit.repoId.trim();
+    if (!repoId) throw new Error("CONTROLLER_WORKLOG_REPOSITORY_ID_REQUIRED");
+    const registered = findRegisteredRepositoryByCheckoutRoot(root, controllerHome);
+    if (registered && registered.repoId !== repoId) {
+      throw new Error(`CONTROLLER_WORKLOG_REPOSITORY_ID_MISMATCH: expected ${registered.repoId}, received ${repoId}`);
+    }
+    return {
+      controllerHome,
+      repoId,
+      repoRoot: root,
+      physicalPath: join(repositoryControllerRoot(controllerHome, repoId), WORKLOG_CONTROLLER_RELATIVE_PATH),
+    };
+  }
+
+  const controllerHome = durableControllerHome();
+  const registered = findRegisteredRepositoryByCheckoutRoot(root, controllerHome);
+  if (!registered) return undefined;
+  return {
+    controllerHome,
+    repoId: registered.repoId,
+    repoRoot: root,
+    physicalPath: join(repositoryControllerRoot(controllerHome, registered.repoId), WORKLOG_CONTROLLER_RELATIVE_PATH),
+  };
+}
+
+/** Resolve Controller-owned worklog storage without registering or initializing the repository. */
+export function resolveControllerWorklogStorage(
+  repoRoot: string,
+  explicit?: ControllerWorklogStorageAuthority,
+): ResolvedControllerWorklogStorage {
+  const storage = resolveControllerWorklogStorageIfKnown(repoRoot, explicit);
+  if (!storage) throw new Error(`CONTROLLER_WORKLOG_REPOSITORY_AUTHORITY_REQUIRED: ${resolve(repoRoot)}`);
+  return storage;
 }
 
 function eventId(): string {
@@ -75,6 +125,7 @@ export function appendControllerWorklogEvent(
     at?: string;
     actor?: string;
   },
+  authority?: ControllerWorklogStorageAuthority,
 ): ControllerWorklogEvent {
   const record: ControllerWorklogEvent = {
     schemaVersion: 1,
@@ -93,18 +144,19 @@ export function appendControllerWorklogEvent(
     statusTo: event.statusTo,
     details: event.details,
   };
-  const path = worklogPath(repoRoot);
-  mkdirSync(dirname(path), { recursive: true });
-  appendFileSync(path, `${JSON.stringify(record)}\n`, "utf-8");
+  const storage = resolveControllerWorklogStorage(repoRoot, authority);
+  mkdirSync(dirname(storage.physicalPath), { recursive: true });
+  appendFileSync(storage.physicalPath, `${JSON.stringify(record)}\n`, "utf-8");
   return record;
 }
 
 export function tryAppendControllerWorklogEvent(
   repoRoot: string,
   event: Parameters<typeof appendControllerWorklogEvent>[1],
+  authority?: ControllerWorklogStorageAuthority,
 ): void {
   try {
-    appendControllerWorklogEvent(repoRoot, event);
+    appendControllerWorklogEvent(repoRoot, event, authority);
   } catch (_error) {
     // Worklog recording is evidence enrichment. It must not corrupt the source mutation.
   }
@@ -113,12 +165,13 @@ export function tryAppendControllerWorklogEvent(
 export function listControllerWorklogEvents(
   repoRoot: string,
   filter: WorklogFilter = {},
+  authority?: ControllerWorklogStorageAuthority,
 ): ControllerWorklogEvent[] {
-  const path = worklogPath(repoRoot);
-  if (!existsSync(path)) return [];
+  const storage = resolveControllerWorklogStorageIfKnown(repoRoot, authority);
+  if (!storage || !existsSync(storage.physicalPath)) return [];
   const since = filter.since ? Date.parse(filter.since) : Number.NEGATIVE_INFINITY;
   const until = filter.until ? Date.parse(filter.until) : Number.POSITIVE_INFINITY;
-  const events = readFileSync(path, "utf-8")
+  const events = readFileSync(storage.physicalPath, "utf-8")
     .split(/\r?\n/)
     .filter(Boolean)
     .flatMap((line) => {
@@ -155,13 +208,14 @@ export function exportControllerWorklog(
     format?: "markdown" | "json";
     outputPath?: string;
     filter?: WorklogFilter;
+    authority?: ControllerWorklogStorageAuthority;
   } = {},
 ): { path: string; format: "markdown" | "json"; eventCount: number } {
   const format = options.format ?? "markdown";
   const events = listControllerWorklogEvents(repoRoot, {
     ...options.filter,
     limit: options.filter?.limit ?? 5000,
-  }).slice().reverse();
+  }, options.authority).slice().reverse();
   const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
   const defaultPath = `tasks/reports/controller-worklog-${stamp}.${format === "json" ? "json" : "md"}`;
   const outputPath = options.outputPath?.trim() || defaultPath;
@@ -196,6 +250,6 @@ export function exportControllerWorklog(
   return { path: relative(repoRoot, absolute).replace(/\\/g, "/"), format, eventCount: events.length };
 }
 
-export function controllerWorklogLocation(): string {
-  return WORKLOG_PATH;
+export function controllerWorklogLocation(repoId: string = "<repoId>"): string {
+  return `controller-home://repositories/${repoId}/controller/worklog.jsonl`;
 }

package/src/cli/editing/edit-operation-contract.ts

@@ -0,0 +1,92 @@
+export const EDIT_OPERATION_TYPES = [
+  'create',
+  'write',
+  'replace',
+  'insert_before',
+  'insert_after',
+  'prepend',
+  'append',
+  'delete',
+] as const;
+
+export type EditOperation =
+  | { type: 'create'; path: string; content: string }
+  | { type: 'write'; path: string; expectedSha256: string; content: string }
+  | { type: 'replace'; path: string; expectedSha256: string; replacements: Array<{ oldText: string; newText: string; replaceAll?: boolean }> }
+  | { type: 'insert_before' | 'insert_after'; path: string; expectedSha256: string; anchor: string; content: string; occurrence?: number }
+  | { type: 'prepend' | 'append'; path: string; expectedSha256: string; content: string }
+  | { type: 'delete'; path: string; expectedSha256: string };
+
+export const EDIT_OPERATION_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    type: { type: 'string', enum: [...EDIT_OPERATION_TYPES] },
+    path: { type: 'string' },
+    content: { type: 'string' },
+    expected_sha256: { type: 'string' },
+    anchor: { type: 'string', description: 'Anchor text for insert_before or insert_after.' },
+    occurrence: { type: 'number', description: '1-based anchor occurrence; defaults to 1.' },
+    replacements: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          old_text: { type: 'string' },
+          new_text: { type: 'string' },
+          replace_all: { type: 'boolean' },
+        },
+        required: ['old_text', 'new_text'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['type', 'path'],
+  additionalProperties: false,
+} as const;
+
+function objectEntries(value: unknown): Record<string, unknown>[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is Record<string, unknown> => typeof entry === 'object' && entry !== null && !Array.isArray(entry));
+}
+
+function normalizeReplacements(value: unknown): Array<{ oldText: string; newText: string; replaceAll?: boolean }> {
+  return objectEntries(value).map((replacement) => ({
+    oldText: String(replacement.old_text ?? replacement.oldText ?? ''),
+    newText: String(replacement.new_text ?? replacement.newText ?? ''),
+    replaceAll: replacement.replace_all === true || replacement.replaceAll === true,
+  }));
+}
+
+export function normalizeEditOperation(entry: Record<string, unknown>): EditOperation {
+  const type = String(entry.type ?? '');
+  const path = String(entry.path ?? '');
+  const expectedSha256 = String(entry.expected_sha256 ?? entry.expectedSha256 ?? '');
+  if (type === 'create') return { type, path, content: String(entry.content ?? '') };
+  if (type === 'delete') return { type, path, expectedSha256 };
+  if (type === 'write') return { type, path, expectedSha256, content: String(entry.content ?? '') };
+  if (type === 'replace') {
+    const replacements = Array.isArray(entry.replacements)
+      ? normalizeReplacements(entry.replacements)
+      : (entry.old_text !== undefined || entry.oldText !== undefined)
+        ? normalizeReplacements([entry])
+        : [];
+    if (replacements.length === 0) throw new Error('replace requires replacements[] or old_text/new_text');
+    return { type, path, expectedSha256, replacements };
+  }
+  if (type === 'insert_before' || type === 'insert_after') {
+    return {
+      type,
+      path,
+      expectedSha256,
+      anchor: String(entry.anchor ?? ''),
+      content: String(entry.content ?? ''),
+      occurrence: typeof entry.occurrence === 'number' ? Math.trunc(entry.occurrence) : undefined,
+    };
+  }
+  if (type === 'prepend' || type === 'append') return { type, path, expectedSha256, content: String(entry.content ?? '') };
+  throw new Error(`invalid edit operation type: ${type}`);
+}
+
+export function normalizeEditOperations(value: unknown): EditOperation[] {
+  return objectEntries(value).map(normalizeEditOperation);
+}