@atollhq/skill-codex 0.4.23 → 0.4.25

package/README.md

@@ -6,13 +6,27 @@ Gives your Codex agent the ability to manage tasks, goals, KPIs, initiatives, mi
 
 ## Install
 
+Install or refresh the local skill files without configuring credentials:
+
+```bash
+npx --yes @atollhq/skill-codex@latest
+```
+
+Bare invocation and `--install-only` only update `~/.codex/skills/atoll/`, the profile-neutral routing hint, and compatibility references. They do not inspect or change Atoll credentials, profiles, shell files, or repo configuration, even when `ATOLL_*` variables are present.
+
+Configure a named profile explicitly:
+
+```bash
+npx --yes @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org org-uuid --project project-id --team team-id
+```
+
+For intentional environment configuration, use `--configure`:
+
 ```bash
-npx @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org your-org-id --project project-id --team team-id
-# or
-ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=your-org-id npx @atollhq/skill-codex@latest
+ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=org-uuid npx --yes @atollhq/skill-codex@latest --configure
 ```
 
-Optional defaults: `--project`, `--team`, and `--base-url` are stored with the selected mode. Use `--no-project`, `--no-team`, or `--no-base-url` to clear previously saved defaults. Pass `--profile` to store credentials and defaults only in that named Atoll CLI profile. The installer does not write global `ATOLL_*` exports to `~/.zshrc` or `~/.bashrc` in profile mode. Use `atoll --profile agent-a ...` for profile-scoped commands, or omit `--profile` to use env-var mode.
+Configuration mode supports `--project`, `--team`, and `--base-url`. Use `--no-project`, `--no-team`, or `--no-base-url` to clear saved defaults. Pass `--profile` to store credentials and defaults only in that named Atoll CLI profile. The installer does not write global `ATOLL_*` exports in profile mode. Use `atoll --profile agent-a ...` for profile-scoped commands.
 
 For multi-org setups, keep global Codex instructions neutral and bind profiles per repo:
 
@@ -25,16 +39,16 @@ npx @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org your-
 
 Get an agent API key from **Agents** in the Atoll app. Integration keys are managed from **Settings > Integrations**.
 
-This does six things:
+Every invocation installs the local skill assets, routing hint, and compatibility references. Configuration mode additionally:
 
 1. Installs the `atoll` skill to `~/.codex/skills/atoll/`
 2. Appends (or updates) a small profile-neutral Atoll skill routing hint in `~/.codex/AGENTS.md`
 3. Copies API reference files to `~/.codex/atoll-references/`
 4. Creates or updates the named Atoll CLI profile when `--profile` is provided
-5. Appends Atoll env var exports to your shell profile (`~/.zshrc` or `~/.bashrc`) only when no profile is provided
+5. Appends Atoll env var exports to your shell profile (`~/.zshrc` or `~/.bashrc`) when `--configure` is used without a profile
 6. Optionally writes repo-local profile guidance when `--write-project-instructions` is provided
 
-For profile mode, Codex has the Atoll skill immediately, global Codex guidance points to that skill without embedding the full Atoll guide, and terminal commands can use `atoll --profile agent-a ...`. For env-var mode, the installer writes `ATOLL_ENV_MODE=1` with the credential exports; open a fresh shell or `source` your profile.
+For profile mode, Codex has the Atoll skill immediately, global Codex guidance points to that skill without embedding the full Atoll guide, and terminal commands can use `atoll --profile agent-a ...`. For explicitly requested env-var mode, the installer writes `ATOLL_ENV_MODE=1` with the credential exports; open a fresh shell or `source` your profile.
 
 Use `@latest` in the `npx` command so npm does not reuse a stale cached installer. In profile mode, the installer prints its package version and a verification command; run `atoll --profile agent-a agent-context --json` if you need to confirm the profile was created.
 

package/bin/install.mjs

