elanous 0.2.21 → 0.2.23

package/src/cli/mcp-login.ts

@@ -5,9 +5,11 @@ import { getUserConfig, reloadUserConfig, saveUserConfig, type McpServerSpec } f
 import {
   discoverMcpOAuth,
   exchangeAuthorizationCode,
+  ensureClientRegistration,
   loadStoredRegistration,
   loopbackRedirectPort,
   prepareMcpOAuthAuthorization,
+  authorizeMcpDevice,
   type McpOAuthFetch,
 } from '../mcp/mcp-oauth.js';
 import { parseWwwAuthenticate } from '../mcp/client.js';
@@ -31,7 +33,15 @@ export interface McpLoginOpts {
   out?: Output;
   readConfigFn?: () => { mcp?: { servers: McpServerSpec[] } };
   fetch?: McpOAuthFetch;
+  storePath?: string;
   openBrowser?: (url: string) => Promise<void>;
+  /** Aside browser agent; failures fall back to the existing browser flow. */
+  approveBrowser?: (url: string) => Promise<void>;
+  /** How long to wait for the approval callback after aside returns before falling back to the browser. */
+  asideCallbackGraceMs?: number;
+  /** Device-poll timing seam (test only). */
+  deviceSleep?: (ms: number) => Promise<void>;
+  deviceNow?: () => number;
   browserEnv?: NodeJS.ProcessEnv;
   browserPlatform?: NodeJS.Platform;
   createListener?: (handler: (req: IncomingMessage, res: ServerResponse) => void) => Server;
@@ -69,21 +79,58 @@ export async function runMcpLogin(opts: McpLoginOpts): Promise<McpLoginResult> {
 
   let server: Server | undefined;
   try {
-    const early = await listenForCallback(opts.createListener, 0);
-    server = early.server;
+    const why = browserUnavailableReason(opts.browserEnv ?? process.env, opts.browserPlatform ?? process.platform);
+    const oauthOpts = { ...(opts.fetch ? { fetch: opts.fetch } : {}), ...(opts.storePath ? { storePath: opts.storePath } : {}) };
+    const early = why && !opts.createListener ? undefined : await listenForCallback(opts.createListener, 0);
+    server = early?.server;
     const challenge = await requestChallenge(spec.url, opts.fetch);
     if (!challenge.resourceMetadata) {
       out.error(`✗ server '${opts.serverId}' did not provide a 401 Bearer resource_metadata challenge`);
       return { exitCode: 1 };
     }
+    const discovered = await discoverMcpOAuth(challenge.resourceMetadata, {
+      resourceUrl: spec.url, ...oauthOpts,
+    });
+    if ((why || !discovered.metadata.authorizationEndpoint) && discovered.metadata.deviceAuthorizationEndpoint) {
+      if (early?.server.listening) await closeServer(early.server);
+      if (why) out.log(why);
+      const stored = loadStoredRegistration(discovered.metadata.issuer, oauthOpts);
+      const deviceRegistration = await ensureClientRegistration(discovered.metadata, { ...oauthOpts, deviceCode: true });
+      const authorizeDevice = (registration: typeof deviceRegistration) => authorizeMcpDevice(discovered.metadata, registration, {
+        scope: challenge.scope,
+        resource: discovered.resource.resource,
+        ...oauthOpts,
+        ...(opts.deviceSleep ? { sleep: opts.deviceSleep } : {}),
+        ...(opts.deviceNow ? { now: opts.deviceNow } : {}),
+        onDeviceCode: ({ userCode, verificationUri, verificationUriComplete }) => {
+          out.log(`Authorize '${opts.serverId}' at ${verificationUriComplete ?? verificationUri}`);
+          out.log(`Device code: ${userCode}`);
+        },
+      });
+      try {
+        await authorizeDevice(deviceRegistration);
+      } catch (error) {
+        // A reused client the server does not accept for the device grant (e.g. an old browser client stored
+        // without its loopback URI) gets one fresh device registration; anything else fails as before.
+        const reused = stored?.clientId === deviceRegistration.clientId;
+        if (!reused || !discovered.metadata.registrationEndpoint || !/\((?:unauthorized_client|invalid_client)\)/.test(String(error))) throw error;
+        await authorizeDevice(await ensureClientRegistration(discovered.metadata, { ...oauthOpts, deviceCode: true, forceReregister: true }));
+      }
+      out.log(`✓ credentials saved for '${opts.serverId}' (${discovered.metadata.issuer})`);
+      persistLoginDiscovery(opts, discovered.metadata, out);
+      return { exitCode: 0 };
+    }
+    const callbackListener = early ?? await listenForCallback(opts.createListener, 0);
+    server = callbackListener.server;
     const opened = await openLoginListener({
-      early,
+      early: callbackListener,
       serverId: opts.serverId,
       resourceMetadataUrl: challenge.resourceMetadata,
       ...(challenge.scope ? { scope: challenge.scope } : {}),
       resourceUrl: spec.url,
-      ...(opts.fetch ? { fetch: opts.fetch } : {}),
+      ...oauthOpts,
       ...(opts.createListener ? { createListener: opts.createListener } : {}),
+      onListener: (openedServer) => { server = openedServer; },
     });
     const listener = opened.listener;
     server = listener.server;
@@ -94,47 +141,39 @@ export async function runMcpLogin(opts: McpLoginOpts): Promise<McpLoginResult> {
     void callbackPromise.catch(() => undefined);
     out.log(`Open this URL to authorize '${opts.serverId}':`);
     out.log(authorization.request.url);
-    const why = browserUnavailableReason(opts.browserEnv ?? process.env, opts.browserPlatform ?? process.platform);
     if (why) {
       out.log(why);
       debug.log('browser.open', 'skipped', { reason: why.includes('ssh') ? 'ssh' : 'no-display' });
     } else {
       try {
-        await (opts.openBrowser ?? openDefaultBrowser)(authorization.request.url);
+        if (opts.approveBrowser || !opts.openBrowser) {
+          await (opts.approveBrowser ?? approveWithAside)(authorization.request.url);
+          // A clean aside exit is not an approval: only the loopback callback is. If it has not arrived
+          // shortly after aside finished, fall back to the browser (the listener stays open for it).
+          let timer: ReturnType<typeof setTimeout> | undefined;
+          const arrived = await Promise.race([
+            callbackPromise.then(() => true, () => true),
+            new Promise<boolean>((resolve) => { timer = setTimeout(() => resolve(false), opts.asideCallbackGraceMs ?? 15_000); }),
+          ]);
+          if (timer) clearTimeout(timer);
+          if (!arrived) throw new Error('aside finished without an approval callback');
+        } else await opts.openBrowser(authorization.request.url);
       } catch {
-        out.error('Could not open the default browser; open the URL above manually.');
+        if (!opts.approveBrowser && opts.openBrowser) {
+          out.error('Could not open the default browser; open the URL above manually.');
+        } else {
+          try {
+            await (opts.openBrowser ?? openDefaultBrowser)(authorization.request.url);
+          } catch {
+            out.error('Could not open the default browser; open the URL above manually.');
+          }
+        }
       }
     }
     const callback = await callbackPromise;
-    await exchangeAuthorizationCode(authorization.metadata, authorization.request, callback, {
-      ...(opts.fetch ? { fetch: opts.fetch } : {}),
-    });
+    await exchangeAuthorizationCode(authorization.metadata, authorization.request, callback, oauthOpts);
     out.log(`✓ credentials saved for '${opts.serverId}' (${authorization.metadata.issuer})`);
-    // ⭐⭐ 🔴 여기가 이 파일의 «가장 중요한» 여덟 줄이다 (대표 2026-09-10).
-    //
-    //   초판은 issuer 를 «화면에 찍고 끝»이었다. 그런데 자격증명 저장소는
-    //   issuer 를 «키»로 쓰고(`getValidAccessToken(issuer, …)`), 데몬은 그
-    //   issuer 를 오직 config 의 `mcp.servers[].oauthIssuer` 에서만 얻는다
-    //   (`register-mcp-clients.ts` 는 spec 에 «있을 때만» 넘기고,
-    //    `McpClient.oauthAccessToken()` 은 `if (!this.oauthIssuer) return null`).
-    //
-    //   ⇒ 그래서 `mcp login` 이 «성공하고 ✓ 를 찍어도» 사람이 config 를 손으로
-    //      고치지 않으면 그 토큰은 영영 안 쓰인다. 2026-09-10 에 krea 를 붙이며
-    //      실제로 그 두 줄을 손으로 박았다. 「로그인했는데 도구가 0개」의 원인이다.
-    const persist = (opts.persistDiscoveryFn ?? persistDiscoveredIssuer)({
-      serverId: opts.serverId,
-      issuer: authorization.metadata.issuer,
-      ...(authorization.metadata.tokenEndpoint ? { tokenEndpoint: authorization.metadata.tokenEndpoint } : {}),
-    });
-    if (persist.error) {
-      // ⛔ 자격증명은 «이미 저장됐다» — 되쓰기 실패로 로그인 자체를 실패로 접으면
-      //    사람이 같은 브라우저 왕복을 또 한다. 경고로 내고 손 처방을 같이 준다.
-      out.error(`⚠ config 에 oauthIssuer 를 못 적었습니다: ${persist.error}`);
-      out.error(`  손으로: mcp.servers[] 의 '${opts.serverId}' 칸에 "oauthIssuer": "${authorization.metadata.issuer}" 를 더하세요.`);
-    } else if (persist.written) {
-      out.log(`✓ config 갱신 — '${opts.serverId}'.oauthIssuer = ${authorization.metadata.issuer}`);
-    }
-    out.log(`  도는 데몬에 반영하려면: elanous mcp reload`);
+    persistLoginDiscovery(opts, authorization.metadata, out);
     return { exitCode: 0 };
   } catch (error) {
     const stage = loginFailureStage(error);
@@ -146,8 +185,29 @@ export async function runMcpLogin(opts: McpLoginOpts): Promise<McpLoginResult> {
     out.error(`✗ MCP login failed: ${error instanceof Error ? error.message : String(error)}`);
     return { exitCode: 1 };
   } finally {
-    if (server) await closeServer(server);
+    if (server?.listening) await closeServer(server);
+  }
+}
+
+function persistLoginDiscovery(
+  opts: McpLoginOpts,
+  metadata: { issuer: string; tokenEndpoint: string },
+  out: Output,
+): void {
+  // ⭐⭐ issuer 를 config 에도 적어야 저장한 토큰을 데몬이 찾는다.
+  const persist = (opts.persistDiscoveryFn ?? persistDiscoveredIssuer)({
+    serverId: opts.serverId,
+    issuer: metadata.issuer,
+    tokenEndpoint: metadata.tokenEndpoint,
+  });
+  if (persist.error) {
+    // 자격은 이미 저장됐다. config 쓰기 실패는 경고로 남긴다.
+    out.error(`⚠ config 에 oauthIssuer 를 못 적었습니다: ${persist.error}`);
+    out.error(`  손으로: mcp.servers[] 의 '${opts.serverId}' 칸에 "oauthIssuer": "${metadata.issuer}" 를 더하세요.`);
+  } else if (persist.written) {
+    out.log(`✓ config 갱신 — '${opts.serverId}'.oauthIssuer = ${metadata.issuer}`);
   }
+  out.log(`  도는 데몬에 반영하려면: elanous mcp reload`);
 }
 
 async function requestChallenge(url: string, fetchFn?: McpOAuthFetch): Promise<{ resourceMetadata?: string; scope?: string }> {
@@ -175,7 +235,9 @@ async function openLoginListener(opts: {
   scope?: string;
   resourceUrl: string;
   fetch?: McpOAuthFetch;
+  storePath?: string;
   createListener?: McpLoginOpts['createListener'];
+  onListener?: (server: Server) => void;
   early: Awaited<ReturnType<typeof listenForCallback>>;
 }): Promise<{ listener: Awaited<ReturnType<typeof listenForCallback>>; authorization: Awaited<ReturnType<typeof prepareMcpOAuthAuthorization>> }> {
   const prior = await priorRegistration(opts);
@@ -189,6 +251,7 @@ async function openLoginListener(opts: {
       redirectUri: listener.redirectUri,
       resourceUrl: opts.resourceUrl,
       ...(opts.fetch ? { fetch: opts.fetch } : {}),
+      ...(opts.storePath ? { storePath: opts.storePath } : {}),
     });
     return { listener, authorization };
   }
@@ -196,6 +259,7 @@ async function openLoginListener(opts: {
   if (preferred !== null) {
     try {
       const listener = await listenForCallback(opts.createListener, preferred);
+      opts.onListener?.(listener.server);
       debug.log('mcp.login', 'callback-port', { serverId: opts.serverId, source: 'registered' });
       const authorization = await prepareMcpOAuthAuthorization({
         resourceMetadataUrl: opts.resourceMetadataUrl,
@@ -203,6 +267,7 @@ async function openLoginListener(opts: {
         redirectUri: listener.redirectUri,
         resourceUrl: opts.resourceUrl,
         ...(opts.fetch ? { fetch: opts.fetch } : {}),
+        ...(opts.storePath ? { storePath: opts.storePath } : {}),
       });
       return { listener, authorization };
     } catch (error) {
@@ -210,6 +275,7 @@ async function openLoginListener(opts: {
     }
   }
   const listener = await listenForCallback(opts.createListener, 0);
+  opts.onListener?.(listener.server);
   debug.log('mcp.login', 'callback-port', {
     serverId: opts.serverId,
     source: 'reregistered',
@@ -221,6 +287,7 @@ async function openLoginListener(opts: {
     redirectUri: listener.redirectUri,
     resourceUrl: opts.resourceUrl,
     ...(opts.fetch ? { fetch: opts.fetch } : {}),
+    ...(opts.storePath ? { storePath: opts.storePath } : {}),
     forceReregister: true,
   });
   return { listener, authorization };
@@ -230,13 +297,14 @@ async function priorRegistration(opts: {
   resourceMetadataUrl: string;
   resourceUrl: string;
   fetch?: McpOAuthFetch;
+  storePath?: string;
 }): Promise<ReturnType<typeof loadStoredRegistration>> {
   try {
     const discovered = await discoverMcpOAuth(opts.resourceMetadataUrl, {
       resourceUrl: opts.resourceUrl,
       ...(opts.fetch ? { fetch: opts.fetch } : {}),
     });
-    return loadStoredRegistration(discovered.metadata.issuer);
+    return loadStoredRegistration(discovered.metadata.issuer, opts);
   } catch {
     return null;
   }
@@ -368,6 +436,12 @@ async function closeServer(server: Server): Promise<void> {
   await new Promise<void>((resolve) => server.close(() => resolve()));
 }
 
+async function approveWithAside(url: string): Promise<void> {
+  // Aside decides how to interact with the provider page; only the state-checked
+  // loopback callback (not the agent's answer) can complete this login.
+  await execFileAsync('aside', ['exec', '--effort', 'low', `Open this OAuth authorization URL in your browser and approve access for elanous: ${url}. Do not reveal passwords, codes or tokens in your response.`], { timeout: 90_000 });
+}
+
 async function openDefaultBrowser(url: string): Promise<void> {
   const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
   const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];

package/src/cli/plugin-cli.ts

@@ -6,7 +6,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { elanousStateRoot } from '../autopilot/state-paths.js';
 import { userConfigPath } from '../user-config.js';
 import { debug, redactSecretText } from '../debug/log.js';
-import { addMarket, listMarkets, MarketFetchError, updateMarket } from '../plugins/install/market-fetch.js';
+import { addMarket, ensureInternalMarketIndex, listMarkets, MarketFetchError, updateMarket } from '../plugins/install/market-fetch.js';
 import { emitDecision } from '../live/detail-switch.js';
 import { OFFICIAL_INDEX_KEYS } from '../market/official-keys.js';
 import { installPlugin, listInstalledPlugins, PluginInstallError, removePlugin, type InstallEvent } from '../plugins/install/plugin-install.js';
@@ -145,6 +145,26 @@ export function registerPluginCommands(program: Command): void {
       }
     });
   const market = plugin.command('market').description('Manage signed plugin marketplaces');
+  market.command('internal <name> <enterpriseId>').description('Fetch signed entries from a configured internal HTTPS market for an allowed enterprise')
+    .option('--refresh', 'Refresh the signed internal market index')
+    .option('--json', 'Print verified knowledge packs and loop bundles as JSON')
+    .action(async (name: string, enterpriseId: string, opts: { refresh?: boolean; json?: boolean }) => {
+      try {
+        const root = elanousStateRoot();
+        const result = await ensureInternalMarketIndex(name, enterpriseId, {
+          root, marketDir: join(root, 'plugins', 'markets'), refresh: opts.refresh,
+        });
+        const entries = { name: result.market.name, enterpriseId, sequence: result.index.sequence,
+          knowledgePacks: result.index.knowledgePacks ?? [], loopBundles: result.index.loopBundles ?? [] };
+        debug.log('plugin.cli', 'market.internal', { name: result.market.name, sequence: result.index.sequence });
+        if (opts.json) stdout.write(JSON.stringify(entries) + '\n');
+        else console.log(`Fetched internal market ${entries.name} (sequence ${entries.sequence}): ${entries.knowledgePacks.length} knowledge packs, ${entries.loopBundles.length} loop bundles`);
+      } catch (error) {
+        if (opts.json) stdout.write(JSON.stringify({ event: 'failed', cause: safeCause(error) }) + '\n');
+        else console.error(`plugin market internal failed: ${safeCause(error)}`);
+        process.exitCode = 1;
+      }
+    });
   market.command('add <name> <url>').description('Register a marketplace URL')
     .action((name: string, url: string) => {
       try {

package/src/cli/pod-cli.ts

@@ -33,6 +33,27 @@ const HELP = `elanous pod run [--pool <스펙>] [--skill <이름,…>] [--llm gr
   하니스 없이 명령 하나를 Pod 에서 돌리고 산출 경로를 한 줄로 알린다.
   --deadline 생략 시 ${POD_COMMAND_DEADLINE_SECONDS}초(기존 Pod Job 수명 상한).`;
 
+/** clone 트리는 `bun install` 없이 뜨므로 `bun test`·`bun run` 은 «Cannot find package» 로 실패한다
+ *  (실측 2026-10-10 21:47 node-b · `pod run --clone -- bun test src/steward/launch.test.ts` → 1 fail ·
+ *  설치만 붙여 다시 치니 58초 Completed). Pod 문제로 오인하기 쉬워 «발사 전»에 한 줄로 알린다 — 발사는 막지 않는다. */
+export const POD_CLONE_WITHOUT_INSTALL_WARNING =
+  '⚠ --clone 트리에는 node_modules 가 없다 — 시험이면 sh -c "bun install --frozen-lockfile && <명령>" 꼴로 감싸라';
+
+/** `--clone` ⊕ 명령 첫 낱말이 `bun` ⊕ 둘째가 `test`·`run` ⊕ 명령 어디에도 `install` 낱말(토큰)이 없으면 경고 대상이다. */
+export function podCloneWithoutInstallWarning(
+  commandArgs: readonly string[],
+  clone: boolean | undefined,
+): string | null {
+  if (!clone) return null;
+  const [argv0, argv1] = commandArgs;
+  if (argv0 !== 'bun') return null;
+  if (argv1 !== 'test' && argv1 !== 'run') return null;
+  // Exact argv token only: `installation.test.ts` or a single `install helper` argument is not an install
+  // (a shell string like `sh -c "bun install && …"` never reaches here — its argv0 is `sh`).
+  if (commandArgs.includes('install')) return null;
+  return POD_CLONE_WITHOUT_INSTALL_WARNING;
+}
+
 export function registerPodCommands(program: Command, deps: PodCliDeps = {}): void {
   const io = deps.io ?? {
     log: (line: string) => console.log(line),
@@ -148,6 +169,11 @@ export function registerPodCommands(program: Command, deps: PodCliDeps = {}): vo
         }
       }
       const skills = (opts.skill ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+      const cloneWarning = podCloneWithoutInstallWarning(commandArgs, opts.clone);
+      if (cloneWarning !== null) {
+        io.error(cloneWarning);
+        debug.log('pod.run', 'clone-without-install', { argv0: commandArgs[0], argv1: commandArgs[1] });
+      }
       try {
         const result = await run({
           command: commandArgs,

package/src/cli/pr-cli.ts

@@ -57,11 +57,15 @@ import { branchLineageSlug, findSiblingPrs } from './pr-lineage.js';
 import { parseReleaseNoteSection } from '../release-loop/release-note.js';
 import { landingFreezeMessage } from '../release-loop/landing-freeze.js';
 import { admitLandingMerge } from '../self-implement/frozen-merges.js';
+import { verifyOverlapEvidence } from './pr-land-overlap-evidence.js';
 import { enqueueL8ShadowQueue, runL8ShadowQueue, shadowPrNumber, statusL8ShadowQueue, type L8ShadowQueueDeps } from '../self-implement/l8-merge-queue.js';
 
 export { branchLineageSlug, findSiblingPrs };
 
 export interface PrLandOpts {
+  /** Pin an existing PR and its reviewed head; both must be supplied together. */
+  pr?: string;
+  expectedHead?: string;
   base?: string;
   cwd?: string;
   dryRun?: boolean;
@@ -80,6 +84,8 @@ export interface PrLandOpts {
   forceFreeze?: string;
   /** Land even though changed files would leak into the public export (the reason goes in --land-reason). */
   allowPublicLeak?: boolean;
+  /** Pinned landing only: JSON evidence (rebased · re-gated · reviewed head) that replaces the unavailable non-interactive overlap approval. */
+  overlapEvidence?: string;
 }
 
 export interface PrGranularityOpts {
@@ -995,6 +1001,7 @@ function emitLandingOverlapAdvisory(
   base: string,
   currentFiles: readonly string[],
   out: { log: (message: string) => void },
+  overlappingLandings: string[] = [],
 ): boolean {
   if (currentFiles.length === 0) {
     record('overlap', true, { outcome: 'no-changed-files' });
@@ -1006,6 +1013,8 @@ function emitLandingOverlapAdvisory(
     return false;
   }
   const overlaps = overlapWithCurrentChanges(commits, currentFiles);
+  const current = new Set(currentFiles);
+  overlappingLandings.push(...commits.filter((commit) => commit.files.some((file) => current.has(file))).map((commit) => commit.hash));
   const line = formatOverlapAdvisory(overlaps);
   if (line) {
     record('overlap', true, {
@@ -1180,10 +1189,37 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
 
   const cwd = opts.cwd ?? process.cwd();
   const run = deps.run ?? defaultCmdRunner;
+  const pinned = opts.pr !== undefined || opts.expectedHead !== undefined;
+  if (opts.overlapEvidence !== undefined && (!pinned || !opts.overlapEvidence.trim())) {
+    out.error('✗ overlap-evidence: --overlap-evidence <file> 는 --pr ⊕ --expected-head 머리 고정 착지에서만 쓴다.');
+    return 1;
+  }
+  let pinnedBranch: string | undefined;
+  let pinnedUrl: string | undefined;
+  if (pinned) {
+    const pr = Number(opts.pr);
+    if (!/^[1-9]\d*$/.test(opts.pr ?? '') || !Number.isSafeInteger(pr) || !/^[a-f0-9]{40}$/i.test(opts.expectedHead ?? '') || opts.hold || opts.dryRun) {
+      out.error('✗ expected-head: --pr and --expected-head (full SHA) are required together without --hold/--dry-run');
+      return 1;
+    }
+    const viewed = run('gh', ['pr', 'view', String(pr), '--json', 'headRefOid,headRefName,state,isDraft,url'], { cwd });
+    let value: { headRefOid?: string; headRefName?: string; state?: string; isDraft?: boolean; url?: string } = {};
+    try { if (viewed.ok) value = JSON.parse(viewed.out) as typeof value; } catch { /* unreadable is not approval */ }
+    const local = run('git', ['rev-parse', 'HEAD'], { cwd });
+    const dirty = run('git', ['status', '--porcelain'], { cwd });
+    if (value.state !== 'OPEN' || value.isDraft !== false || value.headRefOid?.toLowerCase() !== opts.expectedHead!.toLowerCase()
+      || !value.url?.endsWith(`/pull/${pr}`) || !value.headRefName || !local.ok || local.out.trim().toLowerCase() !== opts.expectedHead!.toLowerCase()
+      || !dirty.ok || dirty.out.trim()) {
+      out.error('✗ expected-head: PR OPEN non-draft, matching local HEAD and clean worktree required');
+      return 1;
+    }
+    pinnedBranch = value.headRefName;
+    pinnedUrl = value.url;
+  }
   const resolveBase = deps.resolveBase ?? resolveDeliverableBase;
   const branch = (deps.currentBranch ?? liveCurrentBranch)(cwd);
-  if (!branch) {
-    const detail = '현재 브랜치를 해석하지 못했습니다.';
+  if (!branch || (pinned && branch !== pinnedBranch)) {
+    const detail = pinned ? 'PR head branch와 현재 브랜치가 다릅니다.' : '현재 브랜치를 해석하지 못했습니다.';
     record('branch', false);
     out.error(`✗ branch: ${detail}`);
     return 1;
@@ -1536,7 +1572,8 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     return 1;
   }
 
-  const overlapFound = emitLandingOverlapAdvisory(run, cwd, base, changedPaths, out);
+  const overlappingLandings: string[] = [];
+  const overlapFound = emitLandingOverlapAdvisory(run, cwd, base, changedPaths, out, overlappingLandings);
   const siblingFound = emitSiblingPrAdvisory(
     branch,
     deps.listOpenPrs ?? (() => lookupOpenPrs(run, cwd)),
@@ -1567,6 +1604,26 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     });
   }
   const hold = !!opts.hold || overlapDecision?.outcome === 'user-hold';
+  // TA-LAND-OVERLAP — 비대화형 «승인 불가»만 증거로 대신한다(사람의 hold 는 증거로 뒤집지 않는다) · 증거가 없거나 어긋나면 종전 거부 그대로.
+  let overlapEvidenceAccepted = false;
+  if (pinned && overlapDecision?.outcome === 'unavailable' && opts.overlapEvidence !== undefined) {
+    const ref = resolveRemoteBranchRef(run, cwd, base);
+    const verdict = verifyOverlapEvidence({
+      evidencePath: opts.overlapEvidence, pr: Number(opts.pr), expectedHead: opts.expectedHead!,
+      remote: ref.remote, branch: ref.branch, cwd, run, readFile, overlappingLandings,
+    });
+    overlapEvidenceAccepted = verdict.ok;
+    if (verdict.ok) {
+      out.log(verdict.mode === 'already-ancestor'
+        ? `✓ overlap-evidence: already-ancestor — 겹친 최근 착지 ${overlappingLandings.length}개가 전부 head ${opts.expectedHead!.slice(0, 12)} 의 조상 · review pass must-fix 0 (${verdict.reviewResult})`
+        : `✓ overlap-evidence: ${ref.remote}/${ref.branch} ${verdict.baseTip.slice(0, 12)} ⊂ head ${opts.expectedHead!.slice(0, 12)} · gate passed on that base · review pass must-fix 0 (${verdict.reviewResult})`);
+    }
+    else out.error(`✗ overlap-evidence: ${verdict.reason}`);
+  }
+  if (pinned && overlapDecision && overlapDecision.outcome !== 'user-merge' && !overlapEvidenceAccepted) {
+    out.error('✗ expected-head: overlap merge approval unavailable for the reviewed head');
+    return 1;
+  }
 
   const manager = deps.manager ?? makePrManager(run);
   const existing = manager.findPrForBranchOutcome(branch, cwd);
@@ -1638,7 +1695,12 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     }
   }
 
-  const upsert = manager.upsertPr({
+  // A pinned, already-reviewed commit must not go through upsertPr (git add/commit/force-push/PR edit).
+  const upsert = pinned
+    ? existing.status === 'ok OUTPUT' && existing.url === pinnedUrl
+      ? { ok: true as const, url: pinnedUrl!, reused: true }
+      : { ok: false as const, reason: 'gh' as const, detail: 'pinned PR is not the branch open PR' }
+    : manager.upsertPr({
     branch,
     worktreePath: cwd,
     base,
@@ -1654,7 +1716,7 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     ...(excludingActiveRunFiles ? { excludePaths } : {}),
   });
   if (!upsert.ok) {
-    if (upsert.reason === 'noop' && excludingActiveRunFiles) {
+    if (upsert.reason === 'noop' && excludingActiveRunFiles && !pinned) {
       record('upsert-ready-noop', true, { excludePaths, detail: upsert.detail });
       out.log(`✓ upsert-ready: 제외 후 올릴 것이 없습니다 — ${upsert.detail}`);
       return 0;
@@ -1664,6 +1726,13 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     return 1;
   }
   record('upsert-ready', true);
+  if (pinned) {
+    const upsertHead = run('git', ['rev-parse', 'HEAD'], { cwd });
+    if (!upsert.reused || upsert.url !== pinnedUrl || !upsertHead.ok || upsertHead.out.trim().toLowerCase() !== opts.expectedHead!.toLowerCase()) {
+      out.error('✗ expected-head: pinned PR identity or reviewed HEAD changed');
+      return 1;
+    }
+  }
   out.log(`✓ upsert-ready: ${upsert.url}${upsert.reused ? ' (기존 PR)' : ' (새 PR)'}`);
 
   if (hold) {
@@ -1688,21 +1757,34 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     debug.log('harness.merge', 'frozen', { prUrl: upsert.url, reason: frozen.reason, until: frozen.until });
     record('freeze', true, { url: upsert.url, reason: frozen.reason, until: frozen.until });
     out.log(`✓ ready: ${upsert.url} — ${landingFreezeMessage(frozen)} · 병합 연기`);
-    return 0;
+    return pinned ? 1 : 0;
   }
   if (admission.kind === 'taken') {
     record('freeze', true, { url: upsert.url, resumedElsewhere: true });
     out.log(`✓ ready: ${upsert.url} — 동결이 막 풀려 보류 병합 재개가 이 PR 을 맡았습니다`);
-    return 0;
+    return pinned ? 1 : 0;
   }
   const landing = admission;
+  if (pinned) {
+    const view = run('gh', ['pr', 'view', String(opts.pr), '--json', 'headRefOid,state,isDraft'], { cwd });
+    let current: { headRefOid?: string; state?: string; isDraft?: boolean } = {};
+    try { if (view.ok) current = JSON.parse(view.out) as typeof current; } catch { /* fail closed */ }
+    const finalHead = run('git', ['rev-parse', 'HEAD'], { cwd });
+    if (current.headRefOid?.toLowerCase() !== opts.expectedHead!.toLowerCase() || current.state !== 'OPEN' || current.isDraft !== false
+      || !finalHead.ok || finalHead.out.trim().toLowerCase() !== opts.expectedHead!.toLowerCase()) {
+      landing.end(false);
+      out.error('✗ expected-head: PR head/state changed before merge');
+      return 1;
+    }
+  }
   let merged: ReturnType<typeof manager.mergePrOutcome>;
   try {
-  merged = manager.mergePrOutcome(upsert.url);
+  merged = manager.mergePrOutcome(upsert.url, pinned ? opts.expectedHead : undefined, pinned ? cwd : undefined);
   // `GIT-S14` — 병합이 «미완료(OPEN)»로 끝났고 GitHub 가 아직 `mergeable=UNKNOWN`(병합 가능 여부 계산 중)이면
   //   짧게 기다렸다 다시 병합한다. 표본 셋(08-25 · 09-24 🅢 #20233 등)이 모두 «같은 명령 재시도에 병합»이었다.
   //   ⛔ UNKNOWN 일 때만 재시도한다 — CONFLICTING 등 다른 값은 기다려도 안 풀린다(그대로 실패를 낸다).
   const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  // pinned 도 재시도한다 — mergePrOutcome 이 머리를 다시 확인하고 --match-head-commit 으로 병합하므로 바뀐 머리로는 안 들어간다.
   for (let attempt = 1; !merged.ok && merged.kind === 'not-merged' && merged.state === 'OPEN' && attempt <= PR_LAND_MERGEABLE_UNKNOWN_RETRIES; attempt += 1) {
     const mergeable = run('gh', ['pr', 'view', upsert.url, '--json', 'mergeable', '--jq', '.mergeable'], { cwd });
     const value = mergeable.ok ? mergeable.out.trim() : '';
@@ -1710,7 +1792,7 @@ export async function runPrLand(opts: PrLandOpts = {}, deps: PrLandDeps = {}): P
     record('merge-retry', true, { attempt, mergeable: value, waitMs: PR_LAND_MERGEABLE_UNKNOWN_WAIT_MS });
     out.log(`⏳ merge: mergeable=UNKNOWN — GitHub 가 병합 가능 여부를 아직 계산 중입니다 · ${PR_LAND_MERGEABLE_UNKNOWN_WAIT_MS / 1000}초 뒤 다시 병합 (${attempt}/${PR_LAND_MERGEABLE_UNKNOWN_RETRIES})`);
     await sleep(PR_LAND_MERGEABLE_UNKNOWN_WAIT_MS);
-    merged = manager.mergePrOutcome(upsert.url);
+    merged = manager.mergePrOutcome(upsert.url, pinned ? opts.expectedHead : undefined, pinned ? cwd : undefined);
   }
   } finally { landing.end(merged!?.ok === true); }
   if (!merged.ok) {
@@ -1781,6 +1863,8 @@ export function registerPrCommands(program: Command, deps: PrLandDeps = {}, queu
     .description('현재 브랜치 PR을 생성 또는 갱신해 ready 상태로 만들고 squash merge')
     .option('--base <branch>', 'PR base branch')
     .option('--cwd <path>', '작업 트리 경로')
+    .option('--pr <number>', '기존 PR 번호 고정 (--expected-head 와 함께)')
+    .option('--expected-head <sha>', '리뷰된 PR 머리 SHA 고정 (--pr 와 함께)')
     .option('--dry-run', '변경 없이 landing 계획만 출력')
     .option('--hold', 'PR을 생성 또는 갱신한 뒤 병합하지 않고 쌓아 둔다')
     .option('--title <title>', 'PR title')
@@ -1795,6 +1879,7 @@ export function registerPrCommands(program: Command, deps: PrLandDeps = {}, queu
     .option('--land-reason <text>', '권고를 보고도 지금 내는 이유(예: 남이 기다리는 차단 해제)')
     .option('--force-freeze <reason>', '동결을 넘겨 병합할 명시적 이유(필수)')
     .option('--allow-public-leak', '바뀐 파일이 공개본에 사적 흔적을 실어도 착지(이유는 --land-reason)')
+    .option('--overlap-evidence <file>', '머리 고정 착지 전용: 비대화형 겹침 승인을 대신할 증거 JSON {pr, head, gate:{head,baseCommit,passed}, reviewResult} — 재기반·재게이트·리뷰를 CLI 가 다시 잰다(겹친 착지가 전부 머리의 조상이면 리뷰만 · gate 생략 가능)')
     .action(async (opts: PrLandOpts) => {
       // ⛔⭐⭐⭐ **관측 sink 를 먼저 건다** — 라이브 도그푸드가 잡은 결함(2026-08-03).
       //   단위 테스트는 `debug.log` 가 **불렸다**를 단언하지만, standalone CLI 는 sink 를 등록하지