@moretea-labs/forge 1.7.2 → 1.8.1

package/adapters/mcp/tunnels/openai-secure-tunnel.ts

@@ -0,0 +1,223 @@
+import { readFileSync } from 'fs';
+import { credentialReference } from '../../../packages/kernel/identity/api/index';
+
+export const OPENAI_SECURE_TUNNEL_PLATFORM = 'openai-secure-tunnel' as const;
+
+export interface OpenAiSecureTunnelRuntimeConfig {
+  alias: string;
+  tunnelId: string;
+  mcpServerUrl: string;
+  runtimeApiKeyRef?: string;
+  profile?: string;
+  profileDir?: string;
+  adminProfile?: string;
+}
+
+export interface OpenAiSecureTunnelRuntimeStatusPayload {
+  process_running?: boolean;
+  healthy?: boolean;
+  ready?: boolean;
+  tunnel_id?: string;
+  profile_path?: string;
+  runtime_state?: string;
+  error?: string;
+  remote_lookup_attempted?: boolean;
+  remote_error?: string;
+  remote?: unknown;
+  control_plane_poll_health?: { state?: string; reason?: string };
+  local?: {
+    control_plane_poll_health?: { state?: string; reason?: string };
+    log?: { tail?: string };
+  };
+}
+
+export interface OpenAiSecureTunnelRuntimeObservation {
+  ok: boolean;
+  running: boolean;
+  healthy: boolean;
+  ready: boolean;
+  tunnelMatches: boolean;
+  endpointMatches: boolean;
+  controlPlaneState: 'ready' | 'degraded' | 'unknown';
+  controlPlaneDetail: string;
+  alias: string;
+  tunnelId: string;
+  observedTunnelId?: string;
+  clientInstanceId?: string;
+  remoteLookupAttempted?: boolean;
+  detail: string;
+  profilePath?: string;
+}
+
+export function isOpenAiTunnelId(value: string): boolean {
+  return /^tunnel_[0-9a-f]{32}$/.test(value);
+}
+
+export function isOpenAiTunnelAlias(value: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(value);
+}
+
+export function isOpenAiRuntimeApiKeyRef(value: string): boolean {
+  if (/^env:[A-Za-z_][A-Za-z0-9_]*$/.test(value)) return true;
+  return /^file:\//.test(value);
+}
+
+export function tunnelRuntimeProfileTargetsEndpoint(profilePath: string | undefined, endpoint: string): boolean {
+  if (!profilePath) return false;
+  try { return readFileSync(profilePath, 'utf8').includes(endpoint); } catch { return false; }
+}
+
+export function openAiSecureTunnelStatusArgs(
+  alias: string,
+  options: Pick<OpenAiSecureTunnelRuntimeConfig, 'adminProfile'> = {},
+): string[] {
+  if (!isOpenAiTunnelAlias(alias)) throw new Error('OPENAI_TUNNEL_ALIAS_INVALID');
+  const args = ['runtimes', 'status', alias, '--json'];
+  if (options.adminProfile?.trim()) args.push('--admin-profile', options.adminProfile.trim());
+  return args;
+}
+
+export function openAiSecureTunnelConnectArgs(config: OpenAiSecureTunnelRuntimeConfig): string[] {
+  if (!isOpenAiTunnelAlias(config.alias)) throw new Error('OPENAI_TUNNEL_ALIAS_INVALID');
+  if (!isOpenAiTunnelId(config.tunnelId)) throw new Error('OPENAI_TUNNEL_ID_INVALID');
+  if (!config.runtimeApiKeyRef || !isOpenAiRuntimeApiKeyRef(config.runtimeApiKeyRef)) {
+    throw new Error('OPENAI_TUNNEL_RUNTIME_API_KEY_REF_REQUIRED');
+  }
+  // Kernel receives only a reference shape; tunnel-client remains owner of the secret.
+  credentialReference(config.runtimeApiKeyRef, OPENAI_SECURE_TUNNEL_PLATFORM);
+  const endpoint = new URL(config.mcpServerUrl);
+  if (endpoint.protocol !== 'http:' || !['127.0.0.1', 'localhost', '::1'].includes(endpoint.hostname)) {
+    throw new Error('OPENAI_TUNNEL_MCP_SERVER_LOOPBACK_REQUIRED');
+  }
+  const args = [
+    'runtimes', 'connect',
+    '--alias', config.alias,
+    '--tunnel-id', config.tunnelId,
+    '--runtime-api-key', config.runtimeApiKeyRef,
+    '--mcp-server-url', config.mcpServerUrl,
+  ];
+  if (config.adminProfile) args.push('--admin-profile', config.adminProfile);
+  if (config.profile) args.push('--profile', config.profile);
+  if (config.profileDir) args.push('--profile-dir', config.profileDir);
+  return args;
+}
+
+function controlPlaneEvidence(value: OpenAiSecureTunnelRuntimeStatusPayload): {
+  state: OpenAiSecureTunnelRuntimeObservation['controlPlaneState'];
+  detail: string;
+  clientInstanceId?: string;
+} {
+  let clientInstanceId: string | undefined;
+  let latestControlPlane: { level?: string; msg?: string; error?: string } | undefined;
+  const tail = value.local?.log?.tail;
+  if (typeof tail === 'string') {
+    for (const line of tail.trim().split('\n').reverse()) {
+      try {
+        const event = JSON.parse(line) as Record<string, unknown>;
+        if (!clientInstanceId && typeof event.client_instance_id === 'string') clientInstanceId = event.client_instance_id;
+        if (!latestControlPlane && event.component === 'controlplane') {
+          latestControlPlane = {
+            level: typeof event.level === 'string' ? event.level : undefined,
+            msg: typeof event.msg === 'string' ? event.msg : undefined,
+            error: typeof event.error === 'string' ? event.error : undefined,
+          };
+        }
+        if (clientInstanceId && latestControlPlane) break;
+      } catch { /* bounded diagnostic tail may contain non-JSON lines */ }
+    }
+  }
+
+  const remoteError = typeof value.remote_error === 'string' ? value.remote_error.trim() : '';
+  if (value.remote_lookup_attempted === true) {
+    if (remoteError) return { state: 'degraded', detail: `remote lookup failed: ${remoteError}`, ...(clientInstanceId ? { clientInstanceId } : {}) };
+    if (value.remote && typeof value.remote === 'object') {
+      return { state: 'ready', detail: 'remote tunnel lookup succeeded', ...(clientInstanceId ? { clientInstanceId } : {}) };
+    }
+  }
+
+  const pollHealth = value.control_plane_poll_health ?? value.local?.control_plane_poll_health;
+  const pollState = pollHealth?.state?.trim().toLowerCase();
+  if (pollState === 'ready' || pollState === 'healthy') {
+    return { state: 'ready', detail: pollHealth?.reason?.trim() || `control-plane poll state is ${pollState}`, ...(clientInstanceId ? { clientInstanceId } : {}) };
+  }
+  if (pollState === 'degraded' || pollState === 'error' || pollState === 'failed') {
+    return { state: 'degraded', detail: pollHealth?.reason?.trim() || `control-plane poll state is ${pollState}`, ...(clientInstanceId ? { clientInstanceId } : {}) };
+  }
+
+  if (latestControlPlane) {
+    const message = [latestControlPlane.msg, latestControlPlane.error].filter(Boolean).join(': ');
+    if (/poller recovered|polling operational/i.test(message)) {
+      return { state: 'ready', detail: message, ...(clientInstanceId ? { clientInstanceId } : {}) };
+    }
+    if (latestControlPlane.level === 'WARN' || latestControlPlane.level === 'ERROR' || /timed out|timeout|deadline|reset by peer|lookup .*i\/o timeout|context canceled/i.test(message)) {
+      return { state: 'degraded', detail: message || 'latest control-plane event is degraded', ...(clientInstanceId ? { clientInstanceId } : {}) };
+    }
+  }
+
+  return {
+    state: 'unknown',
+    detail: pollHealth?.reason?.trim() || 'remote control-plane reachability was not established',
+    ...(clientInstanceId ? { clientInstanceId } : {}),
+  };
+}
+
+export function parseOpenAiSecureTunnelRuntimeStatus(
+  stdout: string,
+  expected: Pick<OpenAiSecureTunnelRuntimeConfig, 'alias' | 'tunnelId' | 'mcpServerUrl'>,
+): OpenAiSecureTunnelRuntimeObservation {
+  let value: OpenAiSecureTunnelRuntimeStatusPayload;
+  try {
+    value = JSON.parse(stdout || '{}') as OpenAiSecureTunnelRuntimeStatusPayload;
+  } catch {
+    return {
+      ok: false,
+      running: false,
+      healthy: false,
+      ready: false,
+      tunnelMatches: false,
+      endpointMatches: false,
+      controlPlaneState: 'unknown',
+      controlPlaneDetail: 'status payload was not valid JSON',
+      alias: expected.alias,
+      tunnelId: expected.tunnelId,
+      detail: 'OpenAI tunnel runtime status was not valid JSON',
+    };
+  }
+  const running = value.process_running === true;
+  const healthy = value.healthy === true;
+  const ready = value.ready === true;
+  const tunnelMatches = value.tunnel_id === expected.tunnelId;
+  const endpointMatches = tunnelRuntimeProfileTargetsEndpoint(value.profile_path, expected.mcpServerUrl);
+  const controlPlane = controlPlaneEvidence(value);
+  // `process_running` only describes runtimes that tunnel-client supervises
+  // itself. An externally owned service manager (launchd/systemd) reports the
+  // runtime as not running while the tunnel is healthy, reachable, and bound to
+  // the expected identity. Health, readiness, tunnel id, and endpoint binding are
+  // the transport facts; process registry state is diagnostic only.
+  const localReady = healthy && ready && tunnelMatches && endpointMatches;
+  const ok = localReady && controlPlane.state === 'ready';
+  const mismatches: string[] = [];
+  if (!tunnelMatches && value.tunnel_id) mismatches.push(`tunnel id mismatch (${value.tunnel_id})`);
+  if (!endpointMatches && value.profile_path) mismatches.push('runtime profile targets a different MCP endpoint');
+  if (!healthy) mismatches.push(`runtime is ${value.runtime_state ?? 'not running'}`);
+  if (healthy && !ready) mismatches.push('runtime is not ready');
+  if (value.error) mismatches.push(value.error);
+  if (controlPlane.state !== 'ready') mismatches.push(`control plane ${controlPlane.state}: ${controlPlane.detail}`);
+  return {
+    ok,
+    running,
+    healthy,
+    ready,
+    tunnelMatches,
+    endpointMatches,
+    controlPlaneState: controlPlane.state,
+    controlPlaneDetail: controlPlane.detail,
+    alias: expected.alias,
+    tunnelId: expected.tunnelId,
+    ...(value.tunnel_id ? { observedTunnelId: value.tunnel_id } : {}),
+    ...(controlPlane.clientInstanceId ? { clientInstanceId: controlPlane.clientInstanceId } : {}),
+    ...(value.remote_lookup_attempted === undefined ? {} : { remoteLookupAttempted: value.remote_lookup_attempted }),
+    detail: ok ? `managed runtime ${expected.alias} is locally ready and its OpenAI control plane is reachable for ${expected.tunnelId}` : (mismatches.join('; ') || 'OpenAI tunnel runtime is not ready'),
+    ...(value.profile_path ? { profilePath: value.profile_path } : {}),
+  };
+}

