elanous 0.2.0 → 0.2.4

package/src/cli/pwa-test.ts

@@ -26,27 +26,31 @@
 //     personal :443 forwards).
 //
 // Auto port collision recovery:
-//   - NEXUS port: prefer 31415 → 31420 (skip 31416-31419 to keep the
-//     classic +5 NEXUS spacing) → 31421+. Skip if production daemon
-//     (`~/.elanous/nexus/.lock`) holds it OR an unrelated process binds
-//     it (lsof check).
+//   - NEXUS port: coordinator lease in 31450–31499; if the coordinator is
+//     absent or answers with any error, fall back to the machine-local
+//     test-band lease (`leaseTestPort`, 31450–31499). Never pick
+//     production-reserved ports (31413 · 31415 · 31420).
 //   - Next dev port (HMR mode only): prefer 3210 → 3211 → 3212+.
 //     Skip if any process binds the port.
 //   - Stale `<repo>/.elanous-test/.lock` is an idempotent reuse — the
 //     command refuses with a clear hint unless `--force` is passed.
 
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { execFileSync } from 'node:child_process';
+import { leaseTestPort } from './port-lease-local.js';
+import { debug } from '../debug/log.js';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:net';
 import { dirname, join as joinPath, resolve as resolvePath } from 'node:path';
 
-import { setTestStateRoot, getTestStateRoot } from '../nexus/paths.js';
+import { setTestStateRoot } from '../nexus/paths.js';
+import { readNexusRuntimeAt } from '../nexus/runtime.js';
+import { isPidAlive } from '../process/pid-liveness.js';
+import { lastMeaningfulLogLine } from './bg-launch.js';
+import { PORT_BANDS } from '../control-plane/ports.js';
+import { PORT_LEASE_TTL_MS } from '../control-plane/port-lease-heartbeat.js';
+import { resolvePrimary, type PrimaryAddress, type PrimaryConfig } from '../control-plane/primary.js';
 import { runPwaStart, type PwaStartMode, type PwaStartOpts, type PwaStartResult } from './pwa-start.js';
 import { runPwaStop, type PwaStopOpts, type PwaStopResult } from './pwa-stop.js';
