borgmcp 5.3.0 → 5.4.1

package/docs/SESSION_IDENTITY.md

@@ -0,0 +1,15 @@
+# Agent Session Identity
+
+ARRIVAL is announced once for each known agent session and cube/drone pair, using local lifecycle state. Changing the ARRIVAL wording or reconnecting the MCP transport does not create another announcement for that identity. A different session announces immediately, without a time window. Resuming an already announced session remains suppressed. This state does not affect credentials, authorization, stream ownership, or liveness.
+
+The startup instruction itself remains process-local: reconnecting may display it again. Calling `borg_log` with ARRIVAL applies the persistent identity check. Unknown identity always announces rather than concealing a possible restart. READY suppression is unchanged.
+
+## Harness Coverage
+
+- **Claude Code:** the latest SessionStart hook observed for this launch. Borg puts a random correlation in the launch environment. `borg-regen` stores that correlation, the hook's `session_id`, and its observation time in the worktree's `.borgmcp/claude-session.json`. A reconnect with the same correlation reads the same observation; a successful hook on resume replaces it. Missing, invalid, unreadable, or prior-launch state is unknown. Claude identity can be stale after a resume whose SessionStart hook failed.
+- **Codex:** exactly one non-ephemeral user thread, excluding subagents, in this launch's Borg-owned app-server. Zero or multiple candidates, an unreadable thread, or an unavailable socket is unknown. No recency guess identifies a session.
+- **OpenCode:** the existing launch-correlation binding, rechecked against session metadata. Missing or changed binding, an unseen root session, duplicated launch metadata, or failed inspection is unknown. The identity reader does not follow the wake injector's `/new` selection heuristic.
+
+`borg_stream-status` reports the identity source, the harness-prefixed session id, and the age of the observation in its text response. For Claude this age is measured from the hook, not the MCP child's start. Age is diagnostic only: there is no expiry heuristic. For Codex and OpenCode the observation is a fresh query. Unknown results report their reason.
+
+These identifiers denote harness conversations, not operating-system processes. Restarting a harness into a new conversation produces a new identity; explicitly resuming the same conversation retains its identity when ownership is known. Session identifiers are not secrets or authorization inputs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "5.3.0",
+  "version": "5.4.1",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",
@@ -72,7 +72,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
-    "borgmcp-shared": "2.1.0",
+    "borgmcp-shared": "2.2.0",
     "chalk": "^5.3.0",
     "prompts": "^2.4.2",
     "which": "^4.0.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) {