@commonlyai/cli 0.1.172 → 0.1.174

package/node_modules/@commonlyai/seats/src/valet/env.js

@@ -0,0 +1,164 @@
+/**
+ * Build the env and HOME one run executes in. The run starts from nothing the
+ * user's login can be found through: a short allowlist of locale/terminal
+ * variables, a fresh HOME whose XDG dirs sit inside it, and only the
+ * credentials its grant names.
+ *
+ * What this is NOT: a filesystem sandbox. A process that already knows an
+ * absolute path (/Users/<you>/.claude) can still open it, and macOS keychain
+ * items are reached through the user's security session, not through HOME.
+ * This removes the paths a CLI discovers its login by; an OS sandbox
+ * (Seatbelt, bwrap) is what stops a process that goes looking.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdtemp, mkdir, chmod, readFile, rm } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { delimiter, join, resolve, sep } from 'node:path';
+import { traceOf } from '../trace/events.js';
+import { runFailure } from '../failures.js';
+import { MIN_CREDENTIAL_LENGTH } from '../upstream-refusal.js';
+import { validateGrant } from './grant.js';
+
+// Same spirit as the goose adapter's SAFE_ENV: locale, terminal and TLS trust
+// only. USER/LOGNAME are left out on purpose; they name the account whose
+// login this boundary exists to hide.
+export const BASE_ENV_ALLOWLIST = /^(?:PATH|LANG|LC_[A-Z0-9_]+|TERM|TZ|SSL_CERT_FILE|SSL_CERT_DIR|NO_COLOR|CI)$/;
+
+const isInside = (path, dir) => {
+  const a = resolve(path);
+  const b = resolve(dir);
+  return a === b || a.startsWith(b.endsWith(sep) ? b : b + sep);
+};
+
+/**
+ * PATH entries under the real home both name it and often hold shims that
+ * read the user's login (~/.local/bin/claude). Adapters run their CLI by
+ * absolute path, so the run loses nothing it needs.
+ */
+const scrubPath = (value, realHomes) => value.split(delimiter)
+  .filter((entry) => entry && !realHomes.some((home) => isInside(entry, home)))
+  .join(delimiter);
+
+const pickBaseEnv = (baseEnv, realHomes) => {
+  const env = {};
+  for (const [name, value] of Object.entries(baseEnv)) {
+    if (typeof value === 'string' && BASE_ENV_ALLOWLIST.test(name)) env[name] = value;
+  }
+  if (env.PATH !== undefined) env.PATH = scrubPath(env.PATH, realHomes);
+  return env;
+};
+
+const makeHome = async (root) => {
+  const home = await mkdtemp(join(root || tmpdir(), 'seat-home-'));
+  // Conventional layout, so a CLI that ignores XDG_* and defaults to
+  // ~/.config still lands inside the throwaway HOME.
+  const dirs = {
+    XDG_CONFIG_HOME: join(home, '.config'),
+    XDG_DATA_HOME: join(home, '.local', 'share'),
+    XDG_STATE_HOME: join(home, '.local', 'state'),
+    XDG_CACHE_HOME: join(home, '.cache'),
+    TMPDIR: join(home, 'tmp'),
+  };
+  await chmod(home, 0o700);
+  for (const dir of Object.values(dirs)) await mkdir(dir, { recursive: true, mode: 0o700 });
+  // mkdir's mode is masked by umask; set it explicitly on every level made.
+  for (const dir of [join(home, '.local'), ...Object.values(dirs)]) await chmod(dir, 0o700);
+  return { home, dirs };
+};
+
+/** A value that cannot ride an env var is the same as no value. */
+const usable = (value) => typeof value === 'string' && value.length > 0 && !value.includes('\0');
+
+const resolveOne = async (spec, { baseEnv, resolveSecret }) => {
+  if (spec.from === 'env') return baseEnv[spec.ref || spec.name];
+  if (spec.from === 'file') return (await readFile(spec.ref, 'utf8')).replace(/\r?\n$/, '');
+  if (typeof resolveSecret !== 'function') return undefined;
+  return resolveSecret(spec.name, spec);
+};
+
+/**
+ * The grant.issued entry for grantMeta. Its scope is the room grant this run
+ * acts under (exact tool names, a connection id), as the host knows it; the
+ * run grant's own credential names and patterns show up in credential.* and
+ * in each permission.decided rule. `taskId` + `podId` bind the grant to that
+ * board task, ending when it is done unless `endsOn` says otherwise.
+ */
+const grantIssued = (meta) => {
+  const {
+    grantId = randomUUID(), parentGrantId, scope = {}, target, issuedBy, expiresAt, taskId, podId, endsOn = 'task.done',
+  } = meta;
+  return {
+    grantId,
+    ...(parentGrantId === undefined ? {} : { parentGrantId }),
+    scope: { tools: [], audience: [], ...scope },
+    ...(target ? { target } : {}),
+    ...(issuedBy ? { issuedBy } : {}),
+    ...(expiresAt ? { expiresAt: expiresAt instanceof Date ? expiresAt.toISOString() : expiresAt } : {}),
+    ...(taskId ? { binding: { taskId, podId, endsOn } } : {}),
+  };
+};
+
+/**
+ * prepareRunEnv({ grant, baseEnv, resolveSecret, root?, require?, trace?, ctx?, grantMeta? })
+ *   → { env, home, cleanup, granted: [names], grantId? }
+ *
+ * `require` lists credential names the adapter cannot run without; one the
+ * grant does not name fails the run as credential_denied before any spawn.
+ * A named credential that cannot be resolved, or that resolves to fewer than
+ * MIN_CREDENTIAL_LENGTH characters, fails it the same way: a run that
+ * silently lacks its key fails later and less legibly, and a value that short
+ * would slip past the refusal-text reader's redaction.
+ *
+ * Events go to `trace`, else ctx.trace: grant.issued (only with grantMeta,
+ * first), then credential.granted {names} or credential.denied {name, reason}.
+ * Values never enter an event or a message, and a hook that offers
+ * redact(values) is handed the resolved values so the record can scrub them
+ * out of agent text too.
+ */
+export const prepareRunEnv = async ({
+  grant, baseEnv = {}, resolveSecret, root, require: required = [], trace, ctx, grantMeta,
+} = {}) => {
+  const valid = validateGrant(grant);
+  const hook = trace && typeof trace.emit === 'function' ? trace : traceOf(ctx);
+  const issued = grantMeta ? grantIssued(grantMeta) : null;
+  if (issued) hook.emit('grant.issued', issued);
+  const realHomes = [...new Set([baseEnv.HOME, homedir()].filter(Boolean))];
+  const DENIED = {
+    not_granted: 'is not in the run grant',
+    unresolved: 'could not be resolved',
+    too_short: `resolved to a value shorter than ${MIN_CREDENTIAL_LENGTH} characters`,
+  };
+  const deny = (name, reason, values) => {
+    hook.emit('credential.denied', { name, reason });
+    return runFailure('credential_denied', `${name} ${DENIED[reason]}`, { credentials: values });
+  };
+
+  const granted = new Set(valid.credentials.map((c) => c.name));
+  const missing = required.find((name) => !granted.has(name));
+  if (missing) throw deny(missing, 'not_granted', []);
+
+  const { home, dirs } = await makeHome(root);
+  const cleanup = () => rm(home, { recursive: true, force: true });
+  const env = { ...pickBaseEnv(baseEnv, realHomes), HOME: home, ...dirs };
+  const values = [];
+  try {
+    for (const spec of valid.credentials) {
+      let value;
+      // A resolver's error text may quote the secret it failed on; drop it.
+      try { value = await resolveOne(spec, { baseEnv, resolveSecret }); } catch { value = undefined; }
+      if (!usable(value)) throw deny(spec.name, 'unresolved', values);
+      // A value this short cannot be told apart from ordinary text, so the
+      // refusal-text reader would not redact it. Refuse it here, before spawn.
+      if (value.length < MIN_CREDENTIAL_LENGTH) throw deny(spec.name, 'too_short', values);
+      values.push(value);
+      env[spec.name] = value;
+    }
+  } catch (error) {
+    await cleanup();
+    throw error;
+  }
+  if (typeof hook.redact === 'function') hook.redact(values);
+  const names = valid.credentials.map((c) => c.name);
+  hook.emit('credential.granted', { names });
+  return { env, home, cleanup, granted: names, ...(issued ? { grantId: issued.grantId } : {}) };
+};

