From 7bb69417a8f77d2c59a06fe6bb533523c62532f4 Mon Sep 17 00:00:00 2001 From: Jinwoo-H Date: Sun, 8 Nov 2026 21:33:30 -0500 Subject: [PATCH] fix(orchestration): record orchestration as the origin of nested workers on connected servers; lead the guide with new-child worker-start --on --worktree new-child now tells the server that orchestration picked the parent, so the server records the child's lineage as orchestration, as a local child is, instead of cli. Older coordinators omit the field and keep cli. The guide now shows new-child first and new-top-level as the no-parent choice. --- skill-guides/orchestration.md | 3 +- .../references/placement-and-remote.md | 8 +- src/cli/bundled-skill-guides.ts | 11 +-- .../federated-worker-agent-launch.ts | 7 +- .../federated-worker-child-parent.ts | 10 ++- .../federation/federated-worker-start.ts | 5 +- .../federation-child-lineage-origin.test.ts | 78 +++++++++++++++++++ .../runtime-worktree-lineage-recording.ts | 5 +- .../orchestration-federation-start-params.ts | 4 +- 9 files changed, 114 insertions(+), 17 deletions(-) create mode 100644 src/main/runtime/rpc/methods/orchestration/federation/federation-child-lineage-origin.test.ts diff --git a/skill-guides/orchestration.md b/skill-guides/orchestration.md index 8187a43ec48..cd92e95fc84 100644 --- a/skill-guides/orchestration.md +++ b/skill-guides/orchestration.md @@ -36,7 +36,8 @@ ORCA orchestration worker-start --spec "" --worktree current --agent codex - If a receipt has `next`, follow it. When Orca has nothing for you, end your turn. - `--worktree current` uses your workspace. Use a new one only when the user - asks or sharing would conflict: + asks or sharing would conflict: `--worktree new-child --name ` + nests it under yours. For one with no parent, use `--worktree new-top-level --repo id: --name ` (`ORCA repo list --json` gives the id). If nothing needs to come back to you (the user will work in those chats), don't start workers; per workspace run diff --git a/skill-guides/orchestration/references/placement-and-remote.md b/skill-guides/orchestration/references/placement-and-remote.md index e633f12bd90..1ea5a060559 100644 --- a/skill-guides/orchestration/references/placement-and-remote.md +++ b/skill-guides/orchestration/references/placement-and-remote.md @@ -17,11 +17,11 @@ when requesting a child of the current workspace. # Child of the current worktree. ORCA orchestration worker-start --task --worktree new-child --agent codex --setup run -# On a connected server; the Run stays on yours. -ORCA orchestration worker-start --task --on --worktree new-top-level --repo --name --agent codex --setup run +# On a connected server, nested under your workspace; the Run stays on yours. +ORCA orchestration worker-start --task --on --worktree new-child --repo --name --agent codex --setup run -# On a connected server, nested under your workspace in the sidebar. -ORCA orchestration worker-start --task --on --worktree new-child --repo --name --agent codex --setup run +# On a connected server, with no parent. +ORCA orchestration worker-start --task --on --worktree new-top-level --repo --name --agent codex --setup run ``` With `--on`, both `new-child` and `new-top-level` need `--repo` naming a diff --git a/src/cli/bundled-skill-guides.ts b/src/cli/bundled-skill-guides.ts index c5d92714523..9c75ce5f704 100644 --- a/src/cli/bundled-skill-guides.ts +++ b/src/cli/bundled-skill-guides.ts @@ -3959,7 +3959,8 @@ const ORCHESTRATION_MARKDOWN = [ "- If a receipt has `next`, follow it. When Orca has nothing for you, end your", " turn.", "- `--worktree current` uses your workspace. Use a new one only when the user", - " asks or sharing would conflict:", + " asks or sharing would conflict: `--worktree new-child --name `", + " nests it under yours. For one with no parent, use", " `--worktree new-top-level --repo id: --name `", " (`ORCA repo list --json` gives the id). If nothing needs to come back to you", " (the user will work in those chats), don't start workers; per workspace run", @@ -4115,11 +4116,11 @@ const ORCHESTRATION_PLACEMENT_AND_REMOTE_REFERENCE_MARKDOWN = [ "# Child of the current worktree.", "ORCA orchestration worker-start --task --worktree new-child --agent codex --setup run", "", - "# On a connected server; the Run stays on yours.", - "ORCA orchestration worker-start --task --on --worktree new-top-level --repo --name --agent codex --setup run", + "# On a connected server, nested under your workspace; the Run stays on yours.", + "ORCA orchestration worker-start --task --on --worktree new-child --repo --name --agent codex --setup run", "", - "# On a connected server, nested under your workspace in the sidebar.", - "ORCA orchestration worker-start --task --on --worktree new-child --repo --name --agent codex --setup run", + "# On a connected server, with no parent.", + "ORCA orchestration worker-start --task --on --worktree new-top-level --repo --name --agent codex --setup run", "```", "", "With `--on`, both `new-child` and `new-top-level` need `--repo` naming a", diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-agent-launch.ts b/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-agent-launch.ts index a61d23827de..0a3b9d07f9f 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-agent-launch.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-agent-launch.ts @@ -102,7 +102,12 @@ export async function launchFederatedWorkerAgent(args: { activate: false, ...(args.creatorProvenance ? { creatorProvenance: args.creatorProvenance } : {}), lineage: params.crossStoreParent - ? { crossStoreParent: params.crossStoreParent } + ? { + crossStoreParent: params.crossStoreParent, + ...(params.crossStoreParentInferredFrom + ? { crossStoreParentInferredFrom: params.crossStoreParentInferredFrom } + : {}) + } : { noParent: true } }) created = result.worktree diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-child-parent.ts b/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-child-parent.ts index 9fb931fcac9..8c90bf47eac 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-child-parent.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-child-parent.ts @@ -25,7 +25,10 @@ export async function resolveFederatedChildParent(args: { callerSession: OrchestrationSessionCaller | undefined serverCapabilities: readonly string[] | undefined serverName: string -}): Promise<{ crossStoreParent: CrossStoreParentRef } | { warning: string }> { +}): Promise< + | { crossStoreParent: CrossStoreParentRef; crossStoreParentInferredFrom: 'orchestration-context' } + | { warning: string } +> { const { runtime } = args // Orchestration's caller authority picks the workspace; the shared builder verifies and names it. const callerId = await resolveDispatchCallerWorktreeId(runtime, args.from, args.callerSession) @@ -48,5 +51,8 @@ export async function resolveFederatedChildParent(args: { `--worktree new-child can't nest under this workspace: ${resolved.reason} Use --worktree new-top-level.` ) } - return { crossStoreParent: resolved.parent } + return { + crossStoreParent: resolved.parent, + crossStoreParentInferredFrom: 'orchestration-context' + } } diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-start.ts b/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-start.ts index 83f641642da..1cb692c1d60 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-start.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-start.ts @@ -184,7 +184,10 @@ export async function startFederatedWorker(args: FederatedWorkerStartRequest): P // A server creates new-child as top-level plus this parent, so older servers parse it too. worktree: createsWorktree ? 'new-top-level' : worktree, ...(childParent && 'crossStoreParent' in childParent - ? { crossStoreParent: childParent.crossStoreParent } + ? { + crossStoreParent: childParent.crossStoreParent, + crossStoreParentInferredFrom: childParent.crossStoreParentInferredFrom + } : {}), name: params.name, repo: params.repo, diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federation-child-lineage-origin.test.ts b/src/main/runtime/rpc/methods/orchestration/federation/federation-child-lineage-origin.test.ts new file mode 100644 index 00000000000..90e78bd74fd --- /dev/null +++ b/src/main/runtime/rpc/methods/orchestration/federation/federation-child-lineage-origin.test.ts @@ -0,0 +1,78 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import { OrcaRuntimeService } from '../../../../orca-runtime' +import { OrchestrationDb } from '../../../../orchestration/db/orchestration-db' +import '../../../../orchestration/db/contract-constants' +import '../../../../orchestration/db/messages/mailbox-routing-page' +import '../../../../orchestration/db/dispatch-row-writer' +import '../../../../orchestration/db/attempt-outcome-projection' +import { crossStoreCreateLineage } from '../../../../workspaces/lineage/runtime-worktree-lineage-recording' +import { ORCHESTRATION_METHODS } from '../orchestration' + +const PARENT = { + installationId: 'home-install', + workspaceKey: 'worktree:repo::/home/parent', + instanceId: 'parent-instance' +} + +describe('a server nesting an orchestration worker under a workspace on another machine', () => { + let db: OrchestrationDb | undefined + + afterEach(() => db?.close()) + + async function createdLineage(attach: Record) { + db = new OrchestrationDb(':memory:') + const runtime = new OrcaRuntimeService() + runtime.setOrchestrationDb(db) + vi.spyOn(runtime, 'validateOrchestrationAgentLauncher').mockImplementation(() => {}) + // oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: worktree-creation support reads only id and kind. + vi.spyOn(runtime, 'showRepo').mockResolvedValue({ id: 'repo', kind: 'git' } as never) + const create = vi + .spyOn(runtime, 'createManagedWorktree') + .mockRejectedValue(new Error('stop after create args')) + const method = ORCHESTRATION_METHODS.find( + (candidate) => candidate.name === 'orchestration.federationAttachStart' + )! + await method + .handler( + method.params!.parse({ + runId: 'run-home', + dispatchId: 'ctx_child', + taskId: 'task_child', + taskSpec: 'work on the server', + protocolVersion: 3, + worktree: 'new-top-level', + repo: 'repo', + name: 'child', + agent: 'codex', + crossStoreParent: PARENT, + ...attach + }), + { + runtime, + orchestrationMutation: { + callerFingerprint: 'home_peer', + requestId: 'request_child', + method: 'orchestration.federationAttachStart', + payloadHash: 'child_payload' + } + } + ) + .catch(() => undefined) + const lineage = create.mock.calls[0]?.[0].lineage + if (!lineage?.crossStoreParent) { + throw new Error('the server created no nested worktree') + } + return crossStoreCreateLineage({ ...lineage, crossStoreParent: lineage.crossStoreParent }) + } + + it('records orchestration as the origin when orchestration picked the parent', async () => { + await expect( + createdLineage({ crossStoreParentInferredFrom: 'orchestration-context' }) + ).resolves.toEqual({ + kind: 'crossStore', + parent: PARENT, + origin: 'orchestration', + capture: { source: 'orchestration-context', confidence: 'inferred' } + }) + }) +}) diff --git a/src/main/runtime/workspaces/lineage/runtime-worktree-lineage-recording.ts b/src/main/runtime/workspaces/lineage/runtime-worktree-lineage-recording.ts index ab7dc62c145..6b75b5ea9b7 100644 --- a/src/main/runtime/workspaces/lineage/runtime-worktree-lineage-recording.ts +++ b/src/main/runtime/workspaces/lineage/runtime-worktree-lineage-recording.ts @@ -59,7 +59,7 @@ export function crossStoreManualLineage(parent: CrossStoreParentRef): CrossStore } } -/** App picks are manual; otherwise the CLI's --parent-worktree, or the caller workspace it inferred. */ +/** App picks are manual; an orchestration-picked parent is orchestration's; else the CLI's flag or inferred caller. */ export function crossStoreCreateLineage(input: { crossStoreParent: CrossStoreParentRef parentWorkspaceOrigin?: 'manual' @@ -71,7 +71,8 @@ export function crossStoreCreateLineage(input: { return { kind: 'crossStore', parent: input.crossStoreParent, - origin: 'cli', + origin: + input.crossStoreParentInferredFrom === 'orchestration-context' ? 'orchestration' : 'cli', capture: input.crossStoreParentInferredFrom ? { source: input.crossStoreParentInferredFrom, confidence: 'inferred' } : { source: 'explicit-cli-flag', confidence: 'explicit' } diff --git a/src/shared/rpc-contract/orchestration-federation-start-params.ts b/src/shared/rpc-contract/orchestration-federation-start-params.ts index 1446bc95382..36da2c56dca 100644 --- a/src/shared/rpc-contract/orchestration-federation-start-params.ts +++ b/src/shared/rpc-contract/orchestration-federation-start-params.ts @@ -29,7 +29,9 @@ export const FederationAttachStartParams = z.object({ devMode: z.boolean().optional(), /** The coordinator's workspace, for `--on --worktree new-child`; sent only to servers * advertising worktree.lineage.crossMachine. The new worktree nests under it. */ - crossStoreParent: CrossStoreParentRefSchema.optional() + crossStoreParent: CrossStoreParentRefSchema.optional(), + /** Orchestration picked the parent; omitted by older coordinators, whose children record `cli`. */ + crossStoreParentInferredFrom: z.literal('orchestration-context').optional() }) export type FederationAttachStartInput = z.infer