From fc8ff4298cd1c167c90721516bfb30e4c2871644 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Mon, 24 Aug 2026 10:00:02 -0700
Subject: [PATCH] Document host extraction safety for destructive worktree ops

Unqualified identities must stay undefined rather than defaulting to
'local'. Destructive operations depend on correct host identification.
Added tests and JSDoc to clarify this safety-critical behavior.
---
 .../worktree/host-qualified-identity.test.ts  | 21 +++++++++++++++++++
 .../worktree/host-qualified-identity.ts       |  7 +++++++
 2 files changed, 28 insertions(+)

diff --git a/src/shared/worktree/host-qualified-identity.test.ts b/src/shared/worktree/host-qualified-identity.test.ts
index 9b866e5d044..f6237005b28 100644
--- a/src/shared/worktree/host-qualified-identity.test.ts
+++ b/src/shared/worktree/host-qualified-identity.test.ts
@@ -63,4 +63,25 @@ describe('worktree host identity', () => {
   it('rejects identities without a host separator', () => {
     expect(getExecutionHostIdFromWorktreeHostIdentity('ssh:build-box')).toBeUndefined()
   })
+
+  // An unqualified row must not be assumed local: a destructive action keyed off
+  // this would then run against the wrong host.
+  it('leaves an unqualified identity without a host', () => {
+    expect(
+      getExecutionHostIdFromWorktreeHostIdentity(
+        composeWorktreeHostIdentity(undefined, WORKTREE_ID)
+      )
+    ).toBeUndefined()
+  })
+
+  it('recovers the host from a qualified identity', () => {
+    expect(
+      getExecutionHostIdFromWorktreeHostIdentity(composeWorktreeHostIdentity('local', WORKTREE_ID))
+    ).toBe('local')
+    expect(
+      getExecutionHostIdFromWorktreeHostIdentity(
+        composeWorktreeHostIdentity(toSshExecutionHostId('build-box'), WORKTREE_ID)
+      )
+    ).toBe(toSshExecutionHostId('build-box'))
+  })
 })
diff --git a/src/shared/worktree/host-qualified-identity.ts b/src/shared/worktree/host-qualified-identity.ts
index 9733aed2dd5..dcdc4411724 100644
--- a/src/shared/worktree/host-qualified-identity.ts
+++ b/src/shared/worktree/host-qualified-identity.ts
@@ -39,6 +39,13 @@ export function composeWorktreeHostIdentity(
   return `${hostId ?? ''}${HOST_SEPARATOR}${worktreeId}`
 }
 
+/**
+ * The host back out of an identity, when the identity names one.
+ *
+ * An empty prefix (`|<worktreeId>`) stays undefined rather than defaulting to
+ * `local`: an unqualified row may be on any host, and callers use this to pick
+ * the host a destructive action runs against.
+ */
 export function getExecutionHostIdFromWorktreeHostIdentity(
   identity: string
 ): ExecutionHostId | undefined {