@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.0.0

package/src/lib/budgets.js

@@ -0,0 +1,85 @@
+import { randomUUID } from 'node:crypto';
+import { HubError } from './errors.js';
+
+function assertLimit(value, limit, code, label) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new HubError(code, `${label} usage must be a finite non-negative number`);
+  }
+  if (value > limit) {
+    throw new HubError(code, `${label} budget exceeded (${value} > ${limit})`);
+  }
+}
+
+export class BudgetGuard {
+  #active = new Map();
+
+  constructor({
+    maxTokens,
+    maxCostUsd,
+    maxWallMs,
+    maxOutputBytes,
+    maxConcurrency,
+    now = Date.now,
+  }) {
+    for (const [name, value] of Object.entries({
+      maxTokens,
+      maxCostUsd,
+      maxWallMs,
+      maxOutputBytes,
+      maxConcurrency,
+    })) {
+      if (!Number.isFinite(value) || value <= 0 || (name === 'maxConcurrency' && !Number.isInteger(value))) {
+        throw new HubError('HUB_BUDGET_INVALID', `${name} must be an explicit positive finite limit`);
+      }
+    }
+    this.limits = { maxTokens, maxCostUsd, maxWallMs, maxOutputBytes, maxConcurrency };
+    this.now = now;
+  }
+
+  acquire() {
+    assertLimit(
+      this.#active.size + 1,
+      this.limits.maxConcurrency,
+      'HUB_BUDGET_CONCURRENCY',
+      'Concurrency'
+    );
+    const startedAt = this.now();
+    if (!Number.isFinite(startedAt) || startedAt < 0) {
+      throw new HubError('HUB_BUDGET_TIME', 'Monotonic clock returned an invalid value');
+    }
+    const lease = { id: randomUUID(), startedAt };
+    this.#active.set(lease.id, { ...lease, tokens: 0, costUsd: 0, outputBytes: 0 });
+    return { ...lease };
+  }
+
+  assertWithin({ id, tokens, costUsd, outputBytes }) {
+    const lease = this.#active.get(id);
+    if (!lease) throw new HubError('HUB_BUDGET_LEASE_INVALID', 'Budget lease is not active');
+    assertLimit(tokens, this.limits.maxTokens, 'HUB_BUDGET_TOKENS', 'Token');
+    assertLimit(costUsd, this.limits.maxCostUsd, 'HUB_BUDGET_COST', 'Cost');
+    assertLimit(outputBytes, this.limits.maxOutputBytes, 'HUB_BUDGET_OUTPUT', 'Output');
+    assertLimit(this.now() - lease.startedAt, this.limits.maxWallMs, 'HUB_BUDGET_TIME', 'Wall time');
+  }
+
+  consume(lease, delta) {
+    const current = this.#active.get(lease.id);
+    if (!current) throw new HubError('HUB_BUDGET_LEASE_INVALID', 'Budget lease is not active');
+    const next = {
+      id: current.id,
+      tokens: current.tokens + delta.tokens,
+      costUsd: current.costUsd + delta.costUsd,
+      outputBytes: current.outputBytes + delta.outputBytes,
+    };
+    this.assertWithin(next);
+    Object.assign(current, next);
+    return { ...current };
+  }
+
+  release(lease) {
+    this.#active.delete(lease.id);
+  }
+
+  get active() {
+    return this.#active.size;
+  }
+}

package/src/lib/cliDefaults.js

@@ -0,0 +1,20 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export async function readCliDefaults({ env = process.env, home = os.homedir() } = {}) {
+  const file = path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'agentpulse', 'config.json');
+  let config;
+  try {
+    config = JSON.parse(await readFile(file, 'utf8'));
+  } catch {
+    return {};
+  }
+  const aliases = Object.keys(config?.profiles || {});
+  const alias = config?.profiles?.[config.defaultProfile] ? config.defaultProfile : aliases.length === 1 ? aliases[0] : null;
+  const profile = alias ? config.profiles[alias] : null;
+  return {
+    platformUrl: profile?.baseUrl || profile?.url || null,
+    devOrgSlug: profile?.devOrgSlug || null,
+  };
+}