package/node_modules/@commonlyai/seats/src/valet/grant.js

@@ -0,0 +1,118 @@
+/**
+ * A grant says what one run may hold and do: which credentials reach its env,
+ * and which tool calls it may make without asking, only after asking, or never.
+ *
+ *   {
+ *     credentials: [{ name: 'OPENAI_API_KEY', from: 'env'|'file'|'resolver', ref? }],
+ *     tools: { allow: [pattern], ask: [pattern], deny: [pattern] },
+ *   }
+ *
+ * `from: 'env'` copies baseEnv[ref ?? name]; `from: 'file'` reads the absolute
+ * path in `ref`; `from: 'resolver'` asks the host's resolveSecret(name, spec),
+ * with `ref` as an opaque hint for it.
+ *
+ * A tool pattern is `<kind>` or `<kind>:<title glob>`, where kind is one of
+ * ACP's ToolKind values or `*`. `execute` matches every execute call;
+ * `execute:git status*` matches execute calls whose title starts that way;
+ * `*:*.env*` matches any kind by title. Globs know `*` and `?` only.
+ *
+ * The title is text the agent chose. A title-glob deny narrows what the agent
+ * can do; a title-glob allow is only as strong as the agent's honesty about
+ * its title, so prefer kind-level allows and put execute behind ask.
+ *
+ * Precedence is deny > ask > allow, and a call no rule names is denied.
+ *
+ * `network` rules are refused for now rather than accepted and ignored: a run
+ * would believe it was fenced when nothing enforces the fence. TODO: egress
+ * allowlist once a sandbox can enforce it.
+ */
+
+export const TOOL_KINDS = Object.freeze(['read', 'edit', 'delete', 'move', 'search', 'execute', 'think', 'fetch', 'other']);
+export const CREDENTIAL_SOURCES = Object.freeze(['env', 'file', 'resolver']);
+const RULE_LISTS = ['deny', 'ask', 'allow']; // checked in this order: the precedence
+const VALIDATED = Symbol('validated grant');
+
+const ENV_NAME = /^[A-Z_][A-Z0-9_]*$/;
+// Names the run env is built from. A credential under one of these names would
+// overwrite the boundary itself (a granted HOME points back at the real login).
+const RESERVED_NAME = /^(?:HOME|PATH|TMPDIR|USER|LOGNAME|SHELL|PWD|LANG|LC_[A-Z0-9_]+|TERM|TZ|NO_COLOR|CI|SSL_CERT_FILE|SSL_CERT_DIR|XDG_[A-Z0-9_]+)$/;
+
+const fail = (message) => { throw new Error(`grant: ${message}`); };
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const refuseUnknownKeys = (value, allowed, where) => {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) fail(`unknown field ${where}${key}`);
+  }
+};
+
+const globToRegExp = (glob) => new RegExp(`^${glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[\\s\\S]*').replace(/\?/g, '[\\s\\S]')}$`);
+
+/** Parse once at validation so matching never re-reads a malformed pattern. */
+const parsePattern = (pattern, where) => {
+  if (typeof pattern !== 'string' || !pattern.trim()) fail(`${where} must be a non-empty string`);
+  const colon = pattern.indexOf(':');
+  const kind = colon === -1 ? pattern : pattern.slice(0, colon);
+  const title = colon === -1 ? null : pattern.slice(colon + 1);
+  if (kind !== '*' && !TOOL_KINDS.includes(kind)) fail(`${where} names unknown tool kind "${kind}"`);
+  if (title !== null && !title) fail(`${where} has an empty title glob`);
+  return Object.freeze({ pattern, kind, title: title === null ? null : globToRegExp(title) });
+};
+
+const validateCredential = (credential, index, seen) => {
+  const where = `credentials[${index}]`;
+  if (!isPlainObject(credential)) fail(`${where} must be an object`);
+  refuseUnknownKeys(credential, ['name', 'from', 'ref'], `${where}.`);
+  const { name, from, ref } = credential;
+  if (typeof name !== 'string' || !ENV_NAME.test(name)) fail(`${where}.name must be an ENV_NAME (A-Z, 0-9, _)`);
+  if (RESERVED_NAME.test(name)) fail(`${where}.name ${name} is reserved for the run env`);
+  if (seen.has(name)) fail(`${where}.name ${name} is granted twice`);
+  seen.add(name);
+  if (!CREDENTIAL_SOURCES.includes(from)) fail(`${where}.from must be one of ${CREDENTIAL_SOURCES.join(', ')}`);
+  if (ref !== undefined && (typeof ref !== 'string' || !ref)) fail(`${where}.ref must be a non-empty string`);
+  if (from === 'env' && ref !== undefined && !ENV_NAME.test(ref)) fail(`${where}.ref must be an ENV_NAME for from: env`);
+  if (from === 'file' && (ref === undefined || !ref.startsWith('/'))) fail(`${where}.ref must be an absolute path for from: file`);
+  return Object.freeze(ref === undefined ? { name, from } : { name, from, ref });
+};
+
+/** Validate and freeze a grant. Throws on the first problem; never repairs one. */
+export const validateGrant = (grant) => {
+  if (grant && grant[VALIDATED]) return grant;
+  if (!isPlainObject(grant)) fail('must be an object');
+  if ('network' in grant) fail('network rules are not enforced yet; remove the field rather than rely on it');
+  refuseUnknownKeys(grant, ['credentials', 'tools'], '');
+  const credentials = grant.credentials ?? [];
+  if (!Array.isArray(credentials)) fail('credentials must be an array');
+  const seen = new Set();
+  const tools = grant.tools ?? {};
+  if (!isPlainObject(tools)) fail('tools must be an object');
+  refuseUnknownKeys(tools, RULE_LISTS, 'tools.');
+  const rules = {};
+  for (const list of RULE_LISTS) {
+    const patterns = tools[list] ?? [];
+    if (!Array.isArray(patterns)) fail(`tools.${list} must be an array`);
+    rules[list] = Object.freeze(patterns.map((pattern, i) => parsePattern(pattern, `tools.${list}[${i}]`)));
+  }
+  return Object.freeze({
+    [VALIDATED]: true,
+    credentials: Object.freeze(credentials.map((c, i) => validateCredential(c, i, seen))),
+    tools: Object.freeze(rules),
+  });
+};
+const matches = (parsed, kind, title) => (parsed.kind === '*' || parsed.kind === kind)
+  && (parsed.title === null || parsed.title.test(title));
+
+/**
+ * Which rule decides this tool call. ACP makes `kind` optional and means
+ * `other` when it is absent, so that is what an unknown or missing kind is.
+ * Returns { decision: 'allow'|'ask'|'deny', rule: { list, pattern } }.
+ */
+export const matchToolCall = (grant, toolCall = {}) => {
+  const valid = validateGrant(grant);
+  const kind = TOOL_KINDS.includes(toolCall?.kind) ? toolCall.kind : 'other';
+  const title = typeof toolCall?.title === 'string' ? toolCall.title : '';
+  for (const list of RULE_LISTS) {
+    const hit = valid.tools[list].find((parsed) => matches(parsed, kind, title));
+    if (hit) return { decision: list, rule: { list, pattern: hit.pattern } };
+  }
+  return { decision: 'deny', rule: { list: 'default', pattern: null } };
+};

