@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/control-plane/facade/handoff-inbox-application.ts

@@ -1,6 +1,6 @@
 import { getControllerSession, releaseObservedControllerSession } from '../../../../packages/kernel/controller/api/index';
-import { getWorkContract, isTerminalWorkContractStatus } from '../../../../packages/kernel/work/api/index';
-import { listSchedules } from '../../../../packages/kernel/scheduler/api/index';
+import { listUserRequests } from '../../../../packages/kernel/identity/api/index';
+import { getWorkContract, semanticWorkState } from '../../../../packages/kernel/work/api/index';
 import type { HandoffItem } from './types';
 import {
   acknowledgeHandoffItem,
@@ -44,8 +44,8 @@ export type HandoffInboxApplicationRunner = (
 ) => ReturnType<typeof runHandoffInboxApplication>;
 
 export interface HandoffAttentionResolver {
-  workIsTerminal(workId: string): boolean | undefined;
-  scheduleIsEnabled(scheduleId: string): boolean | undefined;
+  userRequestIsPending(requestId: string): boolean | undefined;
+  owningWorkIsOpen?(workId: string): boolean | undefined;
 }
 
 /**
@@ -55,15 +55,11 @@ export interface HandoffAttentionResolver {
  */
 export function handoffRequiresAttention(item: HandoffItem, resolver: HandoffAttentionResolver): boolean {
   if (item.status !== 'pending') return false;
+  const requestId = item.canonicalUserRequestId?.trim();
+  if (!requestId) return false;
   const workId = item.workId?.trim();
-  if (workId && resolver.workIsTerminal(workId) === true) return false;
-
-  const scheduleId = item.currentState.taskId?.trim();
-  const scheduleFailure = item.creationReason === 'repeated_infrastructure_failure'
-    && Boolean(scheduleId)
-    && (item.id.startsWith('schedule-failure-') || item.id.startsWith('schedule-'));
-  if (scheduleFailure && scheduleId && resolver.scheduleIsEnabled(scheduleId) === false) return false;
-  return true;
+  if (workId && resolver.owningWorkIsOpen?.(workId) === false) return false;
+  return resolver.userRequestIsPending(requestId) === true;
 }
 
 export function listHandoffAttentionItems(
@@ -71,22 +67,13 @@ export function listHandoffAttentionItems(
   limit = 50,
 ): HandoffItem[] {
   const candidates = listHandoffItems({ ...store, status: 'pending', limit: 100 });
-  const scheduleIds = new Set(candidates
-    .filter((item) => item.creationReason === 'repeated_infrastructure_failure'
-      && (item.id.startsWith('schedule-failure-') || item.id.startsWith('schedule-')))
-    .map((item) => item.currentState.taskId?.trim())
-    .filter((value): value is string => Boolean(value)));
-  const schedules = scheduleIds.size > 0
-    ? new Map(listSchedules(store.controllerHome, store.repoId).map((schedule) => [schedule.scheduleId, schedule.enabled] as const))
-    : new Map<string, boolean>();
+  const pendingRequests = new Set(listUserRequests(store.controllerHome, 'pending').map((request) => request.requestId));
   const resolver: HandoffAttentionResolver = {
-    workIsTerminal: (workId) => {
+    userRequestIsPending: (requestId) => pendingRequests.has(requestId),
+    owningWorkIsOpen: (workId) => {
       const work = getWorkContract(store, workId);
-      return work ? isTerminalWorkContractStatus(work.status) : undefined;
+      return work ? semanticWorkState(work) === 'open' : undefined;
     },
-    scheduleIsEnabled: (scheduleId) => scheduleIds.has(scheduleId)
-      ? schedules.get(scheduleId) ?? false
-      : undefined,
   };
   const boundedLimit = Math.max(1, Math.min(Math.trunc(limit), 100));
   return candidates.filter((item) => handoffRequiresAttention(item, resolver)).slice(0, boundedLimit);

package/src/runtime/control-plane/facade/handoff-inbox-store.ts

@@ -1,5 +1,12 @@
-import { mkdirSync } from 'fs';
-import { join } from 'path';
+import {
+  listUserRequests,
+  recordUserRequest,
+  resolveUserRequest,
+  type CreateUserRequestInput,
+  type UserRequest,
+} from '../../../../packages/kernel/identity/api/index';
+import { existsSync, mkdirSync, renameSync } from 'fs';
+import { dirname, join } from 'path';
 import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
 import { withControllerLock } from '../../../cli/repositories/locks';
 import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../../shared/json-files';
@@ -51,21 +58,35 @@ export interface HandoffItemSummary {
   blockingDecision?: string;
 }
 
-/** Only create handoffs for judgement points — never ordinary logs/events. */
+/** Genuine person-only blockers. Mechanical failures stay in their owning runtime domain. */
 export const HANDOFF_ELIGIBLE_REASONS = new Set<HandoffCreationReason>([
   'policy_approval_required',
   'ambiguous_outcome',
   'missing_authorization',
   'invalid_objective',
-  'repeated_infrastructure_failure',
-  'codex_worker_requires_review',
   'destructive_action_requires_confirmation',
 ]);
 
+interface HandoffMigrationMarker {
+  schemaVersion: 1;
+  repoId: string;
+  migratedAt: string;
+  legacyItemCount: number;
+  migratedUserRequestCount: number;
+  skippedMechanicalCount: number;
+  archivedPath?: string;
+}
+
 function nowIso(options: HandoffInboxStoreOptions): string {
   return options.now?.() ?? new Date().toISOString();
 }
 
+function usesCanonicalUserRequestStore(
+  options: HandoffInboxStoreOptions,
+): options is HandoffInboxStoreOptions & { controllerHome: string; repoId: string } {
+  return Boolean(options.controllerHome && options.repoId && !options.root);
+}
+
 function withHandoffInboxWriteLock<T>(
   options: HandoffInboxStoreOptions,
   owner: string,
@@ -74,7 +95,7 @@ function withHandoffInboxWriteLock<T>(
   if (!options.controllerHome || !options.repoId || options.root) return operation();
   return withControllerLock(
     options.controllerHome,
-    { scope: 'task', repoId: options.repoId, taskId: 'handoff-inbox' },
+    { scope: 'task', repoId: options.repoId, taskId: 'handoff-inbox-migration' },
     owner,
     operation,
   );
@@ -97,24 +118,213 @@ export function handoffInboxPath(location: HandoffInboxStoreLocation): string {
   return join(handoffInboxRoot(location), 'index.json');
 }
 
+function handoffMigrationMarkerPath(options: HandoffInboxStoreOptions & { controllerHome: string; repoId: string }): string {
+  return join(
+    options.controllerHome,
+    'system',
+    'user-requests',
+    'migrations',
+    `handoff-inbox-${sanitizeFileComponent(options.repoId)}.json`,
+  );
+}
+
 export function emptyHandoffInboxStore(updatedAt: string): HandoffInboxStore {
   return { schemaVersion: 1, updatedAt, items: [] };
 }
 
-export function readHandoffInboxStore(options: HandoffInboxStoreOptions): HandoffInboxStore {
+function readLegacyHandoffInboxStore(options: HandoffInboxStoreOptions): HandoffInboxStore {
   return readJsonFile<HandoffInboxStore>(handoffInboxPath(options), emptyHandoffInboxStore(nowIso(options)));
 }
 
-export function writeHandoffInboxStore(options: HandoffInboxStoreOptions, store: HandoffInboxStore): HandoffInboxStore {
-  writeJsonAtomic(handoffInboxPath(options), store);
-  return store;
-}
-
 export function shouldCreateHandoff(reason: HandoffCreationReason | string | undefined): boolean {
   if (!reason) return false;
   return HANDOFF_ELIGIBLE_REASONS.has(reason as HandoffCreationReason);
 }
 
+function userActionForHandoff(item: Pick<HandoffItem, 'creationReason'>): CreateUserRequestInput['actionRequired'] | undefined {
+  return item.creationReason === 'missing_authorization' || item.creationReason === 'policy_approval_required'
+    ? 'grant_permission'
+    : item.creationReason === 'destructive_action_requires_confirmation'
+      ? 'confirm_destructive'
+      : item.creationReason === 'ambiguous_outcome' || item.creationReason === 'invalid_objective'
+        ? 'product_decision'
+        : undefined;
+}
+
+function canonicalUserRequestInput(item: HandoffItem): CreateUserRequestInput | undefined {
+  const actionRequired = userActionForHandoff(item);
+  if (!actionRequired) return undefined;
+  const rootCauseKey = ['user-request', item.repoId, item.workId ?? 'repo', item.creationReason ?? 'decision', item.reason].join(':');
+  return {
+    requestId: item.canonicalUserRequestId?.trim() || item.id,
+    kind: actionRequired === 'product_decision' ? 'user_decision_request' : 'user_action_request',
+    rootCauseKey,
+    title: item.title,
+    summary: item.summary,
+    actionRequired,
+    targetScope: {
+      scopeKind: item.workId ? 'work' : 'repository',
+      scopeId: item.workId ?? item.repoId,
+      repoId: item.repoId,
+      ...(item.workId ? { workId: item.workId } : {}),
+    },
+    presentation: {
+      legacyHandoffId: item.id,
+      severity: item.severity,
+      creationReason: item.creationReason,
+      reason: item.reason,
+      currentState: item.currentState as unknown as Record<string, unknown>,
+      attemptedActions: item.attemptedActions,
+      evidenceRefs: item.evidenceRefs,
+      blockingDecision: item.blockingDecision,
+      recommendedDecision: item.recommendedDecision,
+      recommendedPrompt: item.recommendedPrompt,
+      recommendedContinuationPrompt: item.recommendedContinuationPrompt,
+      approvalAction: item.approvalAction,
+      suggestedNextActions: item.suggestedNextActions,
+    },
+  };
+}
+
+function projectedStatus(request: UserRequest): HandoffStatus {
+  if (request.status === 'pending') return 'pending';
+  const decision = request.resolution?.decision.trim().toLowerCase() ?? '';
+  return request.status === 'cancelled' || decision === 'dismissed' || decision.startsWith('dismissed:')
+    ? 'dismissed'
+    : 'resolved';
+}
+
+function projectedCreationReason(value: string | undefined): HandoffCreationReason | undefined {
+  return value && HANDOFF_ELIGIBLE_REASONS.has(value as HandoffCreationReason)
+    ? value as HandoffCreationReason
+    : undefined;
+}
+
+function projectUserRequest(request: UserRequest, fallbackRepoId: string): HandoffItem {
+  const presentation = request.presentation;
+  const repoId = request.targetScope?.repoId ?? fallbackRepoId;
+  const workId = request.targetScope?.workId;
+  const id = presentation?.legacyHandoffId?.trim() || request.requestId;
+  const status = projectedStatus(request);
+  return {
+    schemaVersion: 1,
+    id,
+    repoId,
+    ...(workId ? { workId } : {}),
+    canonicalUserRequestId: request.requestId,
+    title: request.title,
+    severity: presentation?.severity ?? 'needs_review',
+    status,
+    reason: presentation?.reason ?? request.summary,
+    creationReason: projectedCreationReason(presentation?.creationReason),
+    summary: request.summary,
+    currentState: (presentation?.currentState ?? {
+      repoId,
+      ...(workId ? { workId } : {}),
+      statusSummary: status === 'pending' ? 'waiting for user action or decision' : 'user request resolved',
+    }) as unknown as HandoffItem['currentState'],
+    attemptedActions: presentation?.attemptedActions ?? [],
+    evidenceRefs: (presentation?.evidenceRefs ?? []) as HandoffItem['evidenceRefs'],
+    blockingDecision: presentation?.blockingDecision,
+    recommendedDecision: presentation?.recommendedDecision ?? 'Complete the requested user action or decision.',
+    recommendedPrompt: presentation?.recommendedPrompt ?? `Resolve UserRequest ${request.requestId}.`,
+    recommendedContinuationPrompt: presentation?.recommendedContinuationPrompt,
+    approvalAction: presentation?.approvalAction as HandoffItem['approvalAction'],
+    suggestedNextActions: (presentation?.suggestedNextActions ?? []) as HandoffItem['suggestedNextActions'],
+    decision: request.resolution?.decision,
+    resolver: request.resolution?.resolvedBy,
+    createdAt: request.createdAt,
+    updatedAt: request.updatedAt,
+  };
+}
+
+function userRequestsForRepository(
+  options: HandoffInboxStoreOptions & { controllerHome: string; repoId: string },
+): UserRequest[] {
+  return listUserRequests(options.controllerHome, 'all')
+    .filter((request) => request.targetScope?.repoId === options.repoId);
+}
+
+function requestForHandoffId(
+  options: HandoffInboxStoreOptions & { controllerHome: string; repoId: string },
+  id: string,
+): UserRequest | undefined {
+  const normalized = sanitizeFileComponent(id);
+  return userRequestsForRepository(options).find((request) => (
+    request.requestId === normalized
+    || request.presentation?.legacyHandoffId === normalized
+  ));
+}
+
+/**
+ * One-time authority migration. Genuine human Handoffs become canonical
+ * UserRequests; mechanical/worker-review rows are archived as history only.
+ * After the marker is written, the legacy index is never read again.
+ */
+export function migrateLegacyHandoffInbox(
+  options: HandoffInboxStoreOptions & { controllerHome: string; repoId: string },
+): HandoffMigrationMarker {
+  const markerPath = handoffMigrationMarkerPath(options);
+  if (existsSync(markerPath)) return readJsonFile<HandoffMigrationMarker>(markerPath);
+  return withHandoffInboxWriteLock(options, `migrate-handoff-inbox:${options.repoId}`, () => {
+    if (existsSync(markerPath)) return readJsonFile<HandoffMigrationMarker>(markerPath);
+    const legacyPath = handoffInboxPath(options);
+    const legacyStore = existsSync(legacyPath)
+      ? readJsonFile<HandoffInboxStore>(legacyPath, emptyHandoffInboxStore(nowIso(options)))
+      : emptyHandoffInboxStore(nowIso(options));
+    let migratedUserRequestCount = 0;
+    let skippedMechanicalCount = 0;
+    for (const item of legacyStore.items) {
+      const input = canonicalUserRequestInput(item);
+      if (!input) {
+        skippedMechanicalCount += 1;
+        continue;
+      }
+      let request = recordUserRequest(options.controllerHome, input);
+      if (isTerminalHandoffStatus(item.status) && request.status === 'pending') {
+        request = resolveUserRequest(options.controllerHome, {
+          requestId: request.requestId,
+          decision: item.decision?.trim() || item.status,
+          resolvedBy: item.resolver?.trim() || 'handoff-migration',
+        });
+      }
+      void request;
+      migratedUserRequestCount += 1;
+    }
+    const migratedAt = nowIso(options);
+    let archivedPath: string | undefined;
+    const marker: HandoffMigrationMarker = {
+      schemaVersion: 1,
+      repoId: options.repoId,
+      migratedAt,
+      legacyItemCount: legacyStore.items.length,
+      migratedUserRequestCount,
+      skippedMechanicalCount,
+    };
+    mkdirSync(dirname(markerPath), { recursive: true });
+    writeJsonAtomic(markerPath, marker);
+    if (existsSync(legacyPath)) {
+      archivedPath = `${legacyPath}.migrated-${Date.now()}`;
+      try {
+        renameSync(legacyPath, archivedPath);
+      } catch {
+        archivedPath = undefined;
+      }
+    }
+    const persisted = { ...marker, ...(archivedPath ? { archivedPath } : {}) };
+    if (archivedPath) writeJsonAtomic(markerPath, persisted);
+    return persisted;
+  });
+}
+
+export function readHandoffInboxStore(options: HandoffInboxStoreOptions): HandoffInboxStore {
+  if (!usesCanonicalUserRequestStore(options)) return readLegacyHandoffInboxStore(options);
+  migrateLegacyHandoffInbox(options);
+  const items = userRequestsForRepository(options).map((request) => projectUserRequest(request, options.repoId));
+  const updatedAt = items.reduce((latest, item) => item.updatedAt > latest ? item.updatedAt : latest, nowIso(options));
+  return { schemaVersion: 1, updatedAt, items };
+}
+
 export function createHandoffItem(options: HandoffInboxStoreOptions, input: CreateHandoffInput): HandoffItem {
   if (input.creationReason && !shouldCreateHandoff(input.creationReason)) {
     throw new Error(`handoff creation reason is not eligible: ${input.creationReason}`);
@@ -132,19 +342,16 @@ export function createHandoffItem(options: HandoffInboxStoreOptions, input: Crea
     createdAt: at,
     updatedAt: input.updatedAt ?? at,
   };
-  return withHandoffInboxWriteLock(options, `create-handoff:${item.id}`, () => {
-    const store = readHandoffInboxStore(options);
-    if (store.items.some((existing) => existing.id === item.id)) {
-      throw new Error(`handoff already exists: ${item.id}`);
-    }
-    const nextStore: HandoffInboxStore = {
-      schemaVersion: 1,
-      updatedAt: item.updatedAt,
-      items: [item, ...store.items],
-    };
-    writeHandoffInboxStore(options, nextStore);
-    return item;
-  });
+  if (!usesCanonicalUserRequestStore(options)) {
+    throw new Error('HANDOFF_LEGACY_STORE_READ_ONLY: provide controllerHome + repoId so UserRequest owns the durable write');
+  }
+  migrateLegacyHandoffInbox(options);
+  const requestInput = canonicalUserRequestInput(item);
+  if (!requestInput) {
+    throw new Error('HANDOFF_USER_REQUEST_REQUIRED: mechanical failures must remain in their owning runtime domain');
+  }
+  const request = recordUserRequest(options.controllerHome, requestInput);
+  return projectUserRequest(request, options.repoId);
 }
 
 export function listHandoffItems(options: ListHandoffOptions): HandoffItem[] {
@@ -187,8 +394,13 @@ export function summarizeHandoffItem(item: HandoffItem): HandoffItemSummary {
 }
 
 export function getHandoffItem(options: HandoffInboxStoreOptions, id: string): HandoffItem | undefined {
-  const sanitizedId = sanitizeFileComponent(id);
-  return readHandoffInboxStore(options).items.find((item) => item.id === sanitizedId);
+  if (!usesCanonicalUserRequestStore(options)) {
+    const sanitizedId = sanitizeFileComponent(id);
+    return readLegacyHandoffInboxStore(options).items.find((item) => item.id === sanitizedId);
+  }
+  migrateLegacyHandoffInbox(options);
+  const request = requestForHandoffId(options, id);
+  return request ? projectUserRequest(request, options.repoId) : undefined;
 }
 
 function setHandoffStatus(
@@ -198,22 +410,21 @@ function setHandoffStatus(
   patch: Partial<Pick<HandoffItem, 'decision' | 'resolver'>> = {},
 ): HandoffItem {
   const sanitizedId = sanitizeFileComponent(id);
-  return withHandoffInboxWriteLock(options, `update-handoff:${sanitizedId}`, () => {
-    const store = readHandoffInboxStore(options);
-    const index = store.items.findIndex((item) => item.id === sanitizedId);
-    if (index < 0) throw new Error(`handoff not found: ${sanitizedId}`);
-    const at = nowIso(options);
-    const item: HandoffItem = {
-      ...store.items[index],
-      ...patch,
-      status,
-      updatedAt: at,
-    };
-    const items = [...store.items];
-    items[index] = item;
-    writeHandoffInboxStore(options, { schemaVersion: 1, updatedAt: at, items });
-    return item;
-  });
+  if (!usesCanonicalUserRequestStore(options)) {
+    throw new Error('HANDOFF_LEGACY_STORE_READ_ONLY: legacy Handoff records are migration input only');
+  }
+  migrateLegacyHandoffInbox(options);
+  const request = requestForHandoffId(options, sanitizedId);
+  if (!request) throw new Error(`handoff not found: ${sanitizedId}`);
+  if (status === 'acknowledged') return projectUserRequest(request, options.repoId);
+  const resolved = request.status === 'pending'
+    ? resolveUserRequest(options.controllerHome, {
+        requestId: request.requestId,
+        decision: patch.decision?.trim() || status,
+        resolvedBy: patch.resolver?.trim() || 'system',
+      })
+    : request;
+  return projectUserRequest(resolved, options.repoId);
 }
 
 export function acknowledgeHandoffItem(options: HandoffInboxStoreOptions, id: string): HandoffItem {
@@ -225,16 +436,9 @@ export function resolveHandoffItem(
   id: string,
   input?: ResolveHandoffInput,
 ): HandoffItem {
-  if (!input?.decision?.trim() || !input?.resolver?.trim()) {
-    // Backward-compatible path used by older callers; prefer explicit decision + resolver.
-    return setHandoffStatus(options, id, 'resolved', {
-      decision: input?.decision?.trim() || 'resolved',
-      resolver: input?.resolver?.trim() || 'system',
-    });
-  }
   return setHandoffStatus(options, id, 'resolved', {
-    decision: input.decision.trim().slice(0, 1_000),
-    resolver: input.resolver.trim().slice(0, 200),
+    decision: input?.decision?.trim().slice(0, 1_000) || 'resolved',
+    resolver: input?.resolver?.trim().slice(0, 200) || 'system',
   });
 }
 

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

@@ -1,7 +1,6 @@
 export * from './types';
 export * from './handoff-inbox-store';
 export * from '../../../../packages/kernel/work/api/index';
-export * from './work-task-projection';
 export * from './work-continuation';
 export * from '../../../../packages/kernel/controller/api/index';
 export * from './plan-contract-store';

package/src/runtime/control-plane/facade/operation-digest.ts

@@ -155,13 +155,12 @@ export function statusLabelForPhase(phase: UserFacingPhase): string {
 function defaultNextActions(phase: UserFacingPhase, jobId?: string, errorClass?: UserFacingErrorClass): SuggestedNextAction[] {
   if (phase === 'queued' || phase === 'running' || phase === 'waiting') {
     return [{
-      label: '查看任务状态',
-      tool: 'rh_work',
-      operation: 'continue',
-      payload: jobId ? { work_id: jobId } : undefined,
+      label: '查看运行状态',
+      tool: 'rh_status',
+      operation: 'get',
       risk: 'readonly',
       confidence: 'high',
-      reason: '轮询或继续查看当前执行状态。',
+      reason: '读取当前运行事实，不通过 Work lifecycle 操作轮询执行。',
     }];
   }
   if (phase === 'failed' || phase === 'timed_out') {
@@ -433,25 +432,23 @@ export function buildAcceptedQueuedDigest(input: {
     requestId: input.requestId,
     suggestedNextActions: [
       {
-        label: '等待任务完成',
-        tool: 'rh_work',
-        operation: 'continue',
-        payload: { work_id: input.jobId, wait: true },
+        label: '查看任务运行状态',
+        tool: 'rh_status',
+        operation: 'get',
         risk: 'readonly',
         confidence: 'high',
-        reason: '对长时间任务使用 wait/work_get 获取终态摘要。',
+        reason: '长时间执行由 Process/Runtime 自己持有；状态读取不推进 Work lifecycle。',
       },
       ...defaultNextActions('queued', input.jobId),
     ],
     nextActions: [
       {
-        label: '等待任务完成',
-        tool: 'rh_work',
-        operation: 'continue',
-        payload: { work_id: input.jobId, wait: true },
+        label: '查看任务运行状态',
+        tool: 'rh_status',
+        operation: 'get',
         risk: 'readonly',
         confidence: 'high',
-        reason: '对长时间任务使用 wait/work_get 获取终态摘要。',
+        reason: '长时间执行由 Process/Runtime 自己持有；状态读取不推进 Work lifecycle。',
       },
       ...defaultNextActions('queued', input.jobId),
     ],