@@ -22,45 +22,86 @@ import { fileURLToPath } from 'node:url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'))
+const configurationFlags = new Set([
+  '--configure',
+  '--profile',
+  '--key',
+  '--org',
+  '--project',
+  '--no-project',
+  '--team',
+  '--no-team',
+  '--base-url',
+  '--no-base-url',
+  '--write-project-instructions',
+  '--project-dir',
+  '--instruction-files',
+  '--force-project-instructions',
+])
+const valueFlags = {
+  '--profile': 'profile',
+  '--key': 'key',
+  '--org': 'org',
+  '--project': 'project',
+  '--team': 'team',
+  '--base-url': 'baseUrl',
+  '--project-dir': 'projectDir',
+  '--instruction-files': 'instructionFiles',
+}
+
+function hasConfigurationIntent(argv) {
+  return argv.slice(2).some((arg) => configurationFlags.has(arg.split('=', 1)[0]))
+}
 
 function parseArgs(argv) {
   const args = {}
   for (let i = 2; i < argv.length; i++) {
-    if (argv[i] === '--profile' && argv[i + 1]) args.profile = argv[++i]
-    else if (argv[i] === '--key' && argv[i + 1]) args.key = argv[++i]
-    else if (argv[i] === '--org' && argv[i + 1]) args.org = argv[++i]
-    else if (argv[i] === '--project' && argv[i + 1]) args.project = argv[++i]
-    else if (argv[i] === '--no-project') args.clearProject = true
-    else if (argv[i] === '--team' && argv[i + 1]) args.team = argv[++i]
-    else if (argv[i] === '--no-team') args.clearTeam = true
-    else if (argv[i] === '--base-url' && argv[i + 1]) args.baseUrl = argv[++i]
-    else if (argv[i] === '--no-base-url') args.clearBaseUrl = true
-    else if (argv[i] === '--write-project-instructions') args.writeProjectInstructions = true
-    else if (argv[i] === '--project-dir' && argv[i + 1]) args.projectDir = argv[++i]
-    else if (argv[i] === '--instruction-files' && argv[i + 1]) args.instructionFiles = argv[++i]
-    else if (argv[i] === '--force-project-instructions') args.forceProjectInstructions = true
-    else if (argv[i] === '--help' || argv[i] === '-h') args.help = true
+    const argument = argv[i]
+    const separator = argument.indexOf('=')
+    const flag = separator === -1 ? argument : argument.slice(0, separator)
+    const inlineValue = separator === -1 ? undefined : argument.slice(separator + 1)
+    const nextValue = inlineValue ?? argv[i + 1]
+    const valueKey = valueFlags[flag]
+    if (valueKey) {
+      if (!nextValue || nextValue.startsWith('-')) {
+        throw new Error(`${flag} requires a non-empty value`)
+      }
+      args[valueKey] = nextValue
+      if (inlineValue === undefined) i++
+    } else if (flag === '--no-project') args.clearProject = true
+    else if (flag === '--no-team') args.clearTeam = true
+    else if (flag === '--no-base-url') args.clearBaseUrl = true
+    else if (flag === '--install-only') args.installOnly = true
+    else if (flag === '--configure') args.configure = true
+    else if (flag === '--write-project-instructions') args.writeProjectInstructions = true
+    else if (flag === '--force-project-instructions') args.forceProjectInstructions = true
+    else if (flag === '--help' || flag === '-h') args.help = true
+    else throw new Error(`Unknown option: ${flag}`)
   }
   return args
 }
 
 function printUsage() {
   console.log(`
-Usage: npx @atollhq/skill-codex@latest [--profile <name>] --key <api-key> --org <org-id> [--project <id>] [--team <id-or-slug>] [--base-url <url>]
-   or: ATOLL_API_KEY=<api-key> ATOLL_ORG_ID=<org-id> npx @atollhq/skill-codex@latest
+Usage: npx @atollhq/skill-codex@latest --install-only
+   or: npx @atollhq/skill-codex@latest --configure [--profile <name>] --key <api-key> --org <org-id> [--project <id>] [--team <id-or-slug>] [--base-url <url>]
+   or: ATOLL_API_KEY=<api-key> ATOLL_ORG_ID=<org-id> npx @atollhq/skill-codex@latest --configure
 
 Options:
-  --profile   Atoll CLI profile name to create/update. Profile mode does not write shell env vars.
-  --key       Atoll API key (sk_atoll_...). Defaults to ATOLL_API_KEY.
-  --org       Organization ID. Defaults to ATOLL_ORG_ID.
-  --project   Default project ID. Defaults to ATOLL_PROJECT.
+  --profile   Atoll CLI profile name to create/update. Enables configuration mode.
+  --key       Atoll API key (sk_atoll_...). Used in configuration mode; defaults to ATOLL_API_KEY.
+  --org       Organization ID. Used in configuration mode; defaults to ATOLL_ORG_ID.
+  --project   Default project ID. Used in configuration mode; defaults to ATOLL_PROJECT.
   --no-project Clear any saved default project.
-  --team      Default team ID or slug. Defaults to ATOLL_TEAM.
+  --team      Default team ID or slug. Used in configuration mode; defaults to ATOLL_TEAM.
   --no-team   Clear any saved default team.
-  --base-url  Atoll base URL. Defaults to ATOLL_BASE_URL.
+  --base-url  Atoll base URL. Used in configuration mode; defaults to ATOLL_BASE_URL.
   --no-base-url Clear any saved custom base URL.
+  --install-only
+              Install or refresh local skill files without reading or changing credentials.
+  --configure Explicitly enable profile or environment credential configuration.
   --write-project-instructions
-              Write a small repo-local Atoll profile block. Requires --profile.
+              Write a small repo-local Atoll profile block. Requires --configure and --profile.
   --project-dir
               Directory for repo-local instructions. Defaults to the current directory.
   --instruction-files
@@ -72,24 +113,35 @@ Options:
 Installs the Atoll integration for Codex CLI:
   - Installs the atoll skill to ~/.codex/skills/atoll/
   - Writes a small AGENTS.md routing hint to ~/.codex/
-  - Creates/updates an Atoll CLI profile when --profile is provided
+  - Leaves authentication and profile configuration unchanged by default
+  - Creates/updates credentials only when --configure or another configuration flag is provided
   - Optionally writes repo-local AGENTS.md/CLAUDE.md profile guidance with --write-project-instructions
-  - Otherwise writes Atoll env vars to your shell profile for env-var mode
 `)
 }
 
 const args = parseArgs(process.argv)
-args.key ??= process.env.ATOLL_API_KEY
-args.org ??= process.env.ATOLL_ORG_ID
-if (args.clearProject) delete args.project
-else args.project ??= process.env.ATOLL_PROJECT
-if (args.clearTeam) delete args.team
-else args.team ??= process.env.ATOLL_TEAM
-if (args.clearBaseUrl) delete args.baseUrl
-else args.baseUrl ??= process.env.ATOLL_BASE_URL
+const configurationIntent = hasConfigurationIntent(process.argv)
+
+if (args.installOnly && configurationIntent) {
+  console.error('Error: --install-only cannot be combined with credential or profile configuration flags')
+  printUsage()
+  process.exit(1)
+}
 
 if (args.help) { printUsage(); process.exit(0) }
 
+const configureMode = configurationIntent
+if (configureMode) {
+  args.key ??= process.env.ATOLL_API_KEY
+  args.org ??= process.env.ATOLL_ORG_ID
+  if (args.clearProject) delete args.project
+  else args.project ??= process.env.ATOLL_PROJECT
+  if (args.clearTeam) delete args.team
+  else args.team ??= process.env.ATOLL_TEAM
+  if (args.clearBaseUrl) delete args.baseUrl
+  else args.baseUrl ??= process.env.ATOLL_BASE_URL
+}
+
 console.log(`Running @atollhq/skill-codex installer v${packageJson.version}`)
 
 const instructionFileChoices = (args.instructionFiles ?? 'agents')
