@moretea-labs/forge 1.7.0 → 1.7.1

package/src/cli/repositories/structured-git.ts

@@ -274,7 +274,43 @@ export function repositoryGitCommit(controllerHome: string, repository: Reposito
   if (diffCheck.status === 0 && input.allowEmpty !== true) {
     return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, before, stage, after: repositoryGitStatus(repository), committed: false, error: { code: 'GIT_NOTHING_STAGED', message: 'No staged changes to commit. Pass paths to stage, or allow_empty=true for an empty commit.' } };
   }
-  const commitArgs = ['commit', '-m', message, ...(input.allowEmpty === true ? ['--allow-empty'] : []), ...(paths.length > 0 ? ['--only', '--', ...paths] : [])];
+  const mergeInProgress = runGit(repository, ['rev-parse', '--verify', 'MERGE_HEAD'], 64 * 1024).ok;
+  if (mergeInProgress) {
+    const unresolved = runGit(repository, ['diff', '--name-only', '--diff-filter=U', '-z'], 128 * 1024);
+    const unresolvedPaths = unresolved.stdout.split('\0').map((path) => path.trim()).filter(Boolean);
+    if (!unresolved.ok || unresolvedPaths.length > 0) {
+      return {
+        repoId: repository.repoId,
+        checkoutId: repository.activeCheckoutId,
+        before,
+        stage,
+        after: repositoryGitStatus(repository),
+        committed: false,
+        error: { code: 'GIT_MERGE_UNRESOLVED', message: unresolvedPaths.length > 0 ? `Merge still has unresolved path(s): ${unresolvedPaths.join(', ')}` : unresolved.stderr || 'Unable to inspect unresolved merge paths.' },
+      };
+    }
+    if (paths.length > 0) {
+      const stagedNames = runGit(repository, ['diff', '--cached', '--name-only', '-z'], 128 * 1024);
+      if (!stagedNames.ok) {
+        return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, before, stage, after: repositoryGitStatus(repository), committed: false, error: { code: 'GIT_MERGE_STAGED_SCOPE_INSPECTION_FAILED', message: stagedNames.stderr || 'Unable to inspect the merge index.' } };
+      }
+      const allowed = new Set(paths);
+      const stagedPaths = stagedNames.stdout.split('\0').map((path) => path.trim()).filter(Boolean);
+      const outsideScope = stagedPaths.filter((path) => !allowed.has(path));
+      if (outsideScope.length > 0) {
+        return {
+          repoId: repository.repoId,
+          checkoutId: repository.activeCheckoutId,
+          before,
+          stage,
+          after: repositoryGitStatus(repository),
+          committed: false,
+          error: { code: 'GIT_MERGE_STAGED_SCOPE_MISMATCH', message: `Resolved merge index contains staged path(s) outside the requested commit scope: ${outsideScope.join(', ')}` },
+        };
+      }
+    }
+  }
+  const commitArgs = ['commit', '-m', message, ...(input.allowEmpty === true ? ['--allow-empty'] : []), ...(!mergeInProgress && paths.length > 0 ? ['--only', '--', ...paths] : [])];
   const commit = executeRepositoryGitCommand(controllerHome, repository, { args: commitArgs, authorization: 'explicit_user_request', ...input });
   const ok = commit.status === 'executed' && commit.ok === true;
   return {
@@ -289,12 +325,30 @@ export function repositoryGitCommit(controllerHome: string, repository: Reposito
   };
 }
 