package/adapters/mcp/types.ts

@@ -0,0 +1,41 @@
+export type McpProfileName = 'planner' | 'executor' | 'orchestrator' | 'controller';
+export type McpPathIntent = 'read' | 'write';
+export type McpAgentRunnerName = 'codex' | 'claude';
+/** Controller MCP tools/list exposure profile.
+ * - facade: explicit five-tool ChatGPT orchestration surface
+ * - core/advanced (default compatibility labels): bounded stable controller surface
+ * - full: compatibility mode — all legacy + runtime tools
+ */
+export type McpToolset = 'facade' | 'core' | 'advanced' | 'full';
+
+export interface McpPolicy {
+  profile: McpProfileName;
+  readGlobs: string[];
+  writeGlobs: string[];
+  denyGlobs: string[];
+  maxFileBytes: number;
+  execution: {
+    fixedWorkflowCheck: boolean;
+    codexRunner: boolean;
+    agentRunner: boolean;
+    allowedAgents: McpAgentRunnerName[];
+    runnerTimeoutMs: number;
+    runnerMaxTimeoutMs: number;
+  };
+}
+
+export interface McpPathDecision {
+  ok: boolean;
+  relativePath?: string;
+  absolutePath?: string;
+  reason?: string;
+}
+
+export interface McpAuditEntry {
+  timestamp: string;
+  tool: string;
+  status: 'ok' | 'blocked' | 'failed';
+  targetPath?: string;
+  inputHash?: string;
+  error?: string;
+}

