@commonlyai/cli 0.1.80 → 0.1.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.80",
+  "version": "0.1.84",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/agent.js

@@ -48,6 +48,7 @@ import {
   readPodFocus,
 } from '../lib/pod-focus.js';
 import { claimReleaseFor, ackResultFor } from '../lib/claim-outcome.js';
+import { prepareCommitAttribution } from '../lib/commit-attribution.js';
 import { detectBwrap } from '../lib/sandbox/bwrap.js';
 import { resolvePublicSandboxMode } from '../lib/sandbox/mode.js';
 import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
@@ -190,6 +191,7 @@ export const bootstrapAgentRecordFromEnv = async ({
 
   return {
     agentName,
+    displayName: identity?.displayName || primary?.displayName || agentName,
     instanceId: identity?.instanceId || primary?.instanceId || 'default',
     podId: primary?.podId || null,
     instanceUrl,
@@ -731,6 +733,7 @@ export const performAttach = async ({
     runtimeToken,
     detected,
     wrappedCli: adapter.name,
+    displayName: installation.displayName || displayName || agentName,
     environment,
     workspace,
   };
@@ -907,6 +910,7 @@ export const performRun = ({
   token,
   adapter,
   agentName,
+  displayName = null,
   instanceId = 'default',
   podId = null,
   environment = null,
@@ -1370,11 +1374,28 @@ export const performRun = ({
       };
     }
     let result;
+    let commitAttribution = null;
     try {
+      // The local CLI is a wrapper for a Commonly seat, so its Git commits
+      // carry the seat and the adapter's selected model/effort. `stub` exists
+      // only for tests and has no commit-making child process.
+      if (adapter?.name !== 'stub') {
+        commitAttribution = prepareCommitAttribution({
+          cwd: agentCwd,
+          env: process.env,
+          agentName,
+          displayName,
+          instanceId,
+          adapter: adapter?.name,
+          model: seatEnvironment?.model,
+          effort: seatEnvironment?.effort,
+        });
+      }
       result = await adapter.spawn(frameDecisionForkRule(promptWithFocus), {
         sessionId,
         cwd: agentCwd,
-        env: process.env,
+        env: commitAttribution?.env || process.env,
+        commitAttributionEnv: commitAttribution?.sandboxEnv || null,
         memoryLongTerm,
         environment: seatEnvironment,
         // Runtime context the Claude/Codex adapters expose only to their
@@ -1389,10 +1410,14 @@ export const performRun = ({
         metadata: { event },
       });
     } finally {
-      // Best-effort by construction: `close` logs and returns on a failed
-      // revoke, so a turn that already produced an answer is not failed by
-      // cleanup. The boot sweep collects anything left behind.
-      await lease.close();
+      try {
+        commitAttribution?.cleanup();
+      } finally {
+        // Best-effort by construction: `close` logs and returns on a failed
+        // revoke, so a turn that already produced an answer is not failed by
+        // cleanup. The boot sweep collects anything left behind.
+        await lease.close();
+      }
     }
 
     if (result.newSessionId) {
@@ -2511,7 +2536,7 @@ Docs:
         const envAbsPath = opts.env ? pathResolve(opts.env) : null;
         const {
           installation, instanceId, runtimeToken, detected, wrappedCli,
-          environment, workspace,
+          displayName, environment, workspace,
         } = await performAttach({
           client,
           adapterName,
@@ -2525,6 +2550,7 @@ Docs:
 
         saveAgentToken(opts.name, {
           agentName: opts.name,
+          displayName,
           instanceId,
           podId: opts.pod,
           instanceUrl,
@@ -2717,6 +2743,7 @@ Docs:
         token: record.runtimeToken,
         adapter,
         agentName: record.agentName,
+        displayName: record.displayName || record.agentName,
         instanceId: record.instanceId,
         podId: record.podId,
         environment: record.environment || null,

package/src/commands/inbox.js

@@ -21,6 +21,7 @@ import {
   formatItemLine,
   nextCursorFrom,
   parseCursor,
+  parseWindowMs,
   readCursorFile,
   readInboxToken,
   resolveAccountLabel,
@@ -84,6 +85,9 @@ export const runInboxList = async (opts = {}, deps = {}) => {
     // Validated before the request: a typo in --kind must not cost a network
     // round trip, and must not read a queue the caller did not ask for.
     const kind = normalizeKind(opts.kind);
+    // Validated here with --kind, for the same reason: a typo must not cost a
+    // request, and a caller who asked for a window must not silently get another.
+    const windowMs = parseWindowMs(opts.window);
     // Read and check the cursor BEFORE connecting: this is a local-file fact, and
     // a misuse of the flags must not cost even the identity request that
     // resolves the account.
@@ -103,23 +107,28 @@ export const runInboxList = async (opts = {}, deps = {}) => {
         + `--kind ${cursorIn.kind} --cursor-file <path>.${cursorIn.kind}.`,
       );
     }
-    const sinceMs = cursorIn ? cursorIn.ms : null;
-    const since = cursorIn ? cursorIn.at : null;
+    // The window: W behind the cursor's own stamp, not at it. A row stamped before
+    // the cursor can commit after the read that wrote it, and it is that read's
+    // `since` — not the row — that made it invisible; a read starting W earlier
+    // sees it. The ids already delivered inside the window are what keep the
+    // re-read from printing the old rows again (see lib/inbox.js).
+    const sinceMs = cursorIn ? cursorIn.ms - windowMs : null;
+    const since = sinceMs === null ? null : new Date(sinceMs).toISOString();
 
     const {
       baseUrl, request, account,
     } = await connect(opts, { env, fetchImpl, sleep });
 
-    const { items, meta } = await fetchQueue(request, { podId: opts.pod });
+    const { items, meta } = await fetchQueue(request, { podId: opts.pod, since });
     const selected = filterItems(items, {
       kind,
       sinceMs,
-      // The ids already delivered at the cursor's own millisecond. An item that
-      // shares that millisecond but is not among them arrived after the cursor
-      // was written, and is exactly the row a bare `ms > since` loses.
+      // Everything already delivered inside the window. An item of the same id in
+      // the response is a re-delivery, not news; an item that merely shares its
+      // instant with one is news, which is why this dedupes by id and not by time.
       seenIds: cursorIn ? cursorIn.ids : [],
     });
-    const cursor = nextCursorFrom(selected, cursorIn, kind);
+    const cursor = nextCursorFrom(selected, cursorIn, kind, windowMs);
 
     if (opts.json) {
       log(JSON.stringify({
@@ -138,7 +147,7 @@ export const runInboxList = async (opts = {}, deps = {}) => {
       const counts = countsLine(meta?.countsByKind);
       log(`open: ${Number.isInteger(meta?.count) ? meta.count : items.length}${counts ? ` (${counts})` : ''}`);
       if (selected.length === 0) {
-        log(since ? `(no items newer than ${since})` : '(queue is empty)');
+        log(since ? `(nothing new; the window since ${since} was re-read)` : '(queue is empty)');
       }
       for (const item of selected) log(formatItemLine(item));
       log(`cursor: ${cursor ? cursor.at : ''}`);
@@ -226,16 +235,23 @@ Examples:
   $ commonly inbox list --json | jq '.items[].title'
   $ commonly inbox list --kind decision --pod <podId>
   $ commonly inbox list --cursor-file ~/.commonly/inbox/connector-ops.cursor   # only what is new
+  $ commonly inbox list --cursor-file ~/.commonly/inbox/c.cursor --window 300  # widen the re-read to 5m
   $ commonly inbox ack <attentionItemId>
   $ commonly inbox choose <decisionId> 2
 
-Cost: \`list\` reads the WHOLE queue, one request per 50 items — 550 open
-items is 11 requests — and /api/activity is limited to 60 a minute **keyed on
+Cost: with no cursor, \`list\` reads the WHOLE queue, one request per 50 items —
+550 open items is 11 requests. /api/activity is limited to 60 a minute **keyed on
 the caller's IP**, so every session on one host (and the operator's browser)
-shares that budget. A 429 is backed off and retried twice on the server's own
-\`Retry-After\`, then reported. A cursor narrows what is PRINTED, not what is
-read: the route has no created-since filter yet, so \`--pod\` is the one scope
-that narrows the request itself.
+shares that budget; a 429 is backed off and retried twice on the server's own
+\`Retry-After\`, then reported.
+
+With \`--cursor-file\`, the read instead asks for \`createdAt >= cursor - W\`
+(\`--window\`, default 60s), so a watcher tick is ONE request. W is the margin
+over write-commit latency plus the writer's clock offset — a row is stamped before
+its write commits, so resuming exactly at the cursor would lose it. Rows already
+delivered inside W are dropped by id, which is the re-delivery the window is for.
+The counts printed in the header still describe the whole open set; only the rows
+inside the window are printed.
 
 \`ack\` deliberately ships WITHOUT an \`--all\`: a burst of acks shares that same
 per-IP budget, so a paced loop is the caller's decision and a bulk
@@ -253,6 +269,7 @@ their attention as runtime events, not from this queue.
     .option('--token-file <path>', INBOX_TOKEN_HELP)
     .option('--since <cursor>', 'ISO-8601 timestamp; only items created after it')
     .option('--cursor-file <path>', 'Read the cursor from this file and write the advanced cursor back')
+    .option('--window <seconds>', 'Re-read this far behind the cursor, dropping ids already delivered (default 60; 0 = exact cursor)')
     .option('--kind <kind>', `Only this kind: ${INBOX_KINDS.join('|')}`)
     .option('--pod <podId>', 'Only this pod')
     .option('--json', 'Emit one JSON object (with the resolved account and the cursor)')

package/src/lib/adapters/claude.js

@@ -45,7 +45,7 @@
 
 import { spawn as childSpawn, spawnSync } from 'child_process';
 import { createHash, randomUUID } from 'crypto';
-import { realpathSync } from 'fs';
+import { accessSync, constants, realpathSync } from 'fs';
 import {
   chmod,
   lstat,
@@ -73,6 +73,7 @@ import {
   wrapArgvWithSeatbelt,
 } from '../sandbox/seatbelt.js';
 import { CREDENTIAL_FILE_VAR, CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
+import { supportedGitHooks } from '../commit-attribution.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
 import { prepareMcpSpawn } from '../mcp-home.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
@@ -90,6 +91,22 @@ const DEFAULT_TIMEOUT_MS = (() => {
 })();
 
 const buildPrompt = buildMemoryPreamble;
+const RUNTIME_CREDENTIAL_PLACEHOLDER = '${COMMONLY_AGENT_TOKEN}';
+
+const QUOTE_SHELL_ARGUMENT = (value) => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+const HEADER_TOKEN_HELPER_SOURCE = `import { readFileSync } from 'node:fs';
+
+const credentialFile = process.env.${CREDENTIAL_FILE_VAR};
+if (!credentialFile) throw new Error('missing ${CREDENTIAL_FILE_VAR}');
+const token = readFileSync(credentialFile, 'utf8').trim();
+if (!token) throw new Error('empty ${CREDENTIAL_FILE_VAR}');
+const templates = JSON.parse(readFileSync(process.argv[2], 'utf8'));
+const headers = Object.fromEntries(
+  Object.entries(templates).map(([name, parts]) => [name, parts.join(token)]),
+);
+process.stdout.write(JSON.stringify(headers) + '\\n');
+`;
 
 const PUBLIC_DENIED_TOOLS = [
   'WebSearch',
@@ -289,9 +306,9 @@ const runClaude = ({ cmd, args, cwd, env, timeoutMs, credentials = [], spawnImpl
 
 // Keep Commonly placeholders in the MCP JSON and expose their values only in
 // Claude's per-spawn environment. Claude Code natively expands ${VAR} in MCP
-// command/args/env/url/headers fields. Substituting here used to materialize the raw
-// cm_agent_* bearer token in a transient JSON file, which made the token
-// readable to any co-confined child allowed to read that config directory.
+// command/args/env/url/header fields. Token-bearing HTTP headers are routed
+// through headersHelper below, because a literal expansion would put the
+// credential in Claude's environment and every MCP child's environment.
 //
 // Recognised placeholders:
 //   ${COMMONLY_TOKEN_FILE}    — the PATH of this spawn's credential file
@@ -323,20 +340,67 @@ const buildMcpExpansionEnv = (mcpConfig, ctx) => {
     // added only when the value is non-empty AND the declaration still references
     // it — and `serialized` is the config AFTER the credential rewrite, which is
     // what moves the default declaration off this value and onto the file. A
-    // reference the rewrite cannot move (args, url, headers, or a string that
-    // merely contains the placeholder) keeps the value for that spawn, because
-    // claude substitutes those literally and there is no file channel for them.
-    // That is the measured carve-out, and createMcpConfig warns when it applies
-    // so the seat still carrying the value is named rather than assumed fixed.
+    // reference that cannot use the file channel (args, url, unsupported or
+    // non-HTTP headers, or a string that merely contains the placeholder) keeps
+    // the value for that spawn. createMcpConfig warns when this carve-out applies.
     COMMONLY_AGENT_TOKEN: ctx.runtimeToken || '',
   };
   const output = {};
   for (const [key, value] of Object.entries(values)) {
-    if (value && serialized.includes(`\${${key}}`)) output[key] = value;
+    const referenced = serialized.includes(`\${${key}}`)
+      || (key === CREDENTIAL_FILE_VAR && ctx.headersHelperUsesCredentialFile === true);
+    if (value && referenced) output[key] = value;
   }
   return output;
 };
 
+const isHttpTransport = (server) => {
+  const transport = String(server?.transport || server?.type || '').trim().toLowerCase();
+  return transport === 'http' || transport === 'streamable-http';
+};
+
+const getTokenHeaderTemplates = (server) => {
+  if (!isHttpTransport(server) || !server.headers || typeof server.headers !== 'object') return null;
+  const templates = Object.fromEntries(
+    Object.entries(server.headers)
+      .filter(([, value]) => typeof value === 'string' && value.includes(RUNTIME_CREDENTIAL_PLACEHOLDER))
+      .map(([name, value]) => [name, value.split(RUNTIME_CREDENTIAL_PLACEHOLDER)]),
+  );
+  return Object.keys(templates).length > 0 ? templates : null;
+};
+
+const writePrivateFile = async (path, contents) => {
+  await writeFile(path, contents, { encoding: 'utf8', mode: 0o600 });
+  await chmod(path, 0o600);
+};
+
+// Claude's headersHelper is invoked when an HTTP connection is established and
+// again after an authentication retry. Keep the token out of its config and
+// environment: the helper reads the current per-spawn file on every invocation.
+const createTokenHeaderHelpers = async (mcpServers, dir) => {
+  const servers = mcpServers
+    .map((server, index) => ({ server, index, templates: getTokenHeaderTemplates(server) }))
+    .filter((item) => item.templates);
+  if (servers.length === 0) return new Map();
+
+  const scriptPath = join(dir, 'headers-helper.mjs');
+  await writePrivateFile(scriptPath, HEADER_TOKEN_HELPER_SOURCE);
+  const helpers = new Map();
+  for (const { server, index, templates } of servers) {
+    const templatesPath = join(dir, `headers-${index}.json`);
+    await writePrivateFile(templatesPath, JSON.stringify(templates));
+    helpers.set(server.name, {
+      command: [
+        QUOTE_SHELL_ARGUMENT(process.execPath),
+        QUOTE_SHELL_ARGUMENT(scriptPath),
+        QUOTE_SHELL_ARGUMENT(templatesPath),
+      ].join(' '),
+      headerNames: Object.keys(templates),
+    });
+  }
+  return helpers;
+};
+
 const buildMcpConfig = (mcpServers, ctx = {}) => {
   // Shape: `{ mcpServers: { <name>: { ... } } }` — the standard MCP client
   // config, which claude's `--mcp-config` reads directly.
@@ -367,7 +431,13 @@ const buildMcpConfig = (mcpServers, ctx = {}) => {
         label: 'claude',
       }).env;
     }
-    if (server.headers) entry.headers = { ...server.headers };
+    const headerHelper = ctx.dynamicHeaderHelpers?.get(server.name);
+    if (server.headers) {
+      const headers = { ...server.headers };
+      for (const headerName of headerHelper?.headerNames || []) delete headers[headerName];
+      if (Object.keys(headers).length > 0 || !headerHelper) entry.headers = headers;
+    }
+    if (headerHelper) entry.headersHelper = headerHelper.command;
     mcpServersMap[server.name] = entry;
   }
   return { mcpServers: mcpServersMap };
@@ -389,7 +459,14 @@ const createMcpConfig = async (mcpServers, ctx = {}) => {
     // config — no second lifecycle to get wrong — and so it is inside the one
     // non-workspace path the Seatbelt profile admits.
     credential = writeCredentialFile(ctx.runtimeToken, { agentName: ctx.agentName || 'agent', root: dir });
-    const config = buildMcpConfig(mcpServers, { ...ctx, credentialFile: credential?.path || null });
+    const dynamicHeaderHelpers = credential?.path
+      ? await createTokenHeaderHelpers(mcpServers, dir)
+      : new Map();
+    const config = buildMcpConfig(mcpServers, {
+      ...ctx,
+      credentialFile: credential?.path || null,
+      dynamicHeaderHelpers,
+    });
     await writeFile(
       file,
       JSON.stringify(config, null, 2),
@@ -401,12 +478,13 @@ const createMcpConfig = async (mcpServers, ctx = {}) => {
     const expansionEnv = buildMcpExpansionEnv(config, {
       ...ctx,
       credentialFile: credential?.path || null,
+      headersHelperUsesCredentialFile: dynamicHeaderHelpers.size > 0,
     });
     if (expansionEnv[CREDENTIAL_KEY]) {
       // eslint-disable-next-line no-console
       console.warn(
         `[claude] this declaration references ${CREDENTIAL_KEY} in a field claude `
-        + 'substitutes literally (args, url, headers, or a larger string), so the '
+        + 'substitutes literally (args, url, unsupported headers, or a larger string), so the '
         + "value stays in claude's environment for this spawn and every MCP child "
         + `inherits it. Put the credential on the entry's env to get the file channel.`,
       );
@@ -501,6 +579,23 @@ const prepareArgv = async (innerArgv, ctx) => {
   // get the jail only — a derived Linux seat kept Bash/Write/WebFetch and ran on
   // the operator's own Claude settings inside the namespace (Vera 69578).
   const publicBwrapSandbox = sandboxTrust === 'public' && sandboxMode === 'bwrap';
+  const commitHooksPath = ctx.commitAttributionEnv?.COMMONLY_AGENT_HOOKS_PATH || null;
+  const originalHooksPath = ctx.commitAttributionEnv?.COMMONLY_AGENT_ORIGINAL_HOOKS_PATH || null;
+  const commitHookExecutables = commitHooksPath
+    ? supportedGitHooks().map((hookName) => join(commitHooksPath, hookName))
+    : [];
+  const originalHookExecutables = originalHooksPath
+    ? supportedGitHooks()
+      .map((hookName) => join(originalHooksPath, hookName))
+      .filter((hookPath) => {
+        try {
+          accessSync(hookPath, constants.X_OK);
+          return true;
+        } catch {
+          return false;
+        }
+      })
+    : [];
   // A public trust MUST resolve to an enforced mode. Absent mode is resolved
   // above; anything else that lands here (the literal 'none', a typo, a
   // non-string) used to fall through to the bare `claude` spawn below — an
@@ -539,7 +634,7 @@ const prepareArgv = async (innerArgv, ctx) => {
       claudePath: claudeBin,
       statePath: ctx.publicClaudeState.statePath,
       mcpConfigDir: ctx.mcpConfigDir,
-      executablePaths: mcpExecutables,
+      executablePaths: [...mcpExecutables, ...commitHookExecutables, ...originalHookExecutables],
     });
     return {
       cmd: wrapped[0],
@@ -568,7 +663,7 @@ const prepareArgv = async (innerArgv, ctx) => {
     const claudeBin = resolveClaudePath(claudeEnv);
     const wrapped = wrapArgvWithBwrap([claudeBin, ...innerArgv], env, {
       workspacePath: ctx.cwd,
-      readOnlyPaths: ctx.mcpConfigDir ? [ctx.mcpConfigDir] : [],
+      readOnlyPaths: [ctx.mcpConfigDir, commitHooksPath, originalHooksPath].filter(Boolean),
     });
     return { cmd: wrapped[0], args: wrapped.slice(1), env: claudeEnv };
   }
@@ -691,17 +786,21 @@ export default {
           agentName: ctx.agentName,
         });
       }
+      const claudeEnv = buildClaudeEnv(
+        ctx.env,
+        publicClaudeState,
+        mcpConfig?.expansionEnv,
+        mcpConfig?.credential?.path || null,
+      );
+      if (publicNativeSandbox && ctx.commitAttributionEnv) {
+        Object.assign(claudeEnv, ctx.commitAttributionEnv);
+      }
       const spawnCtx = {
         ...ctx,
         mcpConfigPath: mcpConfig?.file || null,
         mcpConfigDir: mcpConfig?.dir || null,
         publicClaudeState,
-        claudeEnv: buildClaudeEnv(
-          ctx.env,
-          publicClaudeState,
-          mcpConfig?.expansionEnv,
-          mcpConfig?.credential?.path || null,
-        ),
+        claudeEnv,
       };
       const { cmd, args, env } = await prepareArgv(baseArgs, spawnCtx);
       const stdout = await runClaude({

package/src/lib/adapters/codex.js

@@ -39,6 +39,7 @@
 
 import { spawn as childSpawn, spawnSync } from 'child_process';
 import { createHash } from 'crypto';
+import { accessSync, constants } from 'fs';
 import {
   chmod,
   lstat,
@@ -57,6 +58,7 @@ import {
   resolve as pathResolve,
 } from 'path';
 import { CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
+import { supportedGitHooks } from '../commit-attribution.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
 import { prepareMcpSpawn } from '../mcp-home.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
@@ -296,13 +298,38 @@ const preparePublicCodexHome = async (ctx) => {
   return publicHome;
 };
 
-const publicPermissionProfileFlags = (mode) => {
+const publicPermissionProfileFlags = (
+  mode,
+  commitAttributionEnv = null,
+) => {
   if (!PUBLIC_SANDBOX_MODES.has(mode)) {
     throw new Error(
       `public codex agents require sandbox.mode=workspace or read-only, got ${mode || 'unset'}`,
     );
   }
   const workspaceAccess = mode === 'read-only' ? 'read' : 'write';
+  const commitHooksPath = commitAttributionEnv?.COMMONLY_AGENT_HOOKS_PATH || null;
+  const originalHooksPath = commitAttributionEnv?.COMMONLY_AGENT_ORIGINAL_HOOKS_PATH || null;
+  const originalHookPaths = originalHooksPath
+    ? supportedGitHooks()
+      .map((hookName) => join(originalHooksPath, hookName))
+      .filter((hookPath) => {
+        try {
+          accessSync(hookPath, constants.X_OK);
+          return true;
+        } catch {
+          return false;
+        }
+      })
+    : [];
+  // Preserve caller-supplied git config entries alongside the appended
+  // hooksPath entry. The explicit allowlist below admits only these concrete
+  // variable names, not arbitrary environment variables.
+  const gitConfigEnv = Object.keys(commitAttributionEnv || {})
+    .filter((name) => /^GIT_CONFIG_(?:COUNT|KEY_\d+|VALUE_\d+)$/.test(name));
+  const gitConfigKeySet = Object.entries(commitAttributionEnv || {})
+    .filter(([name]) => /^GIT_CONFIG_KEY_\d+$/.test(name))
+    .map(([name, value]) => `${toml(name)}=${toml(value)}`);
   const filesystem = [
     '":minimal"="read"',
     '"~/.commonly"="deny"',
@@ -313,16 +340,42 @@ const publicPermissionProfileFlags = (mode) => {
     '"~/.config"="deny"',
     '"/private/tmp"="deny"',
     `":workspace_roots"={"."="${workspaceAccess}",".commonly/**"="deny",".codex/**"="deny","*.env"="deny","*/*.env"="deny","*/*/*.env"="deny"}`,
+    ...(commitHooksPath ? [`${toml(commitHooksPath)}="read"`] : []),
+    ...originalHookPaths.map((hookPath) => `${toml(hookPath)}="read"`),
   ].join(',');
+  const shellEnvironment = [
+    'PATH', 'HOME', 'TMPDIR', 'LANG', 'LC_*',
+    ...(commitHooksPath ? [
+      ...gitConfigEnv,
+      'COMMONLY_AGENT_GIT_CONFIG_INDEX',
+      'COMMONLY_AGENT_GIT_CONFIG_BASE_COUNT',
+      'COMMONLY_AGENT_HOOKS_PATH',
+      'COMMONLY_AGENT_ORIGINAL_HOOKS_PATH',
+      'COMMONLY_AGENT_SEAT_NAME',
+      'COMMONLY_AGENT_SEAT_ID',
+      'COMMONLY_AGENT_ADAPTER',
+      'COMMONLY_AGENT_MODEL',
+      'COMMONLY_AGENT_EFFORT',
+    ] : []),
+  ];
   return [
     '-c', `default_permissions=${toml(PUBLIC_PERMISSION_PROFILE)}`,
     '-c', `permissions.${PUBLIC_PERMISSION_PROFILE}.filesystem={${filesystem}}`,
     '-c', `permissions.${PUBLIC_PERMISSION_PROFILE}.network.enabled=false`,
     // The MCP launcher receives explicitly forwarded env_vars separately.
-    // Model-generated shell commands inherit only a small non-secret core.
-    '-c', 'shell_environment_policy.inherit="core"',
+    // `core` drops explicit GIT_CONFIG_* and hook metadata before include_only
+    // can admit them. When attribution is active, inherit all then constrain
+    // model shells to the exact allowlist below; keep Codex's default secret
+    // filters enabled.
+    '-c', `shell_environment_policy.inherit="${commitHooksPath ? 'all' : 'core'}"`,
     '-c', 'shell_environment_policy.ignore_default_excludes=false',
-    '-c', 'shell_environment_policy.include_only=["PATH","HOME","TMPDIR","LANG","LC_*"]',
+    '-c', `shell_environment_policy.include_only=${JSON.stringify(shellEnvironment)}`,
+    // Codex's default name filter treats GIT_CONFIG_KEY_n as sensitive. Set
+    // only those key names after filtering; their corresponding values stay
+    // in the allowlisted environment instead of riding argv.
+    ...(gitConfigKeySet.length
+      ? ['-c', `shell_environment_policy.set={${gitConfigKeySet.join(',')}}`]
+      : []),
   ];
 };
 
@@ -337,6 +390,7 @@ const buildArgs = ({
   publicSandboxMode = null,
   model = null,
   effort = null,
+  commitAttributionEnv = null,
 }) => {
   const publicSandbox = publicSandboxMode !== null;
   // `--dangerously-bypass-approvals-and-sandbox` disables codex CLI's
@@ -356,7 +410,10 @@ const buildArgs = ({
     ? [
       '--ignore-user-config',
       '--ignore-rules',
-      ...publicPermissionProfileFlags(publicSandboxMode),
+      ...publicPermissionProfileFlags(
+        publicSandboxMode,
+        commitAttributionEnv,
+      ),
     ]
     : ['--dangerously-bypass-approvals-and-sandbox'];
   const common = [
@@ -562,6 +619,7 @@ export default {
         publicSandboxMode,
         model: ctx.environment?.model,
         effort: ctx.environment?.effort,
+        commitAttributionEnv: ctx.commitAttributionEnv,
       });
       const childEnv = { ...(ctx.env || process.env), ...mcp.forwardedEnv };
       // Derived from the process environment, so the bootstrap export has to be
@@ -573,6 +631,9 @@ export default {
         credentialFile: credential?.path || null,
         keepsValue: mcp.forwardedEnv[CREDENTIAL_KEY] !== undefined,
       });
+      if (publicSandboxMode !== null && ctx.commitAttributionEnv) {
+        Object.assign(childEnv, ctx.commitAttributionEnv);
+      }
       if (publicSandboxMode !== null) {
         childEnv.CODEX_HOME = await preparePublicCodexHome(ctx);
       }

package/src/lib/commit-attribution.js

@@ -0,0 +1,201 @@
+import { Buffer } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import {
+  accessSync,
+  constants,
+  mkdtempSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const GIT_HOOKS = [
+  'applypatch-msg',
+  'pre-applypatch',
+  'post-applypatch',
+  'pre-commit',
+  'pre-merge-commit',
+  'prepare-commit-msg',
+  'commit-msg',
+  'post-commit',
+  'pre-rebase',
+  'post-checkout',
+  'post-merge',
+  'pre-push',
+  'pre-receive',
+  'update',
+  'proc-receive',
+  'post-receive',
+  'post-update',
+  'reference-transaction',
+  'push-to-checkout',
+  'pre-auto-gc',
+  'post-rewrite',
+  'sendemail-validate',
+  'fsmonitor-watchman',
+  'p4-pre-submit',
+  'p4-prepare-changelist',
+  'p4-changelist',
+  'p4-post-changelist',
+  'post-index-change',
+];
+
+const cleanSingleLine = (value, fallback) => {
+  let cleaned = '';
+  for (const character of String(value ?? '')) {
+    const codePoint = character.codePointAt(0);
+    cleaned += codePoint <= 0x1f || codePoint === 0x7f ? ' ' : character;
+  }
+  cleaned = cleaned
+    .replace(/[<>]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return cleaned || fallback;
+};
+
+// Use an email-local-part-safe reversible id. URI escapes introduce `%`, which
+// Git does not accept in a co-author trailer address. Keep the reversible form
+// while it fits the 64-character email local-part limit; longer identities use
+// a stable hash so GitHub can still lift the co-author on squash.
+const seatAddressId = (agentName, instanceId) => {
+  const identity = JSON.stringify([
+    cleanSingleLine(agentName, 'agent'),
+    cleanSingleLine(instanceId, 'default'),
+  ]);
+  const reversibleId = Buffer.from(identity).toString('base64url');
+  if (reversibleId.length <= 64) return reversibleId;
+  return `sha256-${createHash('sha256').update(identity).digest('base64url')}`;
+};
+
+const resolveOriginalHooksPath = (cwd, env) => {
+  const result = spawnSync(
+    'git',
+    ['rev-parse', '--path-format=absolute', '--git-path', 'hooks'],
+    { cwd, env, encoding: 'utf8' },
+  );
+  if (result.status !== 0 || !result.stdout.trim()) return null;
+  const hooksPath = resolve(result.stdout.trim());
+  try {
+    return statSync(hooksPath).isDirectory() ? hooksPath : null;
+  } catch {
+    return null;
+  }
+};
+
+const resolveGitConfigCount = (env) => {
+  const raw = env.GIT_CONFIG_COUNT ?? '0';
+  if (!/^(0|[1-9]\d*)$/.test(String(raw))) {
+    throw new Error(`cannot enable commit attribution: GIT_CONFIG_COUNT is invalid (${raw})`);
+  }
+  const count = Number(raw);
+  if (!Number.isSafeInteger(count)) {
+    throw new Error('cannot enable commit attribution: GIT_CONFIG_COUNT is out of range');
+  }
+  return count;
+};
+
+const wrapperHook = () => `#!/bin/sh
+# Commonly CLI commit attribution. Preserve the repository's configured hooks.
+hook_name=\${0##*/}
+config_index=$COMMONLY_AGENT_GIT_CONFIG_INDEX
+base_count=$COMMONLY_AGENT_GIT_CONFIG_BASE_COUNT
+case "$config_index:$base_count" in
+  *[!0-9:]*|:*) exit 1 ;;
+esac
+GIT_CONFIG_COUNT=$base_count
+export GIT_CONFIG_COUNT
+unset "GIT_CONFIG_KEY_$config_index" "GIT_CONFIG_VALUE_$config_index"
+
+original_hooks=\${COMMONLY_AGENT_ORIGINAL_HOOKS_PATH:-}
+if [ -n "$original_hooks" ] && [ "$original_hooks" != "$COMMONLY_AGENT_HOOKS_PATH" ]; then
+  original_hook="$original_hooks/$hook_name"
+  if [ -x "$original_hook" ]; then
+    "$original_hook" "$@"
+    hook_status=$?
+    if [ "$hook_status" -ne 0 ]; then
+      exit "$hook_status"
+    fi
+  fi
+fi
+
+if [ "$hook_name" = "prepare-commit-msg" ] && [ -n "$1" ]; then
+  git interpret-trailers --in-place --if-exists=addIfDifferent \\
+    --trailer "Co-authored-by: $COMMONLY_AGENT_SEAT_NAME <$COMMONLY_AGENT_SEAT_ID@agents.commonly.invalid>" \\
+    --trailer "Agent-Model: $COMMONLY_AGENT_ADAPTER/$COMMONLY_AGENT_MODEL/$COMMONLY_AGENT_EFFORT" \\
+    "$1"
+  exit $?
+fi
+exit 0
+`;
+
+/**
+ * Install a per-spawn Git hook proxy and return an environment for the CLI
+ * child. The proxy delegates every standard hook to the repository's original
+ * hook directory, then adds Commonly trailers after an existing
+ * prepare-commit-msg hook has had its say.
+ */
+export const prepareCommitAttribution = ({
+  cwd,
+  env = process.env,
+  agentName,
+  displayName,
+  instanceId = 'default',
+  adapter,
+  model,
+  effort,
+}) => {
+  const configIndex = resolveGitConfigCount(env);
+  const originalHooksPath = resolveOriginalHooksPath(cwd, env);
+  const hooksDirectory = mkdtempSync(join(tmpdir(), 'commonly-agent-hooks-'));
+  try {
+    const hookSource = wrapperHook();
+    for (const hookName of GIT_HOOKS) {
+      const hookPath = join(hooksDirectory, hookName);
+      writeFileSync(hookPath, hookSource, { encoding: 'utf8', mode: 0o700 });
+      accessSync(hookPath, constants.X_OK);
+    }
+  } catch (error) {
+    rmSync(hooksDirectory, { recursive: true, force: true });
+    throw error;
+  }
+
+  const safeAdapter = cleanSingleLine(adapter, 'unknown');
+  const metadataEnv = {
+    COMMONLY_AGENT_GIT_CONFIG_INDEX: String(configIndex),
+    COMMONLY_AGENT_GIT_CONFIG_BASE_COUNT: String(configIndex),
+    COMMONLY_AGENT_HOOKS_PATH: hooksDirectory,
+    ...(originalHooksPath ? { COMMONLY_AGENT_ORIGINAL_HOOKS_PATH: originalHooksPath } : {}),
+    COMMONLY_AGENT_SEAT_NAME: cleanSingleLine(displayName || agentName, 'agent'),
+    COMMONLY_AGENT_SEAT_ID: seatAddressId(agentName, instanceId),
+    COMMONLY_AGENT_ADAPTER: safeAdapter,
+    COMMONLY_AGENT_MODEL: cleanSingleLine(model, 'default'),
+    COMMONLY_AGENT_EFFORT: cleanSingleLine(effort, 'default'),
+  };
+  const attributionEnv = {
+    ...env,
+    GIT_CONFIG_COUNT: String(configIndex + 1),
+    [`GIT_CONFIG_KEY_${configIndex}`]: 'core.hooksPath',
+    [`GIT_CONFIG_VALUE_${configIndex}`]: hooksDirectory,
+    ...metadataEnv,
+  };
+  const sandboxEnv = {
+    ...metadataEnv,
+    GIT_CONFIG_COUNT: '1',
+    GIT_CONFIG_KEY_0: 'core.hooksPath',
+    GIT_CONFIG_VALUE_0: hooksDirectory,
+    COMMONLY_AGENT_GIT_CONFIG_INDEX: '0',
+    COMMONLY_AGENT_GIT_CONFIG_BASE_COUNT: '0',
+  };
+
+  return {
+    env: attributionEnv,
+    sandboxEnv,
+    hooksDirectory,
+    cleanup: () => rmSync(hooksDirectory, { recursive: true, force: true }),
+  };
+};
+
+export const supportedGitHooks = () => [...GIT_HOOKS];

package/src/lib/inbox.js

@@ -24,20 +24,30 @@
  * `list` prints both, labelled, so neither command has to be discovered by
  * failing first.
  *
- * The cursor is a TIMESTAMP PLUS the ids delivered at exactly that timestamp,
- * compared against `createdAt` — the only field on an item that never moves. The
- * queue's ORDER moves as items are acknowledged (priority, then newest first),
+ * The cursor is a TIMESTAMP PLUS the ids delivered INSIDE A WINDOW that ends at
+ * it, compared against `createdAt` — the only field on an item that never moves.
+ * The queue's ORDER moves as items are acknowledged (priority, then newest first),
  * so an offset cursor would skip rows; `createdAt` cannot.
  *
- * The ids are not decoration. A bare `ms > since` cursor loses any row that
- * shares its millisecond with the cursor and was inserted after the cursor was
- * written: the next run compares `ms > since` (false), nothing prints it, and no
- * later run can see it either, because the cursor never moves. That row is gone
- * silently and forever — the one failure this queue (576 open items, none ever
- * read) cannot afford. So the cursor carries the ids it already delivered at its
- * own millisecond and re-prints only the ones it did not: `ms > sinceMs ||
- * (ms === sinceMs && !delivered.has(id))`. A legacy plain-timestamp cursor parses
- * with an EMPTY set, which degrades toward re-printing rather than skipping.
+ * The window is what makes the cursor safe, and the ids are not decoration. A row
+ * is stamped from the WRITER's clock at the moment of the write and becomes
+ * visible only when that write commits, so a row can carry a stamp before the
+ * cursor and appear after the read that wrote it — and it is not late, it is
+ * simply invisible to a reader who resumes at the cursor. Starting a read W
+ * behind the cursor (`--window`, default 60s) makes that row visible on the next
+ * tick; the ids already delivered inside that window are then dropped, so the
+ * re-read prints only what the caller has not seen. A bare `ms > since` cursor
+ * loses such a row silently and forever — the one failure this queue (576 open
+ * items, none ever read) cannot afford, which is why the recoverable direction
+ * (re-printing, deduped by `attentionItemId`) is always the one taken here. A
+ * legacy plain-timestamp cursor parses with an EMPTY set, which degrades toward
+ * re-printing rather than skipping.
+ *
+ * The window is NOT a guess about clock skew alone: W must exceed the write's
+ * commit latency PLUS the writer's clock offset, and a caller that sets it to 0
+ * gets the exact-cursor behaviour (resume at the cursor, dedupe only the ids
+ * stamped with it). The ids are pruned to the window on every write, so the
+ * cursor file stays the size of one window of deliveries instead of growing.
  *
  * THE GENERAL RULE, which both cursor bugs above are instances of: a resume
  * cursor is valid only for the query that wrote it. `--kind` is a DIFFERENT
@@ -168,6 +178,24 @@ export const parseCursor = (value) => {
   };
 };
 
+/**
+ * `--window <seconds>`: how far behind the cursor a read starts. The default is
+ * the spec's 60s — the margin over in-cluster write latency and clock offset —
+ * and 0 restores the exact-cursor behaviour. Refused rather than clamped: a
+ * negative or unreadable window would silently change which rows a read can see,
+ * and that is the failure this whole module is built to avoid.
+ */
+export const DEFAULT_WINDOW_MS = 60 * 1000;
+
+export const parseWindowMs = (value, fallback = DEFAULT_WINDOW_MS) => {
+  if (value === undefined || value === null || value === '') return fallback;
+  const seconds = Number(String(value).trim());
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    throw new InboxRefusal(`--window must be a number of seconds >= 0, not ${value}.`);
+  }
+  return Math.round(seconds * 1000);
+};
+
 /** A missing cursor file is "nothing seen yet", not an error. */
 export const readCursorFile = (filePath) => {
   if (!filePath) return null;
@@ -217,28 +245,46 @@ export const cursorKeyOf = (item) => String(item?.attentionItemId || item?.id ||
 /**
  * An item with an unparseable `createdAt` is KEPT under a cursor: dropping it
  * would lose the row silently, and re-printing is the recoverable error. The same
- * argument decides the millisecond boundary — see the module header.
+ * argument decides the boundary — see the module header.
+ *
+ * `seenIds` is the set delivered inside the window and is dropped BY ID, whatever
+ * the item's timestamp: the window exists to re-serve those rows to the server
+ * call, and the id is the only thing that can say "the caller already saw this
+ * one". `sinceMs` is the window's own start and is inclusive, matching the
+ * route's bound, so a row stamped exactly at it still prints.
  */
 export const filterItems = (items, { kind = null, sinceMs = null, seenIds = [] } = {}) => {
   const delivered = seenIds instanceof Set ? seenIds : new Set(seenIds);
   return (items || []).filter((item) => {
     if (kind && item?.kind !== kind) return false;
+    if (delivered.has(cursorKeyOf(item))) return false;
     if (sinceMs === null) return true;
     const ms = itemCreatedAtMs(item);
     if (ms === null) return true;
-    if (ms > sinceMs) return true;
-    return ms === sinceMs && !delivered.has(cursorKeyOf(item));
+    return ms >= sinceMs;
   });
 };
 
 /**
- * Newest timestamp delivered, so the next call resumes exactly where this one
- * ended — plus the ids delivered AT that timestamp, which are what make the
- * boundary safe to resume from. Those ids are carried forward only while the
- * timestamp stays put; once it moves, they can never match again (the check needs
- * `ms === sinceMs`) and carrying them would grow the file for nothing.
+ * Newest timestamp this query has covered — the previous cursor's stamp or the
+ * newest item printed, whichever is later — so the next call resumes from W behind
+ * it, plus every id delivered at or after that window's start, which is what the
+ * next read's window will re-serve and must therefore not print twice.
+ *
+ * The max is taken over the PRINTED items, not the server's `nextSince`, because
+ * `--kind` is filtered on this side: the server's window may hold rows of other
+ * kinds that this read will never print, and advancing the cursor onto them would
+ * move the high-water mark past a row of THIS kind that a later page has not
+ * delivered yet. When nothing printed, the cursor stays where it was — the
+ * fallback — so a quiet tick does not move the mark at all.
+ *
+ * The set is recomputed from the window plus the ids the previous cursor had not
+ * yet aged out of it, and both halves are load-bearing: this read's items are
+ * post-dedupe, so a row it dropped is absent from them and would be forgotten
+ * without the carry. The prune is what bounds the file at one window of
+ * deliveries instead of a list of everything ever printed.
  */
-export const nextCursorFrom = (items, fallback = null, kind = null) => {
+export const nextCursorFrom = (items, fallback = null, kind = null, windowMs = DEFAULT_WINDOW_MS) => {
   let max = null;
   for (const item of items || []) {
     const ms = itemCreatedAtMs(item);
@@ -246,15 +292,33 @@ export const nextCursorFrom = (items, fallback = null, kind = null) => {
     if (max === null || ms > max) max = ms;
   }
   if (max === null) return fallback;
-  const at = new Date(max).toISOString();
-  const boundary = (items || []).filter((item) => itemCreatedAtMs(item) === max)
-    .map(cursorKeyOf).filter(Boolean);
-  const carried = fallback && fallback.ms === max ? (fallback.ids || []) : [];
+  // A high-water mark: the newest item printed, or the cursor that came in,
+  // whichever is later. A row printed from inside the window is older than the
+  // mark that delimited that window, and letting it drag the mark back would move
+  // the next read's `since` back with it — reopening ground this query has already
+  // covered and moving the prune cutoff that bounds the id set.
+  const mark = fallback && Number.isFinite(fallback.ms) && fallback.ms > max ? fallback.ms : max;
+  const at = new Date(mark).toISOString();
+  const cutoff = mark - windowMs;
+  const inWindow = (items || []).filter((item) => {
+    const ms = itemCreatedAtMs(item);
+    return ms !== null && ms >= cutoff;
+  }).map(cursorKeyOf).filter(Boolean);
+  // The ids from the previous cursor are NOT dead weight, and dropping them is a
+  // measurable bug: `items` is what this read SELECTED, so a row delivered last
+  // tick has already been filtered out of it, and the set built from `items` alone
+  // would forget it — then the read after that would print it again, and the
+  // dedupe would alternate every tick. They are carried only while the previous
+  // cursor's own stamp is still inside this window; past that the next read's
+  // `since` is later than every one of them, the server can never re-serve them,
+  // and keeping them would grow the file for nothing.
+  const carried = fallback && Number.isFinite(fallback.ms) && fallback.ms >= cutoff
+    ? (fallback.ids || []) : [];
   // The kind is the CURRENT read's, never inherited: the cursor describes the
   // query that just ran, and a mismatch with the file's own kind is what the
   // command refuses on before it makes a request.
   return {
-    at, ms: max, ids: [...new Set([...carried, ...boundary])], kind: kind || null,
+    at, ms: mark, ids: [...new Set([...carried, ...inWindow])], kind: kind || null,
   };
 };
 
@@ -371,21 +435,31 @@ export const createInboxRequest = ({
  * that reports `hasMore: true` beside an empty page would otherwise spin
  * forever, and one that lies about `count` would page past the end.
  */
-export const fetchQueue = async (request, { podId } = {}) => {
+export const fetchQueue = async (request, { podId, since } = {}) => {
   const items = [];
   let meta = {};
   let offset = 0;
   for (;;) {
     // eslint-disable-next-line no-await-in-loop
     const page = await request('/api/activity/decision-queue', {
-      params: { limit: API_PAGE_LIMIT, offset, ...(podId ? { podId } : {}) },
+      params: {
+        limit: API_PAGE_LIMIT,
+        offset,
+        ...(podId ? { podId } : {}),
+        // Only sent when there is a cursor: a first read is asking for everything
+        // the account has, and a bound there would silently hide its older half.
+        ...(since ? { since } : {}),
+      },
     });
     const batch = Array.isArray(page?.items) ? page.items : [];
     items.push(...batch);
     meta = page || {};
     if (!meta.hasMore) break;
     if (batch.length === 0) break;
-    if (Number.isInteger(meta.count) && items.length >= meta.count) break;
+    // A bounded call reports the WHOLE open set in `count` and the window in
+    // `windowCount`, so stopping on `count` would page past the window's end.
+    const reported = since && Number.isInteger(meta.windowCount) ? meta.windowCount : meta.count;
+    if (Number.isInteger(reported) && items.length >= reported) break;
     offset += batch.length;
   }
   return { items, meta };