package/node_modules/@commonlyai/seats/src/valet/permissions.js

@@ -0,0 +1,213 @@
+/**
+ * Turn a grant into ctx.decidePermission: the answer to ACP's
+ * session/request_permission, decided per tool call.
+ *
+ *   allow → the allow_once option
+ *   deny  → the reject_once option, or cancelled when there is none
+ *   ask   → approve({ toolCall, grantRule }) from the host. Only an answer
+ *           that says who gave it decides:
+ *           { approved: true | false, by: <user id>, role, decisionCardId? },
+ *           with `role` an owner role. Anything else (a bare true, 'yes',
+ *           {approved: 1}, an answer naming nobody, a throw, no answer in
+ *           time) is a failed ask, and the policy's default, deny, decides.
+ *           An answer whose role is `pod-member` decides nothing (ADR-033 D5):
+ *           the call stays parked, and approve is called again with
+ *           `refused: { by, role: 'pod-member', reason: 'not_owner' }` so the
+ *           card can show why and wait for the owner.
+ *
+ * allow_always and reject_always are never chosen: either would be remembered
+ * by the agent past this grant, so the next call would skip the check.
+ * An allow rule with no allow_once option therefore denies.
+ */
+import { traceOf } from '../trace/events.js';
+import { argsDigestOf, PARKED_CALL_ROLES, isUserId, policyActorId } from '../record/format.js';
+import { matchToolCall, validateGrant } from './grant.js';
+
+export const DEFAULT_APPROVE_TIMEOUT_MS = 5 * 60 * 1000;
+// An approver that keeps handing back pod-member answers is broken; after this
+// many the ask fails, and the policy's default decides, as for any broken approver.
+export const MAX_REFUSED_ANSWERS = 10;
+
+const optionOfKind = (options, kind) => (Array.isArray(options) ? options : [])
+  .find((option) => option && option.kind === kind && typeof option.optionId === 'string');
+
+const allowAnswer = (options) => {
+  const option = optionOfKind(options, 'allow_once');
+  return option ? { outcome: 'selected', optionId: option.optionId, kind: option.kind } : null;
+};
+const denyAnswer = (options) => {
+  const option = optionOfKind(options, 'reject_once');
+  return option ? { outcome: 'selected', optionId: option.optionId, kind: option.kind } : { outcome: 'cancelled' };
+};
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isText = (value) => typeof value === 'string' && value.length > 0;
+
+// The roles a person can answer a parked call as; `policy` is not a person.
+const ANSWER_ROLES = PARKED_CALL_ROLES.filter((role) => role !== 'policy');
+
+/**
+ * What an approver's answer says. It approves or rejects only when it is an
+ * object whose `approved` is exactly true or false and that names a user id
+ * and an owner role. Any other answer approves nothing: it is a failed ask,
+ * so the record never carries a decision nobody can be held to.
+ */
+const readAnswer = (answer) => {
+  if (!isPlainObject(answer) || typeof answer.approved !== 'boolean') return { verdict: 'failed' };
+  if (!isUserId(answer.by) || !ANSWER_ROLES.includes(answer.role)) return { verdict: 'failed' };
+  return {
+    verdict: answer.approved ? 'approved' : 'rejected',
+    by: answer.by,
+    role: answer.role,
+    ...(isText(answer.decisionCardId) ? { decisionCardId: answer.decisionCardId } : {}),
+  };
+};
+
+const isPodMemberAnswer = (answer) => isPlainObject(answer) && answer.role === 'pod-member';
+
+/**
+ * Wait for the host's approval, bounded. Resolves { verdict, by?, role?,
+ * decisionCardId? }, verdict 'approved' | 'rejected' | 'timed_out' | 'failed'
+ * | 'aborted'; never rejects, so a broken approver becomes a denial rather
+ * than a hung or crashed turn.
+ */
+const awaitApproval = (approve, input, { timeoutMs, signal }) => new Promise((done) => {
+  if (typeof approve !== 'function') { done({ verdict: 'failed' }); return; }
+  if (signal?.aborted) { done({ verdict: 'aborted' }); return; }
+  let finished = false;
+  const finish = (verdict) => {
+    if (finished) return;
+    finished = true;
+    clearTimeout(timer);
+    signal?.removeEventListener?.('abort', onAbort);
+    done(verdict);
+  };
+  const onAbort = () => finish({ verdict: 'aborted' });
+  const timer = setTimeout(() => finish({ verdict: 'timed_out' }), timeoutMs);
+  signal?.addEventListener?.('abort', onAbort, { once: true });
+  let refusals = 0;
+  const ask = (current) => Promise.resolve()
+    .then(() => approve(current))
+    .then((answer) => {
+      if (finished) return;
+      if (!isPodMemberAnswer(answer)) { finish(readAnswer(answer)); return; }
+      // A pod member may not decide a parked call: the call stays parked and
+      // the owner is asked again, with the refusal, inside the same timeout.
+      refusals += 1;
+      if (refusals > MAX_REFUSED_ANSWERS) { finish({ verdict: 'failed' }); return; }
+      const refused = { by: isUserId(answer.by) ? answer.by : null, role: 'pod-member', reason: 'not_owner' };
+      setTimeout(() => { if (!finished) ask({ ...input, refused }); }, 0);
+    }, () => finish({ verdict: 'failed' }));
+  ask(input);
+});
+
+/**
+ * Who decided an ask, for the record. A person who answered is named by the
+ * approver; anything else (no answer in time, an answer naming nobody, a
+ * broken approver, a cancelled run) means the policy's default decided.
+ * Rule-decided calls carry no decidedBy here; the record writer fills in
+ * "policy" for any decision whose rule list is not `ask`.
+ */
+const decider = (approval) => {
+  if (approval.verdict === 'approved' || approval.verdict === 'rejected') {
+    return {
+      decidedBy: approval.by,
+      decidedByRole: approval.role,
+      ...(approval.decisionCardId ? { decisionCardId: approval.decisionCardId } : {}),
+    };
+  }
+  return { decidedBy: 'policy', decidedByRole: 'policy' };
+};
+
+const isAsker = (value) => isPlainObject(value) && isUserId(value.id) && PARKED_CALL_ROLES.includes(value.role);
+
+/**
+ * Who an ask goes to, for permission.requested. `askedOf` is {id, role} or
+ * ({toolCall, grantRule}) => {id, role, decisionCardId?}. A call a
+ * rule decides is asked of the grant's policy. A function that throws or
+ * answers malformed is recorded as asked of the policy too: the record does
+ * not name a person it cannot vouch for.
+ */
+const askOf = (askedOf, input, policy) => {
+  if (input.grantRule?.list !== 'ask') return policy;
+  let answer = askedOf;
+  if (typeof askedOf === 'function') {
+    try { answer = askedOf(input); } catch { answer = null; }
+  }
+  if (!isAsker(answer)) return policy;
+  return {
+    id: answer.id,
+    role: answer.role,
+    ...(isText(answer.decisionCardId) ? { decisionCardId: answer.decisionCardId } : {}),
+  };
+};
+
+/**
+ * createPermissionPolicy(grant, { approve?, trace?, approveTimeoutMs?, signal?, grantId?, askedOf? })
+ *   → (request) => Promise<{outcome:'selected', optionId} | {outcome:'cancelled'}>
+ *
+ * `signal` is the run's AbortSignal: a cancelled run answers a pending ask
+ * with cancelled, which is what ACP asks of a client after session/cancel.
+ * `grantId` is recorded on each decision, to tie it to its grant.issued.
+ * With `askedOf` (above), each request is recorded first as
+ * permission.requested: the question (the tool call's title), who it is
+ * asked of, and the card it rides on. The approver receives that card id.
+ * When the tool call carries `rawInput`, both entries carry its argsDigest.
+ * Given a `trace`, the returned function has `recordsPermissions === true`.
+ */
+export const createPermissionPolicy = (grant, {
+  approve, trace, approveTimeoutMs = DEFAULT_APPROVE_TIMEOUT_MS, signal, grantId, askedOf,
+} = {}) => {
+  const valid = validateGrant(grant);
+  const hook = traceOf({ trace });
+  if (askedOf !== undefined && typeof askedOf !== 'function' && !isAsker(askedOf)) {
+    throw new Error('askedOf must be {id: <user id>, role: <decidedByRole>} or a function returning one');
+  }
+  const policy = { id: policyActorId(grantId), role: 'policy' };
+  const decide = async (request = {}) => {
+    const toolCall = request?.toolCall || {};
+    const options = request?.options;
+    const { decision, rule } = matchToolCall(valid, toolCall);
+    const toolCallId = typeof toolCall.toolCallId === 'string' ? toolCall.toolCallId : null;
+    const argsDigest = argsDigestOf(toolCall.rawInput);
+    let asker = null;
+    if (askedOf !== undefined) {
+      asker = askOf(askedOf, { toolCall, grantRule: rule }, policy);
+      const fallback = `${isText(toolCall.kind) ? toolCall.kind : 'tool'} call`;
+      hook.emit('permission.requested', {
+        toolCallId,
+        options: (Array.isArray(options) ? options : []).filter(isPlainObject).map(({ optionId, kind }) => ({ optionId, kind })),
+        question: isText(toolCall.title) ? toolCall.title : fallback,
+        askedOf: { id: asker.id, role: asker.role },
+        ...(grantId ? { grantId } : {}),
+        ...(asker.decisionCardId ? { decisionCardId: asker.decisionCardId } : {}),
+        ...(argsDigest ? { argsDigest } : {}),
+      });
+    }
+    let approval;
+    let answer;
+    if (decision === 'ask') {
+      const input = { toolCall, grantRule: rule, ...(asker?.decisionCardId ? { decisionCardId: asker.decisionCardId } : {}) };
+      approval = await awaitApproval(approve, input, { timeoutMs: approveTimeoutMs, signal });
+      if (approval.verdict === 'aborted') answer = { outcome: 'cancelled' };
+      else answer = approval.verdict === 'approved' ? allowAnswer(options) : null;
+    } else if (decision === 'allow') {
+      answer = allowAnswer(options);
+    }
+    if (!answer) answer = denyAnswer(options);
+    hook.emit('permission.decided', {
+      outcome: answer.outcome,
+      ...(answer.optionId ? { optionId: answer.optionId, kind: answer.kind } : {}),
+      toolCallId,
+      rule,
+      ...(approval ? { approval: approval.verdict, ...decider(approval) } : {}),
+      ...(grantId ? { grantId } : {}),
+      ...(argsDigest ? { argsDigest } : {}),
+    });
+    return answer.outcome === 'selected' ? { outcome: 'selected', optionId: answer.optionId } : { outcome: 'cancelled' };
+  };
+  // With a trace this writes both permission entries itself, so an adapter
+  // handed it as ctx.decidePermission must not write them again.
+  if (trace) Object.defineProperty(decide, 'recordsPermissions', { value: true });
+  return decide;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.172",
+  "version": "0.1.174",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",
@@ -32,11 +32,16 @@
     "lint:fix": "eslint src --ext .js --fix",
     "test": "node --experimental-vm-modules node_modules/.bin/jest",
     "test:temp-cleanup": "node scripts/verify-temp-cleanup.mjs",
+    "prepack": "node scripts/require-bundled-seats.mjs",
     "prepublishOnly": "node -e \"require('fs').copyFileSync('../docs/agents/skills/commonly/SKILL.md','skills/commonly/SKILL.md')\""
   },
   "dependencies": {
+    "@commonlyai/seats": "file:../packages/seats",
     "commander": "^12.0.0"
   },
