@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/control-plane/facade/codex-delegation.ts

@@ -0,0 +1,196 @@
+import { randomUUID } from 'crypto';
+import { buildFacadeResult } from './facade-result';
+import type {
+  EvidenceRef,
+  FacadeResult,
+  WorkContract,
+} from './types';
+
+export type DelegateTarget = 'codex' | 'grok' | 'claude';
+
+/** @deprecated since 1.4.0; removed no earlier than 2026-12-31. Use controller_claim and handoff_create/read/accept. */
+
+export interface CodexContextPack {
+  schemaVersion: 1;
+  workId?: string;
+  repoId: string;
+  target: DelegateTarget;
+  objective: string;
+  acceptanceCriteria: string[];
+  constraints: WorkContract['constraints'];
+  relevantFilesSummary: string[];
+  policyBoundaries: string[];
+  allowedPaths: string[];
+  forbiddenPaths: string[];
+  currentEvidenceRefs: EvidenceRef[];
+  workContractState?: {
+    workId: string;
+    status: WorkContract['status'];
+    mode: WorkContract['mode'];
+  };
+  policyDecision?: string;
+  expectedOutputFormat: {
+    mustProduce: Array<'evidence_artifact' | 'handoff_item' | 'patch_proposal' | 'suggested_next_actions'>;
+    mustNot: string[];
+  };
+}
+
+export interface GrokDelegateRequestPacket {
+  schemaVersion: 1;
+  requestId: string;
+  target: 'grok';
+  mode: 'bounded_handoff_request';
+  repoId: string;
+  workId?: string;
+  objective: string;
+  acceptanceCriteria: string[];
+  constraints: WorkContract['constraints'];
+  allowedPaths: string[];
+  forbiddenPaths: string[];
+  relevantFilesSummary: string[];
+  policyBoundaries: string[];
+  currentEvidenceRefs: EvidenceRef[];
+  requiredOutputFormat: CodexContextPack['expectedOutputFormat'];
+  instructions: string[];
+  /** Direct Grok execution is not assumed available; ChatGPT remains authority. */
+  directExecutionAvailable: false;
+  returnPath: 'evidence_or_handoff_for_chatgpt_review';
+}
+
+export interface CodexDelegationInput {
+  workId?: string;
+  target?: DelegateTarget;
+  objective: string;
+  acceptanceCriteria?: string[];
+  allowedPaths?: string[];
+  forbiddenPaths?: string[];
+  constraints?: WorkContract['constraints'];
+  relevantFilesSummary?: string[];
+  policyBoundaries?: string[];
+  evidenceRefs?: EvidenceRef[];
+  policyDecision?: string;
+  /** When false, target executor is treated as unavailable. Defaults: codex/claude true if not set; grok false for direct exec. */
+  available?: boolean;
+  /** @deprecated Use available. Kept for stage-2 callers. */
+  codexAvailable?: boolean;
+  workerOutput?: {
+    uncertain?: boolean;
+    summary?: string;
+    patchProposal?: string;
+    evidenceSummary?: string;
+  };
+}
+
+export interface CodexDelegationContext {
+  repoId: string;
+}
+
+function normalizeTarget(value: unknown): DelegateTarget {
+  if (value === 'grok' || value === 'claude' || value === 'codex') return value;
+  return 'codex';
+}
+
+export function buildCodexContextPack(input: CodexDelegationInput & { repoId: string; work?: WorkContract }): CodexContextPack {
+  const work = input.work;
+  const target = normalizeTarget(input.target);
+  return {
+    schemaVersion: 1,
+    workId: input.workId ?? work?.workId,
+    repoId: input.repoId,
+    target,
+    objective: (input.objective || work?.objective || '').slice(0, 2_000),
+    acceptanceCriteria: (input.acceptanceCriteria ?? work?.acceptanceCriteria ?? []).slice(0, 20),
+    constraints: input.constraints ?? work?.constraints ?? { requireHandoffOnAmbiguity: true },
+    relevantFilesSummary: (input.relevantFilesSummary ?? []).slice(0, 30).map((entry) => entry.slice(0, 200)),
+    policyBoundaries: (input.policyBoundaries ?? [
+      `${target} is an external controller, not a Kernel-managed executor.`,
+      'Do not finalize WorkContract.',
+      'Do not push, merge, or perform destructive cleanup.',
+      'Do not return raw secrets, tokens, auth config, or full runtime state.',
+      'Output must be evidence / handoff / patch proposal / suggested_next_actions only.',
+      'ChatGPT must review before rh_work.finalize.',
+    ]).slice(0, 20),
+    allowedPaths: (input.allowedPaths ?? work?.allowedPaths ?? []).slice(0, 50),
+    forbiddenPaths: (input.forbiddenPaths ?? work?.forbiddenPaths ?? ['.env', '_ops/secrets', '**/*secret*', '**/*token*']).slice(0, 50),
+    currentEvidenceRefs: (input.evidenceRefs ?? work?.evidenceRefs ?? []).slice(0, 10),
+    workContractState: work
+      ? { workId: work.workId, status: work.status, mode: work.mode }
+      : undefined,
+    policyDecision: input.policyDecision,
+    expectedOutputFormat: {
+      mustProduce: ['evidence_artifact', 'handoff_item', 'patch_proposal', 'suggested_next_actions'],
+      mustNot: [
+        'finalize_work_contract',
+        'mutate_mainline_state_directly',
+        'push_or_remote_write',
+        'return_raw_stdout_stderr',
+        'return_secrets_or_tokens',
+      ],
+    },
+  };
+}
+
+export function prepareGrokDelegateRequest(
+  input: CodexDelegationInput & { repoId: string; work?: WorkContract },
+): GrokDelegateRequestPacket {
+  const pack = buildCodexContextPack({ ...input, target: 'grok' });
+  return {
+    schemaVersion: 1,
+    requestId: `grok-req-${randomUUID().slice(0, 10)}`,
+    target: 'grok',
+    mode: 'bounded_handoff_request',
+    repoId: pack.repoId,
+    workId: pack.workId,
+    objective: pack.objective,
+    acceptanceCriteria: pack.acceptanceCriteria,
+    constraints: pack.constraints,
+    allowedPaths: pack.allowedPaths,
+    forbiddenPaths: pack.forbiddenPaths,
+    relevantFilesSummary: pack.relevantFilesSummary,
+    policyBoundaries: pack.policyBoundaries,
+    currentEvidenceRefs: pack.currentEvidenceRefs,
+    requiredOutputFormat: pack.expectedOutputFormat,
+    instructions: [
+      'Act as a parallel small-brain reviewer/implementer for ChatGPT.',
+      'Return only bounded evidence, patch proposal, and suggested next actions.',
+      'Do not finalize work, push, or request secrets.',
+      'ChatGPT remains the primary controller and must review before finalize.',
+    ],
+    directExecutionAvailable: false,
+    returnPath: 'evidence_or_handoff_for_chatgpt_review',
+  };
+}
+
+/**
+ * Deprecated compatibility surface. It intentionally performs no Work/Handoff
+ * mutation and never starts or interprets an external controller session.
+ */
+export function delegateToCodexCerebellum(
+  ctx: CodexDelegationContext,
+  input: CodexDelegationInput,
+): FacadeResult {
+  const target = normalizeTarget(input.target);
+  const pack = buildCodexContextPack({
+    ...input,
+    target,
+    repoId: ctx.repoId,
+  });
+  return buildFacadeResult({
+    status: 'blocked',
+    summary: 'DEPRECATED_DELEGATE: delegate is read-only through 2026-12-31 and will be removed in 1.5.0. Use controller_claim, launcher_start, and rh_inbox.create/accept.',
+    data: {
+      target,
+      workId: input.workId,
+      deprecated: true,
+      removalVersion: '1.5.0',
+      removalDate: '2026-12-31',
+      canFinalize: false,
+      contextPack: pack,
+      workerOutputIgnored: input.workerOutput !== undefined,
+    },
+    suggestedNextActions: input.workId ? [
+      { label: 'Claim controller ownership', tool: 'rh_work', operation: 'controller_claim', payload: { work_id: input.workId }, risk: 'workspace_write' },
+      { label: 'Start external controller', tool: 'rh_work', operation: 'launcher_start', payload: { work_id: input.workId, controller_type: target }, risk: 'workspace_write' },
+    ] : [],
+  });
+}