package/src/lib/cloudAuth.js

@@ -0,0 +1,189 @@
+import { HubError } from './errors.js';
+import { cleanOrigin, decodeJwtClaims, fetchJson } from './http.js';
+import { DEV_ORG_INGRESS_HEADER, OAUTH_CLIENT_ID } from './transportContract.js';
+
+const SKEW_MS = 60_000;
+const TOKEN_TIMEOUT_MS = 15_000;
+
+export function loginRequired(reason) {
+  return new HubError(
+    'HUB_LOGIN_REQUIRED',
+    `Pulse connector sign-in is missing or expired (${reason}). Run \`agentpulse pulse login\`, then \`agentpulse pulse start\`.`,
+  );
+}
+
+function refreshUnavailable(reason, cause) {
+  return new HubError(
+    'HUB_REFRESH_UNAVAILABLE',
+    `Could not refresh the Pulse sign-in (${reason}); the connector will retry and claims no work until it succeeds`,
+    cause ? { cause } : {},
+  );
+}
+
+function expiresSoon(expiresAt, now) {
+  const expiry = Date.parse(expiresAt || '');
+  return !Number.isFinite(expiry) || expiry - now() <= SKEW_MS;
+}
+
+export class CloudAuth {
+  constructor({ tokenStore, target, fetch = globalThis.fetch, now = Date.now }) {
+    this.tokenStore = tokenStore;
+    this.target = {
+      ...target,
+      platformUrl: cleanOrigin(target.platformUrl, 'Platform URL'),
+      instanceUrl: target.instanceUrl ? cleanOrigin(target.instanceUrl, 'Instance URL') : null,
+    };
+    this.fetch = fetch;
+    this.now = now;
+    this.devOrgSession = null;
+    this.platformSession = null;
+    this.forceRefresh = false;
+  }
+
+  get instanceUrl() {
+    return this.target.devOrg ? this.target.instanceUrl : this.target.platformUrl;
+  }
+
+  invalidate() {
+    this.devOrgSession = null;
+    this.platformSession = null;
+    if (!this.target.devOrg) this.forceRefresh = true;
+  }
+
+  async #refresh(session) {
+    if (!session.refreshToken) throw loginRequired('access token expired and no refresh token is stored');
+    let refreshed;
+    try {
+      refreshed = await fetchJson({
+        fetch: this.fetch,
+        url: `${this.target.platformUrl}/api/oauth/token`,
+        body: { grant_type: 'refresh_token', client_id: OAUTH_CLIENT_ID, refresh_token: session.refreshToken },
+        timeoutMs: TOKEN_TIMEOUT_MS,
+      });
+    } catch (error) {
+      throw refreshUnavailable('the platform did not answer', error);
+    }
+    if (refreshed.status >= 500 || refreshed.status === 429) {
+      throw refreshUnavailable(`the platform answered HTTP ${refreshed.status}`);
+    }
+    if (refreshed.body?.error === 'invalid_grant') {
+      throw loginRequired('the platform rejected or revoked the refresh token (invalid_grant)');
+    }
+    const claims = decodeJwtClaims(refreshed.body?.access_token);
+    if (
+      !refreshed.ok ||
+      claims?.type !== 'user_delegated' ||
+      claims.sub !== session.userId ||
+      claims.team_id !== session.teamId
+    ) {
+      throw loginRequired('token refresh did not return this user\'s delegated token');
+    }
+    const expiresIn = Number(refreshed.body.expires_in);
+    const next = {
+      ...session,
+      accessToken: refreshed.body.access_token,
+      refreshToken: typeof refreshed.body.refresh_token === 'string' ? refreshed.body.refresh_token : session.refreshToken,
+      expiresAt: new Date(this.now() + (Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : 3600) * 1000).toISOString(),
+    };
+    await this.tokenStore.save(next);
+    return next;
+  }
+
+  async #storedSession() {
+    const session = await this.tokenStore.load();
+    if (!session?.accessToken) throw loginRequired('no stored sign-in');
+    if (
+      session.platformUrl !== this.target.platformUrl ||
+      session.userId !== this.target.userId ||
+      session.teamId !== this.target.teamId
+    ) {
+      throw loginRequired('the stored sign-in belongs to a different platform, team or user');
+    }
+    return session;
+  }
+
+  // The stored session is in the OS secret store (a Keychain read is 0.5-2 s), so it is read once and kept until 60 s
+  // before expiry or until invalidate().
+  async #platformSession() {
+    if (!this.forceRefresh && this.platformSession && !expiresSoon(this.platformSession.expiresAt, this.now)) {
+      return this.platformSession;
+    }
+    this.platformSession = await this.#loadPlatformSession();
+    return this.platformSession;
+  }
+
+  async #loadPlatformSession() {
+    const session = await this.#storedSession();
+    if (!this.forceRefresh && !expiresSoon(session.expiresAt, this.now)) return session;
+    const rejectedAccessToken = this.forceRefresh ? session.accessToken : null;
+    const current = await this.tokenStore.withRefreshLock(async () => {
+      const latest = await this.#storedSession();
+      const refreshedElsewhere = rejectedAccessToken && latest.accessToken !== rejectedAccessToken;
+      if (refreshedElsewhere || (!rejectedAccessToken && !expiresSoon(latest.expiresAt, this.now))) return latest;
+      return this.#refresh(latest);
+    });
+    this.forceRefresh = false;
+    return current;
+  }
+
+  async #mintDevOrgSession(platformSession) {
+    let minted;
+    try {
+      minted = await fetchJson({
+        fetch: this.fetch,
+        url: `${this.target.platformUrl}/api/team/dev-orgs/${encodeURIComponent(this.target.devOrg.id)}/cli-token`,
+        headers: { authorization: `Bearer ${platformSession.accessToken}` },
+        body: {},
+        timeoutMs: TOKEN_TIMEOUT_MS,
+      });
+    } catch (error) {
+      throw new HubError('HUB_TARGET_UNAVAILABLE', 'Could not reach the platform to connect to the dev-org', { cause: error });
+    }
+    if ([401, 403].includes(minted.status) || minted.body?.code === 'NO_USER_IDENTITY') {
+      throw loginRequired(`the platform refused the dev-org connection (HTTP ${minted.status})`);
+    }
+    if (!minted.ok) {
+      throw new HubError(
+        'HUB_TARGET_UNAVAILABLE',
+        `Dev-org ${this.target.devOrg.slug} is not reachable (HTTP ${minted.status}${minted.body?.code ? ` ${minted.body.code}` : ''})`,
+      );
+    }
+    const claims = decodeJwtClaims(minted.body.token);
+    if (claims?.userId !== this.target.userId || claims?.teamId !== this.target.teamId) {
+      throw loginRequired('the dev-org token was minted for a different user');
+    }
+    const instanceUrl = cleanOrigin(minted.body.instanceUrl, 'Dev-org instance URL');
+    if (this.target.instanceUrl && instanceUrl !== this.target.instanceUrl) {
+      throw new HubError(
+        'HUB_TARGET_CHANGED',
+        `Dev-org ${this.target.devOrg.slug} moved to a new address; pair this machine again`,
+      );
+    }
+    this.target.instanceUrl = instanceUrl;
+    return {
+      token: minted.body.token,
+      identityToken: typeof minted.body.identityToken === 'string' ? minted.body.identityToken : null,
+      expiresAt: minted.body.expiresAt,
+    };
+  }
+
+  /** The credentials held in memory now, so the mirror can redact them by identity; it never reads the secret store. */
+  heldSecrets() {
+    return [this.platformSession?.accessToken, this.platformSession?.refreshToken, this.devOrgSession?.token, this.devOrgSession?.identityToken]
+      .filter((value) => typeof value === 'string' && value.length >= 16);
+  }
+
+  async credentials() {
+    const platformSession = await this.#platformSession();
+    if (!this.target.devOrg) return { authorization: `Bearer ${platformSession.accessToken}` };
+    if (!this.devOrgSession || expiresSoon(this.devOrgSession.expiresAt, this.now)) {
+      this.devOrgSession = await this.#mintDevOrgSession(platformSession);
+    }
+    return {
+      authorization: `Bearer ${this.devOrgSession.token}`,
+      ...(this.devOrgSession.identityToken
+        ? { [DEV_ORG_INGRESS_HEADER]: `Bearer ${this.devOrgSession.identityToken}` }
+        : {}),
+    };
+  }
+}

