borgmcp 5.3.0 → 5.4.0

package/src/agent-runtime.ts

@@ -6,11 +6,13 @@
  */
 
 import { BORG_STATE_ROOT_ENV } from './private-root.js';
+import { randomBytes } from 'node:crypto';
 
 export type AgentKind = 'claude' | 'codex' | 'opencode';
 
 /** Pinned into MCP-child environments by Borg launch paths. */
 export const BORG_AGENT_KIND_ENV = 'BORG_AGENT_KIND';
+export const BORG_CLAUDE_LAUNCH_CORRELATION_ENV = 'BORG_CLAUDE_LAUNCH_CORRELATION';
 /** Transport capability only — never use it as the primary CLI identity. */
 export const BORG_CODEX_REMOTE_WAKE_ENV = 'BORG_CODEX_REMOTE_WAKE';
 /** Legacy OpenCode runtime marker, retained for installed-config compatibility. */
@@ -52,7 +54,11 @@ export function withAgentRuntimeEnv(
   delete next[BORG_AGENT_KIND_ENV];
   delete next[BORG_CODEX_REMOTE_WAKE_ENV];
   delete next[BORG_OPENCODE_ENV];
+  delete next[BORG_CLAUDE_LAUNCH_CORRELATION_ENV];
   next[BORG_AGENT_KIND_ENV] = agentKind;
+  if (agentKind === 'claude') {
+    next[BORG_CLAUDE_LAUNCH_CORRELATION_ENV] = randomBytes(32).toString('base64url');
+  }
   if (agentKind === 'opencode') next[BORG_OPENCODE_ENV] = '1';
   return next;
 }

package/src/agent-session-identity.ts