-export function repositoryGitFinishWorkflow(controllerHome: string, repository: RepositoryRecord, input: { targetBranch?: unknown; featureBranch?: unknown; deleteBranch?: unknown; noFf?: unknown; authorizationDecision?: AuthorizationDecision; sessionId?: string; principalId?: string; workId?: string; goalId?: string }): RepositoryGitFinishResult {
+export function repositoryGitFinishWorkflow(controllerHome: string, repository: RepositoryRecord, input: { targetBranch?: unknown; featureBranch?: unknown; deleteBranch?: unknown; noFf?: unknown; preserveDirtyTargetPaths?: unknown; authorizationDecision?: AuthorizationDecision; sessionId?: string; principalId?: string; workId?: string; goalId?: string }): RepositoryGitFinishResult {
   const before = repositoryGitStatus(repository);
   const featureBranch = assertSafeBranchName(input.featureBranch ?? before.branch);
   const targetBranch = assertSafeBranchName(input.targetBranch ?? repository.defaultBranch ?? 'main');
   const steps: RepositoryGitFinishResult['steps'] = [];
   const alreadyOnTarget = before.branch === targetBranch;
+  const requestedPreservedDirtyPaths = normalizePaths(input.preserveDirtyTargetPaths);
+  const currentDirtyPaths = [...new Set([...before.staged, ...before.unstaged, ...before.untracked])].sort();
+  const preserveDirtyTargetInPlace = alreadyOnTarget && requestedPreservedDirtyPaths.length > 0;
+  if (preserveDirtyTargetInPlace) {
+    const requested = new Set(requestedPreservedDirtyPaths);
+    if (requested.size !== currentDirtyPaths.length || currentDirtyPaths.some((path) => !requested.has(path))) {
+      return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: before, completed: false, error: { code: 'GIT_DIRTY_TARGET_OWNERSHIP_MISMATCH', message: 'The exact current dirty target paths no longer match the Work-owned preservation set; retry ownership inspection before integration.' } };
+    }
+    const candidateDiff = runGit(repository, ['diff', '--name-only', `${targetBranch}..${featureBranch}`], 128 * 1024);
+    if (!candidateDiff.ok) {
+      return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: before, completed: false, error: { code: 'GIT_DIRTY_TARGET_PREFLIGHT_FAILED', message: candidateDiff.stderr || 'Unable to inspect candidate paths before dirty-target integration.' } };
+    }
+    const candidatePaths = new Set(candidateDiff.stdout.split(/\r?\n/).map((path) => path.trim()).filter(Boolean));
+    const overlapping = currentDirtyPaths.filter((path) => candidatePaths.has(path));
+    if (overlapping.length > 0) {
+      return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: before, completed: false, error: { code: 'GIT_DIRTY_TARGET_PATH_CONFLICT', message: `Work-owned dirty target path(s) overlap the integration candidate: ${overlapping.join(', ')}` } };
+    }
+  }
   if (!before.clean && !alreadyOnTarget) {
     return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: before, completed: false, error: { code: 'GIT_WORKTREE_NOT_CLEAN', message: 'Commit or revert changes before switching branches to finish a workflow.' } };
   }
@@ -306,7 +360,7 @@ export function repositoryGitFinishWorkflow(controllerHome: string, repository:
     steps.push({ name: 'switch_target', execution: switchTarget });
     if (switchTarget.status !== 'executed' || switchTarget.ok !== true) return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_SWITCH_TARGET_FAILED', message: switchTarget.stderr || 'git switch failed' } };
   }