@@ -118,13 +170,13 @@ if (args.writeProjectInstructions && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(args.p
   process.exit(1)
 }
 
-if (!args.key || !args.org) {
+if (configureMode && (!args.key || !args.org)) {
   console.error('Error: provide --key and --org, or set ATOLL_API_KEY and ATOLL_ORG_ID\n')
   printUsage()
   process.exit(1)
 }
 
-if (!args.key.startsWith('sk_atoll_')) {
+if (configureMode && !args.key.startsWith('sk_atoll_')) {
   console.error('Error: API key must start with sk_atoll_')
   process.exit(1)
 }
@@ -164,6 +216,52 @@ function ensurePrivateDirectory(path) {
   chmodSync(path, 0o700)
 }
 
+function prepareSkillDirectory(path, source) {
+  const existing = lstatIfExists(path)
+  if (existing) {
+    if (existing.isSymbolicLink()) {
+      throw new Error(`Refusing symbolic link for skill directory: ${path}`)
+    }
+    if (!existing.isDirectory()) {
+      throw new Error(`Refusing non-directory skill path: ${path}`)
+    }
+  }
+
+  const parent = dirname(path)
+  mkdirSync(parent, { recursive: true })
+  const tempPath = join(parent, `.${basename(path)}.atoll-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`)
+  const backupPath = `${tempPath}.backup`
+  let movedExisting = false
+  let installed = false
+  try {
+    cpSync(source, tempPath, { recursive: true })
+
+    const current = lstatIfExists(path)
+    if (current) {
+      if (current.isSymbolicLink()) {
+        throw new Error(`Refusing symbolic link for skill directory: ${path}`)
+      }
+      if (!current.isDirectory()) {
+        throw new Error(`Refusing non-directory skill path: ${path}`)
+      }
+      renameSync(path, backupPath)
+      movedExisting = true
+    }
+
+    renameSync(tempPath, path)
+    installed = true
+    if (movedExisting) rmSync(backupPath, { recursive: true, force: true })
+  } catch (error) {
+    if (!installed) {
+      if (lstatIfExists(tempPath)) rmSync(tempPath, { recursive: true, force: true })
+      if (movedExisting && !lstatIfExists(path) && lstatIfExists(backupPath)) {
+        renameSync(backupPath, path)
+      }
+    }
+    throw error
+  }
+}
+
 function readJson(path) {
   assertSafeFile(path)
   if (!existsSync(path)) return {}
@@ -198,10 +296,27 @@ function writePrivateFile(path, content) {
   }
 }
 
-function acquireInstallerLock() {
-  const atollDir = join(homedir(), '.atoll')
-  const target = join(atollDir, 'installer.lock-target')
-  ensurePrivateDirectory(atollDir)
+const codexDir = resolve(process.env.CODEX_HOME || join(homedir(), '.codex'))
+const defaultInstallerLockTarget = join(homedir(), '.atoll', 'installer.lock-target')
+const sharedInstallerLockTarget = join(
+  homedir(),
+  '.atoll-skill-installer.lock-target',
+)
+const codexSkillLockTarget = join(codexDir, '.atoll-skill-installer.lock-target')
+
+function ensureLockDirectory(path) {
+  const entry = lstatIfExists(path)
+  if (entry) {
+    const stat = entry.isSymbolicLink() ? statSync(path) : entry
+    if (!stat.isDirectory()) throw new Error(`Refusing non-directory installer lock path: ${path}`)
+  } else {
+    mkdirSync(path, { recursive: true, mode: 0o700 })
+  }
+}
+
+function acquireInstallerLock(target = defaultInstallerLockTarget) {
+  if (target === defaultInstallerLockTarget) ensurePrivateDirectory(dirname(target))
+  else ensureLockDirectory(dirname(target))
   try {
     writeFileSync(target, '', { flag: 'wx', mode: 0o600 })
   } catch (error) {
@@ -257,7 +372,23 @@ function acquireInstallerLock() {
   }
 }
 
-const releaseInstallerLock = acquireInstallerLock()
+const releaseSharedInstallerLock = acquireInstallerLock(sharedInstallerLockTarget)
+let releaseCodexSkillInstallerLock = null
+let releaseConfigInstallerLock = null
+try {
+  releaseCodexSkillInstallerLock = acquireInstallerLock(codexSkillLockTarget)
+  if (configureMode) releaseConfigInstallerLock = acquireInstallerLock()
+} catch (error) {
+  releaseCodexSkillInstallerLock?.()
+  releaseSharedInstallerLock()
+  throw error
+}
+
+function releaseInstallerLock() {
+  releaseConfigInstallerLock?.()
+  releaseCodexSkillInstallerLock?.()
+  releaseSharedInstallerLock()
+}
 
 function writeAtollProfile() {
   if (!args.profile) return null
@@ -422,14 +553,12 @@ function writeGlobalInstructions(targetPath) {
 }
 
 // 1. Install the Codex skill to ~/.codex/skills/atoll/
-const codexDir = join(homedir(), '.codex')
 mkdirSync(codexDir, { recursive: true })
 
 const skillDir = join(__dirname, '..', 'skill')
 const skillDest = join(codexDir, 'skills', 'atoll')
 const legacySkillDest = join(codexDir, 'skills', 'atoll-api')
-mkdirSync(skillDest, { recursive: true })
-cpSync(skillDir, skillDest, { recursive: true })
+prepareSkillDirectory(skillDest, skillDir)
 console.log(`Installed Atoll skill to ${skillDest}`)
 if (existsSync(legacySkillDest)) {
   rmSync(legacySkillDest, { recursive: true, force: true })
@@ -449,6 +578,13 @@ for (const file of ['api-endpoints.md', 'api-fields.md']) {
 }
 console.log(`Copied API references to ${refsDir}`)
 
+if (!configureMode) {
+  console.log('Authentication/profile configuration left unchanged.')
+  console.log('\nDone! Codex has the Atoll skill installed.')
+  releaseInstallerLock()
+  process.exit(0)
+}
+
 const shell = process.env.SHELL || '/bin/bash'
 const profilePath = shell.includes('zsh')
   ? join(homedir(), '.zshrc')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-codex",
-  "version": "0.4.23",
+  "version": "0.4.25",
   "description": "Install the Atoll project management integration for Codex CLI",
   "bin": {
     "skill-codex": "bin/install.mjs"

package/skill/SKILL.md

@@ -364,6 +364,7 @@ atoll dependency bulk-add --file ./dependencies.json --continue-on-error
 
 Dependency reads include a target issue `identifier` and `projectSlug` when the target belongs to a project. Inaccessible targets remain `issue: null`; projectless targets have both fields set to `null`.
 Dependencies persist a release point in the blocking project's ordered board columns. Add `releaseColumnId` when creating an edge, or omit it to default to that project's `done` column. Use the dependency API PATCH route to change the release point; reads include `releaseColumnId`, `releaseColumn`, and `satisfied`.
+Archiving a blocker preserves the dependency edge and configured release column while satisfying the dependency. Restoring it re-evaluates the same release point and can block the dependent again. Configurable release-point and cancelled-blocker behavior are unchanged.
 The blocking issue must belong to a project because its release point is a board
 column there; a projectless issue may be the blocked target.
 The dependency-release migration backfills existing dependencies to the
@@ -429,6 +430,9 @@ CLI JSON conventions:
 - `atoll heartbeat --json` includes the same structured `cli` update metadata for agents, plus `attention_items`, `attention_summary`, and `recommended_action` when Atoll can propose one concrete strategy-backed next action. `atoll heartbeat --signals-only --json` preserves filtered `signals`, `attention_items`, `attention_summary`, and `recommended_action` for short polling. Handle direct attention items first, then call each handled item's `ack_endpoint`. Follow `recommended_action.usage_guidance`: prefer `suggested_write.operation` when it still matches the board, preserve KPI/initiative/initiative_target/why-now/expected-impact/first-step/success-criteria evidence, and avoid copying deferred busywork into issue or comment payloads. If a `start_work` recommendation uses `issue.update` with a body, update the issue status and preserve that body as an issue comment; `PATCH /issues/{issueId}` accepts `comment_body` for this same-request progress note.
 - Authorized humans can configure an agent's included heartbeat sections and generated-signal focus in the Atoll **Heartbeats** UI. The saved policy is applied by the API before CLI or MCP request-level narrowing; it never changes project access, and existing heartbeat commands require no new arguments.
 - GitHub `workflow_run` signals are accepted only when HMAC-signed and completed, then reread and matched exactly by repository, PR, workflow path, run attempt, and head SHA. Workflow verification is disabled by default and observe-only until an owner/admin enables it in **Settings > Integrations > GitHub**. `attention` mode can add one bounded `verification.completed` attention item through authorized REST or CLI heartbeat for exactly one eligible current agent assignee or, when there is no unambiguous assignee, an eligible configured delivery agent. The public MCP heartbeat excludes this private event type. Unresolved recipients and cancelled, obsolete, superseded, mismatched, or unreadable runs create no attention. Owners and admins can configure 1–10 workflow paths of at most 255 characters each; the bounded evidence list defaults to 25 items and accepts a maximum `limit` of 100. Signed pull-request writes and reconciliation bind PR links to the stable GitHub repository ID, so repository renames keep existing workflow evidence linked. Do not expect raw payloads, secrets, logs, or thread IDs in evidence; owner/admin reconciliation retries pending evidence after current GitHub and PR-link readback.
+- Release-added required GitHub hook events mark existing reconciled and already-pending connections pending. The bounded 15-minute service sweep verifies immutable repository identity and upgrades hooks automatically; transient failures remain pending for retry, and owners/admins can reconcile manually.
+- Issue delivery context selects an open PR first, then the latest updated link, then the highest PR number. `pending` review/workflow state with null provenance means no current-head observation and does not by itself set `partial`. Disabled GitHub verification stops new projections. Workflow conclusions map success/neutral to passed, cancelled/stale/skipped to cancelled, and other supported terminal conclusions to failed.
+- Aggregate review state keeps each reviewer's latest exact-head opinion, ignores comments, and removes dismissed opinions. Change requests win. `approved` means at least one effective approval and no effective change request; it does not prove required-review counts or branch protection.
 - `atoll plan validate/apply` consumes `schemaVersion: "atoll.plan.v1"` files with `milestones`, `issues`, `dependencies`, `initiativeLinks`, and `milestoneLinks`; local `key` values can be referenced by `milestoneKey`, `issueKey`, `dependsOn`, `blockedBy`, or `blocks`.
 
 ## KPI HTTP Sync Drafts
@@ -620,6 +624,64 @@ atoll() {
 atoll "/api/orgs/$ATOLL_ORG_ID/issues?status=todo"
 ```
 
+## Execution and attention CLI workflow
+
+Use `atoll execution list|get|create|transition`, `execution evidence list|add`,
+and `atoll attention create|list|get|cancel` with the selected profile and `--json`.
+Creation requires `--issue`, `--agent <member-id|self>`, and an explicit
+`--idempotency-key`; it returns `assigned` at state version 1. Start with a
+separate `execution transition <id> --to running --expected-state-version 1
+--idempotency-key <start-key>`. Atoll records state; it does not start a harness.
+
+Generic transition targets are `running|waiting|succeeded|failed|cancelled`.
+For `succeeded`, supply `--outcome-summary` unless the execution already has
+linked evidence. The server validates this requirement.
+Use `attention create` to move `running|waiting` to `needs_human`; generic
+transitions cannot enter or leave `needs_human`. Attention kinds are exactly
+`approval|clarification|access|decision|destructive_action|other`. Supply the
+execution's expected state version, title, request summary, why needed, resume
+condition, exactly one member/team/project-admin target, and an idempotency key.
+Never put credentials, access tokens, private paths, prompts, logs, or other
+secrets in attention text. Server permissions and concealed 404 responses remain
+authoritative; do not try another identity to bypass them.
+
+Read `attention get <id>` for the human's resolution and current attention and
+execution versions. Human resolution returns the execution to `waiting`; it
+does not resume a model or harness. Requester `attention cancel` also returns it
+to `waiting` and requires `--expected-attention-version`,
+`--expected-state-version`, and `--idempotency-key`. Human resolve, administrator
+retarget/cancel, and recovery discovery are REST/UI operations, not CLI commands.
+Harness acceptance and the later explicitly fenced `waiting -> running` resume
+remain the separate AH-2122 integration.
+
+Every write uses the caller's explicit idempotency key; transitions and attention
+writes use the caller's expected versions. Never silently fetch a new version
+and write against it. After a POST timeout, network failure, or HTTP 5xx, the
+outcome is uncertain and the CLI does not retry. Read `execution get <id>`,
+`attention get <id>` (or `attention list --execution <id>` when create returned no
+attention ID), or `execution evidence list <id>`. Stop if the result is visible.
+For execution create without an ID, replay the identical create command with
+the same key, then read the returned ID. If replay is needed for another write,
+keep the exact body and key. Stop for operator reconciliation if changed state
+or versions make the outcome ambiguous; never use a new key to force progress.
+
+Evidence add links only an existing authorized issue object using
+`--type <comment|activity_event|issue_pr_link|attachment> --target-id <uuid>
+--idempotency-key <key>`. It does not upload files, URLs, text, or raw logs.
+
+## Human attention
+
+When an execution needs a human, use the attention contract. `POST
+/api/orgs/{id}/attention` records a bounded request and atomically moves the
+execution to `needs_human`; generic execution transitions cannot perform this
+edge. Poll `GET /api/orgs/{id}/attention` or use the exact item endpoint.
+Resolve, cancel, or retarget with both expected versions and an idempotency
+key. Reuse the same key only with the same input. Use `mode=recovery` only as
+an authorized human administrator when the original target is no longer
+eligible. Keep request text concise and never include secrets, credentials,
+logs, prompts, or local paths. The public projection provides current and
+snapshot actor/target fields, execution state, issue, and project context.
+
 ## The Heartbeat Loop
 
 The primary pattern for autonomous agents. Prefer `atoll heartbeat --json` when the CLI is available; it wraps `GET /api/orgs/{id}/heartbeat` and returns the same computed briefing:
@@ -791,6 +853,20 @@ Owners/admins can read billing state with `GET /api/orgs/{id}/billing` and start
 
 Creation endpoints can return `402` with `code: "PLAN_LIMIT_REACHED"` when an org reaches limits for humans, agents/integrations, active projects, or active issues.
 
+## Agent execution REST API
+
+Use the canonical org-scoped execution routes for lifecycle management:
+`GET|POST /api/orgs/{id}/executions`, `GET
+/api/orgs/{id}/executions/{executionId}`, `POST
+/api/orgs/{id}/executions/{executionId}/transitions`, and `GET|POST` on the
+matching `/evidence` route. Create starts in `assigned`; transition writes
+require `expected_state_version` and an idempotency key. Generic transitions
+cannot enter or leave `needs_human`; use the attention contract. Reads follow
+the issue's current project access. Non-guest organization members may also read
+projectless executions; setup-scoped agents and guest members cannot. Creation-
+project metadata does not grant access, and unreadable records are concealed.
+Responses are bounded management projections, not logs or harness controls.
+
 ## API Reference
 
 Full endpoint tables and field schemas:
@@ -827,6 +903,12 @@ default 50) and `offset`, and returns `hasMore`; removing the final link
 requires owner or admin access. Linked issues and projects cannot be deleted
 until the Artifact is unlinked or reassigned.
 
+Artifact list and detail responses include `can_edit`, which is true when the
+current member can create a revision, and `can_unlink`, which is true when the
+current member can remove a visible link. Members with write access can remove
+a link when another link remains; removing a final link requires owner or admin
+access.
+
 Private CLI issue reads request the opt-in metadata-only manifest. Inspect
 `.artifacts`, then use `atoll artifact get <id> --issue <issue>` only when the
 full current body is required. Create and update accept `--body-file -` for
@@ -861,6 +943,17 @@ otherwise the API returns `422` with `code: "github_identity_unavailable"`.
 Reads return bounded display metadata, provenance, observation timestamps, and
 resolvability. Reads require project visibility; writes require project
 `edit`/`admin`, with eligible non-guests allowed for projectless issues.
+For compact implementation evidence, the private REST endpoint
+`GET /api/orgs/{id}/issues/{issueId}/external-operational-signals` returns the
+selected PR, stable repository identity, exact current head SHA, current-head
+review and configured workflow states, bounded provenance, freshness, and a
+safe strongest blocker. Older-head evidence is historical. Configured
+workflows are not GitHub branch-protection required checks. This namespace is
+separate from heartbeat `signals[]` and never changes tasks or dispatches
+agents.
+The selected PR-link state is authoritative. If a same-head PR observation
+disagrees, Atoll clears its observation/provider provenance, falls back to the
+link URL, excludes it from freshness, and sets `partial`.
 Organization-wide templates are readable by non-guests and manageable only by
 organization owners/admins; guest/project-scoped agents never receive them.
 Avatar mutations require both caller and target to belong to the organization

package/skill/references/api-endpoints.md

@@ -220,6 +220,7 @@ bodies, projects only declared public issue fields, preserves nullable
 Add with `{ "blockedByIssueId": "uuid" }` or `{ "blockingIssueId": "uuid" }`; snake_case aliases `{ "blocked_by_issue_id": "uuid" }` and `{ "blocking_issue_id": "uuid" }` are also accepted. The blocking issue must belong to a project; a projectless issue may be the blocked target. Optionally include `releaseColumnId` from the blocking project's board columns. Omit it to use the blocking project's `done` column. PATCH the dependency with `{ "releaseColumnId": "uuid" }`. Circular dependencies rejected (400). Duplicates return 409.
 
 Dependency reads include each authorized target issue's canonical `identifier` and `projectSlug` when it belongs to a project. Projectless targets have both fields `null`; inaccessible targets remain `issue: null`. Release fields include `releaseColumnId` and the compatibility alias `release_column_id`; POST and PATCH accept either camelCase or snake_case release-column input. Release metadata is present when the blocking issue is authorized; a `blocking` target projection may still be `issue: null` independently.
+Archiving a blocker preserves the dependency edge and configured release column while satisfying the dependency. Restoring it re-evaluates the same release point and can block the dependent again. Configurable release-point and cancelled-blocker behavior are unchanged.
 The dependency-release migration backfills existing dependencies to the
 blocking project's `done` column. During a rolling deployment, compatibility
 reads may omit release fields from older rows; treat missing release metadata as
@@ -296,10 +297,10 @@ Artifacts.
 
 | Method | Endpoint | Description |
 | --- | --- | --- |
-| `GET` | `/api/orgs/{id}/artifacts` | List readable artifact metadata and visible links; revision content is omitted; supports `limit` (1-100, default 50) and `offset` (0-10000), and returns `hasMore` |
+| `GET` | `/api/orgs/{id}/artifacts` | List readable artifact metadata and visible links; revision content is omitted; includes `can_edit` and `can_unlink` capabilities; supports `limit` (1-100, default 50) and `offset` (0-10000), and returns `hasMore` |
 | `POST` | `/api/orgs/{id}/artifacts` | Create artifact and immutable revision 1 atomically |
-| `GET` | `/api/orgs/{id}/artifacts/{artifactId}` | Read artifact metadata and visible links |
-| `GET` | `/api/orgs/{id}/artifacts/{artifactId}/revisions` | List immutable revision summaries without content; supports `limit` (1-100, default 50) and `offset`, and returns `hasMore` |
+| `GET` | `/api/orgs/{id}/artifacts/{artifactId}` | Read artifact metadata and visible links, including `can_edit` and `can_unlink` capabilities |
+| `GET` | `/api/orgs/{id}/artifacts/{artifactId}/revisions` | List immutable revision summaries without content; supports `limit` (1-100, default 50) and `offset` (0-10000), and returns `hasMore` |
 | `POST` | `/api/orgs/{id}/artifacts/{artifactId}/revisions` | Create a content revision or title-aware full snapshot with an expected current revision |
 | `GET` | `/api/orgs/{id}/artifacts/{artifactId}/revisions/{revisionId}` | Read one sanitized revision including content |
 | `POST` | `/api/orgs/{id}/artifacts/{artifactId}/links` | Link to an authorized issue or project |
@@ -425,6 +426,20 @@ references return `409`, and resolver failures return `500`.
 
 Returns findings only (not the full graph). Use it for a high-level review — orphaned initiatives/KPIs (no goal), goals with no KPI or no initiative, dangling initiative execution links, KPIs missing targets/stale/off-pace, initiatives missing impact/execution or stalled, blocked/overdue work — then remediate with the goal/KPI/initiative write endpoints above. Owners/admins receive organization-wide execution evidence. Other non-guests receive project-bound issues, milestones, target links, and target findings only for readable projects. A restricted member with no readable projects receives no issue or target execution evidence. Forbidden for guests. CLI: `atoll strategy audit [--severity critical|warning|info] [--json]`.
 
+## Human attention
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/api/orgs/{id}/attention` | List relevant open or closed attention items; supports status, execution, kind, recovery mode, target filters, bounded pagination, and envelope/CLI shape |
+| `POST` | `/api/orgs/{id}/attention` | Request human attention and atomically pause the execution in `needs_human` |
+| `GET` | `/api/orgs/{id}/attention/{attentionId}` | Read one safe attention detail projection |
+| `POST` | `/api/orgs/{id}/attention/{attentionId}/resolve` | Resolve an open item for its eligible human target and leave the execution in `waiting`; a trusted harness performs any later resume |
+| `POST` | `/api/orgs/{id}/attention/{attentionId}/cancel` | Cancel an item as its requesting agent and leave the execution in `waiting`; a trusted harness performs any later resume |
+| `POST` | `/api/orgs/{id}/attention/{attentionId}/admin-cancel` | Cancel an item as an authorized human administrator and leave the execution in `waiting`; a trusted harness performs any later resume |
+| `POST` | `/api/orgs/{id}/attention/{attentionId}/retarget` | Retarget an open item as an authorized human administrator |
+
+The create body is strict and requires `execution_id`, `expected_state_version`, `kind`, `title`, `request_summary`, `why_needed`, `resume_condition`, one exact target shape, and `idempotency_key`. Close and retarget bodies require both expected versions. Mutations are idempotent and return `409` for stale versions, invalid lifecycle edges, conflicting keys, or ineligible targets. `mode=recovery` is restricted to authorized human administrators. Text is bounded and secret-safe; public projections omit provenance, hashes, prompts, logs, credentials, and paths.
+
 ## Heartbeat
 
 | Method | Endpoint | Description |
@@ -455,6 +470,25 @@ atoll heartbeat --severity critical
 `atoll heartbeat --signals-only --json` returns filtered `signals`, direct `attention_items`, `attention_summary`, and `recommended_action` for polling agents.
 KPI stale/off-pace signal metadata includes `linked_initiatives` and `recent_attributed_snapshots`; `--explain-kpi` returns that movement context under `kpi_explanation`.
 
+## Agent executions
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| GET | `/api/orgs/{id}/executions` | List executions in the caller's current issue-project scope; non-guest members may also read projectless executions, except setup agents and guests; filters: `issue_id`, `agent_member_id`, `state`, `active`, `harness_kind`, `updated_after`, `limit`, `offset` (maximum 10,000), `shape` |
+| POST | `/api/orgs/{id}/executions` | Create an execution. Strict body; required `idempotency_key`; starts in `assigned` |
+| GET | `/api/orgs/{id}/executions/{executionId}` | Read safe detail, transitions, and evidence projections |
+| POST | `/api/orgs/{id}/executions/{executionId}/transitions` | Version-fenced transition through the shipped lifecycle RPC |
+| GET/POST | `/api/orgs/{id}/executions/{executionId}/evidence` | List or link existing authorized issue evidence |
+
+Use `expected_state_version` for follow-up transitions. Generic transitions cannot enter
+or leave `needs_human`; those edges return `ATTENTION_CONTRACT_REQUIRED` and
+belong to the attention contract. Reads use the issue's current project access;
+non-guest members may also read projectless executions, except setup agents and
+guests. Creation-project metadata does not grant access. Unreadable records are
+concealed as `404`; public projections omit hashes, provenance, logs,
+prompts, credentials, and paths. This API records state and does not start or
+resume an underlying harness. There is no issue-specific execution route.
+
 ## Activity
 
 | Method | Endpoint | Description |
@@ -600,6 +634,10 @@ requests also sweep a small due batch. Uploads over 2MB return `413`.
 
 Attach PRs manually with a canonical GitHub pull request URL such as `https://github.com/owner/repo/pull/123`; malformed or non-PR URLs return `400`. On attach, Atoll refreshes GitHub metadata when available so title/status/head SHA reflect the PR instead of only the submitted URL. PR links can also be created or refreshed automatically via the GitHub webhook integration.
 
+GET returns `id`, `pr_number`, `github_repo`, nullable
+`github_repository_id`, nullable `external_reference_id`, `pr_url`, `pr_title`,
+`pr_status`, nullable `head_sha`, and `updated_at` for each link.
+
 For project-bound issues, listing requires project access and attaching requires
 `edit` or `admin` access. Eligible non-guests may list and attach links for
 projectless issues. Authorization is bound to the issue's current parent before
@@ -613,12 +651,35 @@ child reads or writes and occurs before URL parsing or GitHub metadata lookup.
 | POST | `/api/orgs/{id}/issues/{issueId}/external-references` | Resolve and link a GitHub PR |
 | GET | `/api/orgs/{id}/issues/{issueId}/external-references/{referenceId}` | Inspect a linked reference |
 | DELETE | `/api/orgs/{id}/issues/{issueId}/external-references/{referenceId}` | Unlink a reference |
+| GET | `/api/orgs/{id}/issues/{issueId}/external-operational-signals` | Read current exact-head GitHub delivery context |
 | GET | `/api/orgs/{id}/projects/{projectId}/external-references` | List project external references |
 | POST | `/api/orgs/{id}/projects/{projectId}/external-references` | Resolve and link a GitHub PR |
 | GET | `/api/orgs/{id}/projects/{projectId}/external-references/{referenceId}` | Inspect a linked reference |
 | DELETE | `/api/orgs/{id}/projects/{projectId}/external-references/{referenceId}` | Unlink a reference |
 
-External Reference POST requests accept `{ "url": "https://github.com/owner/repo/pull/123" }`. They require an authorized GitHub connection and store a reference only when the live response proves numeric immutable repository and pull-request IDs. Missing proof returns `422` with `code: "github_identity_unavailable"`. URLs and caller owner/repo fields are not identity or authorization inputs. Existing PR-link operations remain independent; CLI/MCP tools are deferred to a later slice.
+External Reference POST requests accept `{ "url": "https://github.com/owner/repo/pull/123" }`. They require an authorized GitHub connection and store a reference only when the live response proves numeric immutable repository and pull-request IDs. Missing proof returns `422` with `code: "github_identity_unavailable"`. URLs and caller owner/repo fields are not identity or authorization inputs. Manual PR-link operations remain available without an External Reference; verified delivery projection creates and binds the immutable PR reference. CLI/MCP tools are deferred to a later slice.
+
+The external-operational-signals GET returns `{ deliveryContext }` for the
+selected current PR or `null` when there is no PR link. Selection prefers an
+open link, then the latest `updated_at`, then the highest PR number. It contains stable
+repository identity, exact head SHA, current PR/review/configured-workflow
+state, bounded source and provider-event provenance, freshness, a safe strongest
+blocker, and `partial`. Older-head signals are historical. Configured workflows
+are not GitHub branch-protection required checks and report `required: false`.
+Missing current-head review or configured-workflow evidence appears as
+`pending` with null provenance and does not by itself set `partial`. Disabled
+verification stops new projections. Workflow conclusions map `success` or
+`neutral` to `passed`; `cancelled`, `stale`, or `skipped` to `cancelled`; and
+other supported terminal conclusions to `failed`.
+The selected PR-link state is authoritative. If a same-head PR observation
+disagrees, Atoll clears its observation/provider provenance, uses the link URL
+as `source_url`, excludes it from freshness, and sets `partial`.
+Review aggregation keeps each reviewer's latest exact-head opinion, ignores
+comments, and removes dismissed opinions. Change requests win; `approved`
+means at least one effective approval and no effective change request. It does
+not prove required-review counts or branch protection.
+This read-only namespace is separate from heartbeat `signals[]` and does not
+dispatch agents or change tasks.
 
 ## Project Status Updates
 
@@ -798,6 +859,11 @@ The default new-agent local path (without `setupAgentMemberId`) atomically creat
 | POST | `/api/integrations/github/connect` | Connect a repo |
 | POST | `/api/integrations/github/disconnect` | Disconnect a repo |
 
+Release-added required hook events mark existing reconciled and already-pending connections pending. A bounded
+15-minute service sweep verifies immutable repository identity and upgrades the
+hooks automatically. Transient failures remain pending for retry; owners and
+admins can also use the reconciliation endpoint.
+
 ## Platform Feedback
 
 ### Feedback error contract

package/skill/references/api-fields.md

@@ -782,6 +782,30 @@ The opt-in issue manifest contains only `id`, `type`, `title`,
 Implementation Plan links are limited to one slot per issue, and each such
 Artifact can be authoritative for only one issue.
 
+Artifact list and detail responses also include `can_edit` and `can_unlink`.
+`can_edit` is true when the current member can create a revision. `can_unlink`
+is true when the current member can remove a visible link; removing a final link
+requires owner or admin access, while a member with write access can remove a
+link when another link remains.
+
+## Agent execution fields
+
+Execution projections contain `id`, `issue_id`, `current_project_id`,
+`project_id_at_creation` (provenance only), normalized `state`, `state_version`,
+bounded lifecycle summaries, safe harness/external-run metadata, timestamps,
+and actor objects `{ id, display_name, type, deleted }`. `harness_kind` and
+`external_run_id` reject credentials, tokens, and local filesystem paths;
+legacy unsafe values are redacted as `null` in projections. Deleted agent or actor
+rows use immutable AH-2095 snapshots. Detail adds ordered `transitions` and
+existing `evidence` references `{ id, issue_id, link_type, target_id,
+created_by, created_at }`.
+
+Create requires `issue_id`, `agent_member_id`, and `idempotency_key`; it always
+returns state `assigned`. Transition requires `expected_state_version`,
+`to_state`, and `idempotency_key`. HTTP bodies are strict and omit actor
+provenance; the server derives safe OAuth provenance. The generic transition
+enum excludes `needs_human`.
+
 ## Analytics Response
 
 ```json
@@ -795,6 +819,28 @@ Artifact can be authoritative for only one issue.
 
 ---
 
+## Human attention fields
+
+Attention list/detail projections contain `id`, `status` (`open`, `resolved`, or
+`cancelled`), `kind` (`approval`, `clarification`, `access`, `decision`,
+`destructive_action`, or `other`), bounded `title`, `request_summary`,
+`why_needed`, `resume_condition`, `requested_at`, `closed_at`,
+`resolution_outcome`, `resolution_summary`, `attention_version`, and the
+execution, issue, and project projections. `target` contains the exact target
+type plus a live member/team projection when it still exists and immutable
+snapshot fields. `requester` and `closed_by` contain `{ id, display_name,
+type, deleted }` snapshots. Detail adds
+`execution_state_version_at_request` and `execution_state_version_at_close`.
+
+Create targets are one of `{ target_type: "member", target_member_id }`,
+`{ target_type: "team", target_team_id }`, or
+`{ target_type: "project_admins" }`. Mutation requests use
+`expected_attention_version`, `expected_state_version`, and
+`idempotency_key`; resolve also accepts `resolution_outcome` and an optional
+bounded `resolution_summary`. Free-form text rejects secret-like values.
+Internal requester/actor provenance, hashes, response snapshots, and mutation
+metadata are never returned by the public API.
+
 ## Enums
 
 | Domain | Field | Values |
@@ -876,7 +922,9 @@ be the blocked target when the caller has permission to use it.
 | `releaseColumnId` | UUID | Persistent release column in the blocking issue's project; present when the blocking issue is authorized |
 | `release_column_id` | UUID | Compatibility alias for `releaseColumnId`; present with the canonical field |
 | `releaseColumn` | object or null | `{ id, key, label, position, projectId }` release column projection |
-| `satisfied` | boolean or null | Whether the blocker reached the release column position, or is cancelled |
+| `satisfied` | boolean or null | Whether the blocker is archived or cancelled, or reached the release column position |
+
+Archiving a blocker preserves the dependency edge and configured release column while satisfying the dependency. Restoring it re-evaluates that same release point and can block the dependent again. Configurable release-point and cancelled-blocker behavior are unchanged.
 
 The dependency-release migration backfills existing dependencies to the
 blocking project's `done` column. During a rolling deployment, compatibility
@@ -898,6 +946,35 @@ provider response or return `422` with
 metadata-only Activity actions `external_reference.linked`,
 `external_reference.updated`, or `external_reference.unlinked`.
 
+### External operational delivery context
+
+`GET /api/orgs/{id}/issues/{issueId}/external-operational-signals` returns
+`{ deliveryContext }`. The value is `null` without a linked PR. With several
+links, selection prefers an open PR, then the latest `updated_at`, then the
+highest PR number. Otherwise it
+contains `repository`, `pull_request`, nullable `review`, `workflows`,
+`freshness`, nullable `strongest_blocker`, and `partial`. PR, review, and
+workflow evidence includes nullable `observed_at`, `provider_updated_at`,
+`provider_event_id`, and `source_url`. The PR includes the exact `head_sha`.
+Review state is `pending`, `approved`, or `changes_requested`; workflow state is
+`pending`, `passed`, `failed`, or `cancelled`. Older-head evidence is not
+current. Workflow `required` is always `false` because configured workflow
+paths do not prove GitHub branch protection. Raw payloads, review bodies,
+actors, logs, and credentials are excluded. A `pending` review or workflow with
+null provenance has no current-head observation; this absence does not by
+itself set `partial`. Disabled verification stops new projections. Workflow
+conclusions map `success`/`neutral` to `passed`,
+`cancelled`/`stale`/`skipped` to `cancelled`, and other supported terminal
+conclusions to `failed`.
+The selected PR-link state is authoritative. If a same-head PR observation
+disagrees, its `observed_at`, `provider_updated_at`, and `provider_event_id` are
+null, `source_url` uses the link URL, the observation is excluded from
+`freshness`, and `partial` is true.
+Review aggregation keeps each reviewer's latest exact-head opinion, ignores
+comments, and removes dismissed opinions. Change requests win; `approved`
+means at least one effective approval and no effective change request. It does
+not prove required-review counts or branch protection.
+
 ## Task Activity
 
 `GET /api/orgs/{id}/activity` returns `{ data, currentMemberId, limit, offset,