+  "bundleDependencies": [
+    "@commonlyai/seats"
+  ],
   "devDependencies": {
     "eslint": "^8.56.0",
     "jest": "^29.7.0"

package/src/commands/agent.js

@@ -22,7 +22,6 @@ import { createHash } from 'crypto';
 
 import { requireSeatModel } from '../lib/adapters/seat-model.js';
 import { createClient } from '../lib/api.js';
-import { copyHandoffMemory } from '../lib/handoff-memory.js';
 import {
   buildSpawnId,
   createSpawnCredentialLease,
@@ -83,6 +82,7 @@ import { detectBwrap } from '../lib/sandbox/bwrap.js';
 import { resolvePublicSandboxMode } from '../lib/sandbox/mode.js';
 import { hostSandboxRefusal, windowsSandboxMessage } from '../lib/sandbox/host-check.js';
 import { prepareMcpBeforeFirstPoll } from '../lib/mcp-first-run.js';
+import { createSeatStop } from '../lib/seat-stop.js';
 import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
 import { describeUpstreamRefusal } from '../lib/upstream-refusal.js';
 import {
@@ -987,6 +987,13 @@ export const performAttach = async ({
   // server via legacy normalization).
   const runtimeType = adapter.runtimeType || adapter.name;
 
+  if (memoryFrom) {
+    const capability = await client.get('/api/registry/install/memory-handoff');
+    if (capability?.installTimeMemoryHandoff !== true) {
+      throw new Error('Server does not support install-time memory handoff; upgrade the server before attaching');
+    }
+  }
+
   // Idempotent publish — already-published is expected and fine. Install will
   // surface the real error if the manifest is truly unusable.
   try {
@@ -1010,7 +1017,9 @@ export const performAttach = async ({
   // on config.environment so cross-driver implementations can realize it
   // server-side without re-reading the user's file.
   const installResult = await client.post('/api/registry/install', {
-    ...(memoryFrom ? { resumeExisting: true } : {}),
+    ...(memoryFrom ? {
+      resumeExisting: true, memoryFrom: { agentName: memoryFrom, instanceId: memoryInstance },
+    } : {}),
     agentName,
     podId,
     displayName: displayName || agentName,
@@ -1034,10 +1043,8 @@ export const performAttach = async ({
   const instanceId = installation.instanceId || 'default';
 
   if (memoryFrom) {
-    const memoryCopy = await copyHandoffMemory(client, {
-      sourceAgentName: memoryFrom, sourceInstanceId: memoryInstance,
-      targetAgentName: installation.agentName, targetInstanceId: instanceId,
-    });
+    const memoryCopy = installResult.memoryCopy;
+    if (!memoryCopy) throw new Error('Server does not support install-time memory handoff; upgrade the server before attaching');
     log(memoryCopy.reason === 'source-empty'
       ? 'hosted agent has no long-term memory to copy'
       : 'hosted long-term memory is present in the local agent');
@@ -3830,12 +3837,16 @@ Docs:
       // SIGTERM is the daemon's idle-boundary handoff signal. `stop()` stops
       // future polls but lets the in-flight turn finish and ack before the
       // event loop drains; exiting here would cut a model turn in half.
-      const requestStop = () => {
+      // seat-stop also arms the supervised-group deadline before launchd's
+      // SIGKILL, and kills any group still live when the process exits.
+      const seatStop = createSeatStop({ name, stop });
+      const requestStop = (signal) => {
         console.log(`\n${stamp()} [${name}] stopping after the current turn...`);
-        stop();
+        seatStop.requestStop(signal);
       };
       process.on('SIGINT', requestStop);
       process.on('SIGTERM', requestStop);
+      process.once('exit', seatStop.onExit);
     });
 
   // ── detach (ADR-005) ──────────────────────────────────────────────────────

package/src/lib/adapters/claude.js

@@ -1,5 +1,6 @@
 import { claudeRuntimeInventory } from '../native-runtime-inventory.js';
 import { observeSpawn, controlsFromArguments } from '../runtime-observation.js';
+import { spawnInOwnGroup, wantsOwnProcessGroup } from '@commonlyai/seats/process-group';
 /**
  * claude adapter — wraps the local `claude` CLI as a Commonly agent.
  *
@@ -301,12 +302,14 @@ const publicSkillPromptArgs = async (skillSources) => {
   return { args: text ? ['--append-system-prompt', text] : [], included };
 };
 
-const runClaude = ({ cmd, args, cwd, env, timeoutMs, credentials = [], spawnImpl = childSpawn, onSpawn, controls = {} }) => new Promise((resolve, reject) => {
-  const proc = spawnImpl(cmd, args, {
+// `ownGroup` is set only under the run supervisor, which kills the child's
+// whole group; unsupervised, the spawn options are exactly what they were.
+const runClaude = ({ cmd, args, cwd, env, timeoutMs, credentials = [], spawnImpl = childSpawn, onSpawn, controls = {}, ownGroup = false }) => new Promise((resolve, reject) => {
+  const proc = spawnInOwnGroup(spawnImpl, cmd, args, {
     cwd,
     env,
     stdio: ['ignore', 'pipe', 'pipe'],
-  });
+  }, { ownGroup });
   observeSpawn(proc, onSpawn, controls);
   let stdout = '';
   let stderr = '';
@@ -920,6 +923,7 @@ export default {
         // the value a tail can echo back.
         credentials: spawnCredentials(spawnCtx),
         spawnImpl: ctx._spawnImpl, onSpawn: ctx.onSpawn, controls: controlsFromArguments(modelArgs, { modelFlag: '--model', effortFlag: '--effort' }), // test seam only — do not use in production
+        ownGroup: wantsOwnProcessGroup(ctx),
       });
       // TASK-440: the context this turn left, read from the transcript the
       // child wrote under its own env (an isolated HOME for public seats).
@@ -974,6 +978,7 @@ export default {
           timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
           credentials: spawnCredentials(retryCtx),
           spawnImpl: ctx._spawnImpl, onSpawn: ctx.onSpawn, controls: controlsFromArguments(modelArgs, { modelFlag: '--model', effortFlag: '--effort' }),
+          ownGroup: wantsOwnProcessGroup(ctx),
         });
         const contextTokens = claudeContextTokens({
           cwd: ctx.cwd, sessionId: freshId,