package/src/lib/contract.sha256

@@ -0,0 +1,2 @@
+88e39539d7d2b1775b4970a8aeed416ae6d7203c53df143093ea54d2014cdd31  connector-contract.json
+7b7a59c08797c100b46436123dfcb09b517730357fa90cd0890da9b80308faf3  mirror-contract.json

package/src/lib/daemonComposition.js

@@ -0,0 +1,338 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { AgentSessionStore } from './agentSessions.js';
+import { CloudAuth } from './cloudAuth.js';
+import { defaultSecretStore } from './secretStore.js';
+import { HubError } from './errors.js';
+import { createHubActionHandlers } from './hubActions.js';
+import { discoverLocalHub } from './localHub.js';
+import { LocalHubWriter } from './localHubWriter.js';
+import { assertPairedConfig } from './pairedConfig.js';
+import { canonicalJson, validateDeliveryPlan } from './planContract.js';
+import { TokenStore } from './tokenStore.js';
+import { ConnectorTransport } from './transport.js';
+import { validateRootGrant, WorktreeRegistry, createOwnedWorktree } from './rootPolicy.js';
+import { execFileBounded as execFile } from './subprocess.js';
+
+export async function createProductionDependencies({
+  config,
+  configDir,
+  secretStore = defaultSecretStore(),
+  fetch = globalThis.fetch,
+  log = () => {},
+  onTransportAttempt = () => {},
+}) {
+  assertPairedConfig(config);
+  const tokenStore = new TokenStore({ secretStore, configDir });
+  const sessionId = randomUUID();
+  const worktrees = await WorktreeRegistry.open(configDir);
+  const sessions = await AgentSessionStore.open(configDir);
+  const roots = new Map((config.localRoots || []).map((root) => [root.rootId, root]));
+  let transport;
+  let transportKey;
+
+  const transportFactory = async (currentConfig) => {
+    const paired = assertPairedConfig(currentConfig);
+    const key = [paired.machineId, paired.policyVersion, paired.baseUrl, paired.userId].join('\0');
+    if (transport && transportKey === key) return transport;
+    const auth = new CloudAuth({
+      tokenStore,
+      fetch,
+      target: {
+        platformUrl: paired.target.platformUrl,
+        devOrg: paired.target.devOrg,
+        instanceUrl: paired.baseUrl,
+        userId: paired.userId,
+        teamId: paired.teamId,
+      },
+    });
+    transport = new ConnectorTransport({
+      baseUrl: paired.baseUrl,
+      machine: { machineId: paired.machineId, sessionId, policyVersion: paired.policyVersion },
+      auth,
+      fetch,
+      onAttempt: onTransportAttempt,
+    });
+    transportKey = key;
+    return transport;
+  };
+
+  const hubActions = createHubActionHandlers({
+    writerFor: async () => {
+      let hub;
+      try {
+        hub = await discoverLocalHub({ config });
+      } catch (error) {
+        throw new HubError('hub_unreachable', error.message);
+      }
+      return new LocalHubWriter({ ...hub, fetch, log });
+    },
+  });
+
+  const handlersFactory = ({ drivers, policy }) => {
+    const plannerChoices = Object.entries(policy.providers).flatMap(([provider, models]) =>
+      models.map((model) => ({ provider, model }))
+    );
+    const defaultProvider = plannerChoices.length === 1 ? plannerChoices[0].provider : null;
+    const defaultModel = plannerChoices.length === 1 ? plannerChoices[0].model : null;
+    const budget = (requested = {}) => ({
+      maxTokens: requested.maxTokens || policy.limits.maxTokensPerRun,
+      maxCostUsd: requested.maxCostUsd ?? policy.limits.maxCostUsd,
+      maxWallMs: requested.maxWallMs || policy.limits.maxWallMs,
+      maxOutputBytes: requested.maxOutputBytes || policy.limits.maxOutputBytes,
+    });
+    const workspaceFor = (rootId, mode, cloudJob = {}, expectedWorktreeId = null) => {
+      const root = roots.get(rootId);
+      if (!root) throw new HubError('HUB_CAPABILITY_DENIED', 'Root is not locally approved');
+      if (mode === 'read') return root.canonicalRoot;
+      const candidates = worktrees
+        .list(rootId)
+        .filter(
+          (record) =>
+            record.deliveryId === cloudJob.delivery_id &&
+            record.streamId === cloudJob.stream_id
+        );
+      if (candidates.length !== 1) {
+        throw new HubError(
+          'HUB_WRITE_REQUIRES_WORKTREE',
+          'Write-mode agent requires exactly one connector-owned worktree'
+        );
+      }
+      if (expectedWorktreeId && candidates[0].worktreeId !== expectedWorktreeId) {
+        throw new HubError(
+          'HUB_AGENT_SESSION_BINDING_MISMATCH',
+          'Continuation worktree does not match its durable local agent binding'
+        );
+      }
+      return candidates[0].canonicalPath;
+    };
+    return {
+    'delivery.plan': async (job, context) => {
+      if (!defaultProvider || !defaultModel) {
+        throw new HubError(
+          'HUB_PROVIDER_DENIED',
+          'Planner requires exactly one signed provider/model assignment'
+        );
+      }
+      const rootId = job.arguments.rootIds[0];
+      const result = await drivers.driver(defaultProvider, defaultModel).start({
+        workspace: workspaceFor(rootId, 'read', context.cloudJob),
+        provider: defaultProvider,
+        model: defaultModel,
+        role: 'architect',
+        mode: 'read',
+        prompt: `Produce only a bounded JSON delivery plan for this approved outcome:\n${job.arguments.description}`,
+        budget: budget(job.arguments.budget),
+        attempt: context.attempt,
+        onStart: context.onProcessStart,
+        signal: context.signal,
+      });
+      let plan;
+      try {
+        plan = JSON.parse(result.text);
+      } catch {
+        throw new HubError('HUB_PROVIDER_OUTPUT_INVALID', 'Planner did not return JSON');
+      }
+      const validatedPlan = validateDeliveryPlan(plan, grant);
+      return {
+        plan: validatedPlan,
+        planDigest: createHash('sha256').update(canonicalJson(validatedPlan)).digest('hex'),
+      };
+    },
+    'workspace.inspect': async (job) => {
+      const root = roots.get(job.arguments.rootId);
+      if (!root) throw new HubError('HUB_CAPABILITY_DENIED', 'Root is not locally approved');
+      await validateRootGrant(root);
+      return {
+        summary: 'Approved workspace root is available.',
+        repo: { rootId: root.rootId, repoWrite: root.repoWrite },
+        fileManifestHash: createHash('sha256').update(root.repositoryIdentity).digest('hex'),
+      };
+    },
+    'worktree.create': async (job, context) => {
+      const root = roots.get(job.arguments.rootId);
+      if (!root) throw new HubError('HUB_CAPABILITY_DENIED', 'Root is not locally approved');
+      const record = await createOwnedWorktree({
+        grant: root,
+        deliveryId: context.cloudJob.delivery_id,
+        streamId: context.cloudJob.stream_id,
+        baseRef: root.baseRef,
+        registry: worktrees,
+      });
+      return {
+        summary: 'Connector-owned worktree created.',
+        branch: record.branch,
+        worktreeRef: record.worktreeId,
+        repoHash: root.repositoryIdentity,
+      };
+    },
+    'git.inspect': async (job) => {
+      const root = roots.get(job.arguments.rootId);
+      if (!root) throw new HubError('HUB_CAPABILITY_DENIED', 'Root is not locally approved');
+      await validateRootGrant(root);
+      const env = {
+        PATH: process.env.PATH || '/usr/bin:/bin',
+        LC_ALL: 'C',
+        GIT_CONFIG_GLOBAL: '/dev/null',
+        GIT_CONFIG_SYSTEM: '/dev/null',
+        GIT_TERMINAL_PROMPT: '0',
+      };
+      const status = await execFile(
+        'git',
+        ['status', '--porcelain=v1', '--untracked-files=no'],
+        { cwd: root.canonicalRoot, env, timeout: 30_000, maxBuffer: 512 * 1024 }
+      );
+      let refSha = null;
+      let diffSummary = '';
+      if (job.arguments.ref) {
+        const resolved = await execFile(
+          'git',
+          ['rev-parse', '--verify', '--end-of-options', `${job.arguments.ref}^{commit}`],
+          { cwd: root.canonicalRoot, env, timeout: 30_000, maxBuffer: 64 * 1024 }
+        );
+        refSha = resolved.stdout.trim();
+        if (job.arguments.includeDiffSummary) {
+          const diff = await execFile(
+            'git',
+            ['diff', '--stat', '--no-ext-diff', `${refSha}..HEAD`],
+            { cwd: root.canonicalRoot, env, timeout: 30_000, maxBuffer: 512 * 1024 }
+          );
+          diffSummary = diff.stdout;
+        }
+      }
+      return {
+        summary: 'Git metadata inspected under the approved root.',
+        status: {
+          clean: status.stdout.length === 0,
+          changedEntries: status.stdout.trim() ? status.stdout.trim().split('\n').length : 0,
+          refSha,
+        },
+        diffSummaryHash: createHash('sha256').update(diffSummary).digest('hex'),
+      };
+    },
+    'agent.start': async (job, context) => {
+      const args = job.arguments;
+      const mode = args.role === 'coder' ? 'write' : 'read';
+      const result = await drivers.driver(args.provider, args.model).start({
+        workspace: workspaceFor(args.rootId, mode, context.cloudJob),
+        model: args.model,
+        role: args.role,
+        mode,
+        prompt: `Execute this approved structured intent only:\n${JSON.stringify(args.intent)}`,
+        budget: budget(args.budget),
+        attempt: context.attempt,
+        onStart: context.onProcessStart,
+        signal: context.signal,
+      });
+      await sessions.recordPendingStart(context.cloudJob.id, {
+        agentId: args.agentId,
+        provider: args.provider,
+        model: args.model,
+        role: args.role,
+        mode,
+        rootId: args.rootId,
+        deliveryId: context.cloudJob.delivery_id,
+        streamId: context.cloudJob.stream_id,
+        worktreeId:
+          mode === 'write'
+            ? worktrees
+                .list(args.rootId)
+                .find(
+                  (record) =>
+                    record.deliveryId === context.cloudJob.delivery_id &&
+                    record.streamId === context.cloudJob.stream_id
+                )?.worktreeId
+            : null,
+        providerSessionId: result.sessionId,
+        processIdentity: result.processIdentity,
+        state: 'active',
+      });
+      return {
+        summary: drivers.driver(args.provider, args.model).collectSummary(result).text,
+        agentSessionRefHash: createHash('sha256')
+          .update(String(result.sessionId))
+          .digest('hex'),
+      };
+    },
+    'agent.turn': async (job, context) => {
+      const args = job.arguments;
+      const session = context.sessionBinding?.session;
+      if (!session) throw new HubError('HUB_AGENT_SESSION_MISSING', 'Agent session is not local');
+      await sessions.put(args.agentSessionId, session);
+      const result = await drivers.driver(session.provider, session.model).send({
+        workspace: workspaceFor(
+          args.rootId,
+          session.mode,
+          context.cloudJob,
+          session.worktreeId
+        ),
+        model: session.model,
+        role: session.role,
+        mode: session.mode,
+        sessionId: session.providerSessionId,
+        prompt: `Execute this approved structured intent only:\n${JSON.stringify(args.intent)}`,
+        budget: budget(args.budget),
+        attempt: context.attempt,
+        onStart: context.onProcessStart,
+        signal: context.signal,
+      });
+      await sessions.put(args.agentSessionId, {
+        ...session,
+        providerSessionId: result.sessionId,
+        processIdentity: result.processIdentity,
+      });
+      const summary = drivers.driver(session.provider, session.model).collectSummary(result);
+      return {
+        summary: summary.text,
+        usage: result.usage,
+        evidenceIds: [],
+        needsUser: false,
+      };
+    },
+    'agent.stop': async (job, context) => {
+      const args = job.arguments;
+      const session = context.sessionBinding?.session;
+      if (!session) throw new HubError('HUB_AGENT_SESSION_MISSING', 'Agent session is not local');
+      await sessions.put(args.agentSessionId, session);
+      if (session.processIdentity) {
+        const outcome = await drivers
+          .driver(session.provider, session.model)
+          .cancel(session.processIdentity);
+        if (!outcome.verifiedStopped) {
+          throw new HubError('HUB_CANCELLATION_UNPROVEN', 'Agent process did not stop');
+        }
+      }
+      await sessions.put(args.agentSessionId, { ...session, state: 'stopped' });
+      return { summary: args.reason, stopped: true };
+    },
+    'evidence.collect': async (job) => ({
+      summary: 'Evidence remains local until explicitly approved for upload.',
+      artifacts: job.arguments.kinds.map((kind) => ({
+        kind,
+        label: `Local ${kind.replaceAll('_', ' ')}`,
+        mimeType: 'application/octet-stream',
+        byteSize: 0,
+        sha256: createHash('sha256').update('').digest('hex'),
+        storageMode: 'local_only',
+        redactionVersion: 1,
+        userVisible: true,
+      })),
+    }),
+    ...hubActions,
+  };
+  };
+
+  const sessionResolver = (job) => sessions.resolveContinuation(job);
+  const settlementObserver = (attempt, response, error = null) => {
+    if (attempt.jobType !== 'agent.start') return null;
+    if (error) return sessions.rejectStartSettlement(attempt.jobId);
+    return sessions.applyStartAcknowledgement(attempt.jobId, response);
+  };
+
+  return {
+    tokenStore,
+    transportFactory,
+    handlersFactory,
+    sessionResolver,
+    settlementObserver,
+  };
+}