package/assets/AGENTS.md

@@ -10,17 +10,15 @@ Keep this file focused on the local contract for this primary functional block.
 - Name: `contract-assets`
 - Primary prefix: `assets/workflow-contract.v1.json`
 - Architecture module: `docs/architecture/modules/workflow-engine/contract-assets.md`
-- Workstream: `tasks/workstreams/workflow-engine/contract-assets`
 
 ## Positioning
 
-Owns the workflow-engine-contract-assets capability boundary declared in .ai/context/capabilities.json.
+Owns packaged workflow/compatibility contract assets. Mutable execution lifecycle is Controller Home authority; assets must not reintroduce repo-local machine workflow state.
 
 ## Source Map
 
 - Primary prefix: `assets/workflow-contract.v1.json` (entrypoint)
 - Architecture module: `docs/architecture/modules/workflow-engine/contract-assets.md` (design-source)
-- Workstream: `tasks/workstreams/workflow-engine/contract-assets` (durable-progress)
 
 ## Refresh Hints
 
@@ -52,17 +50,5 @@ Owns the workflow-engine-contract-assets capability boundary declared in .ai/con
 - Semantic diagram source: `docs/architecture/modules/workflow-engine/contract-assets.md`
 - Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
-
-## Active Workstreams
-
-- `tasks/workstreams/workflow-engine/contract-assets/cleanup-script-policy.md`
-  - status: completed
-  - current_slice: todo-01
-  - source_plan: (none)
-
-## Current Session Projection
-
-- Durable progress lives under `tasks/workstreams/workflow-engine/contract-assets`.
-- `tasks/current.md` is a tracked derived status snapshot, not a live lock or task source.
-- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- Runtime progress authority: Forge Controller Home Requirement/Plan/Work/Evidence; this repository block contains authored architecture context only.
 <!-- END ARCHITECTURE CONTRACT -->