package/src/runtime/control-plane/facade/controller-session-store.ts

@@ -0,0 +1,199 @@
+import { join } from 'path';
+import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
+import { withControllerLock } from '../../../cli/repositories/locks';
+import { peekExecutionSession } from '../execution/session-store';
+import { readJsonFile } from '../../shared/json-files';
+import { readOrImportControlPlaneRecord, writeControlPlaneRecord } from '../persistence/sqlite-store';
+import type { ControllerSession, ControllerSessionStore, ControllerType } from './types';
+
+export interface ControllerSessionStoreOptions { controllerHome: string; repoId: string; now?: () => string; }
+
+export interface ControllerSessionClaimInput {
+  workId: string;
+  controllerId: string;
+  controllerType: ControllerType;
+  sessionId: string;
+  principalId?: string;
+  controllerInstanceId?: string;
+  /** Optional compare-and-swap fence supplied by a recovering caller. */
+  expectedClaimGeneration?: number;
+  leaseMs?: number;
+}
+
+function path(options: ControllerSessionStoreOptions): string {
+  return join(repositoryControllerRoot(options.controllerHome, options.repoId), 'controller-sessions.json');
+}
+
+function now(options: ControllerSessionStoreOptions): string { return options.now?.() ?? new Date().toISOString(); }
+
+function read(options: ControllerSessionStoreOptions): ControllerSessionStore {
+  const legacyPath = path(options);
+  return readOrImportControlPlaneRecord<ControllerSessionStore>(options.controllerHome, {
+    namespace: 'controller_session_claim_store',
+    scope: options.repoId,
+    key: 'index',
+    schemaVersion: 1,
+    readLegacy: () => readJsonFile<ControllerSessionStore>(legacyPath, { schemaVersion: 1, updatedAt: now(options), sessions: [] }),
+  })?.value ?? { schemaVersion: 1, updatedAt: now(options), sessions: [] };
+}
+
+function write(options: ControllerSessionStoreOptions, store: ControllerSessionStore): void {
+  writeControlPlaneRecord(options.controllerHome, {
+    namespace: 'controller_session_claim_store',
+    scope: options.repoId,
+    key: 'index',
+    schemaVersion: 1,
+    value: store,
+    action: 'controller_session_claim_write',
+  });
+}
+
+function activeSession(store: ControllerSessionStore, workId: string): ControllerSession | undefined {
+  const at = Date.now();
+  return store.sessions.find((session) => session.workId === workId && Date.parse(session.leaseExpiresAt) > at);
+}
+
+function assertIdentity(input: ControllerSessionClaimInput): void {
+  if (!input.workId.trim() || !input.controllerId.trim() || !input.sessionId.trim()) {
+    throw new Error('CONTROLLER_SESSION_IDENTITY_REQUIRED');
+  }
+}
+
+function claimedSession(
+  options: ControllerSessionStoreOptions,
+  input: ControllerSessionClaimInput,
+  claimedAt: string,
+  previous?: ControllerSession,
+): ControllerSession {
+  const leaseExpiresAt = new Date(
+    Date.parse(claimedAt) + Math.max(1_000, Math.min(input.leaseMs ?? 300_000, 3_600_000)),
+  ).toISOString();
+  const sameOwner = previous?.controllerId === input.controllerId
+    && previous.sessionId === input.sessionId
+    && (previous.controllerInstanceId ?? '') === (input.controllerInstanceId?.trim() ?? '');
+  const claimGeneration = sameOwner
+    ? Math.max(1, previous?.claimGeneration ?? 1)
+    : Math.max(0, previous?.claimGeneration ?? 0) + 1;
+  return {
+    schemaVersion: 1,
+    workId: input.workId,
+    controllerId: input.controllerId,
+    controllerType: input.controllerType,
+    sessionId: input.sessionId,
+    ...(input.principalId?.trim() ? { principalId: input.principalId.trim() } : {}),
+    ...(input.controllerInstanceId?.trim() ? { controllerInstanceId: input.controllerInstanceId.trim() } : {}),
+    claimGeneration,
+    claimedAt,
+    leaseExpiresAt,
+  };
+}
+
+function assertExpectedGeneration(input: ControllerSessionClaimInput, current: ControllerSession | undefined): void {
+  if (input.expectedClaimGeneration === undefined) return;
+  const actual = current?.claimGeneration ?? 0;
+  if (actual !== input.expectedClaimGeneration) {
+    throw new Error(`WORK_CLAIM_GENERATION_MISMATCH: ${input.workId} expected=${input.expectedClaimGeneration} actual=${actual}`);
+  }
+}
+
+function persistClaim(
+  options: ControllerSessionStoreOptions,
+  store: ControllerSessionStore,
+  input: ControllerSessionClaimInput,
+  previous?: ControllerSession,
+): ControllerSession {
+  const claimedAt = now(options);
+  const session = claimedSession(options, input, claimedAt, previous);
+  const sessions = [
+    ...store.sessions.filter((entry) => entry.workId !== input.workId && Date.parse(entry.leaseExpiresAt) > Date.now()),
+    session,
+  ];
+  write(options, { schemaVersion: 1, updatedAt: claimedAt, sessions });
+  return session;
+}
+
+export function getControllerSession(options: ControllerSessionStoreOptions, workId: string): ControllerSession | undefined {
+  return activeSession(read(options), workId);
+}
+
+/**
+ * Strict claim used for first ownership acquisition and explicit release/reclaim flows.
+ * A live claim with any different controller or transport session remains fenced.
+ */
+export function claimControllerSession(
+  options: ControllerSessionStoreOptions,
+  input: ControllerSessionClaimInput,
+): ControllerSession {
+  assertIdentity(input);
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'task', repoId: options.repoId, taskId: `controller-session-${input.workId}` },
+    `controller-claim:${input.controllerId}:${input.sessionId}`,
+    () => {
+      const store = read(options);
+      const current = activeSession(store, input.workId);
+      assertExpectedGeneration(input, current);
+      if (current && (current.controllerId !== input.controllerId || current.sessionId !== input.sessionId)) {
+        throw new Error(`WORK_ALREADY_CLAIMED: ${input.workId} is owned by ${current.controllerId}`);
+      }
+      return persistClaim(options, store, input, current);
+    },
+  );
+}
+
+/**
+ * Resume a claim after transport replacement without allowing same-epoch stealing.
+ * The authenticated principal must remain identical, and a different session id
+ * is accepted only when the previous execution session is gone/invalidated or
+ * belongs to a different Controller instance (the normal rollout boundary).
+ */
+export function resumeControllerSession(
+  options: ControllerSessionStoreOptions,
+  input: ControllerSessionClaimInput & { principalId: string; controllerInstanceId: string },
+): ControllerSession {
+  assertIdentity(input);
+  if (!input.principalId.trim() || !input.controllerInstanceId.trim()) {
+    throw new Error('CONTROLLER_RESUME_AUTHORITY_REQUIRED');
+  }
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'task', repoId: options.repoId, taskId: `controller-session-${input.workId}` },
+    `controller-resume:${input.controllerId}:${input.sessionId}`,
+    () => {
+      const store = read(options);
+      const current = activeSession(store, input.workId);
+      assertExpectedGeneration(input, current);
+      if (!current) return persistClaim(options, store, input);
+      const priorExecution = peekExecutionSession(options.controllerHome, current.sessionId);
+      const currentPrincipal = current.principalId?.trim() || priorExecution?.principalId?.trim() || current.controllerId;
+      if (currentPrincipal !== input.principalId.trim()) {
+        throw new Error(`WORK_CONTROLLER_PRINCIPAL_MISMATCH: ${input.workId} is owned by another authenticated principal`);
+      }
+      if (current.controllerId !== input.controllerId) {
+        throw new Error(`WORK_ALREADY_CLAIMED: ${input.workId} is owned by ${current.controllerId}`);
+      }
+      if (current.sessionId !== input.sessionId) {
+        const priorInstance = current.controllerInstanceId?.trim() || priorExecution?.controllerInstanceId?.trim();
+        const priorSessionUnavailable = !priorExecution || Boolean(priorExecution.invalidatedAt);
+        const crossedControllerEpoch = Boolean(priorInstance && priorInstance !== input.controllerInstanceId.trim());
+        if (!priorSessionUnavailable && !crossedControllerEpoch) {
+          throw new Error(`WORK_ALREADY_CLAIMED: ${input.workId} has an active session ${current.sessionId}`);
+        }
+      }
+      return persistClaim(options, store, input, current);
+    },
+  );
+}
+
+export function releaseControllerSession(options: ControllerSessionStoreOptions, workId: string, controllerId: string): void {
+  withControllerLock(
+    options.controllerHome,
+    { scope: 'task', repoId: options.repoId, taskId: `controller-session-${workId}` },
+    `controller-release:${controllerId}`,
+    () => {
+      const store = read(options);
+      const sessions = store.sessions.filter((entry) => entry.workId !== workId || entry.controllerId !== controllerId);
+      write(options, { schemaVersion: 1, updatedAt: now(options), sessions });
+    },
+  );
+}