package/src/lib/daemonLock.js

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import { HubError } from './errors.js';
+import { acquireOwnerLock } from './ownerLock.js';
+import { ProcessIdentityProvider } from './processOwnership.js';
+import { ensureOwnerOnlyDirectory, writeOwnerOnlyJson } from './storage.js';
+
+export class DaemonLock {
+  constructor({
+    directory,
+    pid = process.pid,
+    identityProvider = new ProcessIdentityProvider(),
+  }) {
+    this.directory = directory;
+    this.pid = pid;
+    this.identityProvider = identityProvider;
+    this.pidFile = path.join(directory, 'daemon.pid');
+    this.healthFile = path.join(directory, 'daemon-health.json');
+    this.acquired = false;
+  }
+
+  async acquire() {
+    await ensureOwnerOnlyDirectory(this.directory);
+    this.releaseLock = await acquireOwnerLock({
+      file: this.pidFile,
+      identity: await this.identityProvider.capture(this.pid),
+      identityProvider: this.identityProvider,
+      heldError: (owner) => new HubError(
+        'HUB_DAEMON_ALREADY_RUNNING',
+        `Pulse daemon is already running${owner?.pid ? ` with pid ${owner.pid}` : ''}`
+      ),
+    });
+    this.acquired = true;
+    return { pid: this.pid };
+  }
+
+  heartbeat(status) {
+    if (!this.acquired) {
+      throw new HubError('HUB_DAEMON_NOT_OWNER', 'Daemon lock is not held by this process');
+    }
+    return writeOwnerOnlyJson(this.healthFile, {
+      pid: this.pid,
+      heartbeatAt: new Date().toISOString(),
+      ...status,
+    });
+  }
+
+  async release() {
+    if (!this.acquired) return;
+    try {
+      await this.releaseLock();
+    } finally {
+      this.acquired = false;
+    }
+  }
+}