pactive 0.0.0-stage → 0.0.2-alpha.1

package/src/core/paths.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { pactiveError } from './errors.mjs';
+
+export const DEFAULT_ROOT_DIRNAME = '.pactive';
+
+/**
+ * Resolve the state root and every file location derived from it.
+ * The root is shared by all hosts: peers, inboxes and outboxes are cross-host.
+ */
+export function resolvePaths(hostKind, env = process.env) {
+  const kind = typeof hostKind === 'string' ? hostKind.trim() : '';
+  if (!kind) throw pactiveError('HOST_KIND_REQUIRED', 'hostKind is required');
+
+  const source = env && typeof env.PACTIVE_STATE_DIR === 'string' ? env.PACTIVE_STATE_DIR.trim() : '';
+  const root = path.resolve(source || path.join(os.homedir(), DEFAULT_ROOT_DIRNAME));
+
+  let stat = null;
+  try {
+    stat = fs.statSync(root);
+  } catch {
+    stat = null;
+  }
+  if (stat) {
+    if (!stat.isDirectory()) {
+      throw pactiveError('STATE_ROOT_INVALID', `state root is not a directory: ${root}`);
+    }
+    try {
+      fs.accessSync(root, fs.constants.W_OK);
+    } catch {
+      throw pactiveError('STATE_ROOT_NOT_WRITABLE', `state root is not writable: ${root}`);
+    }
+  }
+
+  return {
+    root,
+    stateFile: path.join(root, 'state.json'),
+    tasksFile: path.join(root, 'tasks.json'),
+    peersDir: path.join(root, 'peers'),
+    inboxDir: path.join(root, 'inbox'),
+    outboxDir: path.join(root, 'outbox'),
+    ledgerFile: path.join(root, 'ledger.jsonl'),
+    locksDir: path.join(root, 'locks'),
+  };
+}

package/src/core/scheduler.mjs

@@ -0,0 +1,89 @@
+import { pactiveError } from './errors.mjs';
+
+export const TASK_KINDS = ['in', 'at', 'every'];
+
+let seq = 0;
+
+/**
+ * Task table: "in" (delay), "at" (absolute time) and "every" (repeating).
+ * Tasks live in the persisted state, so a restart recovers them.
+ */
+export const schedule = {
+  add(state, spec, now = Date.now()) {
+    if (!spec || typeof spec !== 'object') throw pactiveError('TASK_SPEC_REQUIRED', 'a task spec is required');
+    const ts = Number.isFinite(now) ? now : Date.now();
+    const kind = spec.kind ?? (Number.isFinite(spec.at) ? 'at' : 'in');
+    if (!TASK_KINDS.includes(kind)) {
+      throw pactiveError('TASK_KIND_UNKNOWN', `unknown task kind: ${kind}`);
+    }
+    if (!Array.isArray(state.tasks)) state.tasks = [];
+
+    let dueAt;
+    let everyMs = 0;
+    if (kind === 'at') {
+      if (!Number.isFinite(spec.at)) throw pactiveError('TASK_AT_REQUIRED', 'an "at" task needs spec.at');
+      dueAt = spec.at;
+    } else if (kind === 'every') {
+      everyMs = Number.isFinite(spec.everyMs) ? spec.everyMs : Number.isFinite(spec.intervalMs) ? spec.intervalMs : 0;
+      if (everyMs <= 0) throw pactiveError('TASK_INTERVAL_REQUIRED', 'an "every" task needs a positive interval');
+      dueAt = ts + everyMs;
+    } else {
+      const delay = Number.isFinite(spec.delayMs) ? spec.delayMs
+        : Number.isFinite(spec.afterMs) ? spec.afterMs
+          : Number.isFinite(spec.ms) ? spec.ms : 0;
+      dueAt = ts + delay;
+    }
+
+    const owner = spec.owner ?? state.identity?.ownerKey ?? '';
+    const id = spec.id ?? `task-${ts}-${(seq += 1)}`;
+
+    const existing = state.tasks.find((t) => t.id === id && t.owner === owner && t.dueAt === dueAt && t.active !== false);
+    if (existing) return existing;
+
+    const task = {
+      id,
+      kind,
+      dueAt,
+      owner,
+      everyMs,
+      label: spec.label ?? null,
+      payload: spec.payload ?? null,
+      createdAt: ts,
+      lastRunAt: 0,
+      active: true,
+      expired: kind === 'at' && dueAt <= ts,
+    };
+    state.tasks.push(task);
+    return task;
+  },
+
+  cancel(state, id) {
+    if (!Array.isArray(state.tasks)) return false;
+    const before = state.tasks.length;
+    state.tasks = state.tasks.filter((t) => t.id !== id);
+    return state.tasks.length !== before;
+  },
+
+  list(state) {
+    return Array.isArray(state.tasks) ? [...state.tasks] : [];
+  },
+
+  /** Returns the tasks that are due now and consumes them (once for "in"/"at"). */
+  due(state, now = Date.now()) {
+    const ts = Number.isFinite(now) ? now : Date.now();
+    if (!Array.isArray(state.tasks)) return [];
+    const due = [];
+    for (const task of state.tasks) {
+      if (task.active === false) continue;
+      if (!(task.dueAt <= ts)) continue;
+      due.push({ ...task });
+      task.lastRunAt = ts;
+      if (task.kind === 'every') {
+        task.dueAt = ts + (task.everyMs || 0);
+      } else {
+        task.active = false;
+      }
+    }
+    return due;
+  },
+};