package/src/runtime/control-plane/facade/facade-result.ts

@@ -0,0 +1,41 @@
+import type { EvidenceRef, FacadeDetailLevel, FacadeResult, FacadeStatus, SuggestedNextAction } from './types';
+import { validateSuggestedNextActions } from './suggested-actions';
+
+export interface BuildFacadeResultOptions<TData = Record<string, unknown>> {
+  status?: FacadeStatus;
+  summary: string;
+  data: TData;
+  evidenceRefs?: EvidenceRef[];
+  warnings?: string[];
+  suggestedNextActions?: SuggestedNextAction[];
+  rawAvailable?: boolean;
+  detailLevel?: FacadeDetailLevel;
+}
+
+function boundText(value: string, maxChars: number): string {
+  return value.length <= maxChars ? value : `${value.slice(0, maxChars)}...`;
+}
+
+function boundRecord(value: unknown, depth = 0): unknown {
+  if (typeof value === 'string') return boundText(value, depth === 0 ? 4_000 : 1_000);
+  if (!value || typeof value !== 'object') return value;
+  if (depth >= 5) return '[bounded-depth]';
+  if (Array.isArray(value)) return value.slice(0, 50).map((entry) => boundRecord(entry, depth + 1));
+  const entries = Object.entries(value as Record<string, unknown>).slice(0, 80);
+  return Object.fromEntries(entries.map(([key, entry]) => [key, boundRecord(entry, depth + 1)]));
+}
+
+export function buildFacadeResult<TData = Record<string, unknown>>(options: BuildFacadeResultOptions<TData>): FacadeResult<TData> {
+  const suggestedNextActions = validateSuggestedNextActions(options.suggestedNextActions ?? []);
+  return {
+    schemaVersion: 1,
+    status: options.status ?? 'ok',
+    summary: boundText(options.summary, 1_000),
+    data: boundRecord(options.data) as TData,
+    evidenceRefs: options.evidenceRefs ?? [],
+    warnings: options.warnings ?? [],
+    suggestedNextActions: suggestedNextActions.actions,
+    rawAvailable: options.rawAvailable ?? false,
+    detailLevel: options.detailLevel ?? 'summary',
+  };
+}