-  const protectTrackedChanges = alreadyOnTarget && (before.staged.length > 0 || before.unstaged.length > 0);
+  const protectTrackedChanges = alreadyOnTarget && !preserveDirtyTargetInPlace && (before.staged.length > 0 || before.unstaged.length > 0);
   const finishAuthorization = 'explicit_user_request' as const;
   let stashRef: string | null = null;
   if (protectTrackedChanges) {

package/src/cli/repository/inspector.ts

@@ -733,7 +733,9 @@ export function searchRepositoryMany(
       policyDeniedFiles += 1;
       continue;
     }
-    const size = statSync(decision.absolutePath).size;
+    const info = statSync(decision.absolutePath);
+    if (!info.isFile()) continue;
+    const size = info.size;
     if (size > policy.maxFileBytes) {
       skippedLargeFiles += 1;
       continue;
@@ -780,6 +782,7 @@ type AsyncSearchCandidate =
   | { path: string; kind: 'denied' }
   | { path: string; kind: 'large' }
   | { path: string; kind: 'binary' }
+  | { path: string; kind: 'nonfile' }
   | { path: string; kind: 'source'; bytes: Buffer }
   | { path: string; kind: 'error'; error: unknown };
 
@@ -792,7 +795,9 @@ async function readSearchCandidateAsync(
   try {
     const decision = resolveMcpPath(repoRoot, path, policy, 'read', canonicalRepoRoot);
     if (!decision.ok || !decision.absolutePath) return { path, kind: 'denied' };
-    const size = (await statAsync(decision.absolutePath)).size;
+    const info = await statAsync(decision.absolutePath);
+    if (!info.isFile()) return { path, kind: 'nonfile' };
+    const size = info.size;
     if (size > policy.maxFileBytes) return { path, kind: 'large' };
     const bytes = await readFileAsync(decision.absolutePath);
     if (binary(bytes)) return { path, kind: 'binary' };
@@ -872,6 +877,7 @@ export async function searchRepositoryManyAsync(
         skippedBinaryFiles += 1;
         continue;
       }
+      if (candidate.kind === 'nonfile') continue;
       if (candidate.kind === 'error') throw candidate.error;
       scannedFiles += 1;
       matchSearchManySource(matchState, candidate.path, candidate.bytes);
@@ -950,7 +956,9 @@ export function searchRepository(repoRoot: string, policy: McpPolicy, opts: Sear
       policyDeniedFiles += 1;
       continue;
     }
-    const size = statSync(decision.absolutePath).size;
+    const info = statSync(decision.absolutePath);
+    if (!info.isFile()) continue;
+    const size = info.size;
     if (size > policy.maxFileBytes) {
       skippedLargeFiles += 1;
       continue;

package/src/runtime/context/generic-lsp-provider.ts

@@ -7,7 +7,7 @@ import type {
   SemanticNavigationOutcome,
   SemanticNavigationProvider,
   SemanticNavigationRequest,
-} from './semantic-navigation';
+} from './semantic-navigation-contract';
 
 export interface GenericLspProviderDescriptor {
   id: string;

package/src/runtime/context/semantic-navigation-contract.ts

@@ -0,0 +1,61 @@
+export type SemanticNavigationKind = 'definition' | 'references' | 'implementations';
+
+export interface SemanticNavigationRequest {
+  navigation: SemanticNavigationKind;
+  path: string;
+  line: number;
+  column: number;
+  tsconfigPath?: string;
+  language?: string;
+}
+
+export interface SemanticNavigationLocation {
+  path: string;
+  line: number;
+  column: number;
+  name?: string;
+  kind?: string;
+}
+
+export interface SemanticNavigationResult {
+  providerId: string;
+  providerIdentity?: string;
+  language: string;
+  navigation: SemanticNavigationKind;
+  target: { path: string; line: number; column: number };
+  locations: SemanticNavigationLocation[];
+  policyDeniedReads?: number;
+  details?: Record<string, unknown>;
+}
+
+export type SemanticNavigationOutcome =
+  | { ok: true; result: SemanticNavigationResult }
+  | { ok: false; code: string; message: string };
+
+export interface SemanticNavigationAccess {
+  cacheScope: string;
+  sourceIdentity?: string;
+  profile: string;
+  allowRepositoryPath(relativePath: string): boolean;
+}
+
+export interface SemanticNavigationProvider {
+  id: string;
+  languages: readonly string[];
+  supports(request: SemanticNavigationRequest): boolean;
+  navigate(
+    repoRoot: string,
+    requests: SemanticNavigationRequest[],
+    access: SemanticNavigationAccess,
+  ): Promise<SemanticNavigationOutcome[]>;
+}
+
+export interface IndexedSemanticNavigationRequest {
+  index: number;
+  request: SemanticNavigationRequest;
+}
+
+export interface IndexedSemanticNavigationOutcome {
+  index: number;
+  outcome: SemanticNavigationOutcome;
+}

package/src/runtime/context/semantic-navigation.ts

@@ -3,67 +3,15 @@ import { navigateTypeScriptSymbol } from './typescript-navigation';
 import { navigateSwiftSymbols } from './swift-navigation';
 import { GenericLspSemanticProvider, type GenericLspProviderDescriptor } from './generic-lsp-provider';
 
-export type SemanticNavigationKind = 'definition' | 'references' | 'implementations';
-
-export interface SemanticNavigationRequest {
-  navigation: SemanticNavigationKind;
-  path: string;
-  line: number;
-  column: number;
-  tsconfigPath?: string;
-  language?: string;
-}
-
-export interface SemanticNavigationLocation {
-  path: string;
-  line: number;
-  column: number;
-  name?: string;
-  kind?: string;
-}
-
-export interface SemanticNavigationResult {
-  providerId: string;
-  providerIdentity?: string;
-  language: string;
-  navigation: SemanticNavigationKind;
-  target: { path: string; line: number; column: number };
-  locations: SemanticNavigationLocation[];
-  policyDeniedReads?: number;
-  details?: Record<string, unknown>;
-}
-
-export type SemanticNavigationOutcome =
-  | { ok: true; result: SemanticNavigationResult }
-  | { ok: false; code: string; message: string };
-
-export interface SemanticNavigationAccess {
-  cacheScope: string;
-  sourceIdentity?: string;
-  profile: string;
-  allowRepositoryPath(relativePath: string): boolean;
-}
-
-export interface SemanticNavigationProvider {
-  id: string;
-  languages: readonly string[];
-  supports(request: SemanticNavigationRequest): boolean;
-  navigate(
-    repoRoot: string,
-    requests: SemanticNavigationRequest[],
-    access: SemanticNavigationAccess,
-  ): Promise<SemanticNavigationOutcome[]>;
-}
-
-export interface IndexedSemanticNavigationRequest {
-  index: number;
-  request: SemanticNavigationRequest;
-}
-
-export interface IndexedSemanticNavigationOutcome {
-  index: number;
-  outcome: SemanticNavigationOutcome;
-}
+export * from './semantic-navigation-contract';
+import type {
+  IndexedSemanticNavigationOutcome,
+  IndexedSemanticNavigationRequest,
+  SemanticNavigationAccess,
+  SemanticNavigationOutcome,
+  SemanticNavigationProvider,
+  SemanticNavigationRequest,
+} from './semantic-navigation-contract';
 
 function extensionMatches(path: string, values: readonly string[]): boolean {
   return values.includes(extname(path).toLowerCase());

package/src/runtime/control-plane/execution/direct-edit-work-completion.ts

@@ -1,12 +1,12 @@
 import { createHash } from 'crypto';
 import { getEditSession, listEditSessions, type EditSession } from '../../../cli/editing/edit-session';
-import { globMatches } from '../../../cli/mcp/paths';
 import { runProcess } from '../../../effects/process-runner';
-import { completeRequirementFromWork } from '../persistence/requirement-store';
-import { appendWorkEvidence, getWorkContract, recordWorkCompletionReceipt, updateWorkContract } from '../facade/work-contract-store';
+import { getWorkContract, updateWorkContract } from '../facade/work-contract-store';
+import { completeWorkWithReceipt } from './work-completion-authority';
 import { isDirectEditWorkCompletionReceipt, isTerminalWorkContractStatus, type DirectEditWorkCompletionReceipt, type WorkReconciliationRecord } from '../facade/types';
 import { historicalVerificationEvidenceAtRevision } from './verification-evidence';
 import { readWorkHandle } from './work-handle-store';
+import { assertWorkPathsWithinScope, findWorkPathScopeViolation } from './work-path-scope';
 
 export interface DirectEditWorkCompletionReconciliation {
   completedWorkIds: string[];
@@ -102,6 +102,15 @@ export function reconcileFinalizedDirectEditWorksAfterCommit(input: {
       skipped.push({ sessionId: session.sessionId, workId: session.workId, reason: 'configured_checks_not_passed' });
       continue;
     }
+    const scopeViolation = findWorkPathScopeViolation(work, paths);
+    if (scopeViolation) {
+      skipped.push({
+        sessionId: session.sessionId,
+        workId: session.workId,
+        reason: `${scopeViolation.kind === 'forbidden' ? 'work_scope_forbidden' : 'work_scope_out_of_scope'}:${scopeViolation.path}`,
+      });
+      continue;
+    }
     const status = git(input.repoRoot, ['status', '--porcelain=v1', '--', ...paths]);
     if (!status.ok || status.stdout.trim()) {
       skipped.push({ sessionId: session.sessionId, workId: session.workId, reason: 'owned_paths_not_clean' });
@@ -141,7 +150,7 @@ export function reconcileFinalizedDirectEditWorksAfterCommit(input: {
       verifiedAt: session.verifiedAt ?? session.finalizedAt ?? recordedAt,
       recordedAt,
     };
-    recordWorkCompletionReceipt(
+    completeWorkWithReceipt(
       { controllerHome: input.controllerHome, repoId: input.repoId },
       session.workId,
       receipt,
@@ -248,10 +257,10 @@ export function acceptReviewedDirectEditWorkReconciliation(input: ReviewedDirect
   if (comparedPaths.length !== actualPaths.length || comparedPaths.some((path, index) => path !== actualPaths[index])) {
     throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_PATH_COMPARISON_MISMATCH');
   }
-  for (const path of comparedPaths) {
-    if (work.forbiddenPaths.some((pattern) => globMatches(pattern, path))) throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_FORBIDDEN_PATH: ${path}`);
-    if (work.allowedPaths.length > 0 && !work.allowedPaths.some((pattern) => globMatches(pattern, path))) throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_PATH_OUT_OF_SCOPE: ${path}`);
-  }
+  assertWorkPathsWithinScope(work, comparedPaths, {
+    forbidden: 'DIRECT_EDIT_WORK_RECONCILIATION_FORBIDDEN_PATH',
+    outOfScope: 'DIRECT_EDIT_WORK_RECONCILIATION_PATH_OUT_OF_SCOPE',
+  });
   const dirty = git(input.repoRoot, ['status', '--porcelain=v1', '--', ...comparedPaths]);
   if (!dirty.ok || dirty.stdout.trim()) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_OWNED_PATHS_DIRTY');
 
@@ -318,28 +327,12 @@ export function acceptReviewedDirectEditWorkReconciliation(input: ReviewedDirect
     verifiedAt,
     recordedAt,
   };
-  const recorded = recordWorkCompletionReceipt(
+  completeWorkWithReceipt(
     { controllerHome: input.controllerHome, repoId: input.repoId },
     input.workId,
     receipt,
     'completed_changed',
     'repository_change',
   );
-  if (recorded.requirementId) {
-    try {
-      completeRequirementFromWork({ controllerHome: input.controllerHome }, { requirementId: recorded.requirementId, work: recorded });
-    } catch (error) {
-      try {
-        appendWorkEvidence({ controllerHome: input.controllerHome, repoId: input.repoId }, input.workId, {
-          title: 'requirement completion projection pending',
-          summary: `Work completion remains authoritative; Requirement projection could not be applied: ${error instanceof Error ? error.message : String(error)}`.slice(0, 2_000),
-          detailLevel: 'summary',
-        });
-      } catch {
-        // Reconciliation already recorded the terminal receipt. A diagnostic
-        // write failure cannot make that completed Work non-terminal again.
-      }
-    }
-  }
   return { workId: input.workId, reconciliation, receipt };
 }

package/src/runtime/control-plane/execution/repository-work-attribution.ts

@@ -0,0 +1,106 @@
+import { readExecutionSession } from './session-store';
+import { controllerSessionPrincipalId, getControllerSession, listControllerSessions } from '../facade/controller-session-store';
+import { getWorkContract } from '../facade/work-contract-store';
+import { isTerminalWorkContractStatus } from '../facade/types';
+
+export interface RepositoryWorkAttributionCaller {
+  sessionId?: string;
+  principalId?: string;
+  controllerInstanceId?: string;
+}
+
+export interface RepositoryWorkAttributionTarget {
+  repoId: string;
+  activeCheckoutId: string;
+}
+
+export function resolveExplicitClaimedRepositoryWork(
+  controllerHome: string,
+  target: RepositoryWorkAttributionTarget,
+  caller: RepositoryWorkAttributionCaller | undefined,
+  workId: string,
+) {
+  if (!caller?.principalId?.trim()) return undefined;
+  const work = getWorkContract({ controllerHome, repoId: target.repoId }, workId);
+  if (!work || isTerminalWorkContractStatus(work.status)) throw new Error(`WORK_ATTRIBUTION_INVALID: ${workId}`);
+  const owner = getControllerSession({ controllerHome, repoId: target.repoId }, workId);
+  if (!owner) throw new Error(`WORK_CONTROLLER_CLAIM_REQUIRED: ${workId}`);
+  if (controllerSessionPrincipalId(owner) !== caller.principalId.trim()) {
+    throw new Error(`WORK_CONTROLLER_OWNERSHIP_MISMATCH: ${workId}`);
+  }
+  if (work.checkoutId && work.checkoutId !== target.activeCheckoutId) {
+    throw new Error(
+      `WORK_CHECKOUT_MISMATCH: work=${workId}; resolved_checkout=${target.activeCheckoutId}; expected_work_checkout=${work.checkoutId}; retry with checkout_id=${work.checkoutId} and the same work_id`,
+    );
+  }
+  return work;
+}
+
+export function assertNoBoundExecutionSessionMutation(
+  controllerHome: string,
+  target: RepositoryWorkAttributionTarget,
+  caller?: RepositoryWorkAttributionCaller,
+): void {
+  if (!caller?.principalId?.trim() || !caller.sessionId?.trim()) return;
+  const executionSession = readExecutionSession(controllerHome, {
+    sessionId: caller.sessionId,
+    principalId: caller.principalId,
+    controllerInstanceId: caller.controllerInstanceId,
+  });
+  const workId = executionSession?.activeWorkId?.trim();
+  if (!workId || executionSession?.activeRepositoryId !== target.repoId) return;
+  const work = getWorkContract({ controllerHome, repoId: target.repoId }, workId);
+  if (!work) throw new Error(`WORK_ATTRIBUTION_INVALID: ${workId}`);
+  if (isTerminalWorkContractStatus(work.status)) {
+    throw new Error(`WORK_ATTRIBUTION_TERMINAL: ${work.workId}:${work.status}`);
+  }
+  throw new Error(`WORK_ATTRIBUTION_REQUIRED: ${work.workId}; active execution session mutations must pass work_id explicitly`);
+}
+
+export function resolveClaimedRepositoryWorkId(
+  controllerHome: string,
+  target: RepositoryWorkAttributionTarget,
+  caller?: RepositoryWorkAttributionCaller,
+  explicitWorkId?: unknown,
+): string | undefined {
+  const requestedWorkId = typeof explicitWorkId === 'string' ? explicitWorkId.trim() : '';
+  if (requestedWorkId) {
+    const work = resolveExplicitClaimedRepositoryWork(controllerHome, target, caller, requestedWorkId);
+    return work?.workId;
+  }
+  if (!caller?.principalId?.trim()) return undefined;
+  if (caller.sessionId?.trim()) {
+    const executionSession = readExecutionSession(controllerHome, {
+      sessionId: caller.sessionId,
+      principalId: caller.principalId,
+      controllerInstanceId: caller.controllerInstanceId,
+    });
+    const workId = executionSession?.activeWorkId?.trim();
+    if (workId
+      && executionSession?.activeRepositoryId === target.repoId
+      && (!executionSession.activeCheckoutId || executionSession.activeCheckoutId === target.activeCheckoutId)) {
+      const work = getWorkContract({ controllerHome, repoId: target.repoId }, workId);
+      if (work && isTerminalWorkContractStatus(work.status)) {
+        throw new Error(`WORK_ATTRIBUTION_TERMINAL: ${work.workId}:${work.status}`);
+      }
+      const owner = getControllerSession({ controllerHome, repoId: target.repoId }, workId);
+      if (work && owner?.sessionId === caller.sessionId && controllerSessionPrincipalId(owner) === caller.principalId.trim()) {
+        return workId;
+      }
+    }
+  }
+  const principal = caller.principalId.trim();
+  const candidates = listControllerSessions({ controllerHome, repoId: target.repoId })
+    .filter((owner) => controllerSessionPrincipalId(owner) === principal)
+    .map((owner) => ({ owner, work: getWorkContract({ controllerHome, repoId: target.repoId }, owner.workId) }))
+    .filter((entry): entry is { owner: ReturnType<typeof listControllerSessions>[number]; work: NonNullable<ReturnType<typeof getWorkContract>> } => Boolean(
+      entry.work
+      && !isTerminalWorkContractStatus(entry.work.status)
+      && (!entry.work.checkoutId || entry.work.checkoutId === target.activeCheckoutId),
+    ));
+  if (candidates.length === 1) return candidates[0].work.workId;
+  if (candidates.length > 1) {
+    throw new Error(`WORK_ATTRIBUTION_AMBIGUOUS: principal ${principal} owns ${candidates.length} active Works on checkout ${target.activeCheckoutId}`);
+  }
+  return undefined;
+}