package/src/core/state.mjs

@@ -0,0 +1,189 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { pactiveError } from './errors.mjs';
+import { ensureDir, withLock } from './lock.mjs';
+import { ledger } from './lineage.mjs';
+
+export const SCHEMA_VERSION = 1;
+
+let tmpSeq = 0;
+
+export function defaultState() {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    identity: { agentId: '', ownerKey: '', projectHash: '' },
+    busy: false,
+    controlReturned: false,
+    lastActivityAt: 0,
+    lastUserActivityAt: 0,
+    lastAgentActivityAt: 0,
+    epoch: 0,
+    idle: { enabled: false, thresholdMs: 900000 },
+    policy: {
+      quietStart: null,
+      quietEnd: null,
+      hourlyLimit: 6,
+      minIntervalMs: 600000,
+      cooldownMs: 1800000,
+    },
+    // lastTriggerEpoch is the extra field the frozen shape does not carry: the
+    // "one trigger per activity epoch" rule needs the epoch of the last trigger.
+    guard: { hourWindowStart: 0, hourCount: 0, lastTriggerAt: 0, lastTriggerEpoch: -1 },
+    tasks: [],
+    peers: {},
+    outbox: [],
+  };
+}
+
+/** Accept either a paths object (from resolvePaths) or a state file path. */
+export function toPaths(target) {
+  if (!target) throw pactiveError('STATE_TARGET_REQUIRED', 'a paths object or state file path is required');
+  if (typeof target === 'string') {
+    const stateFile = path.resolve(target);
+    const root = path.dirname(stateFile);
+    return {
+      root,
+      stateFile,
+      tasksFile: path.join(root, 'tasks.json'),
+      peersDir: path.join(root, 'peers'),
+      inboxDir: path.join(root, 'inbox'),
+      outboxDir: path.join(root, 'outbox'),
+      ledgerFile: path.join(root, 'ledger.jsonl'),
+      locksDir: path.join(root, 'locks'),
+    };
+  }
+  if (typeof target.stateFile !== 'string' || !target.stateFile) {
+    throw pactiveError('STATE_TARGET_REQUIRED', 'a paths object or state file path is required');
+  }
+  const root = target.root ?? path.dirname(target.stateFile);
+  return {
+    root,
+    stateFile: target.stateFile,
+    tasksFile: target.tasksFile ?? path.join(root, 'tasks.json'),
+    peersDir: target.peersDir ?? path.join(root, 'peers'),
+    inboxDir: target.inboxDir ?? path.join(root, 'inbox'),
+    outboxDir: target.outboxDir ?? path.join(root, 'outbox'),
+    ledgerFile: target.ledgerFile ?? path.join(root, 'ledger.jsonl'),
+    locksDir: target.locksDir ?? path.join(root, 'locks'),
+  };
+}
+
+export function ensureStateDirs(paths) {
+  ensureDir(paths.root);
+  ensureDir(paths.locksDir);
+  ensureDir(paths.peersDir);
+  ensureDir(paths.inboxDir);
+  ensureDir(paths.outboxDir);
+  return paths;
+}
+
+function normalize(raw) {
+  const base = defaultState();
+  const state = { ...base, ...raw };
+  state.schemaVersion = SCHEMA_VERSION;
+  state.identity = { ...base.identity, ...(raw.identity || {}) };
+  state.idle = { ...base.idle, ...(raw.idle || {}) };
+  state.policy = { ...base.policy, ...(raw.policy || {}) };
+  state.guard = { ...base.guard, ...(raw.guard || {}) };
+  if (!Number.isFinite(state.guard.lastTriggerEpoch)) state.guard.lastTriggerEpoch = -1;
+  state.tasks = Array.isArray(raw.tasks) ? raw.tasks : [];
+  state.peers = raw.peers && typeof raw.peers === 'object' ? raw.peers : {};
+  state.outbox = Array.isArray(raw.outbox) ? raw.outbox : [];
+  state.busy = raw.busy === true;
+  state.controlReturned = raw.controlReturned === true;
+  state.epoch = Number.isFinite(raw.epoch) ? raw.epoch : 0;
+  for (const key of ['lastActivityAt', 'lastUserActivityAt', 'lastAgentActivityAt']) {
+    state[key] = Number.isFinite(raw[key]) ? raw[key] : 0;
+  }
+  return state;
+}
+
+export function loadState(target) {
+  const paths = toPaths(target);
+  let raw;
+  try {
+    raw = fs.readFileSync(paths.stateFile, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return defaultState();
+    throw err;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || parsed.schemaVersion !== SCHEMA_VERSION) {
+      throw pactiveError('STATE_SCHEMA_UNSUPPORTED', `unsupported schemaVersion in ${paths.stateFile}`);
+    }
+    return normalize(parsed);
+  } catch (err) {
+    quarantine(paths, err);
+    return defaultState();
+  }
+}
+
+function quarantine(paths, cause) {
+  const stamp = Date.now();
+  const target = `${paths.stateFile}.corrupt-${stamp}`;
+  try {
+    fs.renameSync(paths.stateFile, target);
+  } catch {
+    return;
+  }
+  try {
+    ledger.append(paths.ledgerFile, {
+      event: 'state.corrupt',
+      reason: cause && cause.code ? cause.code : 'parse-error',
+      file: 'state.json',
+      quarantined: path.basename(target),
+    });
+  } catch {
+    // the ledger must never block the host
+  }
+}
+
+export function saveState(target, state) {
+  const paths = toPaths(target);
+  if (!state || typeof state !== 'object') {
+    throw pactiveError('STATE_REQUIRED', 'a state object is required');
+  }
+  if (state.schemaVersion !== SCHEMA_VERSION) {
+    throw pactiveError('STATE_SCHEMA_UNSUPPORTED', `expected schemaVersion ${SCHEMA_VERSION}`);
+  }
+  ensureStateDirs(paths);
+  const dir = path.dirname(paths.stateFile);
+  tmpSeq += 1;
+  const tmp = path.join(dir, `.${path.basename(paths.stateFile)}.tmp-${process.pid}-${tmpSeq}`);
+  const data = `${JSON.stringify(state, null, 2)}\n`;
+  fs.writeFileSync(tmp, data, { mode: 0o600 });
+  fs.chmodSync(tmp, 0o600);
+  const fd = fs.openSync(tmp, 'r');
+  try {
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, paths.stateFile);
+  fs.chmodSync(paths.stateFile, 0o600);
+  return paths.stateFile;
+}
+
+/** Read-modify-write under a lock; the callback may be async and may mutate in place. */
+export async function mutateState(target, fn) {
+  if (typeof fn !== 'function') throw pactiveError('MUTATOR_REQUIRED', 'mutateState needs a function');
+  const paths = toPaths(target);
+  ensureStateDirs(paths);
+  return withLock(paths.locksDir, 'state', async () => {
+    const current = loadState(paths);
+    const next = await fn(current);
+    const final = next ?? current;
+    saveState(paths, final);
+    return final;
+  }, {
+    onStale: (lockFile) => {
+      try {
+        ledger.append(paths.ledgerFile, { event: 'lock.stale_takeover', lock: path.basename(lockFile) });
+      } catch {
+        // best effort
+      }
+    },
+  });
+}