-import {
-  isAliveNexusLock,
-  readNexusLock,
-  type NexusLockMeta,
-} from '../nexus/supervisor/lock.js';
+import { isAliveNexusLock, type NexusLockMeta } from '../nexus/supervisor/lock.js';
 import {
   mountTailscaleServe,
   unmountTailscaleServe,
@@ -123,13 +127,18 @@ export interface PwaTestOpts {
   // ─── Test seams ─────────────────────────────────────────────
   /** Override the repo root resolution from `argvBin`. */
   repoRoot?: string;
-  /** Replace the production-daemon lock probe. Defaults to reading
-   *  `~/.elanous/nexus/.lock` via the public helpers. */
-  productionLockProbeFn?: () => NexusLockMeta | null;
-  /** Replace the production-daemon liveness check. */
+  /** Replace the lock liveness check used for stale project locks. */
   productionLockAliveFn?: (meta: NexusLockMeta) => boolean;
-  /** Replace the port collision probe. Defaults to `lsof -ti :<port>`. */
-  portInUseFn?: (port: number) => boolean;
+  /** Replace the port collision probe. Defaults to a local bind probe. */
+  portInUseFn?: (port: number) => boolean | Promise<boolean>;
+  /** Explicit primary address and scoped write token for coordinator leases. */
+  coordinatorPrimary?: PrimaryConfig;
+  /** Coordinator request seam; null means coordinator unavailable. A lease must carry its id. */
+  leasePortFn?: (excluded?: readonly number[]) => Promise<CoordinatorPortLease | null>;
+  /** Release a failed central claim before retrying. */
+  releasePortFn?: (port: number) => Promise<void>;
+  /** Test seam — lease directory for the local test-band port lease (default: OS tmp). */
+  leaseDir?: string;
   /** Replace the runPwaStart dependency (the underlying daemon + dev
    *  bring-up · we compose this rather than reimplement). */
   pwaStartFn?: (opts: PwaStartOpts) => Promise<PwaStartResult>;
@@ -165,8 +174,6 @@ export interface PwaTestResult {
   tailscaleMounted?: boolean;
 }
 
-const DEFAULT_NEXUS_PORT = 31415;
-const NEXUS_FALLBACK_PORTS = [31420, 31421, 31422, 31423, 31424];
 const DEFAULT_DEV_PORT = 3210;
 const DEV_FALLBACK_RANGE = [3211, 3212, 3213, 3214, 3215];
 
@@ -209,18 +216,12 @@ function resolveLayout(opts: PwaTestOpts): RepoLayout | null {
   };
 }
 
-function defaultPortInUse(port: number): boolean {
-  try {
-    // `lsof -ti :<port>` exits 0 + prints PIDs when something is
-    // listening; exits 1 with empty stdout when free.
-    const stdout = execFileSync('lsof', ['-ti', `:${port}`, '-sTCP:LISTEN'], {
-      stdio: ['ignore', 'pipe', 'ignore'],
-      timeout: 3000,
-    });
-    return String(stdout).trim().length > 0;
-  } catch {
-    return false;
-  }
+async function defaultPortInUse(port: number): Promise<boolean> {
+  return new Promise(resolve => {
+    const server = createServer();
+    server.once('error', () => resolve(true));
+    server.listen(port, '0.0.0.0', () => server.close(() => resolve(false)));
+  });
 }
 
 function readProjectLock(lockPath: string): NexusLockMeta | null {
@@ -236,81 +237,134 @@ function readProjectLock(lockPath: string): NexusLockMeta | null {
   }
 }
 
-function pickNexusPort(
+async function coordinatorPortRequest(path: string, method: string, body?: unknown, primary?: PrimaryAddress): Promise<Response | null> {
+  primary ??= await resolvePrimary({ role: 'member' });
+  if (!primary.token) return null;
+  try {
+    return await fetch(`${primary.url}${path}`, {
+      method,
+      headers: { Authorization: `Bearer ${primary.token}`, ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      signal: AbortSignal.timeout(1000),
+    });
+  } catch { return null; }
+}
+
+export type CoordinatorPortLease = { port: number; leaseId: string };
+
+export async function requestCoordinatorPort(
+  excluded: readonly number[] = [],
+  send: typeof coordinatorPortRequest = coordinatorPortRequest,
+): Promise<CoordinatorPortLease | null> {
+  return requestCoordinatorPortForPrimary(excluded, await resolvePrimary({ role: 'member' }), send);
+}
+
+async function requestCoordinatorPortForPrimary(
+  excluded: readonly number[], primary: PrimaryAddress, send: typeof coordinatorPortRequest = coordinatorPortRequest,
+): Promise<CoordinatorPortLease | null> {
+  const response = await send('/v1/leases/port', 'POST', {
+    machine: primary.machine ?? (process.env.HOSTNAME || 'local'), purpose: 'nexus-test', ttlMs: PORT_LEASE_TTL_MS, excluded,
+  }, primary);
+  if (!response) return null;
+  if (response.status === 409) {
+    const body: unknown = await response.json();
+    if ((body as { error?: unknown })?.error === 'no-port') return null;
+  }
+  if (!response.ok) throw new Error(`coordinator port lease HTTP ${response.status}`);
+  const body: unknown = await response.json();
+  const port = (body as { port?: unknown })?.port;
+  const leaseId = (body as { lease?: { attrs?: { leaseId?: unknown } } })?.lease?.attrs?.leaseId;
+  if (typeof port !== 'number' || !Number.isInteger(port) || port < PORT_BANDS.test.start || port > PORT_BANDS.test.end ||
+      typeof leaseId !== 'string' || !leaseId) {
+    throw new Error('invalid coordinator port lease');
+  }
+  return { port, leaseId };
+}
+
+async function releaseCoordinatorPort(lease: CoordinatorPortLease, primary?: PrimaryAddress): Promise<void> {
+  primary ??= await resolvePrimary({ role: 'member' });
+  if (!primary.token) return;
+  const response = await fetch(`${primary.url}/v1/leases/port/${lease.port}`, {
+    method: 'DELETE', headers: { Authorization: `Bearer ${primary.token}`, 'x-port-lease-id': lease.leaseId },
+    signal: AbortSignal.timeout(1000),
+  }).catch(() => null);
+  if (!response?.ok && response?.status !== 404 && response?.status !== 403) throw new Error(`coordinator port release ${response ? `HTTP ${response.status}` : 'unavailable'}`);
+}
+
+async function pickNexusPort(
   preferred: number | undefined,
   layout: RepoLayout,
   opts: PwaTestOpts,
-): { port: number; reason: string } | { error: string } {
+): Promise<{ port: number; reason: string; leaseId?: string; primary?: PrimaryAddress } | { error: string }> {
   const inUseFn = opts.portInUseFn ?? defaultPortInUse;
-  const productionProbeFn =
-    opts.productionLockProbeFn ?? readNexusLock;
-  const productionAliveFn = opts.productionLockAliveFn ?? isAliveNexusLock;
-
+  // ⓐ 명시 `--port` 가 이긴다(불변).
   if (preferred !== undefined) {
-    if (inUseFn(preferred)) {
-      return { error: `port ${preferred} already in use (lsof match)` };
-    }
+    if (await inUseFn(preferred)) return { error: `port ${preferred} already in use` };
     return { port: preferred, reason: 'explicit --port' };
   }
+  // ⓑ 관제부 임대 — 없거나(null) «어떤 오류든»(409 no-port · 503 · 네트워크 · 잘못된 응답) ⓒ 로 넘어간다.
+  const central = await pickCoordinatorPort(opts, inUseFn);
+  if (central) return central;
+  // ⓒ 기계 안 로컬 임대(#20864) — 시험 대역(31450~31499)에서만 준다. 운영 대역(31413·31415·31420)은 절대 안 고른다.
+  const claim = await leaseTestPort({
+    owner: layout.repoRoot,
+    ...(opts.leaseDir ? { dir: opts.leaseDir } : {}),
+    ...(opts.portInUseFn ? { inUse: opts.portInUseFn } : {}),
+  });
+  if ('error' in claim) return { error: '시험 대역에 빈 포트가 없습니다 (31450..31499)' };
+  return { port: claim.port, reason: `시험 대역에서 :${claim.port} 임대` };
+}
 
-  // Default: 31415. Production daemon (`~/.elanous/nexus/.lock`) takes
-  // precedence — we never want to clobber the user's primary daemon.
-  const candidates = [DEFAULT_NEXUS_PORT, ...NEXUS_FALLBACK_PORTS];
-
-  // Production probe must read `~/.elanous/nexus/.lock`, not our test
-  // lock. Temporarily clear any in-process test state override so
-  // `readNexusLock` falls through to the default config-dir path.
-  // (Same-process re-entry only — fresh `elanous` invocations start
-  // with testStateRoot=undefined automatically.)
-  const savedTestStateRoot = getTestStateRoot();
-  setTestStateRoot(null);
-  let prodLock: NexusLockMeta | null = null;
-  try { prodLock = productionProbeFn(); } catch { /* swallow */ }
-  finally {
-    if (savedTestStateRoot !== undefined) setTestStateRoot(savedTestStateRoot);
-  }
-  const productionAlive = prodLock && productionAliveFn(prodLock);
-
-  // Project test lock — distinct path; reuse when alive (idempotent
-  // start = informative status), force-take when --force.
-  const projectLock = readProjectLock(layout.lockPath);
+async function releaseCentral(opts: PwaTestOpts, lease: CoordinatorPortLease, primary?: PrimaryAddress): Promise<void> {
+  if (opts.releasePortFn) await opts.releasePortFn(lease.port);
+  else await releaseCoordinatorPort(lease, primary);
+}
 
-  for (const port of candidates) {
-    if (port === DEFAULT_NEXUS_PORT && productionAlive) continue;
-    if (inUseFn(port)) {
-      // The test lock might describe THIS port — if so, it's our own
-      // prior instance and the orchestrator's flow handles that
-      // separately (errors with reuse/force hint at the entry point).
-      if (
-        projectLock
-        && projectLock.pid !== prodLock?.pid
-        && opts.force !== true
-      ) {
-        // We can't tell which port the prior test was on without
-        // reading runtime.json — leave that to the entry point.
-        // Continue to next candidate so a second port lookup keeps
-        // working when the prior is stale.
-      }
-      continue;
+/** 관제부에서 시험 대역 포트를 받는다. 받지 못하면(관제부 부재·오류·잘못된 응답·대역 소진) null — 호출자가 로컬 임대로 넘어간다. */
+async function pickCoordinatorPort(
+  opts: PwaTestOpts,
+  inUseFn: (port: number) => boolean | Promise<boolean>,
+): Promise<{ port: number; reason: string; leaseId: string; primary?: PrimaryAddress } | null> {
+  const primary = opts.leasePortFn ? undefined : await resolvePrimary({ role: 'member', config: opts.coordinatorPrimary });
+  const request = opts.leasePortFn ?? ((excluded: readonly number[]) => requestCoordinatorPortForPrimary(excluded, primary!));
+  const excluded: number[] = [];
+  for (let attempt = PORT_BANDS.test.start; attempt <= PORT_BANDS.test.end; attempt++) {
+    let claimed: CoordinatorPortLease | null;
+    try { claimed = await request(excluded); }
+    catch (err) {
+      debug.log('nexus.port-lease', 'coordinator-fallback', { reason: 'coordinator-error', error: err instanceof Error ? err.message : String(err) });
+      return null;
     }
-    return {
-      port,
-      reason:
-        port === DEFAULT_NEXUS_PORT
-          ? 'default :31415 free'
-          : productionAlive
-            ? `:31415 taken by production daemon (pid ${prodLock!.pid}) → fallback`
-            : 'collision · auto-pick',
-    };
+    if (claimed === null) {
+      debug.log('nexus.port-lease', 'coordinator-fallback', { reason: 'coordinator-unavailable-or-no-port' });
+      return null;
+    }
+    const { port, leaseId } = claimed;
+    if (!Number.isInteger(port) || port < PORT_BANDS.test.start || port > PORT_BANDS.test.end
+        || (PORT_BANDS.reserved as readonly number[]).includes(port) || excluded.includes(port)
+        || typeof leaseId !== 'string' || !leaseId) {
+      debug.log('nexus.port-lease', 'coordinator-fallback', { reason: 'invalid-lease', port });
+      return null;
+    }
+    let occupied: boolean;
+    try { occupied = await inUseFn(port); }
+    catch (err) {
+      await releaseCentral(opts, claimed, primary);
+      throw err;
+    }
+    if (!occupied) return { port, reason: 'coordinator lease', leaseId, ...(primary ? { primary } : {}) };
+    await releaseCentral(opts, claimed, primary);
+    excluded.push(port);
   }
-  return { error: `no free port in [${candidates.join(', ')}]` };
+  debug.log('nexus.port-lease', 'coordinator-fallback', { reason: 'coordinator-band-exhausted' });
+  return null;
 }
 
-function pickDevPort(opts: PwaTestOpts): number | { error: string } {
+async function pickDevPort(opts: PwaTestOpts): Promise<number | { error: string }> {
   const inUseFn = opts.portInUseFn ?? defaultPortInUse;
   const candidates = [DEFAULT_DEV_PORT, ...DEV_FALLBACK_RANGE];
   for (const port of candidates) {
-    if (!inUseFn(port)) return port;
+    if (!await inUseFn(port)) return port;
   }
   return { error: `no free Next dev port in [${candidates.join(', ')}]` };
 }
@@ -436,18 +490,37 @@ async function runStart(
     }
   }
 
-  const nexusPick = pickNexusPort(opts.port, layout, opts);
+  let nexusPick: Awaited<ReturnType<typeof pickNexusPort>>;
+  try { nexusPick = await pickNexusPort(opts.port, layout, opts); }
+  catch (err) {
+    out.error(`✗ coordinator port lease failed: ${err instanceof Error ? err.message : String(err)}`);
+    return { exitCode: 1 };
+  }
   if ('error' in nexusPick) {
     out.error(`✗ ${nexusPick.error}`);
     return { exitCode: 1 };
   }
   const nexusPort = nexusPick.port;
+  const coordinatorPrimary = 'primary' in nexusPick ? nexusPick.primary : undefined;
+  const coordinatorToken = coordinatorPrimary?.token;
+  const releasePickedLease = async (): Promise<void> => {
+    if (nexusPick.reason === 'coordinator lease') {
+      if (opts.releasePortFn) await opts.releasePortFn(nexusPort);
+      else if (nexusPick.leaseId) await releaseCoordinatorPort({ port: nexusPort, leaseId: nexusPick.leaseId }, coordinatorPrimary);
+    }
+  };
 
   let devPort: number | undefined;
   if (isHmr) {
-    const devPick = pickDevPort(opts);
+    let devPick: Awaited<ReturnType<typeof pickDevPort>>;
+    try { devPick = await pickDevPort(opts); }
+    catch (error) {
+      await releasePickedLease();
+      throw error;
+    }
     if (typeof devPick !== 'number') {
       out.error(`✗ ${devPick.error}`);
+      await releasePickedLease();
       return { exitCode: 1 };
     }
     devPort = devPick;
@@ -477,6 +550,7 @@ async function runStart(
     }
   } catch (e) {
     out.error(`✗ config 격리 실패: ${e instanceof Error ? e.message : String(e)} — 운영 오염 위험이라 기동 중단`);
+    await releasePickedLease();
     return { exitCode: 1 };
   }
 
@@ -494,6 +568,7 @@ async function runStart(
     mode,
     httpHost,
     httpPort: nexusPort,
+    ...(nexusPick.reason === 'coordinator lease' ? { coordinatorLeasePort: nexusPort, ...(coordinatorToken ? { coordinatorLeaseToken: coordinatorToken } : {}), ...(nexusPick.leaseId ? { coordinatorLeaseId: nexusPick.leaseId } : {}) } : {}),
     out,
     ...(opts.force ? { force: true } : {}),
     ...(opts.toolCwd !== undefined ? { toolCwd: opts.toolCwd } : {}),
@@ -512,8 +587,16 @@ async function runStart(
     // tailscale-serve.ts (TLS-tcp mode · WS-friendly).
     readShareSwitchFn: () => 'disabled',
   };
-  const startRes = await pwaStartFn(startOpts);
-  if (startRes.exitCode !== 0) return { exitCode: startRes.exitCode };
+  let startRes: PwaStartResult;
+  try { startRes = await pwaStartFn(startOpts); }
+  catch (err) {
+    await releasePickedLease();
+    throw err;
+  }
+  if (startRes.exitCode !== 0) {
+    await releasePickedLease();
+    return { exitCode: startRes.exitCode };
+  }
 
   let url: string | undefined;
   let tailscaleMounted = false;
@@ -674,11 +757,33 @@ function runStatus(
     if (parsed.url) out.log(`  url       ${parsed.url}`);
     out.log(`  started   ${parsed.startedAt ?? '(unknown)'}`);
 
+    // The daemon writes under nexus/ after setTestStateRoot(stateDir); also read
+    // the project-root sidecar when that daemon path does not exist.
+    const daemonRuntimePath = joinPath(layout.stateDir, 'nexus', 'runtime.json');
+    const runtime = readNexusRuntimeAt(existsSync(daemonRuntimePath) ? daemonRuntimePath : layout.runtimePath);
+    const pid = runtime?.pid;
+    const alive = pid !== undefined && isPidAlive(pid);
+    debug.log('nexus.test-status', 'liveness', { pid, alive });
+    out.log(pid === undefined ? '  alive     unknown — runtime.json 에 pid 없음'
+      : alive ? `  alive     yes (pid ${pid})` : `  alive     NO — pid ${pid} 없음`);
+
     const tsState = readMountedState(layout.tailscaleStatePath);
     if (tsState && tsState.mode.kind === 'tls-tcp') {
       out.log(`  tailscale port=${tsState.mode.port} hostname=${tsState.hostname ?? '?'}`);
     }
-    return { exitCode: 0 };
+    if (!alive) {
+      // bg-launch names its detached logs nexus-<Date.now()>.log in this test root.
+      const logsDir = joinPath(layout.stateDir, 'nexus', 'logs');
+      try {
+        const logName = readdirSync(logsDir).filter(name => /^nexus-\d+\.log$/.test(name)).sort().at(-1);
+        if (logName) {
+          const lastLine = lastMeaningfulLogLine(joinPath(logsDir, logName));
+          if (lastLine) out.log(`  last log  ${lastLine}`);
+        }
+      } catch { /* log is optional when the daemon died before creating it */ }
+      out.log('  fix       elanous nexus run --test --stop 으로 기록을 치운 뒤 다시 띄운다');
+    }
+    return { exitCode: alive ? 0 : 1 };
   } catch (err) {
     out.error(`elanous nexus run --test --status: state file unreadable — ${(err as Error).message}`);
     return { exitCode: 1 };

package/src/cli/release-cli.ts

@@ -2,6 +2,7 @@
 //
 //   elanous release prepare --version <x.y.z[-rc.N]> [--source <ref>] [--out <dir>] [--notes-from <ref>] [--skip-e2e]
 //   elanous release publish --dir <prepare 산출> --notes-file <본문> [--yes]
+//   elanous release tag --version <x.y.z> --source <commit> [--yes]
 //   elanous release verify  [--version <x.y.z>]
 //   elanous release notes   --from <ref> [--to <ref>]
 //
@@ -12,11 +13,13 @@
 // ⛔ 공개본은 «원본 매니페스트»(`release/public-export.yaml`)대로만 만든다 — 매매 실행 코드는 그 매니페스트가 이미 뺀다(🅢 #20529).
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import type { Command } from 'commander';
 import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { envLiteral } from '../platform/env-literal.js';
 
 export const DEFAULT_PUBLIC_REPO = 'ElanvitalAI/elanous';
 const SEMVER = /^\d+\.\d+\.\d+(?:-(?:rc|alpha|beta)\.\d+)?$/;
@@ -207,7 +210,54 @@ export function readManifest(dir: string): ReleaseManifest {
   return JSON.parse(readFileSync(join(resolve(dir), 'release.json'), 'utf8')) as ReleaseManifest;
 }
 
-export async function publishRelease(opts: { dir: string; notesFile: string; yes?: boolean; log?: (l: string) => void }, run: Runner = defaultRunner): Promise<{ published: boolean; steps: PublishStep[] }> {
+const COMMIT_SHA = /^[0-9a-f]{40}$/i;
+
+export interface TagOptions { version: string; source: string; yes?: boolean; repoRoot?: string; log?: (line: string) => void }
+
+/** 로컬과 origin 의 태그를 모두 대조한다. 주석 태그는 반드시 peel 해서 원본 커밋을 비교한다. */
+function checkSourceTag(version: string, source: string, repoRoot: string, run: Runner): { tag: string; commit: string; local: boolean; remote: boolean } {
+  if (!isReleaseVersion(version)) throw new Error(`버전 모양이 아니다: ${version}`);
+  if (!COMMIT_SHA.test(source)) throw new Error(`원본 커밋 SHA가 아니다: ${source}`);
+  const tag = `v${version}`;
+  const commit = must(run('git', ['rev-parse', '--verify', `${source}^{commit}`], repoRoot), '원본 커밋 확인');
+  if (commit !== source.toLowerCase()) throw new Error(`원본 커밋 불일치: ${source} ≠ ${commit}`);
+  const localRef = `refs/tags/${tag}`;
+  // `--quiet` 없이 없는 ref 를 물으면 git 은 1 이 아니라 128 을 낸다(📏 2026-09-27 · 0.2.2 소급 태깅이 여기서 멈췄다).
+  const local = run('git', ['show-ref', '--verify', '--quiet', localRef], repoRoot);
+  if (local.status !== 0 && local.status !== 1) must(local, `로컬 태그 ${tag} 조회`);
+  if (local.status === 0) {
+    const target = must(run('git', ['rev-parse', '--verify', `${localRef}^{commit}`], repoRoot), `로컬 태그 ${tag} 확인`);
+    if (target !== commit) throw new Error(`태그 충돌: ${tag} 로컬 ${target} ≠ 원본 ${commit} — 덮지 않는다`);
+  }
+  const remote = must(run('git', ['ls-remote', '--tags', 'origin', localRef, `${localRef}^{}`], repoRoot), `origin 태그 ${tag} 조회`);
+  const refs = new Map(remote.split('\n').filter(Boolean).map((line) => {
+    const [hash, ref] = line.split(/\s+/);
+    return [ref, hash];
+  }));
+  const target = refs.get(`${localRef}^{}`) ?? refs.get(localRef);
+  if (target && target !== commit) throw new Error(`태그 충돌: ${tag} origin ${target} ≠ 원본 ${commit} — 덮지 않는다`);
+  return { tag, commit, local: local.status === 0, remote: Boolean(target) };
+}
+
+function applySourceTag(version: string, source: string, repoRoot: string, run: Runner): void {
+  const state = checkSourceTag(version, source, repoRoot, run);
+  if (!state.local) must(run('git', ['tag', '-a', state.tag, state.commit, '-m', `elanous ${state.tag}`], repoRoot), `내부 태그 ${state.tag} 생성`);
+  if (!state.remote) must(run('git', ['push', 'origin', `refs/tags/${state.tag}:refs/tags/${state.tag}`], repoRoot), `내부 태그 ${state.tag} push`);
+  debug.log('release.publish', 'tagged', { version, commit: state.commit });
+}
+
+/** 이미 발행한 판의 내부 기준점을 소급 태깅한다. --yes 없으면 저장소를 읽거나 쓰지 않는다. */
+export async function tagRelease(opts: TagOptions, run: Runner = defaultRunner): Promise<{ tagged: boolean }> {
+  const log = opts.log ?? ((line: string) => console.log(line));
+  if (!isReleaseVersion(opts.version)) throw new Error(`버전 모양이 아니다: ${opts.version}`);
+  if (!COMMIT_SHA.test(opts.source)) throw new Error(`원본 커밋 SHA가 아니다: ${opts.source}`);
+  log(`${opts.yes ? '▶' : '·'} 내부 태그 v${opts.version} → ${opts.source} (origin push${opts.yes ? '' : ' 예정'})`);
+  if (!opts.yes) return { tagged: false };
+  applySourceTag(opts.version, opts.source, resolve(opts.repoRoot ?? join(import.meta.dir, '..', '..')), run);
+  return { tagged: true };
+}
+
+export async function publishRelease(opts: { dir: string; notesFile: string; yes?: boolean; repoRoot?: string; instanceRoot?: string; log?: (l: string) => void }, run: Runner = defaultRunner): Promise<{ published: boolean; steps: PublishStep[] }> {
   const log = opts.log ?? ((l: string) => console.log(l));
   const m = readManifest(opts.dir);
   if (!existsSync(opts.notesFile)) throw new Error(`릴리스 본문 파일이 없다: ${opts.notesFile} (초안: ${m.notesDraft ?? 'release notes --from <ref>'})`);
@@ -219,7 +269,15 @@ export async function publishRelease(opts: { dir: string; notesFile: string; yes
   const steps = planPublish(m, resolve(opts.notesFile));
   for (const s of steps) log(`${opts.yes ? '▶' : '·'} ${s.what}\n    ${s.command} ${s.args.join(' ')}`);
   if (!opts.yes) { log('⛔ 보기만 했다 — 공개는 되돌릴 수 없다. 실행하려면 --yes'); return { published: false, steps }; }
+  const repoRoot = resolve(opts.repoRoot ?? join(import.meta.dir, '..', '..'));
+  checkSourceTag(m.version, m.sourceCommit, repoRoot, run);
   for (const s of steps) must(run(s.command, s.args, s.cwd), s.what);
+  applySourceTag(m.version, m.sourceCommit, repoRoot, run);
+  const recordDir = join(opts.instanceRoot ?? effectiveInstanceRoot(), 'release', m.version);
+  mkdirSync(recordDir, { recursive: true });
+  const record = join(recordDir, 'release.json');
+  writeFileSync(record, `${JSON.stringify({ ...m, publishedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(record, 0o600);
   log(`✅ 공개: https://github.com/${m.publicRepo}/releases/tag/${m.tag} — 이어서 \`elanous release verify --version ${m.version}\``);
   return { published: true, steps };
 }
@@ -317,7 +375,23 @@ export function stateRoundTrip(elanous: string, home: string, env: NodeJS.Proces
   return { memory, logs: /"registeredStores":0\b/.test(`${read.stdout}${read.stderr}`) ? 'no-store' : 'fail' };
 }
 
-export async function verifyRelease(opts: { version?: string; publicRepo?: string; log?: (l: string) => void }, run: Runner = defaultRunner): Promise<{ ok: boolean; versionLine: string; installerUrl: string; steps?: { install: number | null; selfUpdate: number | null; uninstall: number | null }; state?: { memory: boolean; logs: LogRoundTrip } }> {
+/** 공개 판의 노트가 문서 사이트에 있나 — 🅕 제보(09-27): 0.2.2 노트가 GitHub 릴리스에만 있고 docs 에 없었다(#21137 이 뒤에 옮김).
+ *  `publish` 는 아무 경로의 본문 파일을 받으므로 원본(`release/public/내부 문서 `<판>``)·사이트 배포를 빼먹어도 모른다 ⇒ verify 가 사이트를 잰다.
+ *  정식 판만(`-rc.N` 같은 선행 판은 노트 페이지를 두지 않는다). */
+export const DOCS_SITE = 'https://docs.elanous.ai';
+export function releaseNotesPageUrl(version: string): string | null {
+  if (version.includes('-')) return null;
+  return `${DOCS_SITE}/releases/${version.replace(/\./g, '-')}/`;
+}
+export type NotesPage = 'ok' | 'missing' | 'not-required';
+export function checkReleaseNotesPage(version: string | undefined, run: Runner, cwd: string): { notesPage: NotesPage; url: string | null } {
+  const url = version ? releaseNotesPageUrl(version) : null;
+  if (!url) return { notesPage: 'not-required', url };
+  const r = run('curl', ['-sL', '-o', '/dev/null', '-w', '%{http_code}', url], cwd);
+  return { notesPage: r.status === 0 && r.stdout.trim() === '200' ? 'ok' : 'missing', url };
+}
+
+export async function verifyRelease(opts: { version?: string; publicRepo?: string; log?: (l: string) => void }, run: Runner = defaultRunner): Promise<{ ok: boolean; versionLine: string; installerUrl: string; steps?: { install: number | null; selfUpdate: number | null; uninstall: number | null }; state?: { memory: boolean; logs: LogRoundTrip }; notesPage?: NotesPage }> {
   const log = opts.log ?? ((l: string) => console.log(l));
   if (opts.version !== undefined && !isReleaseVersion(opts.version)) throw new Error(`버전 모양이 아니다: ${opts.version}`);
   const repo = opts.publicRepo ?? DEFAULT_PUBLIC_REPO;
@@ -330,7 +404,7 @@ export async function verifyRelease(opts: { version?: string; publicRepo?: strin
     mkdirSync(home);
     // 검증은 «빈 HOME» 에서만 쓴다 — 물려받은 ELANOUS_*(STATE_DIR 등)·XDG_* 가 있으면 상태 왕복이 운영 저장소에 쓴다.
     const inherited = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('ELANOUS_') && !key.startsWith('XDG_')));
-    const env: NodeJS.ProcessEnv = { ...inherited, HOME: home, ELANOUS_INSTALL_PREFIX: prefix, ELANOUS_INSTALL_SOURCE: '', ELANOUS_VERSION: opts.version ?? '', SHELL: '/bin/zsh' };
+    const env = envLiteral({ ...inherited, HOME: home, ELANOUS_INSTALL_PREFIX: prefix, ELANOUS_INSTALL_SOURCE: '', ELANOUS_VERSION: opts.version ?? '', SHELL: '/bin/zsh' });
     const script = must(run('curl', ['-fsSL', installerUrl], home), `설치기 받기 ${installerUrl}`);
     const install = run('bash', ['-s', '--', '--no-modify-path'], home, { env, input: script });
     const versionLine = run(join(prefix, 'bin', 'elanous'), ['--version'], home, { env }).stdout.trim();
@@ -339,9 +413,10 @@ export async function verifyRelease(opts: { version?: string; publicRepo?: strin
     const uninstall = existsSync(join(prefix, 'current', 'node_modules', 'elanous', 'scripts', 'uninstall.sh'))
       ? run('bash', [join(prefix, 'current', 'node_modules', 'elanous', 'scripts', 'uninstall.sh')], home, { env })
       : { status: null, stdout: '', stderr: 'uninstall.sh 없음' };
-    const ok = install.status === 0 && (opts.version ? versionLine.startsWith(`${opts.version} `) : versionLine.length > 0) && update.status === 0 && state.memory && state.logs !== 'fail';
-    log(`${ok ? '✅' : '⛔'} ${installerUrl}\n  설치 rc=${install.status} · --version «${versionLine}» · 기억 왕복 ${state.memory ? 'ok' : 'FAIL'} · 로그 왕복 ${state.logs === 'ok' ? 'ok' : state.logs === 'fail' ? 'FAIL' : '안 잼(스토어 없음 — 데몬이 한 번 떠야 생긴다)'} · self-update rc=${update.status} · 제거 rc=${uninstall.status}`);
-    return { ok, versionLine, installerUrl, steps: { install: install.status, selfUpdate: update.status, uninstall: uninstall.status }, state };
+    const notes = checkReleaseNotesPage(opts.version, run, home);
+    const ok = install.status === 0 && (opts.version ? versionLine.startsWith(`${opts.version} `) : versionLine.length > 0) && update.status === 0 && state.memory && state.logs !== 'fail' && notes.notesPage !== 'missing';
+    log(`${ok ? '✅' : '⛔'} ${installerUrl}\n  설치 rc=${install.status} · --version «${versionLine}» · 기억 왕복 ${state.memory ? 'ok' : 'FAIL'} · 로그 왕복 ${state.logs === 'ok' ? 'ok' : state.logs === 'fail' ? 'FAIL' : '안 잼(스토어 없음 — 데몬이 한 번 떠야 생긴다)'} · self-update rc=${update.status} · 제거 rc=${uninstall.status} · 노트 페이지 ${notes.notesPage === 'ok' ? 'ok' : notes.notesPage === 'missing' ? `없음 — release/public/docs/releases/${opts.version}.md ⊕ website/pages.json ⊕ \`bun website/scripts/deploy-pages.ts\` (${notes.url})` : '해당 없음'}`);
+    return { ok, versionLine, installerUrl, steps: { install: install.status, selfUpdate: update.status, uninstall: uninstall.status }, state, notesPage: notes.notesPage };
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
@@ -398,6 +473,14 @@ export function registerReleaseCommands(program: Command): void {
         return { ...r, tag: m.tag, publicRepo: m.publicRepo, publicCommit: m.publicCommit, assets: [...new Set([...m.files.map((f) => f.name), 'SHA256SUMS'])].map((name) => join(m.distDir, name)) };
       }, () => true);
     });
+  release.command('tag')
+    .description('이미 발행된 판의 내부 원본 커밋에 주석 태그를 달고 origin 에 push. --yes 없으면 계획만')
+    .requiredOption('--version <x.y.z>', '이미 발행된 판')
+    .requiredOption('--source <commit>', '내부 원본 커밋 SHA')
+    .option('--yes', '태그를 실제로 만든다')
+    .action(async (o: { version: string; source: string; yes?: boolean }) => {
+      await jsonAction(undefined, (log) => tagRelease({ ...o, log }), () => true);
+    });
   release.command('verify')
     .description('공개 주소로 끝까지 — 깨끗한 임시 홈에서 설치 → --version → self-update → 제거')
     .option('--version <x.y.z>', '고정 버전(없으면 latest)')

package/src/cli/remotes-cli.ts

@@ -5,6 +5,8 @@
 // tested without re-running the CLI via Bun.spawn.
 
 import { existsSync, readFileSync } from 'node:fs';
+import { defaultAcpTokenPath } from '../nexus/api/connect-info.js';
+import { DEFAULT_NEXUS_HTTP_PORT } from '../nexus/default-port.js';
 import {
   RemotesStore,
   deriveNameFromHost,
@@ -12,6 +14,9 @@ import {
   type RemoteEntry,
 } from './remotes.js';
 
+/** 이 기계를 가리키는 주소 — 토큰 파일을 직접 읽어도 되는 경우(같은 uid). */
+const LOOPBACK_BOOTSTRAP_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+
 export interface ConnectRemoteOpts {
   host: string;
   name?: string;
@@ -24,6 +29,8 @@ export interface ConnectRemoteOpts {
   ping?: boolean;
   /** Test seam — fetch override. */
   fetchImpl?: typeof fetch;
+  /** Test seam — same-host token file (default `~/.elanous/acp-token`). */
+  localTokenPath?: string;
   /** Test seam — store override (alternate paths). */
   store?: RemotesStore;
   /** Stdout sink (test). */
@@ -45,7 +52,7 @@ export async function connectRemote(opts: ConnectRemoteOpts): Promise<number> {
   const store = opts.store ?? new RemotesStore();
   let parsed: ReturnType<typeof normalizeHost>;
   try {
-    parsed = normalizeHost(opts.host, opts.port ?? 31415);
+    parsed = normalizeHost(opts.host, opts.port ?? DEFAULT_NEXUS_HTTP_PORT);
   } catch (err) {
     out.error(`elanous nexus connect: ${(err as Error).message}`);
     return 1;
@@ -95,9 +102,21 @@ export async function connectRemote(opts: ConnectRemoteOpts): Promise<number> {
     token = readFileSync(opts.tokenFile, 'utf-8').trim();
   }
   if (!token && autoToken) {
+    // 옛 서버(원문을 싣던 판)와의 호환 — 새 서버는 늘 null 이다.
     token = autoToken;
     out.log(`auto_token loaded from ${parsed.host} (loopback bootstrap).`);
   }
+  if (!token && LOOPBACK_BOOTSTRAP_HOSTS.has(parsed.host)) {
+    // 🔐 같은 기계 · 같은 uid — 서버에게 원문을 받지 않고 토큰 파일을 직접 읽는다.
+    const localTokenPath = opts.localTokenPath ?? defaultAcpTokenPath();
+    if (existsSync(localTokenPath)) {
+      const local = readFileSync(localTokenPath, 'utf-8').trim();
+      if (local) {
+        token = local;
+        out.log(`token loaded from ${localTokenPath} (same-host bootstrap).`);
+      }
+    }
+  }
   if (!token) {
     out.error(
       'token required. Pass --token <value> or --token-file <path>. ' +

package/src/cli/remotes.ts

@@ -18,6 +18,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, chmodSync, unlinkSync } from 'node:fs';
 import { join as joinPath, dirname } from 'node:path';
 import { getElanousConfigDir } from '../elanous-config-dir.js';
+import { DEFAULT_NEXUS_HTTP_PORT } from '../nexus/default-port.js';
 
 export const REMOTES_FILE_VERSION = 1;
 
@@ -212,7 +213,7 @@ export function deriveNameFromHost(host: string): string {
 
 /** Parse a host/URL spec the user passed: `mbp.tailnet`, `mbp.tailnet:31415`,
  *  or `http://mbp.tailnet:31415`. Returns base URL (no trailing slash). */
-export function normalizeHost(spec: string, defaultPort = 31415): { url: string; host: string; port: number } {
+export function normalizeHost(spec: string, defaultPort = DEFAULT_NEXUS_HTTP_PORT): { url: string; host: string; port: number } {
   let raw = spec.trim();
   if (raw.length === 0) throw new Error('host required');
   if (!/^https?:\/\//.test(raw)) raw = `http://${raw}`;