@@ -0,0 +1,98 @@
+import { randomBytes } from 'node:crypto';
+import { readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { BORG_CLAUDE_LAUNCH_CORRELATION_ENV, resolveReportableSessionAgentKind } from './agent-runtime.js';
+import { findProjectRoot } from './cubes.js';
+import { ensurePrivateBorgConfigRoot } from './private-root.js';
+import { CodexAppServerClient } from './codex-app-server.js';
+import { codexAppServerSocketFromEnv, isCodexSubagentSource } from './codex-wake-resolve.js';
+import { resolveOpenCodeAgentSessionId } from './opencode-drone.js';
+
+export type AgentSessionIdentity =
+  | { kind: 'known'; id: string; source: string; observedAt: string }
+  | { kind: 'unknown'; reason: string };
+
+function validId(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && value.length <= 512 && !/[\s\x00-\x1f\x7f]/.test(value);
+}
+
+function claudeCorrelation(env: NodeJS.ProcessEnv): string | null {
+  const value = env[BORG_CLAUDE_LAUNCH_CORRELATION_ENV];
+  if (!value || !/^[A-Za-z0-9_-]{43}$/.test(value)) return null;
+  return Buffer.from(value, 'base64url').toString('base64url') === value ? value : null;
+}
+
+/** Identity only: no credential, authorization, liveness, or expiry semantics. */
+export async function recordClaudeSessionStart(
+  payload: string,
+  env: NodeJS.ProcessEnv = process.env,
+  worktree = findProjectRoot(),
+): Promise<void> {
+  const correlation = claudeCorrelation(env);
+  if (!correlation) return;
+  let sessionId: unknown;
+  try { sessionId = JSON.parse(payload)?.session_id; } catch { /* Persist unknown rather than retain an old id. */ }
+  const root = join(worktree, '.borgmcp');
+  await ensurePrivateBorgConfigRoot(root);
+  try { await writeFile(join(root, '.gitignore'), '*\n', { flag: 'wx', mode: 0o600 }); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; }
+  const path = join(root, 'claude-session.json');
+  const temporary = `${path}.${randomBytes(16).toString('hex')}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify({
+      correlation, session_id: validId(sessionId) ? sessionId : null,
+      observedAt: new Date().toISOString(),
+    }) + '\n', { flag: 'wx', mode: 0o600 });
+    await rename(temporary, path);
+  } finally {
+    await unlink(temporary).catch((error: NodeJS.ErrnoException) => { if (error.code !== 'ENOENT') throw error; });
+  }
+}
+
+export async function resolveAgentSessionIdentity(
+  env: NodeJS.ProcessEnv = process.env,
+  worktree = findProjectRoot(),
+): Promise<AgentSessionIdentity> {
+  const kind = resolveReportableSessionAgentKind(env);
+  try {
+    if (kind === 'claude') {
+      const correlation = claudeCorrelation(env);
+      if (!correlation) return { kind: 'unknown', reason: 'claude-launch-correlation-missing' };
+      const record = JSON.parse(await readFile(join(worktree, '.borgmcp', 'claude-session.json'), 'utf8'));
+      if (record?.correlation !== correlation) return { kind: 'unknown', reason: 'claude-launch-correlation-mismatch' };
+      if (!validId(record.session_id) || typeof record.observedAt !== 'string' || !Number.isFinite(Date.parse(record.observedAt))) {
+        return { kind: 'unknown', reason: 'claude-session-start-invalid' };
+      }
+      // Last observed hook, not proof of freshness: a skipped resume hook is
+      // undetectable without a future per-call harness session handoff.
+      return { kind: 'known', id: `claude:${record.session_id}`, source: 'claude-session-start', observedAt: record.observedAt };
+    }
+    if (kind === 'codex') {
+      const socket = codexAppServerSocketFromEnv(env);
+      if (!socket) return { kind: 'unknown', reason: 'codex-launch-socket-missing' };
+      const client = new CodexAppServerClient(socket);
+      try {
+        await client.connect();
+        const candidates: string[] = [];
+        for (const id of await client.loadedThreadIds()) {
+          const thread = await client.readThread(id);
+          // An unreadable candidate could be another user thread; do not guess.
+          if (!thread) return { kind: 'unknown', reason: 'codex-thread-unreadable' };
+          if (thread.ephemeral !== true && !isCodexSubagentSource(thread.source) &&
+              (thread.threadSource === undefined || thread.threadSource === 'user')) candidates.push(thread.id);
+        }
+        if (candidates.length !== 1 || !validId(candidates[0])) return { kind: 'unknown', reason: 'codex-user-thread-not-unique' };
+        return { kind: 'known', id: `codex:${candidates[0]}`, source: 'codex-launch-thread', observedAt: new Date().toISOString() };
+      } finally { client.close(); }
+    }
+    if (kind === 'opencode') {
+      const id = await resolveOpenCodeAgentSessionId();
+      return validId(id)
+        ? { kind: 'known', id: `opencode:${id}`, source: 'opencode-launch-binding', observedAt: new Date().toISOString() }
+        : { kind: 'unknown', reason: 'opencode-launch-binding-unavailable-or-changed' };
+    }
+    return { kind: 'unknown', reason: 'agent-harness-unknown' };
+  } catch {
+    return { kind: 'unknown', reason: `${kind ?? 'agent'}-session-source-unavailable` };
+  }
+}

package/src/index.ts

@@ -100,6 +100,7 @@ import {
   regenWakePathDroneLabel,
 } from './regen-format.js';
 import { startLogStream, getStreamStatus } from './log-stream.js';
+import { resolveAgentSessionIdentity } from './agent-session-identity.js';
 import { isMcpReadinessProbe } from './readiness-probe.js';
 import { runMcpStartupServices } from './startup-services.js';
 import { TOOL_MANIFEST, type ToolManifestEntry } from './tool-manifest.js';
@@ -913,8 +914,12 @@ export async function main() {
             cubeName: active?.name ?? null,
             humanAgo,
           });
+          const agentSession = await resolveAgentSessionIdentity();
+          const identityText = agentSession.kind === 'known'
+            ? `\n\nAgent session source: ${agentSession.source}\nSession id: ${JSON.stringify(agentSession.id)}\nIdentity age: ${Math.max(0, Date.now() - Date.parse(agentSession.observedAt))} ms (observed ${agentSession.observedAt})`
+            : `\n\nAgent session: unknown (${agentSession.reason}); ARRIVAL is not suppressed across reconnects.`;
           return {
-            content: [{ type: 'text', text: silentInertWarning + text }],
+            content: [{ type: 'text', text: silentInertWarning + text + identityText }],
             structuredContent: {
               status,
               wake_path: wakePath,
@@ -1076,16 +1081,16 @@ export async function main() {
           seedDisplayIdentity(active);
           const displayIdentity = renderDisplayIdentity(active);
           const lifecycleSignal = lifecycleSignalForMessage(finalMessage);
+          const agentSession = lifecycleSignal === 'arrival' ? await resolveAgentSessionIdentity() : undefined;
           if (lifecycleSignal) {
-            const decision = await shouldSuppressLifecycleLog(active, finalMessage);
+            const decision = await shouldSuppressLifecycleLog(active, finalMessage, agentSession);
             if (decision.suppress) {
-              await recordLifecycleLog(active, finalMessage);
               if (lifecycleSignal === 'arrival') markArrivalAnnouncedThisProcess();
               return {
                 content: [
                   {
                     type: 'text',
-                    text: `Suppressed duplicate ${decision.signal?.toUpperCase()} lifecycle log for ${displayIdentity.droneLabel}; recent cube log already contains this signal.`,
+                    text: `Suppressed duplicate ${decision.signal?.toUpperCase()} lifecycle log for ${displayIdentity.droneLabel}; this signal is already recorded locally for the current ${decision.signal === 'arrival' ? 'agent session' : 'idle period'}.`,
                   },
                 ],
                 structuredContent: {
@@ -1110,7 +1115,7 @@ export async function main() {
             serverTrustIdentity: active.serverTrustIdentity,
           };
           const result = await appendLog(active.sessionToken, active.apiUrl, finalMessage, appendOpts);
-          await recordLifecycleLog(active, finalMessage);
+          await recordLifecycleLog(active, finalMessage, agentSession);
           if (lifecycleSignal === 'arrival') markArrivalAnnouncedThisProcess();
           let recipientDrones: any[] = [];
           if (result.entry.visibility === 'direct' && result.entry.recipient_drone_ids.length > 0) {

package/src/lifecycle-log-guard.ts

@@ -1,9 +1,12 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { borgConfigRoot } from './private-root.js';
+import type { AgentSessionIdentity } from './agent-session-identity.js';
 
 const STATE_FILE = join(borgConfigRoot(), 'lifecycle-log-state.json');
-const ARRIVAL_DUPLICATE_WINDOW_MS = 10 * 60 * 1000;
+const STATE_LOCK = `${STATE_FILE}.lock`;
+const UNKNOWN_SESSION: AgentSessionIdentity = { kind: 'unknown', reason: 'identity-not-resolved' };
 
 export type LifecycleSignal = 'arrival' | 'ready';
 
@@ -13,10 +16,7 @@ export interface LifecycleLogSubject {
 }
 
 interface LifecycleStateEntry {
-  lastArrival?: {
-    message: string;
-    at: string;
-  };
+  arrivedSessionIds?: string[];
   idleReady?: {
     message: string;
     open: boolean;
@@ -74,27 +74,62 @@ async function readState(): Promise<LifecycleStateRead> {
 }
 
 async function writeState(state: LifecycleStateFile): Promise<void> {
-  await mkdir(dirname(STATE_FILE), { recursive: true });
-  await writeFile(STATE_FILE, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+  const temporary = `${STATE_FILE}.${randomBytes(16).toString('hex')}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify(state, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    await rename(temporary, STATE_FILE);
+  } finally {
+    await unlink(temporary).catch((error: NodeJS.ErrnoException) => { if (error.code !== 'ENOENT') throw error; });
+  }
+}
+
+// Same bounded exclusive-lock and stale-reclaim pattern as local-server-cursor.
+async function withLock<T>(operation: () => Promise<T>): Promise<T> {
+  await mkdir(dirname(STATE_LOCK), { recursive: true });
+  for (let attempt = 0; attempt < 200; attempt += 1) {
+    let handle;
+    try {
+      handle = await open(STATE_LOCK, 'wx', 0o600);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      try {
+        const metadata = await stat(STATE_LOCK);
+        if (Date.now() - metadata.mtimeMs > 30_000) {
+          await unlink(STATE_LOCK);
+          continue;
+        }
+      } catch (inspectionError) {
+        if ((inspectionError as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw inspectionError;
+      }
+      await new Promise((resolvePromise) => setTimeout(resolvePromise, 10));
+      continue;
+    }
+    try {
+      return await operation();
+    } finally {
+      await handle.close();
+      try {
+        await unlink(STATE_LOCK);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      }
+    }
+  }
+  throw new Error('Lifecycle log state is busy');
 }
 
 export function shouldSuppressLifecycleLogFromState(
   message: string,
   state: LifecycleStateEntry | undefined,
-  nowMs: number = Date.now()
+  identity: AgentSessionIdentity = UNKNOWN_SESSION
 ): { suppress: boolean; signal: LifecycleSignal | null } {
   const signal = lifecycleSignalForMessage(message);
   if (!signal) return { suppress: false, signal: null };
 
   if (signal === 'arrival') {
-    const lastArrivalAt = state?.lastArrival?.at
-      ? new Date(state.lastArrival.at).getTime()
-      : NaN;
-    const isRecent =
-      Number.isFinite(lastArrivalAt) &&
-      nowMs - lastArrivalAt < ARRIVAL_DUPLICATE_WINDOW_MS;
     return {
-      suppress: state?.lastArrival?.message === message && isRecent,
+      suppress: identity.kind === 'known' && state?.arrivedSessionIds?.includes(identity.id) === true,
       signal,
     };
   }
@@ -107,26 +142,32 @@ export function shouldSuppressLifecycleLogFromState(
 
 export async function shouldSuppressLifecycleLog(
   subject: LifecycleLogSubject,
-  message: string
+  message: string,
+  identity: AgentSessionIdentity = UNKNOWN_SESSION
 ): Promise<{ suppress: boolean; signal: LifecycleSignal | null }> {
   const state = await readState();
   if (state === UNREADABLE_STATE) throw unreadableStateError();
   return shouldSuppressLifecycleLogFromState(
     message,
-    state.entries[stateKey(subject)]
+    state.entries[stateKey(subject)],
+    identity
   );
 }
 
 export function nextLifecycleStateAfterLog(
   message: string,
   current: LifecycleStateEntry | undefined,
-  nowIso: string = new Date().toISOString()
+  nowIso: string = new Date().toISOString(),
+  identity: AgentSessionIdentity = UNKNOWN_SESSION
 ): LifecycleStateEntry {
   const signal = lifecycleSignalForMessage(message);
   if (signal === 'arrival') {
+    if (identity.kind === 'unknown' || current?.arrivedSessionIds?.includes(identity.id)) return current ?? {};
     return {
       ...current,
-      lastArrival: { message, at: nowIso },
+      // Retain one opaque id per announced session so resuming an older session
+      // also deduplicates. Pruning needs an explicit history-retention contract.
+      arrivedSessionIds: [...(current?.arrivedSessionIds ?? []), identity.id],
     };
   }
   if (signal === 'ready') {
@@ -146,11 +187,14 @@ export function nextLifecycleStateAfterLog(
 
 export async function recordLifecycleLog(
   subject: LifecycleLogSubject,
-  message: string
+  message: string,
+  identity: AgentSessionIdentity = UNKNOWN_SESSION
 ): Promise<void> {
-  const state = await readState();
-  if (state === UNREADABLE_STATE) throw unreadableStateError();
-  const key = stateKey(subject);
-  state.entries[key] = nextLifecycleStateAfterLog(message, state.entries[key]);
-  await writeState(state);
+  await withLock(async () => {
+    const state = await readState();
+    if (state === UNREADABLE_STATE) throw unreadableStateError();
+    const key = stateKey(subject);
+    state.entries[key] = nextLifecycleStateAfterLog(message, state.entries[key], undefined, identity);
+    await writeState(state);
+  });
 }

package/src/opencode-drone.ts

@@ -1568,6 +1568,20 @@ export function settleOpenCodeEntry(sourceEntryId: string): void {
   if (bindingChanged) persistCurrentBinding();
 }
 
+/** Read the launch-selected identity without changing the injection binding. */
+export async function resolveOpenCodeAgentSessionId(): Promise<string | null> {
+  const owner = state;
+  if (!owner?.connected) return null;
+  const binding = readBinding();
+  if (!binding) return null;
+  // The launch marker, unlike the injection binding, does not follow /new.
+  const launch = await findLaunchSession(owner.launchIdentity);
+  if (state !== owner || launch.kind !== 'found' || launch.session.id !== binding.sessionId ||
+      launch.knownRootSessionIds.some((id) => !binding.knownRootSessionIds.includes(id))) return null;
+  const current = readBinding();
+  return current?.sessionId === binding.sessionId ? binding.sessionId : null;
+}
+
 export async function probeOpenCodeDroneArmed(): Promise<boolean | null> {
   const owner = state;
   if (!owner?.connected) return null;

package/src/regen-format.ts

@@ -251,7 +251,7 @@ export function markArrivalAnnouncedThisProcess(): void {
 export function getDronePlaybook(handoverMode: HandoverMode = 'origin'): string {
   const arrivalInstruction = arrivalAnnouncedThisProcess
     ? ''
-    : `\n**Required one-time startup setup:** If this instruction is visible, immediately call \`borg_log message="ARRIVAL: <your-label> (<your-role>) online on ${osHostname()}" to="broadcast"\` before unread-log triage. This is the sole exception to no-work log silence. Do not infer your startup state from peers' \`ARRIVAL:\` entries. After the post succeeds, the client suppresses this instruction until the MCP process restarts; an explicit \`/mcp\` reconnect may show it again.\n`;
+    : `\n**Required one-time startup setup:** If this instruction is visible, immediately call \`borg_log message="ARRIVAL: <your-label> (<your-role>) online on ${osHostname()}" to="broadcast"\` before unread-log triage. This is the sole exception to no-work log silence. Do not infer your startup state from peers' \`ARRIVAL:\` entries. After the post succeeds, the client suppresses this instruction until the MCP process restarts; an explicit \`/mcp\` reconnect may show it again. The log call suppresses repeat ARRIVAL for a known agent session across reconnects; unknown identity announces. Claude identity can be stale after a resume whose SessionStart hook failed. Inspect \`borg_stream-status\` for the identity source and observation age.\n`;
   const reviewReadyRefs = handoverMode === 'local'
     ? '["HEAD"]'
     : '["HEAD","origin/<branch>","origin/main"]';

package/src/regen.ts

@@ -28,6 +28,7 @@ import {
 import { resolveSessionAgentKind } from './codex-app-wake.js';
 import { resolveReportableSessionAgentKind, type AgentKind } from './agent-runtime.js';
 import { handleVersionFlag } from './version.js';
+import { recordClaudeSessionStart } from './agent-session-identity.js';
 import {
   BORG_LAUNCH_REMINDER_DISABLED_ENV,
   BORG_SESSION_ENV,
@@ -61,7 +62,8 @@ async function readStdin(): Promise<string> {
 
 async function main(): Promise<void> {
   handleVersionFlag();
-  const hookSource = parseHookSource(await readStdin());
+  const hookPayload = await readStdin();
+  const hookSource = parseHookSource(hookPayload);
   // gh#673 P1 (WI-4): the SessionStart orientation only activates in
   // borg-launched sessions — a vanilla `claude` anywhere (including an
   // assimilated repo) stays vanilla. Exit-0 no-op: a hook must never
@@ -95,6 +97,10 @@ async function main(): Promise<void> {
   // session-scoped `/loop` + `ScheduleWakeup`, and the kickoff prompt is
   // gone, so the lean orientation adds a "re-establish your wake path" note.
   const source = hookSource;
+  if (resolveSessionAgentKind() === 'claude') {
+    try { await recordClaudeSessionStart(hookPayload); }
+    catch { process.stderr.write('Borg could not record the Claude SessionStart identity.\n'); }
+  }
 
   const active = await getActiveCube();
   if (!active) {