package/assets/CLAUDE.md

@@ -10,17 +10,15 @@ Keep this file focused on the local contract for this primary functional block.
 - Name: `contract-assets`
 - Primary prefix: `assets/workflow-contract.v1.json`
 - Architecture module: `docs/architecture/modules/workflow-engine/contract-assets.md`
-- Workstream: `tasks/workstreams/workflow-engine/contract-assets`
 
 ## Positioning
 
-Owns the workflow-engine-contract-assets capability boundary declared in .ai/context/capabilities.json.
+Owns packaged workflow/compatibility contract assets. Mutable execution lifecycle is Controller Home authority; assets must not reintroduce repo-local machine workflow state.
 
 ## Source Map
 
 - Primary prefix: `assets/workflow-contract.v1.json` (entrypoint)
 - Architecture module: `docs/architecture/modules/workflow-engine/contract-assets.md` (design-source)
-- Workstream: `tasks/workstreams/workflow-engine/contract-assets` (durable-progress)
 
 ## Refresh Hints
 
@@ -52,17 +50,5 @@ Owns the workflow-engine-contract-assets capability boundary declared in .ai/con
 - Semantic diagram source: `docs/architecture/modules/workflow-engine/contract-assets.md`
 - Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
-
-## Active Workstreams
-
-- `tasks/workstreams/workflow-engine/contract-assets/cleanup-script-policy.md`
-  - status: completed
-  - current_slice: todo-01
-  - source_plan: (none)
-
-## Current Session Projection
-
-- Durable progress lives under `tasks/workstreams/workflow-engine/contract-assets`.
-- `tasks/current.md` is a tracked derived status snapshot, not a live lock or task source.
-- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- Runtime progress authority: Forge Controller Home Requirement/Plan/Work/Evidence; this repository block contains authored architecture context only.
 <!-- END ARCHITECTURE CONTRACT -->

package/assets/hooks/AGENTS.md

@@ -10,7 +10,7 @@ Keep this file focused on the local contract for this primary functional block.
 - Route deep implementation detail into nearby docs instead of inflating root agent context files.
 - Treat `.ai/context/context-map.json` as the index of discoverable context files.
 - Do not keep pushing context files deeper by default; add lower-level files only for a separately owned functional block with its own commands and invariants.
-- Prefer repo-local workflow artifacts over tool-specific chat memory.
+- Prefer authored repository context for durable source knowledge and Controller Home for mutable workflow state; tool-specific chat memory is never authority.
 
 <!-- BEGIN CAPABILITY CONTEXT -->
 ## Capability Context
@@ -20,7 +20,6 @@ Keep this file focused on the local contract for this primary functional block.
 - Name: `hook-adapters`
 - Primary prefix: `assets/hooks`
 - Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- Workstream: `tasks/workstreams/runtime-harness/hook-adapters`
 
 ## Positioning
 