package/src/runtime/control-plane/facade/goal-workloop-access.ts

@@ -0,0 +1,177 @@
+import {
+  accessModeDescriptor,
+  isAccessMode,
+  normalizeAccessMode,
+  readRepositoryAccessPolicy,
+  type AccessMode,
+} from '../governance/access-policy';
+import {
+  routeWorkStart as routeWorkStartBase,
+  runGoalWorkloop as runGoalWorkloopBase,
+  type GoalWorkloopContext,
+  type GoalWorkloopOperation,
+  type GoalWorkloopStartInput,
+} from './goal-workloop';
+import { getWorkContract } from './work-contract-store';
+import type { CapabilityRisk, FacadeResult, WorkContractConstraints } from './types';
+
+export {
+  continueGoalWorkloop,
+  finalizeGoalWorkloop,
+  startGoalWorkloop,
+  stopGoalWorkloop,
+  verifyGoalWorkloop,
+  type GoalWorkloopContext,
+  type GoalWorkloopContinueInput,
+  type GoalWorkloopFinalizeInput,
+  type GoalWorkloopOperation,
+  type GoalWorkloopStartInput,
+  type GoalWorkloopStopInput,
+  type GoalWorkloopVerifyInput,
+} from './goal-workloop';
+
+function booleanValue(record: Record<string, unknown>, camel: string, snake: string): boolean | undefined {
+  const value = record[camel] ?? record[snake];
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function numberValue(record: Record<string, unknown>, camel: string, snake: string): number | undefined {
+  const value = record[camel] ?? record[snake];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function accessModeValue(value: unknown): AccessMode | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  const candidate = record.accessMode ?? record.access_mode;
+  return isAccessMode(candidate) ? candidate : undefined;
+}
+
+function constraintsValue(value: unknown): WorkContractConstraints | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  const constraints: WorkContractConstraints = {
+    maxChangedFiles: numberValue(record, 'maxChangedFiles', 'max_changed_files'),
+    maxChangedLines: numberValue(record, 'maxChangedLines', 'max_changed_lines'),
+    allowCommit: booleanValue(record, 'allowCommit', 'allow_commit'),
+    allowMerge: booleanValue(record, 'allowMerge', 'allow_merge'),
+    allowCleanup: booleanValue(record, 'allowCleanup', 'allow_cleanup'),
+    allowDestructive: booleanValue(record, 'allowDestructive', 'allow_destructive'),
+    requireHandoffOnAmbiguity: booleanValue(record, 'requireHandoffOnAmbiguity', 'require_handoff_on_ambiguity'),
+    accessMode: accessModeValue(record),
+    workspaceMode: record.workspaceMode === 'current' || record.workspace_mode === 'current'
+      ? 'current'
+      : record.workspaceMode === 'isolated' || record.workspace_mode === 'isolated'
+        ? 'isolated'
+        : record.workspaceMode === 'auto' || record.workspace_mode === 'auto' ? 'auto' : undefined,
+    requireWorktree: booleanValue(record, 'requireWorktree', 'require_worktree'),
+  };
+  return Object.fromEntries(
+    Object.entries(constraints).filter(([, entry]) => entry !== undefined),
+  ) as WorkContractConstraints;
+}
+
+function repositoryDefaultMode(ctx: GoalWorkloopContext): AccessMode {
+  const controllerHome = ctx.workStore.controllerHome;
+  if (!controllerHome) return 'full_access';
+  return readRepositoryAccessPolicy(controllerHome, ctx.repoId).mode;
+}
+
+function resolveMode(ctx: GoalWorkloopContext, constraints?: WorkContractConstraints): AccessMode {
+  return normalizeAccessMode(constraints?.accessMode, repositoryDefaultMode(ctx));
+}
+
+function normalizeStartInput(ctx: GoalWorkloopContext, input: GoalWorkloopStartInput): GoalWorkloopStartInput {
+  const accessMode = resolveMode(ctx, input.constraints);
+  return {
+    ...input,
+    constraints: {
+      requireHandoffOnAmbiguity: true,
+      ...input.constraints,
+      accessMode,
+    },
+  };
+}
+
+function decorateAccessMode(result: FacadeResult, mode: AccessMode): FacadeResult {
+  const descriptor = accessModeDescriptor(mode);
+  const work = result.data.work;
+  return {
+    ...result,
+    data: {
+      ...result.data,
+      accessMode: mode,
+      accessModeLabel: descriptor.shortLabel,
+      accessModeDescription: descriptor.description,
+      ...(work && typeof work === 'object' && !Array.isArray(work)
+        ? {
+            work: {
+              ...(work as Record<string, unknown>),
+              accessMode: mode,
+              accessModeLabel: descriptor.shortLabel,
+            },
+          }
+        : {}),
+    },
+  };
+}
+
+export function routeWorkStart(ctx: GoalWorkloopContext, input: GoalWorkloopStartInput): FacadeResult {
+  const normalized = normalizeStartInput(ctx, input);
+  const mode = normalized.constraints?.accessMode ?? 'full_access';
+  return decorateAccessMode(routeWorkStartBase(ctx, normalized), mode);
+}
+
+export function runGoalWorkloop(
+  ctx: GoalWorkloopContext,
+  operation: GoalWorkloopOperation,
+  args: Record<string, unknown>,
+): FacadeResult {
+  if (operation !== 'start') {
+    const workId = typeof args.work_id === 'string' ? args.work_id : '';
+    const existing = workId ? getWorkContract(ctx.workStore, workId) : undefined;
+    const mode = resolveMode(ctx, existing?.constraints);
+    return decorateAccessMode(runGoalWorkloopBase(ctx, operation, args), mode);
+  }
+
+  const constraints = constraintsValue(args.constraints);
+  return routeWorkStart(ctx, {
+    objective: String(args.objective ?? ''),
+    acceptanceCriteria: Array.isArray(args.acceptance_criteria) ? args.acceptance_criteria.map(String) : undefined,
+    allowedPaths: Array.isArray(args.allowed_paths) ? args.allowed_paths.map(String) : undefined,
+    forbiddenPaths: Array.isArray(args.forbidden_paths) ? args.forbidden_paths.map(String) : undefined,
+    checks: Array.isArray(args.check_ids) ? args.check_ids.map(String) : undefined,
+    constraints,
+    modeInput: {
+      objective: typeof args.objective === 'string' ? args.objective : undefined,
+      expectedFiles: typeof args.expected_files === 'number' ? args.expected_files : undefined,
+      expectedChangedLines: typeof args.expected_changed_lines === 'number' ? args.expected_changed_lines : undefined,
+      scopeClear: args.scope_clear === undefined ? true : args.scope_clear === true,
+      requiresInvestigation: args.requires_investigation === true,
+      requiresLongRunningChecks: args.requires_long_running_checks === true,
+      requiresParallelism: args.requires_parallelism === true,
+      needsDependencies: args.needs_dependencies === true,
+      requiresRecovery: args.requires_recovery === true,
+      requiresWorker: args.requires_worker === true,
+      requiresExternalEffect: args.requires_external_effect === true,
+      requiresApproval: args.requires_approval === true,
+      requiresUserApproval: args.requires_user_approval === true,
+      destructive: args.destructive === true,
+      remoteWrite: args.remote_write === true,
+      secretAccess: args.secret_access === true,
+      risk: typeof args.risk === 'string' ? args.risk as CapabilityRisk : undefined,
+    },
+    requestedBy: args.requested_by === 'user' || args.requested_by === 'system' || args.requested_by === 'scheduler'
+      ? args.requested_by
+      : 'chatgpt',
+    taskId: typeof args.task_id === 'string' ? args.task_id : undefined,
+    issueId: typeof args.issue_id === 'string' ? args.issue_id : undefined,
+    approvalConfirmed: args.approval_confirmed === true,
+    dryRun: args.dry_run === true,
+    forceMode: args.force_mode === 'direct_control' || args.force_mode === 'goal_workloop' || args.force_mode === 'handoff_only'
+      ? args.force_mode
+      : undefined,
+    planId: typeof args.plan_id === 'string' ? args.plan_id : undefined,
+    planStepId: typeof args.plan_step_id === 'string' ? args.plan_step_id : undefined,
+  });
+}