package/src/hosts/dsh/index.mjs

@@ -0,0 +1,128 @@
+// DSH host adapter (contract §2). argv is verbatim per design §1: pactive owns a dedicated profile.
+import { readFileSync, readdirSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  conservativePresence,
+  defaultStateRoot,
+  makeResolver,
+  unreachableReceipt,
+} from '../shared/index.mjs';
+
+export const host = 'dsh';
+export const SUPPORTED_VERSION = '0.2.1-rc.5';
+export const MODE = 'profile';
+
+export const resolveExec = makeResolver('dsh', 'dsh');
+
+export function buildArgv({ pkgRoot, userArgs = [] }) {
+  return ['--profile', 'pactive', ...userArgs];
+}
+
+export function plan({ pkgRoot, env = process.env, userArgs = [] }) {
+  let exec = null;
+  try {
+    exec = resolveExec({ env });
+  } catch {
+    exec = null; // host not installed — the plan stays printable (zero side effects)
+  }
+  return {
+    host,
+    version: SUPPORTED_VERSION,
+    pluginRoot: pkgRoot,
+    exec,
+    mode: MODE,
+    argv: buildArgv({ pkgRoot, userArgs }),
+  };
+}
+
+export function capabilities() {
+  return { actions: ['prompt'], panel: false };
+}
+
+export async function presence(ctx = {}) {
+  return conservativePresence(host, ctx);
+}
+
+export async function inject(ctx, payload) {
+  return unreachableReceipt(`dsh adapter inject is not implemented yet (${payload?.kind ?? 'unknown'})`);
+}
+
+export async function deliver(ctx, msg) {
+  return unreachableReceipt('dsh adapter deliver is not implemented yet');
+}
+
+export async function listSessions(ctx = {}) {
+  return [];
+}
+
+export function stateRoot(ctx = {}) {
+  return defaultStateRoot(ctx);
+}
+
+export function installArgs({ pkgRoot }) {
+  return ['plugin', '--profile', 'pactive', 'add', pkgRoot];
+}
+
+export function uninstallArgs({ pkgRoot }) {
+  // pnpm removes by DEPENDENCY NAME, not by path: `pnpm remove /abs/path` exits 1 and leaves
+  // the profile untouched (defect found 2026-11-05 via install→uninstall→residue probe).
+  return ['plugin', '--profile', 'pactive', 'remove', packageName(pkgRoot)];
+}
+
+/** The dependency name that `install` registered (falls back to the package's own default). */
+function packageName(pkgRoot) {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
+    if (typeof pkg.name === 'string' && pkg.name) return pkg.name;
+  } catch {
+    // manifest unreadable: fall back to the contract name
+  }
+  return 'pactive';
+}
+
+/** Whether the pactive profile currently exists (used to keep `uninstall` idempotent and quiet). */
+export function isInstalled({ env }) {
+  const home = env.DSH_HOME || path.join(os.homedir(), '.dsh');
+  const manifest = path.join(home, 'profiles', 'pactive', 'package.json');
+  try {
+    const pkg = JSON.parse(readFileSync(manifest, 'utf8'));
+    return Boolean(pkg?.dependencies?.pactive) || (pkg?.dsh?.profile?.bundles || []).includes('pactive');
+  } catch {
+    return false;
+  }
+}
+
+/** Remove the pactive-owned DSH profile directory so `uninstall` leaves zero residue (I40). */
+export function cleanup({ env }) {
+  const home = env.DSH_HOME || path.join(os.homedir(), '.dsh');
+  const profileDir = path.join(home, 'profiles', 'pactive');
+  const manifest = path.join(profileDir, 'package.json');
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(manifest, 'utf8'));
+  } catch {
+    return { removed: false, reason: 'no-profile' };
+  }
+  if (pkg.name !== 'dsh-profile-pactive') {
+    return { removed: false, reason: 'profile-not-owned' };
+  }
+  rmSync(profileDir, { recursive: true, force: true });
+  // 顺手删掉空的 profiles/：install 会创建它，留一个空目录仍会被算作"残留 1 项"（I40）。
+  const profilesDir = path.join(home, 'profiles');
+  try {
+    if (readdirSync(profilesDir).length === 0) rmSync(profilesDir, { recursive: true, force: true });
+  } catch {
+    // profiles/ 已不存在 —— 幂等
+  }
+  return { removed: true, path: profileDir };
+}
+
+export function verifyArgs({ pkgRoot }) {
+  return ['plugin', '--profile', 'pactive', 'list'];
+}
+
+export function verifyMatch({ pkgRoot }, output) {
+  return String(output ?? '').includes(pkgRoot);
+}