@@ -30,12 +29,11 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 
 - Primary prefix: `assets/hooks` (entrypoint)
 - Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md` (design-source)
-- Workstream: `tasks/workstreams/runtime-harness/hook-adapters` (durable-progress)
 
 ## Refresh Hints
 
 - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
-- `bash scripts/check-task-workflow.sh --strict`
+- `forge run check-task-workflow --strict`
 <!-- END CAPABILITY CONTEXT -->
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->
@@ -62,14 +60,5 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 - Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
 - Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
-
-## Active Workstreams
-
-- (none yet)
-
-## Current Session Projection
-
-- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
-- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
-- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- Runtime progress authority: Forge Controller Home Requirement/Plan/Work/Evidence; this repository block contains authored architecture context only.
 <!-- END ARCHITECTURE CONTRACT -->

package/assets/hooks/CLAUDE.md

@@ -10,7 +10,7 @@ Keep this file focused on the local contract for this primary functional block.
 - Route deep implementation detail into nearby docs instead of inflating root agent context files.
 - Treat `.ai/context/context-map.json` as the index of discoverable context files.
 - Do not keep pushing context files deeper by default; add lower-level files only for a separately owned functional block with its own commands and invariants.
-- Prefer repo-local workflow artifacts over tool-specific chat memory.
+- Prefer authored repository context for durable source knowledge and Controller Home for mutable workflow state; tool-specific chat memory is never authority.
 
 <!-- BEGIN CAPABILITY CONTEXT -->
 ## Capability Context
@@ -20,7 +20,6 @@ Keep this file focused on the local contract for this primary functional block.
 - Name: `hook-adapters`
 - Primary prefix: `assets/hooks`
 - Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- Workstream: `tasks/workstreams/runtime-harness/hook-adapters`
 
 ## Positioning
 
@@ -30,12 +29,11 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 
 - Primary prefix: `assets/hooks` (entrypoint)
 - Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md` (design-source)
-- Workstream: `tasks/workstreams/runtime-harness/hook-adapters` (durable-progress)
 
 ## Refresh Hints
 
 - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
-- `bash scripts/check-task-workflow.sh --strict`
+- `forge run check-task-workflow --strict`
 <!-- END CAPABILITY CONTEXT -->
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->
@@ -62,14 +60,5 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 - Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
 - Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
-
-## Active Workstreams
-
-- (none yet)
-
-## Current Session Projection
-
-- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
-- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
-- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- Runtime progress authority: Forge Controller Home Requirement/Plan/Work/Evidence; this repository block contains authored architecture context only.
 <!-- END ARCHITECTURE CONTRACT -->

package/assets/hooks/hook-input.sh

@@ -14,9 +14,12 @@ if [[ -z "${HOOK_REPO_ROOT:-}" ]]; then
   export HOOK_REPO_ROOT
 fi
 
-if [[ -f "${HOOK_REPO_ROOT:-$(pwd)}/.ai/hooks/lib/workflow-state.sh" ]]; then
+HOOK_BUNDLE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+if [[ -f "$HOOK_BUNDLE_DIR/lib/workflow-state.sh" ]]; then
+  # Source workflow helpers from the same selected hook bundle. A central hook
+  # must never fall back to a stale repo-local lib and silently change authority.
   # shellcheck source=/dev/null
