@phnx-labs/agents-cli 1.22.112 → 1.22.113

package/dist/lib/session/process-view.js

@@ -0,0 +1,176 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { getCacheDir, getTerminalsDir, getDaemonDir } from '../state.js';
+import { atomicWriteFileSync, withFileLock } from '../fs-atomic.js';
+// Linux UAPI PID_NS_INIT_INO (include/uapi/linux/nsfs.h; previously
+// PROC_PID_INIT_INO in include/linux/proc_ns.h). This is a kernel-defined
+// namespace identity, independent of PID 1's executable or command name.
+function isInitialPidNamespace(view) {
+    return view.pidNamespace === 'pid:[4026531836]';
+}
+function sameProcessView(owner, view) {
+    return owner.bootId === view.bootId && owner.pidNamespace === view.pidNamespace
+        && owner.initStartTicks === view.initStartTicks;
+}
+/** Authenticate the legacy singleton with kernel socket credentials. A host
+ * daemon invisible in a nested namespace has peer PID 0, never a colliding PID.
+ * No socket/PID/command-name guess grants migration authority. */
+function verifiedLegacyDaemon() {
+    try {
+        execFileSync('python3', ['-c', `import os,socket,struct,sys
+s=socket.socket(socket.AF_UNIX,socket.SOCK_STREAM)
+s.settimeout(0.2)
+s.connect(sys.argv[1])
+pid,uid,gid=struct.unpack('3i',s.getsockopt(socket.SOL_SOCKET,socket.SO_PEERCRED,12))
+assert pid>0 and uid==os.getuid()
+assert pid==int(open(sys.argv[2]).read().strip())
+assert os.readlink('/proc/%d/ns/pid'%pid)==os.readlink('/proc/self/ns/pid')
+`, path.join(getCacheDir(), 'helpers', 'browser', 'browser.sock'), path.join(getDaemonDir(), 'daemon.pid')], {
+            stdio: 'ignore', timeout: 1000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasLegacyState() {
+    return [path.join(getTerminalsDir(), 'by-pid'), path.join(getCacheDir(), 'state', 'sessions')]
+        .some(dir => fs.existsSync(dir) && fs.readdirSync(dir).length > 0)
+        // Health/log output records attempted starts, not ownership. The ordinary
+        // start path writes health.json BEFORE spawning its first daemon.
+        || ['daemon.pid', 'daemon.lifetime', 'heartbeat.json'].some(file => fs.existsSync(path.join(getDaemonDir(), file)))
+        || fs.existsSync(path.join(getCacheDir(), 'helpers', 'browser', 'browser.sock'))
+        || ['.active-sessions.json', '.active-session-immutable.json'].some(file => fs.existsSync(path.join(getCacheDir(), file)));
+}
+/** Measure the calling process, never infer authority from a process name. */
+export function currentProcessView() {
+    if (process.platform !== 'linux')
+        return {};
+    try {
+        if (Number(fs.readFileSync('/proc/self/stat', 'utf8').split(' ', 1)[0]) !== process.pid)
+            return undefined;
+        const bootId = fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+        const pidNamespace = fs.readlinkSync('/proc/self/ns/pid');
+        // NSpid is relative to the procfs mount. Multiple coordinates mean this
+        // mount exposes an ancestor namespace, even if numeric PIDs happen to match.
+        const procPids = fs.readFileSync('/proc/self/status', 'utf8').match(/^NSpid:\s+([^\n]+)$/m)?.[1].trim().split(/\s+/);
+        if (procPids?.length !== 1 || Number(procPids[0]) !== process.pid)
+            return undefined;
+        const initStat = fs.readFileSync('/proc/1/stat', 'utf8');
+        const initStartTicks = initStat.slice(initStat.lastIndexOf(')') + 2).split(' ')[19];
+        const stat = fs.readFileSync('/proc/self/stat', 'utf8');
+        const ownerStartTicks = stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
+        return bootId && pidNamespace && /^\d+$/.test(initStartTicks) && /^\d+$/.test(ownerStartTicks)
+            ? { bootId, pidNamespace, initStartTicks, ownerPid: process.pid, ownerStartTicks } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read-only ownership check. Observing a HOME never claims or migrates it. */
+export function hostProcessView() {
+    const view = currentProcessView();
+    if (!view || process.platform !== 'linux')
+        return view;
+    try {
+        const owner = JSON.parse(fs.readFileSync(path.join(getTerminalsDir(), 'process-view.json'), 'utf8'));
+        return sameProcessView(owner, view) ? view : undefined;
+    }
+    catch (error) {
+        // The initial kernel namespace is authoritative before any daemon has
+        // enrolled this HOME. This observation itself must remain read-only.
+        return error.code === 'ENOENT' && isInitialPidNamespace(view) ? view : undefined;
+    }
+}
+/** Explicit writers may enroll a fresh HOME in their measured namespace.
+ * Foreign ownership remains protected even when the prior writer is invisible.
+ * The initial host may enroll legacy state before daemon startup. */
+export function writerProcessView() {
+    const view = currentProcessView();
+    if (!view || process.platform !== 'linux')
+        return view;
+    const file = path.join(getTerminalsDir(), 'process-view.json');
+    try {
+        if (fs.existsSync(file)) {
+            const owner = JSON.parse(fs.readFileSync(file, 'utf8'));
+            return sameProcessView(owner, view) ? view : undefined;
+        }
+        // A foreign observer of legacy state must not even create a directory or
+        // claim lock. Repeat this preflight under the lock before enrollment.
+        if (hasLegacyState() && !isInitialPidNamespace(view))
+            return undefined;
+        fs.mkdirSync(getTerminalsDir(), { recursive: true });
+        return withFileLock(file, () => {
+            if (fs.existsSync(file)) {
+                const owner = JSON.parse(fs.readFileSync(file, 'utf8'));
+                return sameProcessView(owner, view) ? view : undefined;
+            }
+            // Unowned nonempty registry is not evidence this caller owns the host.
+            if (hasLegacyState() && !isInitialPidNamespace(view))
+                return undefined;
+            atomicWriteFileSync(file, JSON.stringify(view), 'utf8');
+            return view;
+        }, { realpath: false, acquireTimeoutMs: 0 });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Preflight BEFORE even the PID-keyed legacy lifecycle lock is inspected.
+ * The same decision is repeated under that lock before daemon state changes. */
+export function daemonProcessViewAllowed() {
+    const view = currentProcessView();
+    if (!view)
+        return false;
+    if (process.platform !== 'linux')
+        return true;
+    try {
+        const file = path.join(getTerminalsDir(), 'process-view.json');
+        if (!fs.existsSync(file))
+            return !hasLegacyState() || isInitialPidNamespace(view) || verifiedLegacyDaemon();
+        const owner = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (sameProcessView(owner, view))
+            return true;
+        return typeof owner.bootId === 'string' && !!owner.bootId && owner.bootId !== view.bootId
+            && (isInitialPidNamespace(view) || verifiedLegacyDaemon());
+    }
+    catch {
+        return false;
+    }
+}
+/** Called by the canonical daemon writer before lifecycle mutation.
+ * This is a writer statement, not an observer's guess about a numeric PID.
+ * Existing same-boot ownership cannot be taken over from another namespace. */
+export function recordDaemonProcessView() {
+    const view = currentProcessView();
+    if (!view)
+        throw new Error('Cannot record daemon ownership from an incoherent process namespace');
+    if (process.platform !== 'linux')
+        return;
+    const file = path.join(getTerminalsDir(), 'process-view.json');
+    fs.mkdirSync(getTerminalsDir(), { recursive: true });
+    withFileLock(file, () => {
+        if (fs.existsSync(file)) {
+            const owner = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (sameProcessView(owner, view))
+                return;
+            if (typeof owner.bootId !== 'string' || !owner.bootId || owner.bootId === view.bootId || (!isInitialPidNamespace(view) && !verifiedLegacyDaemon())) {
+                throw new Error('Another or unverified process namespace owns host session state; automatic reuse of a private-container HOME across namespaces is unsupported. Run in the owning namespace or use a fresh HOME.');
+            }
+        }
+        else if (hasLegacyState() && !isInitialPidNamespace(view) && !verifiedLegacyDaemon()) {
+            throw new Error('Legacy session state requires a verified live canonical daemon before namespace migration');
+        }
+        atomicWriteFileSync(file, JSON.stringify(view), 'utf8');
+    }, { realpath: false, acquireTimeoutMs: 0 });
+}
+export function requireHostProcessView() {
+    if (!hostProcessView())
+        throw new Error('Host session state is unavailable in this process namespace; read the host daemon snapshot or run sessions on the host.');
+}
+export function requireWriterProcessView() {
+    if (!writerProcessView())
+        throw new Error('Host session state is unavailable in this process namespace; run the writer in its owning namespace or use a fresh HOME. Automatic reuse of a private-container HOME across namespaces is unsupported.');
+}

package/dist/lib/session/projection.d.ts

@@ -0,0 +1,13 @@
+import type { SessionWatchEnvelope, SessionWatchRow } from './watch.js';
+/** Device observations are not sessions: a launcher may observe a peer's run.
+ * Keep those observations separately and publish execution-owned state once. */
+export declare class SessionProjection {
+    private readonly observations;
+    private projected;
+    private selected;
+    private sequence;
+    private readonly streamId;
+    /** Only the selected observation may publish execution-owned attention. */
+    rowForObservation(scope: string, rowKey: string): SessionWatchRow | undefined;
+    apply(event: SessionWatchEnvelope): SessionWatchEnvelope[];
+}

package/dist/lib/session/projection.js

@@ -0,0 +1,101 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { normalizeHost } from '../machine-id.js';
+/** Device observations are not sessions: a launcher may observe a peer's run.
+ * Keep those observations separately and publish execution-owned state once. */
+export class SessionProjection {
+    observations = new Map();
+    projected = new Map();
+    selected = new Map();
+    sequence = 0;
+    streamId = randomUUID();
+    /** Only the selected observation may publish execution-owned attention. */
+    rowForObservation(scope, rowKey) {
+        const key = this.selected.get(`${normalizeHost(scope)}\0${rowKey}`);
+        return key ? this.projected.get(key) : undefined;
+    }
+    apply(event) {
+        const scope = normalizeHost(event.scope);
+        if (event.type === 'reset')
+            this.observations.set(scope, new Map(event.rows.map(row => [row.rowKey, row])));
+        if (event.type === 'upsert') {
+            if (!this.observations.has(scope))
+                this.observations.set(scope, new Map());
+            this.observations.get(scope).set(event.rowKey, event.row);
+        }
+        if (event.type === 'remove')
+            this.observations.get(scope)?.delete(event.rowKey);
+        const stamp = () => ({ version: 1, streamId: this.streamId, sequence: ++this.sequence, capturedAt: event.capturedAt });
+        if (event.type === 'scope' || event.type === 'heartbeat') {
+            // An unavailable owner retains its last observation until its next reset.
+            return [{ ...event, ...stamp(), scope }];
+        }
+        // A launch exists before a non-Claude harness mints its session id. Join an
+        // id-less placeholder only through an exact, unambiguous durable launch id.
+        const launchSessions = new Map();
+        for (const [observer, rows] of this.observations)
+            for (const row of rows.values()) {
+                if (!row.launchId || !row.sessionId)
+                    continue;
+                const owner = normalizeHost(row.machine || row.sourceDevice || observer);
+                const launch = `${owner}\0${row.kind}\0${row.launchId}`;
+                const ids = launchSessions.get(launch) ?? new Set();
+                ids.add(row.sessionId);
+                launchSessions.set(launch, ids);
+            }
+        const groups = new Map();
+        for (const [observer, rows] of this.observations)
+            for (const row of rows.values()) {
+                const owner = normalizeHost(row.machine || row.sourceDevice || observer);
+                const launchIds = row.launchId ? launchSessions.get(`${owner}\0${row.kind}\0${row.launchId}`) : undefined;
+                const sessionId = row.sessionId || (launchIds?.size === 1 ? [...launchIds][0] : undefined);
+                const identity = sessionId ? `${row.kind}\0${sessionId}` : `${observer}\0${row.rowKey}`;
+                const key = createHash('sha256').update(`${owner}\0${identity}`).digest('base64url').slice(0, 22);
+                const group = groups.get(key) ?? [];
+                group.push({ scope: observer, row });
+                groups.set(key, group);
+            }
+        const next = new Map();
+        const selected = new Map();
+        for (const [rowKey, observations] of groups) {
+            const owner = normalizeHost(observations[0].row.machine || observations[0].row.sourceDevice || observations[0].scope);
+            const authoritative = observations.filter(item => item.scope === owner);
+            // Once the owner has answered, its absence is authoritative too. A stale
+            // launcher/history mirror cannot resurrect a removed execution.
+            const candidates = authoritative.length ? authoritative : this.observations.has(owner) ? [] : observations;
+            candidates.sort((a, b) => Number(a.row.previous) - Number(b.row.previous)
+                || (b.row.lastActivityMs ?? b.row.startedAtMs ?? 0) - (a.row.lastActivityMs ?? a.row.startedAtMs ?? 0)
+                || a.row.rowKey.localeCompare(b.row.rowKey));
+            const candidate = candidates[0];
+            const chosen = candidate?.row;
+            if (!chosen)
+                continue;
+            selected.set(`${candidate.scope}\0${chosen.rowKey}`, rowKey);
+            const observerTerminals = observations.filter(item => !item.row.previous && (item.row.terminalId || item.row.viewingIn || item.row.provenance?.reply))
+                .map(({ scope: device, row }) => ({ device, terminalId: row.terminalId, launchId: row.launchId, viewingIn: row.viewingIn, provenance: row.provenance }))
+                .sort((a, b) => a.device.localeCompare(b.device) || (a.terminalId ?? '').localeCompare(b.terminalId ?? ''));
+            next.set(rowKey, {
+                ...chosen, rowKey, sourceDevice: owner, machine: owner,
+                observerTerminals,
+                recovery: chosen.resumable && chosen.sessionId
+                    ? { command: 'agents', args: ['sessions', 'resume', chosen.sessionId, '--device', owner], ...(chosen.cwd ? { cwd: chosen.cwd } : {}) }
+                    : null,
+            });
+        }
+        const result = [];
+        // A reset still replaces only its source scope. Cross-scope migrations are
+        // explicit removes/upserts, so existing clients converge without a new API.
+        if (event.type === 'reset')
+            result.push({ ...stamp(), type: 'reset', scope, rows: [...next.values()].filter(row => row.sourceDevice === scope) });
+        for (const [key, row] of this.projected)
+            if (!next.has(key) && !(event.type === 'reset' && row.sourceDevice === scope)) {
+                result.push({ ...stamp(), type: 'remove', scope: row.sourceDevice, rowKey: key });
+            }
+        for (const [key, row] of next)
+            if (!(event.type === 'reset' && row.sourceDevice === scope) && JSON.stringify(this.projected.get(key)) !== JSON.stringify(row)) {
+                result.push({ ...stamp(), type: 'upsert', scope: row.sourceDevice, rowKey: key, row });
+            }
+        this.projected = next;
+        this.selected = selected;
+        return result;
+    }
+}

package/dist/lib/session/remote/watch.d.ts

@@ -49,6 +49,14 @@ export type SessionWatchEnvelope = {
 };
 export interface SessionWatchRow extends Omit<ActiveSession, 'viewingIn' | 'context'> {
     context: ActiveSession['context'] | 'recent';
+    /** Observer-local terminal/reply facts; never overwrite execution-owner state. */
+    observerTerminals?: {
+        device: string;
+        terminalId?: string;
+        launchId?: string;
+        viewingIn: string | null;
+        provenance?: ActiveSession['provenance'];
+    }[];
     /** Flat durable branch for history rows that are not currently in a worktree. */
     branch?: string;
     rowKey: string;

package/dist/lib/session/remote/watch.js

@@ -1,3 +1,4 @@
+import { SessionProjection } from '../projection.js';
 import { createHash, randomUUID } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -421,7 +422,10 @@ function remoteWatchCommand(os) {
  * peer resets only its own scope. There is no recurring fleet list command.
  */
 export async function watchFleetSessions(options) {
-    const local = watchLocalSessions({ scope: machineId(), signal: options.signal, emit: options.emit });
+    const projection = new SessionProjection();
+    const emit = (event) => { for (const projected of projection.apply(event))
+        options.emit(projected); };
+    const local = watchLocalSessions({ scope: machineId(), signal: options.signal, emit });
     let devices;
     try {
         devices = await loadDevices();
@@ -447,14 +451,14 @@ export async function watchFleetSessions(options) {
                     const event = JSON.parse(line);
                     if (event.version !== SESSION_WATCH_VERSION || typeof event.sequence !== 'number')
                         return false;
-                    options.emit(event);
+                    emit(event);
                     return true;
                 }
                 catch {
                     return false; /* incomplete/non-protocol peer output is not state */
                 }
             },
-            onUnavailable: (reason) => options.emit(state.scope(scope, 'unavailable', reason)),
+            onUnavailable: (reason) => emit(state.scope(scope, 'unavailable', reason)),
         });
     });
     await Promise.all([local, ...peerTasks]);

package/dist/lib/session/session-cache.js

@@ -24,6 +24,7 @@
  * through to a live gather.
  */
 import * as fs from 'fs';
+import { writerProcessView, requireWriterProcessView } from './process-view.js';
 import * as path from 'path';
 import { createMemoryCache } from '../memory-cache.js';
 import { getCacheDir } from '../state.js';
@@ -248,6 +249,7 @@ export function readActiveSessionsCache(scope) {
  * so a local warm never drops a fleet snapshot a reader just wrote.
  */
 export function writeActiveSessionsCache(scope, sessions, opts = {}) {
+    requireWriterProcessView();
     const snap = {
         version: 1,
         scope,
@@ -412,6 +414,7 @@ export function assertNoLiveStatusFields(fields) {
  * refill identity fields without re-deriving them.
  */
 export function updateImmutableMemos(sessions, nowMs = Date.now()) {
+    requireWriterProcessView();
     for (const s of sessions) {
         if (!s.sessionId)
             continue;
@@ -534,6 +537,12 @@ export async function loadLocalActiveSessions(opts = {}) {
     const maxAge = opts.maxAgeMs ?? DEFAULT_ACTIVE_CACHE_MAX_AGE_MS;
     const readCache = opts.readCache ?? readActiveSessionsCache;
     const writeCache = opts.writeCache ?? writeActiveSessionsCache;
+    if (!writerProcessView()) {
+        const cached = readCache('local');
+        if (cached)
+            return { sessions: cached.sessions, servedFromCache: true, capturedAt: cached.capturedAt };
+        requireWriterProcessView();
+    }
     if (!opts.forceRefresh) {
         const cached = readCache('local');
         if (cached && isActiveSnapshotFresh(cached.capturedAt, now, maxAge)) {
@@ -570,6 +579,12 @@ export async function loadFleetActiveSessions(opts) {
     const maxAge = opts.maxAgeMs ?? DEFAULT_ACTIVE_CACHE_MAX_AGE_MS;
     const readCache = opts.readCache ?? readActiveSessionsCache;
     const writeCache = opts.writeCache ?? writeActiveSessionsCache;
+    if (!writerProcessView()) {
+        const cached = readCache('fleet');
+        if (cached)
+            return { sessions: cached.sessions, remoteDeviceCount: cached.remoteDeviceCount ?? 0, servedFromCache: true, capturedAt: cached.capturedAt };
+        requireWriterProcessView();
+    }
     if (!opts.forceRefresh) {
         const cached = readCache('fleet');
         if (cached && isActiveSnapshotFresh(cached.capturedAt, now, maxAge)) {

package/dist/lib/session/testdata/pid-registry-namespace.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/session/testdata/pid-registry-namespace.js

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { prunePidSessionRegistry, readPidSessionEntry, writePidSessionEntry } from '../pid-registry.js';
+import { getActiveSessions } from '../active.js';
+import { loadLocalActiveSessions, loadFleetActiveSessions, writeActiveSessionsCache, updateImmutableMemos, readActiveSessionsCache } from '../session-cache.js';
+// Invoked only by the isolated-HOME test fork, inside a real unshare namespace.
+const hostPid = Number(process.argv[2]);
+// Names convey no authority: this is PID 1 with its own procfs in one variant.
+fs.writeFileSync('/proc/self/comm', 'init');
+assert.equal(readPidSessionEntry(hostPid)?.sessionId, 'host-session');
+assert.throws(() => process.kill(hostPid, 0), { code: 'ESRCH' });
+writePidSessionEntry({ pid: hostPid, agent: 'codex', sessionId: 'namespace-collision', startedAtMs: Date.now() });
+assert.equal(readPidSessionEntry(hostPid)?.sessionId, 'host-session');
+prunePidSessionRegistry(() => false);
+assert.equal(readPidSessionEntry(hostPid)?.sessionId, 'host-session');
+const local = await loadLocalActiveSessions({ forceRefresh: true, gather: async () => { throw new Error('partial gather must never run'); } });
+assert.equal(local.sessions[0].sessionId, 'host-session');
+assert.equal(local.capturedAt, 1);
+assert.equal(local.servedFromCache, true);
+const fleet = await loadFleetActiveSessions({ forceRefresh: true, gather: async () => { throw new Error('partial fleet gather must never run'); } });
+assert.equal(fleet.remoteDeviceCount, 2);
+assert.equal(fleet.capturedAt, 1);
+assert.equal((await getActiveSessions())[0].sessionId, 'host-session');
+assert.throws(() => writeActiveSessionsCache('local', []), /process namespace/);
+assert.throws(() => updateImmutableMemos([]), /process namespace/);
+assert.equal(readActiveSessionsCache('local')?.capturedAt, 1);
+console.log('host pid: ESRCH; overwrite: refused; registry and snapshots: retained');

package/dist/lib/session/testdata/process-view-namespace.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/session/testdata/process-view-namespace.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { getTerminalsDir } from '../../state.js';
+import { hostProcessView, requireWriterProcessView, recordDaemonProcessView } from '../process-view.js';
+const mode = process.argv[2];
+try {
+    if (mode === 'hook-first') {
+        const hook = process.env.AGENTS_SESSION_IDENTITY_TEST_HOOK;
+        const child = hook
+            ? spawnSync('bash', [hook], { input: JSON.stringify({ session_id: 'init-hook', cwd: process.cwd() }), encoding: 'utf8', env: process.env })
+            : spawnSync('bun', [import.meta.filename, 'once'], { encoding: 'utf8', env: process.env });
+        if (child.status !== 0)
+            throw new Error(child.stderr);
+        if (!fs.existsSync(`${getTerminalsDir()}/process-view.json`))
+            throw new Error('child did not enroll its namespace');
+    }
+    if (mode === 'daemon')
+        recordDaemonProcessView();
+    if (mode === 'read') {
+        console.log(hostProcessView() ? 'owned' : 'unowned');
+        process.exit(0);
+    }
+    if (mode === 'publish' || mode === 'snapshot') {
+        const { loadLocalActiveSessions, loadFleetActiveSessions, writeActiveSessionsCache } = await import('../session-cache.js');
+        if (mode === 'publish') {
+            writeActiveSessionsCache('local', [], { capturedAt: 1 });
+            writeActiveSessionsCache('fleet', [], { capturedAt: 1 });
+        }
+        else {
+            const gather = async () => { throw new Error('foreign observer gathered'); };
+            const local = await loadLocalActiveSessions({ forceRefresh: true, gather });
+            const fleet = await loadFleetActiveSessions({ forceRefresh: true, gather });
+            if (!local.servedFromCache || !fleet.servedFromCache || local.capturedAt !== 1 || fleet.capturedAt !== 1)
+                throw new Error('foreign snapshot changed');
+            console.log('observed');
+            process.exit(0);
+        }
+    }
+    if (mode === 'sessions') {
+        const { loadLocalActiveSessions } = await import('../session-cache.js');
+        const result = await loadLocalActiveSessions({ forceRefresh: true });
+        if (result.servedFromCache || !Array.isArray(result.sessions))
+            throw new Error('cold discovery did not run');
+    }
+    requireWriterProcessView();
+    console.log('owned');
+    if (mode === 'hold' || mode === 'hook-first') {
+        process.on('SIGTERM', () => process.exit(0));
+        setInterval(() => { }, 1000);
+    }
+}
+catch (error) {
+    console.error(error.message);
+    console.log('denied');
+    process.exitCode = 2;
+}

package/dist/lib/session/testdata/process-view-private.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/session/testdata/process-view-private.js

@@ -0,0 +1,12 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { writePidSessionEntry, readLivePidSessionEntry } from '../pid-registry.js';
+import { writeActiveSessionsCache, readActiveSessionsCache } from '../session-cache.js';
+// A container owns its private home regardless of the name of PID 1.
+assert.equal(process.pid, 1);
+fs.writeFileSync('/proc/self/comm', process.argv[2]);
+writePidSessionEntry({ pid: process.pid, agent: 'codex', sessionId: 'private-home', startedAtMs: Date.now() });
+assert.equal(readLivePidSessionEntry(process.pid)?.sessionId, 'private-home');
+writeActiveSessionsCache('local', [{ context: 'headless', kind: 'codex', sessionId: 'private-home', status: 'running' }]);
+assert.equal(readActiveSessionsCache('local')?.sessions[0]?.sessionId, 'private-home');
+console.log('private home: registry and snapshot published');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.112",
+  "version": "1.22.113",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",