package/src/hosts/errors.mjs

@@ -0,0 +1,24 @@
+// Contract §2 error taxonomy.
+export class PactiveError extends Error {
+  constructor(message, { code = 'PACTIVE_ERROR', exitCode = 1, cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'PactiveError';
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+
+/** The host binary could not be found → CLI exit code 127. */
+export class HostMissingError extends PactiveError {
+  constructor(host, attempted = null) {
+    const envVar = `PACTIVE_${host.toUpperCase()}_BIN`;
+    super(
+      `host binary for '${host}' not found${attempted ? ` (${attempted})` : ''} — install '${host}' or set ${envVar}`,
+      { code: 'HOST_MISSING', exitCode: 127 },
+    );
+    this.name = 'HostMissingError';
+    this.host = host;
+    this.attempted = attempted;
+    this.envVar = envVar;
+  }
+}

package/src/hosts/opcteam/index.mjs

@@ -0,0 +1,77 @@
+// OPCteam host adapter (contract §2). argv is verbatim per design §1: the package root is the plugin root.
+import path from 'node:path';
+
+import {
+  conservativePresence,
+  defaultStateRoot,
+  makeResolver,
+  unreachableReceipt,
+} from '../shared/index.mjs';
+
+export const host = 'opcteam';
+export const SUPPORTED_VERSION = '1.1.6-test';
+export const MODE = 'plugin-dir';
+
+export const resolveExec = makeResolver('opcteam', 'opcteam');
+
+export function buildArgv({ pkgRoot, userArgs = [] }) {
+  return ['--plugin-dir', pkgRoot, ...userArgs];
+}
+
+export function plan({ pkgRoot, env = process.env, userArgs = [] }) {
+  let exec = null;
+  try {
+    exec = resolveExec({ env });
+  } catch {
+    exec = null; // host not installed — the plan stays printable (zero side effects)
+  }
+  return {
+    host,
+    version: SUPPORTED_VERSION,
+    pluginRoot: pkgRoot,
+    exec,
+    mode: MODE,
+    argv: buildArgv({ pkgRoot, userArgs }),
+  };
+}
+
+export function capabilities() {
+  return { actions: ['prompt'], panel: false };
+}
+
+export async function presence(ctx = {}) {
+  return conservativePresence(host, ctx);
+}
+
+export async function inject(ctx, payload) {
+  return unreachableReceipt(`opcteam adapter inject is not implemented yet (${payload?.kind ?? 'unknown'})`);
+}
+
+export async function deliver(ctx, msg) {
+  return unreachableReceipt('opcteam adapter deliver is not implemented yet');
+}
+
+export async function listSessions(ctx = {}) {
+  return [];
+}
+
+export function stateRoot(ctx = {}) {
+  return defaultStateRoot(ctx);
+}
+
+export function installArgs({ pkgRoot }) {
+  return ['plugin', 'marketplace', 'add', pkgRoot];
+}
+
+export function uninstallArgs({ pkgRoot }) {
+  return ['plugin', 'marketplace', 'remove', path.basename(pkgRoot)];
+}
+
+export function verifyArgs({ pkgRoot }) {
+  return ['plugin', 'marketplace', 'list'];
+}
+
+export function verifyMatch({ pkgRoot }, output) {
+  const text = String(output ?? '');
+  return text.includes(pkgRoot) || text.includes(path.basename(pkgRoot));
+}

package/src/hosts/pi/index.mjs

@@ -0,0 +1,82 @@
+// Pi host adapter (contract §2). argv is verbatim per design §1/§7.1.
+import path from 'node:path';
+
+import {
+  conservativePresence,
+  defaultStateRoot,
+  makeResolver,
+  unreachableReceipt,
+} from '../shared/index.mjs';
+
+export const host = 'pi';
+export const SUPPORTED_VERSION = '1.4.0';
+export const MODE = 'extension+skill';
+
+export const resolveExec = makeResolver('pi', 'pi');
+
+export function buildArgv({ pkgRoot, userArgs = [] }) {
+  return [
+    '--extension',
+    path.join(pkgRoot, 'pi', 'extension.ts'),
+    '--skill',
+    path.join(pkgRoot, 'pi', 'skills', 'pactive'),
+    ...userArgs,
+  ];
+}
+
+export function plan({ pkgRoot, env = process.env, userArgs = [] }) {
+  let exec = null;
+  try {
+    exec = resolveExec({ env });
+  } catch {
+    exec = null; // host not installed — the plan stays printable (zero side effects)
+  }
+  return {
+    host,
+    version: SUPPORTED_VERSION,
+    pluginRoot: pkgRoot,
+    exec,
+    mode: MODE,
+    argv: buildArgv({ pkgRoot, userArgs }),
+  };
+}
+
+export function capabilities() {
+  return { actions: ['prompt'], panel: false };
+}
+
+export async function presence(ctx = {}) {
+  return conservativePresence(host, ctx);
+}
+
+export async function inject(ctx, payload) {
+  return unreachableReceipt(`pi adapter inject is not implemented yet (${payload?.kind ?? 'unknown'})`);
+}
+
+export async function deliver(ctx, msg) {
+  return unreachableReceipt('pi adapter deliver is not implemented yet');
+}
+
+export async function listSessions(ctx = {}) {
+  return [];
+}
+
+export function stateRoot(ctx = {}) {
+  return defaultStateRoot(ctx);
+}
+
+export function installArgs({ pkgRoot }) {
+  return ['install', pkgRoot];
+}
+
+export function uninstallArgs({ pkgRoot }) {
+  return ['remove', pkgRoot];
+}
+
+export function verifyArgs({ pkgRoot }) {
+  return ['list'];
+}
+
+export function verifyMatch({ pkgRoot }, output) {
+  return String(output ?? '').includes(pkgRoot);
+}

package/src/hosts/shared/index.mjs

@@ -0,0 +1,64 @@
+// Shared host-adapter helpers (contract §2).
+// Host-specific knowledge stays in src/hosts/<host>/index.mjs; this file only holds
+// the mechanics every adapter needs (binary resolution + conservative fallbacks).
+import { accessSync, constants, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { HostMissingError } from '../errors.mjs';
+
+export function isExecutable(p) {
+  try {
+    if (!statSync(p).isFile()) return false;
+    accessSync(p, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function findOnPath(name, env = process.env) {
+  for (const dir of (env.PATH ?? '').split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, name);
+    if (isExecutable(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** env.PACTIVE_<HOST>_BIN → PATH lookup → throw HostMissingError (exit 127). */
+export function makeResolver(host, binaryName) {
+  return function resolveExec({ env = process.env } = {}) {
+    const override = env[`PACTIVE_${host.toUpperCase()}_BIN`];
+    if (override) {
+      if (isExecutable(override)) return path.resolve(override);
+      throw new HostMissingError(host, override);
+    }
+    const found = findOnPath(binaryName, env);
+    if (found) return found;
+    throw new HostMissingError(host, null);
+  };
+}
+
+/** Conservative presence: the CLI adapter cannot observe the host session itself. */
+export function conservativePresence(host, ctx = {}) {
+  return {
+    online: false,
+    busy: false,
+    controlReturned: false,
+    lastUserActivityAt: null,
+    lastAgentActivityAt: null,
+    agentId: ctx.agentId ?? `unknown#${host}#unknown`,
+    sessionId: ctx.sessionId ?? 'unknown',
+    hostKind: host,
+  };
+}
+
+/** Never claim success for an unimplemented channel (contract §2 five-state receipt). */
+export function unreachableReceipt(reason) {
+  return { ok: false, state: 'unreachable', reason, at: Date.now() };
+}
+
+export function defaultStateRoot(ctx = {}) {
+  return ctx.stateRoot ?? ctx.paths?.root ?? path.join(os.homedir(), '.pactive');
+}