-  . "${HOOK_REPO_ROOT:-$(pwd)}/.ai/hooks/lib/workflow-state.sh"
+  . "$HOOK_BUNDLE_DIR/lib/workflow-state.sh"
 fi
 
 hook_read_stdin_once() {
@@ -546,6 +549,10 @@ hook_failure_log_file() {
     workflow_failure_log_file
     return 0
   fi
+  if [[ -n "${FORGE_HOOK_STATE_ROOT:-}" && "${FORGE_HOOK_STATE_ROOT}" == /* ]]; then
+    printf '%s/failures/latest.jsonl' "${FORGE_HOOK_STATE_ROOT%/}"
+    return 0
+  fi
   printf '.ai/harness/failures/latest.jsonl'
 }
 

package/assets/hooks/lib/workflow-state.sh

@@ -70,44 +70,62 @@ workflow_repo_relative_path() {
   esac
 }
 
+workflow_machine_state_path() {
+  local value="$1"
+  local default_value="$2"
+  local relative_path
+
+  value="$(workflow_repo_relative_path "$value" "$default_value" '.ai/harness/')"
+  if [[ -n "${FORGE_HOOK_STATE_ROOT:-}" && "${FORGE_HOOK_STATE_ROOT}" == /* ]]; then
+    relative_path="${value#.ai/harness/}"
+    printf '%s/%s' "${FORGE_HOOK_STATE_ROOT%/}" "$relative_path"
+    return 0
+  fi
+  printf '%s' "$value"
+}
+
 workflow_context_map_file() {
   workflow_repo_relative_path "$(workflow_policy_get '.context.map_file' '.ai/context/context-map.json')" '.ai/context/context-map.json' '.ai/context/'
 }
 
 workflow_failure_log_file() {
-  workflow_repo_relative_path "$(workflow_policy_get '.harness.failure_log_file' '.ai/harness/failures/latest.jsonl')" '.ai/harness/failures/latest.jsonl' '.ai/harness/'
+  workflow_machine_state_path "$(workflow_policy_get '.harness.failure_log_file' '.ai/harness/failures/latest.jsonl')" '.ai/harness/failures/latest.jsonl'
 }
 
 workflow_events_file() {
-  workflow_repo_relative_path "$(workflow_policy_get '.harness.events_file' '.ai/harness/events.jsonl')" '.ai/harness/events.jsonl' '.ai/harness/'
+  workflow_machine_state_path "$(workflow_policy_get '.harness.events_file' '.ai/harness/events.jsonl')" '.ai/harness/events.jsonl'
 }
 
 workflow_trace_file() {
+  if [[ -n "${FORGE_HOOK_STATE_ROOT:-}" && "${FORGE_HOOK_STATE_ROOT}" == /* ]]; then
+    printf '%s/trace.jsonl' "${FORGE_HOOK_STATE_ROOT%/}"
+    return 0
+  fi
   printf '%s' ".claude/.trace.jsonl"
 }
 
 workflow_runs_dir() {
-  workflow_repo_relative_path "$(workflow_policy_get '.harness.runs_dir' '.ai/harness/runs')" '.ai/harness/runs' '.ai/harness/'
+  workflow_machine_state_path "$(workflow_policy_get '.harness.runs_dir' '.ai/harness/runs')" '.ai/harness/runs'
 }
 
 workflow_resume_packet_file() {
-  workflow_repo_relative_path "$(workflow_policy_get '.session.resume_file' '.ai/harness/session/resume.md')" '.ai/harness/session/resume.md' '.ai/harness/'
+  workflow_machine_state_path "$(workflow_policy_get '.session.resume_file' '.ai/harness/session/resume.md')" '.ai/harness/session/resume.md'
 }
 
 workflow_pending_orchestration_file() {
+  # Legacy read/migration surface only. Modern controller-home repositories do
+  # not create a second file-backed Plan/pending authority from hooks.
   workflow_repo_relative_path "$(workflow_policy_get '.planning.pending_orchestration_file' '.ai/harness/planning/pending.json')" '.ai/harness/planning/pending.json' '.ai/harness/'
 }
 
 workflow_ensure_harness_surface() {
+  # Hooks initialize only rebuildable machine diagnostics. Authored task/context
+  # directories and semantic Plan state remain repository/Controller concerns.
   mkdir -p \
-    "tasks/notes" \
-    "$(dirname "$(workflow_context_map_file)")" \
-    "$(dirname "$(workflow_policy_file)")" \
     "$(dirname "$(workflow_checks_file)")" \
     "$(dirname "$(workflow_session_continuation_file)")" \
     "$(dirname "$(workflow_resume_packet_file)")" \
     "$(dirname "$(workflow_failure_log_file)")" \
-    "$(dirname "$(workflow_pending_orchestration_file)")" \
     "$(workflow_runs_dir)"
 
   [[ -f "$(workflow_checks_file)" ]] || printf "{}\n" > "$(workflow_checks_file)"
@@ -1094,11 +1112,11 @@ workflow_active_notes() {
 }
 
 workflow_checks_file() {
-  workflow_repo_relative_path "$(workflow_policy_get '.harness.checks_file' '.ai/harness/checks/latest.json')" '.ai/harness/checks/latest.json' '.ai/harness/'
+  workflow_machine_state_path "$(workflow_policy_get '.harness.checks_file' '.ai/harness/checks/latest.json')" '.ai/harness/checks/latest.json'
 }
 
 workflow_session_continuation_file() {
-  workflow_repo_relative_path "$(workflow_policy_get '.session.continuation_file' '.ai/harness/session/continuation.md')" '.ai/harness/session/continuation.md' '.ai/harness/'
+  workflow_machine_state_path "$(workflow_policy_get '.session.continuation_file' '.ai/harness/session/continuation.md')" '.ai/harness/session/continuation.md'
 }
 
 # mkdir-based mutual exclusion (macOS ships no flock). Spins ~2s, breaks locks