apoc 0.9.1

Agentic process control for LLMs
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
# apoc

**Unrestricted process control and durable execution for LLM agents.**

[![crates.io](https://img.shields.io/crates/v/apoc.svg)](https://crates.io/crates/apoc)
[![docs.rs](https://docs.rs/apoc/badge.svg)](https://docs.rs/apoc)
[![license](https://img.shields.io/crates/l/apoc.svg)](https://docs.rs/crate/apoc/latest/source/LICENSE)
[![MSRV](https://img.shields.io/badge/MSRV-1.95-blue.svg)](https://docs.rs/crate/apoc/latest/source/Cargo.toml)

`apoc` (apocalypse) replaces shell-shaped process inspection, PID bookkeeping,
background-job glue, and one-off supervisors with one typed control plane. It
gives agents fresh process state, exact process identities, durable executions,
bounded concurrency, resource ownership, causal history, and JavaScript
composition through the same command graph.

It is built for workloads where independent operations run concurrently,
long-lived work must survive the initiating call, and later agents need to
inspect exact outcomes without reconstructing state from terminal transcripts.

[Install](#install) · [Quick start](#quick-start) ·
[Execution model](#choose-the-smallest-execution-surface) ·
[MCP](#use-apoc-through-mcp) · [Security](#security-and-trust-model) ·
[Operations](#upgrade-and-verify) · [Reference](#reference)

## Core guarantees

| Capability | Contract |
| --- | --- |
| Process identity | Mutations target boot ID, PID, and nanosecond start time to prevent PID-reuse mistakes. |
| Durable execution | Accepted commands retain specifications, attempts, bounded logs, events, ownership, and terminal results. |
| Exact arguments | Direct argv is the default; shell parsing requires explicit `--shell`. |
| Replay safety | Caller-supplied idempotency keys prevent repeated operating-system mutations. |
| One command graph | CLI, MCP, and Code Mode share schemas, validation, history, and execution state. |
| Local-first operation | No account, telemetry service, or required remote control plane. |

## Status and scope

| Property | Current contract |
| --- | --- |
| Release | `0.9.1` |
| Platform | Supported: macOS |
| Minimum Rust version | `1.95` |
| Interfaces | CLI, MCP stdio, Code Mode JavaScript, and an embedded Rust library |
| Compatibility | SemVer releases with versioned durable schemas and pre-migration database backups |
| Release gates | rustfmt, Clippy with warnings denied, workspace tests, package contents, and publish dry-run on macOS CI |
| State | Local SQLite database, execution logs, and content-addressed artifacts |
| Authority | The operating-system permissions of the user who starts apoc |
| License | MIT |

The `0.x` line is actively evolving. Breaking public-interface changes receive
a minor version bump; durable state changes use explicit schema migrations.

## Security and trust model

apoc is not a sandbox, policy engine, confirmation layer, or embedded model. It
exposes destructive operations and their metadata directly, using the authority
of the user who starts it. The calling agent remains responsible for selecting
the correct target and action.

apoc can ask a decider you register before it launches a command. It ships no
deciders and no rules; with none registered it asks nothing, records nothing,
and refuses nothing. A decider guards against accidents, not adversaries: apoc
has no privilege boundary, so an agent that can run commands can also remove a
decider. See [Ask a decider before commands run](#ask-a-decider-before-commands-run).

apoc has no telemetry, account service, update checker, or automatic network
access. Network requests occur only when the user configures and invokes an
HTTP, MCP, or OpenAPI provider.

## Composed Code Mode

Prefer native MCP arguments over shell-quoted JavaScript. A short call is enough:

```json
{"code":"return await apoc.execution_command({executable:'cargo',arg:['check','--locked']});"}
```

Local calls inherit the outer purpose and derive mutation keys automatically.
Optional outer `purpose` states the intent once. Optional `idempotency_key`
preserves child replay across new executions; without it, keys stay scoped to
one execution and its replay passes. Explicit nested values override defaults,
and external connector arguments remain unchanged.

Save lengthy source and use `apoc code run @program.js --purpose 'Verify build'
--idempotency-key build-v1 --timeout-ms 45000`. Files are UTF-8 and resolve
relative to the caller directory. CLI mutations require a purpose and key;
framework discovery is purpose-free.

Commands judge exit zero by default. Add an expectation when success means
something else. Compose dependent calls with `await`, independent calls with
`Promise.all`, and return only the result the next decision needs.
See the [operator skill](skills/apoc/SKILL.md) for concise examples and references.

## Install

```sh
cargo install apoc --version 0.9.1 --locked
apoc skill install --purpose 'Install the apoc operator skill.' --idempotency-key skill/install-v1
apoc version --purpose 'Check the installed apoc version.' --format json
apoc skill status --purpose 'Check the apoc skill installation.' --format json
```

`apoc skill install` writes the embedded operator contract to
`~/.agents/skills/apoc` and links the Codex and Claude skill roots to that
canonical copy. Run it again after an upgrade. A successful status reports
`"ready": true`.

Each crates.io release contains the complete MIT-licensed source. Development
happens in a private repository; the crates.io package and docs.rs source view
are the public source distribution.

## Quick start

Run one exact-argv command and receive its durable result:

```sh
apoc execution command /usr/bin/printf \
  --purpose 'verify the apoc installation' \
  --idempotency-key quick-start/printf-v1 \
  --format json \
  -- '%s\n' 'hello from apoc'
```

The default response contains only the execution ID and verdict:

```json
{"id":"EXECUTION_ID","outcome":"passed"}
```

Retained logs and the complete record require an explicit addressed read.

Use the returned execution ID to inspect or control the work later:

```sh
apoc execution get EXECUTION_ID --purpose 'Check the execution state.' --format json
apoc execution tree EXECUTION_ID --purpose 'Inspect the managed process tree.' --format json
apoc execution logs EXECUTION_ID --tail-bytes 65536 --purpose 'Read the latest execution logs.' --format json
apoc execution wait EXECUTION_ID --timeout-ms 30000 --purpose 'Wait for the execution to finish.' --format json
apoc execution cancel EXECUTION_ID --timeout-ms 2000 --idempotency-key execution/cancel-1 --purpose 'Cancel the active execution.' --format json
```

`execution wait --timeout-ms` is a client wait boundary. If the execution is
still active at that boundary, it returns the current `pending` verdict without
canceling or failing the execution.

Limit a native execution and every process it owns with one family budget:

```sh
apoc code run '
  return await apoc.execution_command({
    executable: "cargo",
    arg: ["test", "--workspace"],
    cwd: "/absolute/project",
    memory_limit_mb: 2048,
    cpu_percent: 200,
    cpu_time_ms: 600000,
    child_processes: 64,
    timeout_ms: 900000,
    idempotency_key: "tests/resource-budget-v1",
    purpose: "Run the workspace tests inside a bounded native execution family."
  });
' --purpose 'Run the workspace tests inside a bounded native execution family.' \
  --idempotency-key tests/resource-budget-outer-v1 --format json
```

`memory_limit_mb` caps combined resident memory. `cpu_percent` caps the sampled
combined CPU rate, where 100 percent equals one logical CPU. `cpu_time_ms` caps
accumulated CPU time. apoc samples these native ceilings every 100 milliseconds,
persists the measured breach, and recursively cancels the execution graph. They
are cancellation ceilings, not kernel reservations. Use built-in isolated
execution with `memory_mb`, `cpu_count`, and `pids_max` when the command needs
hard VM resource allocation.

Run the same exact-argv command in apoc's built-in macOS VZ guest with
`--isolated`. This path does not require provider registration. `local` resolves
the packaged or development VM bundle; an absolute bundle path and a canonical
`sha256:<digest>` image reference are also accepted.

Rust INCURS owns this command surface and the native `apoc-macos-vz` provider.
apoc keeps the durable execution identity, retry policy, verified image,
exports, redacted logs, controls, and recovery. The provider owns
Virtualization.framework configuration, pooling, snapshot attempts, and the
guest transport. Snapshot restore failures are recorded against the compatible
image fingerprint and fall back to a cold warmed VM instead of claiming a
snapshot exists.

```sh
apoc execution command /bin/uname \
  --isolated \
  --image local \
  --workspace-mode none \
  --idempotency-key quick-start-isolated-v1 \
  --purpose 'Read the isolated guest kernel identity.' \
  --format json \
  -- -a
```

Declare files or directories to import after the guest command with `--export`.
Each matching export becomes a verified, content-addressed execution artifact.
The source is an absolute guest path, the destination is a unique artifact name,
and `when` is `success`, `failure`, or `always`.

```sh
apoc execution command /bin/sh \
  --isolated \
  --workspace-mode none \
  --export '{"source":"/tmp/result","destination":"result","when":"success"}' \
  --artifact-bytes 1048576 \
  --idempotency-key isolated-export-v1 \
  --verbosity trace \
  --purpose 'Create and retain one isolated result.' \
  --format json \
  -- -c 'printf result > /tmp/result'

apoc code artifact EXECUTION_ID ARTIFACT_ID \
  --purpose 'Read the retained isolated result.' \
  --format json
```

apoc verifies the guest SHA-256 and the total artifact byte budget before it
stores anything. It rejects incomplete streams, undeclared indexes, duplicate
destinations, missing condition-matching exports, and exports emitted for the
wrong terminal condition. The stored envelope uses `application/x-tar`; its
archive contains the exported value at `value`.

An isolated execution remains controllable through its apoc execution ID. Start
the command, then send UTF-8 input, a named signal, or cancellation through the
same public lifecycle used for native commands.

```sh
apoc execution start /usr/bin/head \
  --isolated \
  --workspace-mode none \
  --guest-cwd /tmp \
  --idempotency-key isolated-input-v1 \
  --verbosity trace \
  --purpose 'Start an isolated input consumer.' \
  --format json \
  -- -c 5

apoc execution input EXECUTION_ID hello \
  --idempotency-key isolated-head/input-1 \
  --purpose 'Write five bytes to the isolated input consumer.' \
  --format json
apoc execution signal EXECUTION_ID TERM \
  --idempotency-key isolated-head/term-1 \
  --purpose 'Terminate the isolated execution.' \
  --format json
apoc execution cancel EXECUTION_ID \
  --idempotency-key isolated-head/cancel-1 \
  --purpose 'Cancel the isolated execution and release its VM.' \
  --format json
```

apoc claims each input, signal, or cancel idempotency key before dispatch and
records the result afterward. An exact retry returns the original result, a
changed request conflicts, and an ambiguous prior dispatch is not repeated. It
rejects new controls before provider acceptance and after terminal state.
Terminal publication guarantees the active control handle is gone and the VM
slot can return to the pool.

Pass `--pty` to allocate a controlling terminal inside the isolated guest.
Standard output and standard error share the stdout event stream, and
`execution input` writes through the PTY master. The initial terminal size is
80 columns by 24 rows.

```sh
apoc execution command /bin/sh \
  --isolated \
  --workspace-mode none \
  --pty \
  --idempotency-key isolated-shell/tty-1 \
  --purpose 'Verify the isolated controlling terminal.' \
  --format json \
  -- -c 'test -t 0 && test -t 1 && test -t 2 && printf tty-ready'
```

Isolated commands accept secret environment references without storing their
resolved values. apoc resolves each value only while constructing the provider
request, withholds logs while redaction is pending, and replaces every complete
value with `[REDACTED]` before publishing terminal state. Recovery removes
potentially unsafe logs if a required value can no longer be resolved.

```sh
apoc execution command /bin/sh \
  --isolated \
  --workspace-mode none \
  --secret-env TOKEN=env:DEPLOY_TOKEN \
  --idempotency-key isolated-secret/check-1 \
  --purpose 'Verify isolated secret transport and redaction.' \
  --format json \
  -- -c 'printf "%s" "$TOKEN"'
```

`--max-attempts` also applies to isolated executions. apoc retains one public
execution ID, assigns deterministic provider request IDs ending in
`:attempt:N`, records every failed attempt, appends output in attempt order,
and makes cancellation wake retry backoff immediately. Live input and signals
are unavailable between attempts until the next provider identity is accepted.

## Choose the smallest execution surface

| Work | Preferred surface |
| --- | --- |
| One process query or mutation | `apoc process ...` |
| One managed command | `apoc execution command` or `start` |
| One isolated macOS VZ command | `apoc execution command --isolated` or `start --isolated` |
| Live processes for a known execution | `apoc execution tree EXECUTION_ID` |
| Repeat a command or typed apoc operation until an outcome | `apoc poll run` or `start` |
| Known independent commands | `apoc execution batch` |
| A native stdout pipeline | `apoc execution pipeline` |
| Heterogeneous concurrent tools | `apoc code run` |
| Agent-host integration | `apoc --mcp` |
| External MCP, OpenAPI, or macOS action | `apoc provider ...` and `apoc action ...` |
| Prior apoc use in this worktree | `apoc history ...` |

Every surface resolves through the same typed graph and durable lifecycle:

```text
CLI        MCP        Code Mode
 |          |             |
 +----------+-------------+
            |
     typed command graph
            |
       per-user daemon
       /      |       \
 executions  events  ownership
            |
 macOS processes, isolated VZ, and providers
```

All commands support TOON, JSON, YAML, Markdown, and JSONL output. Use
`--schema` for one command's JSON Schema and `--llms` for the compact
LLM-readable command manifest. Use `--filter-output` when an agent needs only a
few fields from a CLI response. Code Mode programs should return a compact
synthesis instead of complete nested execution envelopes.

## Process discovery and control

apoc resolves a selector from a fresh native snapshot before every mutation.
The durable identity is `BOOT_ID:PID@STARTED_AT_NS`, so PID reuse cannot redirect
an operation to a different process.

When an execution ID is available, inspect its processes with `execution tree`.
It recursively follows owned child executions and verifies every captured root by
boot ID, PID, and nanosecond start time before returning a fresh tree. Its
`state` is `pending`, `active`, `terminal`, or `inconsistent`; terminal
executions return an explicit terminal result with an empty `processes` array.
Do not extract a PID or PGID from `execution get` and pass it to `process tree`.

```sh
apoc execution tree EXECUTION_ID --purpose 'Inspect the managed process tree.' --format json
apoc process list --selector match:node --sort memory --limit 20 --purpose 'List relevant Node processes.'
apoc process select port:5173/tcp --purpose 'Select the development server process.'
apoc process tree name:vite --purpose 'Inspect the Vite process tree.'
apoc process files pid:4242 --purpose 'List files opened by the process.'
apoc process sockets --listening --protocol tcp --purpose 'List listening TCP sockets.'
apoc process probe pid:4242 --purpose 'Check whether the process still exists.'
apoc process sample --selector match:node --count 5 --interval-ms 250 --purpose 'Sample resource use for Node processes.'
```

Selectors are `pid:`, `name:`, `match:` regular expressions, `pgid:`, `port:`
with optional `/tcp` or `/udp`, and `all`. A bare integer is a PID.

Structured queries combine process fields, regular expressions, socket
ownership, and recorded apoc ownership:

```sh
apoc process query '{
  "all":[{"command_regex":"node|bun"}],
  "any":[{"port":5173},{"actor":"release-agent"}],
  "not":[{"name":"Code Helper"}],
  "sort":"memory",
  "limit":20
}' --purpose 'Find high-memory Node processes.'
```

The causal journal answers relationship questions from recorded evidence:

```sh
apoc process why pid:4242 --purpose 'Explain why apoc knows this process.'
apoc process impact pid:4242 --purpose 'Assess the impact of controlling the process.'
apoc process owner pid:4242 --purpose 'Identify the process owner.'
apoc process related pid:4242 --purpose 'Find related process records.'
apoc process changed pid:4242 --purpose 'Read recorded changes for the process.'
apoc process context pid:4242 --events 50 --purpose 'Read the durable process context.'
```

Process mutations accept caller-supplied idempotency keys. Repeating the same
normalized request and key returns the original receipt without another
operating-system call. Empty selections fail unless `--allow-empty` is explicit.

These commands can stop or suspend host processes. Resolve and inspect the
selector before mutating a target when its identity is not already known.

```sh
apoc process signal name:vite TERM --purpose 'Terminate the Vite process cleanly.' --idempotency-key deploy-91/term
apoc process stop port:5173/tcp --timeout-ms 2000 --force \
  --purpose 'Stop the process holding the development port.' \
  --idempotency-key deploy-91/free-port
apoc process pause pgid:4242 --purpose 'Pause the process group for debugging.' --idempotency-key debug-7/pause
apoc process resume pgid:4242 --purpose 'Resume the paused process group.' --idempotency-key debug-7/resume
```

## Durable execution contract

`execution` is the public lifecycle abstraction. Direct argv is the default.
Place apoc options before the first literal `--`, then pass each exact child
argv value after it. That first separator belongs to apoc; every later `--`
belongs to the child. Structured MCP and Code Mode calls use the same `arg`
array. If apoc reports an unknown child flag, do not retry with `--arg`; move
apoc options before `--` and the complete child argv after it. Use `--shell`
only when the program intentionally requires zsh parsing.

```sh
apoc execution start /usr/bin/python3 \
  --name docs \
  --purpose 'serve documentation for review' \
  --idempotency-key docs/server-v1 \
  --max-attempts 3 \
  --retry-backoff-ms 500 \
  --timeout-ms 300000 \
  -- -m http.server 8000
```

An execution records its versioned specification, working directory, repository
and worktree state, attempts, exact process identities, output paths, parent,
session, lease, progress time, and terminal result.

- An omitted working directory inherits the caller's current directory through
  the CLI, MCP, and Code Mode.
- A relative `--cwd` resolves from that directory. apoc validates and
  canonicalizes it before accepting the execution.
- `command`, `batch`, and `pipeline` return a verdict, or
  `{ execution, replayed, logs }` at `--verbosity trace`.
- The CLI exit status matches the managed result while structured stdout remains
  available to the caller.
- Inline stdout and stderr are bounded 32 KiB tails with explicit truncation
  flags. Full logs remain available through `execution logs`.
- Launch failures, nonzero exits, timeouts, and cancellations are terminal
  execution results after acceptance. They are not transport failures.
- A progress timeout advances when retained stdout or stderr grows or the
  execution lifecycle advances. If it stalls, apoc preserves `last_progress_at`
  and records both that timestamp and `stalled_at` in the terminal result.
- Reusing an idempotency key for a different normalized request fails before
  launching work.

Use `execution list --error-code CODE` to find executions by their canonical
terminal cause, including launch failures, timeouts, stalls, and cancellations.

### Opt-in execution telemetry

Execution resource telemetry is off by default. Add `--telemetry` to `execution command`, `start`,
`batch`, `pipeline`, either poll target, or `code run`/`start` when a task needs
measurements. The default interval is 250 ms and the default retained raw-data
cap is 64 MiB; override them with `--telemetry-interval-ms` and
`--telemetry-max-bytes`.

```sh
apoc execution command cargo \
  --telemetry \
  --purpose 'Measure the package test execution.' \
  --idempotency-key tests/telemetry-v1 \
  --verbosity trace \
  -- test -p package-name
```

One capture follows the selected execution, every recursively owned apoc child
execution, and every live OS descendant of their stable process identities. A
sample contains wall time, current and accumulated CPU, resident and virtual
memory, disk reads and writes, and process count. It excludes command lines,
environment values, and log contents. When the byte cap is reached, apoc removes
the oldest complete samples and preserves stable sequence numbers for the newest
ones.

Attach to work that is already running with a keyed mutation. `get` returns a
compact newest-and-peaks summary unless the caller addresses raw NDJSON lines:

```sh
apoc execution telemetry start EXECUTION_ID \
  --idempotency-key incident-42/telemetry-start \
  --purpose 'Attach telemetry to the active execution.' --format json
apoc execution telemetry get EXECUTION_ID --grep '"memory_bytes"' --context 1 \
  --purpose 'Find memory measurements before expanding a range.' --format json
apoc execution telemetry get EXECUTION_ID --lines 40-80 \
  --purpose 'Read the selected telemetry sequence range.' --format json
apoc execution telemetry stop EXECUTION_ID \
  --idempotency-key incident-42/telemetry-stop \
  --purpose 'Stop sampling while preserving retained measurements.' --format json
```

Active captures resume after daemon recovery. A telemetry collection or storage
fault marks only the capture `degraded`; it never changes the execution verdict.
With telemetry disabled, apoc starts no sampler and writes no capture or sample
records.

Secret environment values use `NAME=env:VARIABLE`. apoc stores the reference
and resolves the value only when the process launches. Literal environment
values are part of the durable execution specification and are stored locally.

## Local error tracking

apoc automatically records local error metadata in
`<apoc state directory>/telemetry/errors.jsonl`. On macOS the default is
`~/Library/Application Support/apoc/telemetry/errors.jsonl`; `APOC_HOME` selects
a different state directory. Nothing is uploaded.

The log covers CLI and parser failures, MCP tool errors, typed-command failures,
daemon RPC faults, failed execution transitions, Code Mode errors, history storage failures,
and Rust panics. Records contain a timestamp, build and execution-schema
versions, OS and architecture, PID, operation, error code, available invocation
and execution IDs, and a SHA-256 error fingerprint. Panic records also identify
the source location. Arguments, environment values, purpose text, output logs,
and raw error messages are excluded. Use the IDs to inspect existing durable
history and execution records when the complete diagnostic is needed.

Each log retains at most 1 MiB and rotates to `errors.previous.jsonl`, keeping
at most 2 MiB across the pair. The directory is private (0700), and files are
0600. Recording is best effort: unavailable storage or a contended nonblocking
lock skips the event without changing a command's output, exit status, or
verdict. Set `APOC_ERROR_TELEMETRY=off` before launching apoc to disable it;
restart an existing daemon for that daemon to inherit the setting.

This error log is separate from the opt-in execution resource sampler described
above. Successful executions and allowed nonzero exits do not generate execution-failure events.

## Debug a managed Node execution

Use `debugger run` to launch Node as a durable execution and return its linked
debugger session in one typed call. apoc adds `--inspect-brk=HOST:PORT` when the
Node argv does not already declare an inspector option. Every other argument
remains exact argv.

```sh
apoc code run '
  return await apoc.debugger_run({
    executable: "node",
    arg: ["app.js"],
    port: 9231,
    id: "s0",
    purpose: "Launch Node and open its debugger.",
    idempotency_key: "debug/app/run-v1"
  });
' --purpose 'Launch Node and open its debugger.' \
  --idempotency-key debug/app/run-outer-v1 --format json
```

Use `debugger open` when the target already exists. `debugger targets` returns
Node and page target identities, titles, URLs, and WebSocket endpoints.

Debugger source locations are one-based. Breakpoints use a source suffix and
survive script reloads because apoc sends `Debugger.setBreakpointByUrl`.

```sh
apoc code run '
  return await apoc.debugger_breakpoint_set({
    id: "s0", file: "src/app.js", line: 42,
    purpose: "Break before the failing statement.",
    idempotency_key: "debug/app/break-42-v1"
  });
' --purpose 'Break before the failing statement.' \
  --idempotency-key debug/app/break-outer-v1 --format json

apoc code run 'return await apoc.debugger_status({id:"s0", purpose:"Read the debugger state."});' \
  --idempotency-key debug/app/status-outer-v1 \
  --purpose 'Read the debugger state.' --format json
apoc code run 'return await apoc.debugger_stack({id:"s0", purpose:"Read the paused stack."});' \
  --idempotency-key debug/app/stack-outer-v1 \
  --purpose 'Read the paused stack.' --format json
apoc code run 'return await apoc.debugger_evaluate({id:"s0", expression:"value", idempotency_key:"debug/app/eval-1", purpose:"Inspect the paused value."});' \
  --idempotency-key debug/app/eval-outer-v1 \
  --purpose 'Inspect the paused value.' --format json
apoc code run 'return await apoc.debugger_step({id:"s0", kind:"over", idempotency_key:"debug/app/step-1", purpose:"Step over once."});' \
  --idempotency-key debug/app/step-outer-v1 \
  --purpose 'Step over once.' --format json
```

`step` accepts `over`, `into`, or `out`. `continue` waits for the next pause,
exit, or disconnect; `resume` returns the observed running state. Source,
scopes, variables, `this`, properties, prototypes, scripts, listeners, console,
exceptions, health, Chrome DevTools Protocol (CDP) trace, and durable event reads are separate typed
commands. Evaluation retains object IDs, unserializable values, descriptions,
and exception details. If a CLI object ID begins with `-`, put the positional
arguments after the first literal `--`.

Every debugger mutation requires an idempotency key. Sessions, actor-scoped
selection, breakpoints, hit counts, events, diagnostics, and replay receipts
are durable. On daemon restart, apoc reconnects an open Node session and
restores its breakpoints. `debugger restart` cancels and relaunches the linked
execution while preserving the session and breakpoint identities. `debugger
close` disconnects CDP but does not cancel the linked execution; cancel that
execution explicitly when the program should stop.

## Capture taps and expression watches

A tap is a conditional CDP logpoint that captures one JavaScript expression
without pausing the target. The source line is one-based. By default, apoc
escapes the source suffix into a URL regular expression; `url_regex` overrides
that match for bundles and generated scripts.

```sh
apoc code run '
  return await apoc.debugger_tap_add({
    id: "s0", file: "src/cart.js", line: 42,
    expression: "cart.total",
    idempotency_key: "debug/cart/tap-total-v1",
    purpose: "Capture the cart total without pausing."
  });
' --purpose 'Capture the cart total without pausing.' \
  --idempotency-key debug/cart/tap-total-outer-v1 --format json
```

`debugger_tap_list` reports whether each tap resolved against a loaded script.
An unresolved tap remains pending and resolves when CDP reports its eventual
script location. `debugger_tap_hits` returns retained hits in chronological
order. Tap sentinel messages are routed into hit storage at the protocol-event
boundary and never enter user console, recorder `after`, timeline, or `why`
evidence. `debugger_tap_remove` disables the adapter breakpoint but preserves
its hit history.

An expression watch samples a running or paused JavaScript runtime every 250
milliseconds and stores only value or evaluation-error transitions. The target
is both its label and default expression; use `expression` when the label and
JavaScript differ. The `access` value records the evidence intent as `read`,
`write`, or `rw`.

```sh
apoc code run '
  return await apoc.debugger_watch_add({
    id: "s0", target: "cart total", expression: "cart.total",
    access: "write",
    idempotency_key: "debug/cart/watch-total-v1",
    purpose: "Retain cart total changes."
  });
' --purpose 'Retain cart total changes.' \
  --idempotency-key debug/cart/watch-total-outer-v1 --format json
```

`debugger_watch_list`, `debugger_watch_hits`, and `debugger_watch_remove` read,
inspect, and disable watches. apoc retains the newest 1,000 hits per tap or
watch while preserving total observed hit counts. Enabled taps and watch
workers restore when an open debugger session reconnects or restarts. Every add
or remove requires an idempotency key.

## Control a browser page

Launch Chrome through `execution start`, discover its page target with
`debugger targets`, and attach it with `debugger open --target-id`. The session
view reports `browser_cdp`, the stable page target ID, and any linked execution.
The browser subgroup then uses that named durable session.

For headless automation, launch Chrome for Testing rather than branded Google
Chrome. Branded Chrome 153 quits `--headless=new` on its own about thirty
seconds after launch, with a clean exit and no message, which ends the debugger
session midway; the session error then reads `Debugger connection closed: the
connection failed: ...`. Chrome for Testing stays up. Install it with
`npx @puppeteer/browsers install chrome@stable`.

```sh
apoc code run '
  const page = await apoc.debugger_browser_navigate({
    id: "browser-main", action: "url", target: "http://127.0.0.1:3000",
    timeout_ms: 30000,
    idempotency_key: "browser/app/navigate-v1",
    purpose: "Open the local application."
  });
  const button = await apoc.debugger_browser_dom({
    id: "browser-main", selector: "button[type=submit]",
    purpose: "Inspect the submit button."
  });
  return {page, button};
' --purpose 'Open and inspect the local application.' \
  --idempotency-key browser/app/navigate-outer-v1 --format json
```

`debugger browser navigate` supports URL, reload, back, and forward. `click`
and `type` dispatch trusted input; `select` updates the element and dispatches
input and change events. DOM, computed styles, cookies, local and session
storage, performance metrics, network requests and bodies, WebSocket frames,
and page lifecycle events are addressed reads.

`debugger browser screenshot` stores a content-addressed PNG artifact. It can
capture the viewport, full page, or one selector; optional viewport overrides
and forced `hover`, `active`, `focus`, or `visited` state are restored before
the command returns. Inline base64 PNG bytes require `--inline`.

Mocks, device emulation, throttling, and JavaScript and CSS coverage are durable
browser-session state. Mocks restore after daemon restart. Every navigation,
interaction, capture, mock, emulation, throttling, and coverage command requires
an idempotency key.

## Record a browser session

Start a flight recording on an attached page session. apoc captures the current
page immediately, captures later frame navigations, and resumes the capture
worker when the daemon reconnects the session.

```sh
apoc code run '
  return await apoc.debugger_recording_start({
    id: "browser-main",
    max_frames: 200,
    max_bytes: 104857600,
    idempotency_key: "record/app/start-v1",
    purpose: "Start the browser flight recording."
  });
' --purpose 'Start the browser flight recording.' \
  --idempotency-key record/app/start-outer-v1 --format json
```

`capture` adds a reasoned manual frame. `shoot` is the deliberate-capture
variant. `mark` captures a frame and protects it with a named timeline mark.
`captures` and `marks` read one recording by its durable ID. `replay` restores
one retained capture URL and vertical scroll position. `stop` captures a final
frame and terminalizes the recording.

`after` captures current browser state and compares it with `--at capture:ID`
or `--at mark:NAME`; without `--at`, it uses the latest retained capture. The
durable result includes changed pixels and their bounding region, new console
entries, exceptions and failed requests, storage and computed-style changes,
new accessibility findings, performance changes, explicit probe warnings, and
a content-addressed self-contained HTML report. `after-get` reads one analysis
by ID, and `afters` lists analyses for a recording.

`timeline` joins captures, marks, console errors, exceptions, network failures,
after diffs, debugger events, invocation purposes, workspace commit and dirty
digests, executions, and correlated apoc causal events by epoch millisecond. It
returns bounded structured items and a content-addressed, self-contained HTML
filmstrip. Timeline trimming retains every mark, error, exception, and diff and
at least the newest item of every joined evidence kind. The report mutation
requires an idempotency key.

`why` selects the latest recorded error or exception, optionally restricted by
a case-insensitive substring, then ranks edits with explicit causal path
evidence, diffs, executions, and causal events inside a configurable lookback
window. Stack-file matches receive a deterministic boost. The result includes
the nearest mark, invocation purpose, commit, diff, and execution plus explicit
limitations when apoc did not record file-level edit or commit evidence.

The first, latest, and marked captures are protected from count and logical-byte
retention trimming. If those protected frames exceed a configured bound, status
reports `retention_overflow` instead of claiming that apoc discarded evidence.
Every recorder mutation requires an idempotency key.

## Record and replay a browser flow

A flow records user actions while a browser flight recording is running. It
preserves a stable selector and structural fallback for clicks, changed inputs,
and selected key presses, plus scroll positions and top-level navigations. An
active flow resumes after the daemon reconnects its browser session.

```sh
apoc code run '
  const flow = await apoc.debugger_flow_record({
    id: "browser-main",
    name: "checkout",
    idempotency_key: "flow/checkout/record-v1",
    purpose: "Record the checkout browser flow."
  });
  return flow;
' --purpose 'Record the checkout browser flow.' \
  --idempotency-key flow/checkout/record-outer-v1 --format json
```

Perform the browser actions, then call `debugger_flow_stop`. `debugger_flow_run`
opens the recorded start URL and replays the ordered steps. Before each element
action, it waits until the primary selector or structural fallback is visible
and hit-testable. Every attempted step stores a browser capture. New console
errors or exceptions fail that step and skip the remaining steps. Starting with
the second run, each step reports its screenshot difference from the matching
step in the preceding run.

`debugger_flow_list` returns compact durable flow records.
`debugger_flow_show` returns one named flow with its ordered steps and prior run
evidence. Record, stop, and run are mutations and require idempotency keys. A
flow remains tied to its browser session and the active flight recording that
owns its captures.

## Preserve and replay a debugger evidence trace

An evidence trace binds a named interval to an existing debugger session and
its apoc-owned execution. If a browser flight recording is active when the
trace starts, the trace also binds that recording. Starting a trace does not
launch or own another process.

```sh
apoc code run '
  return await apoc.trace_start({
    id: "s0",
    name: "checkout failure",
    idempotency_key: "trace/checkout/start-v1",
    purpose: "Start checkout failure evidence."
  });
' --purpose 'Start checkout failure evidence.' \
  --idempotency-key trace/checkout/start-outer-v1 --format json
```

`trace_stop` closes the interval. `trace_show` joins debugger events, recording
captures and marks, after analyses, tap hits, watch transitions, and flow steps
into one bounded chronological timeline. `trace_list` returns compact durable
trace records.

`trace_use` selects a trace for the invoking actor. `trace_replay` selects the
latest item or an explicit `KIND:ID` anchor and restores a browser capture when
that item is replayable. `trace_cursor` reads the current anchor. `trace_move`
moves backward or forward through the timeline, optionally filtered by kind;
`trace_jump` moves to the previous or next item of a required kind. Unknown and
malformed anchors fail instead of silently selecting different evidence.

`trace_export` writes a versioned JSON bundle into apoc's content-addressed
artifact store. `trace_import` validates a bundle from an explicit path,
preserves its trace identity and items, marks it imported, and stores its exact
bytes in the receiving artifact store. `trace_gc` keeps the requested newest
terminal traces plus every active recording trace. All trace state mutations,
including cursor movement, require idempotency keys.

## Record and replay an rr trace

`rr_record` launches rr as a durable apoc execution and passes the target as
exact argv. It defaults to the built-in isolated VZ backend on macOS and the
native backend elsewhere. Select either path explicitly with `backend: "isolated"`
or `backend: "native"`; isolated calls accept `image: "local"`, an absolute
bundle path, or a canonical image digest. apoc owns the recording execution,
logs, lease, terminal verdict, export artifact, and resulting trace identity.

The local macOS image pins the software-counter rr fork at Git revision
`c93b27695e2bed5ceec7770a568379452cbf55c5`. The bundle verifier exposes that
revision as `build.rr_software_counters_revision`. Isolated recording uses rr's
`-W -n` software-counter mode because Apple Silicon VMs do not expose the
hardware performance counters required by upstream rr.

```sh
apoc code run '
  return await apoc.rr_record({
    executable: "./app",
    arg: ["--fixture", "failing.json"],
    name: "native-crash",
    backend: "isolated",
    image: "local",
    idempotency_key: "rr/native-crash/record-v1",
    purpose: "Record the native crash with rr."
  });
' --purpose 'Record the native crash with rr.' \
  --idempotency-key rr/native-crash/record-outer-v1 --format json
```

The CLI equivalent places apoc options before the first literal separator and
the exact target argv after it:

```sh
apoc rr record --name native-crash \
  --backend isolated --image local \
  --idempotency-key rr/native-crash/record-v1 \
  --purpose 'Record the native crash with rr.' \
  -- ./app --fixture failing.json
```

After a successful isolated recording, the provider exports the workspace-bound
trace as a digest-verified execution artifact. apoc copies it into the debugger
CAS, materializes a sandbox-readable replay copy, and removes the uniquely named
temporary workspace directory. Native recording uses the same final artifact
and materialized trace contract. apoc does not infer success from a directory
alone: if the managed execution reaches no successful verdict, the trace fails
and no partial directory is promoted as a replay artifact.

`rr_replay` starts interactive rr replay as a durable PTY execution. Use its
execution ID with `execution_attach`, `execution_input`, `execution_signal`, and
`execution_cancel`; replay does not introduce a second lifecycle. Event, process
ID, and end-of-trace selection map to rr `-g`, `-p`, and `-e`. `rr_ps` runs rr
process inspection as a one-shot durable execution and returns its bounded
logs.

`rr_import` accepts an explicit rr trace directory without requiring rr to be
installed on the importing host. It archives without following symlinks,
validates extraction through the tar reader, normalizes replay permissions, and
stores both the CAS artifact and an apoc-owned materialized directory. `rr_list`
and `rr_show` return the
durable trace, execution, replay, artifact, failure, and timestamp links. Only
rr-backed traces claim instruction-level replay; debugger evidence traces do
not.

## Every call is an assertion

Agent context is the scarcest resource in an execution loop, so an execution
answers with a verdict and nothing else. Silence is safe because the caller
declares what a correct result looks like before the command runs.

```sh
apoc execution command npm \
  --expect-stdout-regex 'All tests passed' \
  --purpose 'Verify the worker suite passes before touching the API.' \
  --idempotency-key tests/worker-suite-v1 \
  -- test
```

```json
{"id": "01a00c9e-46c6-7b20-b68b-951987567f62", "outcome": "failed"}
```

That is the entire response, for a success and a failure alike. `outcome` uses
the JUnit and TAP vocabulary:

| `outcome` | Meaning |
| --- | --- |
| `passed` | Exited zero and any declared expectation held |
| `failed` | The assertion did not hold: a nonzero exit, or a missed expectation |
| `error` | A fault reached no verdict: launch failure, stall, or cancellation |
| `skipped` | Declared but never launched |
| `pending` | Durably owned and not yet terminal |

- Expectations are the predicates a poll already evaluates:
  `--expect-exit-code`, `--expect-stdout-regex`, `--expect-stderr-regex`,
  `--expect-json-pointer` with `--expect-json-equals`, and `--expect-js`. A poll
  evaluates one repeatedly; a command evaluates it once.
- The CLI exit status mirrors the verdict, so a shell caller needs no payload at
  all. A missed expectation exits nonzero even when the program exited zero.
- The expectation is stored in the durable spec, so invocation history records
  what each call asserted, not merely what it ran.
- A batch or pipeline has no single output to assert against, so every declared
  command carries its own `expect`. A child whose assertion did not hold fails
  that child and its parent, even when the program exited zero.

```sh
apoc execution batch --max-parallel 2 \
  --purpose 'Assert both suites before merging.' \
  --idempotency-key verify/assert-suites-v1 \
  --commands '[
    {"id":"unit","argv":["npm","test"],
     "expect":{"kind":"stdout_regex","pattern":"0 failing"}},
    {"id":"types","argv":["npx","tsc","--noEmit"],
     "expect":{"kind":"exit_code","codes":[0]}}
  ]'
```

### Reveal output progressively

Output is never returned unless it is asked for. Search the durable log, then
expand around what you find:

```sh
apoc execution logs EXECUTION_ID --grep 'AssertionError' --context 2 \
  --purpose 'Locate the failing assertion.' --format json
apoc execution logs EXECUTION_ID --lines 340-420 \
  --purpose 'Read the failure in context.' --format json
```

Matching runs inside the daemon, so a 500 KB log is never shipped to a caller
that wants one line. Every slice reports `total_matches`, `stdout_lines`, and
`stderr_lines`, so a caller always knows how much it has not read.

### Verbosity

`--verbosity off|error|warn|info|debug|trace`, following syslog and `tracing`.
The default is `error`, the verdict above. `-v` reaches `info` (status, exit
code, withheld sizes, follow-up reads) and `-vv` reaches `debug` (bounded log
tails); each of those only adds to the level below it. `-q` lowers the level, and
`off` returns no payload at all.

`trace` is the exception to that ladder: it answers with the complete durable
record rather than the verdict envelope, so a typed consumer addresses the record
by the JSON Pointer it already uses. It still carries `outcome`, so no level
costs you the verdict.

`APOC_VERBOSITY` sets a session default and reaches nested Code Mode calls
through the invoking process. `--view outcome|full` and `APOC_VIEW` remain as
deprecated aliases, each keeping the contract it named: `outcome` is the
collapsed verdict, `full` is the complete record.

`execution logs`, `attach`, `tree`, and `poll iterations` always return their own
detail because they are the drill-down. Poll conditions and recipe output
validation always evaluate the complete record, so their pointers, regexes, and
schemas address every field.

## Poll commands and typed apoc operations

Use `poll run` when one observation must be repeated until it matches or reaches
a bound. Use `poll start` to return the durable parent execution immediately.
Both forms use the existing `execution get`, `wait`, and `cancel` lifecycle.

```sh
apoc poll run command curl \
  --interval-mode fixed-delay \
  --interval-ms 1000 \
  --until-stdout-regex '"status":"ready"' \
  --duration-ms 300000 \
  --purpose 'Wait for the local health endpoint to report ready.' \
  --format json \
  -- http://localhost:3000/health
```

Poll options are named arguments and have no ordering requirement before `--`.
The separator preserves exact command argv. Interval behavior uses these request
arguments; it does not use interval subcommands.

| `--interval-mode` | Arguments | Behavior |
| --- | --- | --- |
| `fixed-delay` | `--interval-ms` | Wait after each unmatched observation. |
| `backoff` | `--initial-interval-ms`, `--multiplier`, `--max-interval-ms` | Increase the delay to the cap. |
| `fixed-rate` | `--interval-ms` | Use acceptance-based ticks, skip missed ticks, and never overlap. |

Conditions include repeated `--until-exit-code`, stdout or stderr regex,
`--until-json-pointer` with `--until-json-equals`, and a pure boolean
`--until-js` expression over `observation`. Select one condition family. A poll
without a condition must include `--max-iterations` or `--duration-ms` and
completes as bounded sampling. A condition that reaches a bound fails with
`POLL_CONDITION_NOT_MET`.

Poll the shared typed graph with `apoc` as the target. This does not spawn a
nested apoc CLI process:

```sh
apoc poll start apoc process.ports \
  --arguments '{"port":3000}' \
  --until-js 'observation.result.length > 0' \
  --interval-mode fixed-rate \
  --interval-ms 5000 \
  --duration-ms 600000 \
  --purpose 'Wait for a process to own port 3000.' \
  --format json
```

The parent result stays compact. Expand only the evidence needed for diagnosis:

```sh
apoc poll iterations POLL_ID --limit 20 --purpose 'List recent poll observations.' --format json
apoc poll iteration POLL_ID ITERATION_ID --purpose 'Read one poll observation.' --format json
apoc execution logs CHILD_EXECUTION_ID --tail-bytes 65536 --purpose 'Read the command iteration logs.' --format json
```

## Run independent commands concurrently

Use one batch when the agent already knows the independent commands. apoc bounds
concurrency, records each child, and returns a compact failure-oriented parent.
`max_parallel` defaults to the logical CPU count and is limited to 256.

```json
{
  "commands": [
    { "id": "unit", "argv": ["cargo", "test", "--lib"] },
    { "id": "types", "argv": ["cargo", "check", "--all-targets"] },
    { "id": "format", "argv": ["cargo", "fmt", "--", "--check"] }
  ],
  "max_parallel": 3,
  "fail_fast": false
}
```

```sh
apoc execution batch \
  --commands '[{"id":"unit","argv":["cargo","test","--lib"]},{"id":"types","argv":["cargo","check","--all-targets"]}]' \
  --purpose 'verify the worktree concurrently' \
  --idempotency-key verify-91/batch \
  --format json
```

CLI callers may pass `--commands` once with a JSON array, or repeat it with one
JSON command object per occurrence. Use `--file commands.json` for larger or
reusable definitions. MCP and Code Mode pass the structured array directly.

Use a pipeline only when stdout must flow between stages. apoc creates native
pipes, starts every stage before waiting, keeps each child's stderr separate,
captures final stdout on the parent, and enables pipefail by default.

```json
[
  { "id": "produce", "argv": ["/usr/bin/printf", "apocalypse"] },
  { "id": "uppercase", "argv": ["/usr/bin/tr", "[:lower:]", "[:upper:]"] }
]
```

```sh
apoc execution pipeline \
  --commands '[{"id":"produce","argv":["/usr/bin/printf","apocalypse"]},{"id":"uppercase","argv":["/usr/bin/tr","[:lower:]","[:upper:]"]}]' \
  --purpose 'Uppercase the generated release text.' \
  --idempotency-key release-91/pipeline \
  --format json
```

## Compose heterogeneous work in Code Mode

Code Mode runs generated JavaScript in isolated QuickJS actors. The worker pool
defaults to `min(logical CPUs, 8)`; set `APOC_CODE_WORKERS` to override it.
Separate programs use separate actors, and one program can issue independent
host calls concurrently with `Promise.all`.

Use the typed `apoc.wait({ ms, purpose })` host call for a short delay when no
observable poll condition exists. It is capped at 60,000 milliseconds and does
not start a managed process; JavaScript `setTimeout` is not part of the QuickJS
contract.

```sh
apoc code run '
  const [processes, sockets, tests] = await Promise.all([
    apoc.process_list({ selector: "match:node", limit: 20, purpose: "List relevant Node processes." }),
    apoc.process_sockets({ listening: true, protocol: "tcp", limit: 100, purpose: "List listening TCP sockets." }),
    apoc.execution_command({
      executable: "cargo",
      arg: ["test"],
      idempotency_key: "verify/current-worktree-v1",
      purpose: "Verify the current worktree."
    })
  ]);
  return { processes, sockets, tests };
' --purpose 'Inspect processes and verify the current worktree.' \
  --idempotency-key verify/current-worktree-outer-v1 --format json
```

Code Mode persists source, immutable capabilities, ordered calls, replay state,
result, events, and oversized artifacts. Provider mutations record intent before
dispatch. Replay skips operations that already have a durable applied receipt.

Do not fan out shell strings that each invoke apoc through a host tool's
`Promise.all`. Use one `execution batch` for known commands or one Code Mode
program with typed `apoc.*` calls. Avoid concatenating large source trees with
`cat`; use targeted searches, bounded reads, or a compact Code Mode synthesis.

After apoc accepts a managed execution, an unsuccessful terminal status resolves
normally inside JavaScript. Inspect `execution.status` and throw explicitly when
the surrounding program must fail.

```sh
apoc code start 'return await apoc.execution_list({ purpose: "List recent executions." });' \
  --purpose 'Start an execution inventory query.' \
  --idempotency-key inventory/outer-v1 --format json
apoc code get EXECUTION_ID --purpose 'Check the Code Mode execution.' --format json
apoc code cancel EXECUTION_ID --purpose 'Cancel the Code Mode execution.' --idempotency-key inventory/cancel-v1 --format json
apoc code artifact EXECUTION_ID ARTIFACT_ID --purpose 'Read the Code Mode artifact.' --format json
```

If an outer Code Mode execution ends before its accepted child work is
summarized, recover the direct children without replaying the whole program:

```sh
apoc code run '
  return await apoc.execution_list({
    parent: "OUTER_EXECUTION_ID",
    status: "completed",
    limit: 100,
    purpose: "Recover completed direct child executions."
  });
' --purpose 'Recover direct child executions after an interrupted outer program.' \
  --idempotency-key recovery/direct-children-outer-v1 --format json
```

The parent filter returns direct children only and composes with status and
cursor pagination. Use `execution_get` or `execution_logs` only for selected
IDs. Provider-action receipts are separate from command lifecycle records, so
`receipt_get` is not a command recovery API.

The local executor's 300-second limit measures uninterrupted JavaScript. It is
renewed immediately before and after every host tool call, so connector and
managed-command wait time does not consume the runaway-loop budget. The outer
`code run --timeout-ms` value controls how long that client waits; accepted work
remains durable. A runaway loop fails with `CODE_EXECUTION_TIMEOUT`.

## Coordinate agents and resources

A session groups one agent's executions under a heartbeat. Its root lease is
`session/SESSION_ID`. When the heartbeat expires, the daemon releases the lease,
cancels session-owned executions, and releases their reservations.

```sh
apoc session open --actor release-agent --ttl-ms 60000 --purpose 'Open a release-agent ownership session.' --idempotency-key release-session/open-v1
apoc session heartbeat SESSION_ID --ttl-ms 60000 --purpose 'Renew the release-agent session.' --idempotency-key release-session/heartbeat-v1

apoc reservation acquire port tcp/5173 session/SESSION_ID --purpose 'Reserve the development port.' --idempotency-key release-session/reserve-port-v1
apoc reservation acquire path /absolute/worktree session/SESSION_ID --purpose 'Reserve the release worktree.' --idempotency-key release-session/reserve-worktree-v1

apoc execution start cargo \
  --owner session \
  --session SESSION_ID \
  --purpose 'Start tests owned by the release session.' \
  --idempotency-key release-session/tests-v1 \
  -- test

apoc session close SESSION_ID --timeout-ms 2000 --purpose 'Close the release-agent session.' --idempotency-key release-session/close-v1
```

Reservations provide atomic apoc-local ownership for ports, paths, exact
processes, devices, and custom keys. Port reservations also report native socket
conflicts. `reservation wait` waits for up to 30 seconds.

## Extend the capability graph

Providers add Streamable HTTP MCP, supervised MCP stdio, or OpenAPI operations
to the same graph. Their names become Code Mode namespaces. Secret configuration
uses `PROVIDER:REFERENCE` and resolves only when a client connects or a child
starts.

From an unpacked apoc source package, build and sign the native Rust VZ provider
and build the verified Linux arm64 VM bundle. Isolated execution resolves the
provider internally and does not require registration.

`build-provider.sh` builds `apoc-macos-vz`, signs it, and verifies the
`com.apple.security.virtualization` entitlement. Run it whenever Cargo replaces
the provider binary; an unsigned provider cannot start a virtual machine.

```sh
extensions/macos-native/scripts/build-provider.sh
extensions/macos-native/scripts/build-vm-bundle.sh extensions/macos-native/.build/vm-bundle

apoc execution image import extensions/macos-native/.build/vm-bundle \
  --idempotency-key image/import-v1 \
  --purpose 'Import the verified isolated VM image.' \
  --format json

apoc execution command /bin/echo \
  --isolated \
  --image sha256:IMPORTED_IMAGE_DIGEST \
  --workspace-mode none \
  --idempotency-key isolated-echo-v1 \
  --purpose 'Run echo in the built-in VZ guest.' \
  -- 'hello from VZ'

apoc execution image verify local \
  --purpose 'Verify the configured isolated VM image.' \
  --format json

apoc execution isolation status \
  --purpose 'Read the isolated VM pool without booting a VM.'
apoc execution isolation warmup \
  --vm-bundle "$PWD/extensions/macos-native/.build/vm-bundle" \
  --idempotency-key isolation-warmup-v1 \
  --purpose 'Wait for one usable isolated VM.'
apoc execution isolation drain \
  --idempotency-key isolation-drain-v1 \
  --purpose 'Tear down every pooled isolated VM.'

apoc provider add-mcp-http github https://example.test/mcp \
  --profile-mode required \
  --profile-header authorization=GITHUB_AUTHORIZATION \
  --idempotency-key provider-github-v1 \
  --purpose 'Register the GitHub MCP provider.'
apoc provider add-openapi logistics https://example.test/openapi.json \
  --base-url https://example.test/api \
  --idempotency-key provider-logistics-v1 \
  --purpose 'Register the logistics OpenAPI provider.'
```

`action run` and `action start` use the durable Code Mode lifecycle. Calls with
the same stable resource identity are ordered. Independent resources can run
concurrently. Every mutation stores an intent followed by an applied, failed, or
unknown receipt.

The packaged [native macOS VZ provider](https://docs.rs/crate/apoc/latest/source/extensions/macos-native/README.md)
contains the Rust provider, Linux guest, versioned wire protocol, build scripts,
and signing entitlement. The [image format](docs/image-format.md) is verified in
Rust without starting the daemon, provider, or a VM.

## Use apoc through MCP

The built-in command graph serves MCP stdio with `apoc --mcp`. Register the
absolute installed path so the agent host does not depend on shell startup
configuration:

```sh
APOC_BIN=$(command -v apoc)
codex mcp add apoc -- "$APOC_BIN" --mcp
codex mcp get apoc
```

The MCP, CLI, and Code Mode surfaces share command schemas, execution state,
idempotency behavior, and output contracts.

`apoc --mcp` serves the five Code Mode lifecycle tools — `codemode_search`,
`codemode_execute`, `codemode_execution`, `codemode_decide`, `codemode_cancel` —
and nothing else. The surface stays five tools however many commands apoc grows
and however many MCP servers you configure, so adding either never costs the
model another tool schema.

A program reaches apoc's own commands under `apoc.*`, and every MCP server already
configured on this machine, each under its own namespace: servers registered with Claude
Code, Codex, Cursor, VS Code, Copilot, Amp, Gemini, Windsurf or OpenCode are discovered
without anything to switch on. A namespace is named without being contacted and connects
on its first call, so a server that is slow, unreachable or removed costs nothing until a
program uses it, and cannot fail an execution that never names it. One
program can therefore read a repository, ask a downstream server about it, and
join both in JavaScript without returning to the model in between; only what it
returns crosses back.

`apoc mcp check` reports what was discovered without starting anything, and names the
reason a namespace is empty — an unsupported transport, a placeholder only a person can
supply, a rejected credential. `apoc mcp refresh` is the one command that contacts
servers and caches their schemas.

Two consequences worth knowing. The administrative command groups — `daemon`,
`code`, `profile`, `env`, `recipe`, `recording`, `receipt`, `capability`, `action`,
`provider`, `connector`, `skill`, `mcp`, `decider` — are reachable from the CLI but not from a
program, because each either cannot run safely from inside an execution or is a
human-at-a-terminal operation. And `codemode_decide` always reports that there is
nothing to decide: apoc runs every tool without pausing.

## Embed apoc in a Rust program

The same core the daemon runs can live inside another Rust process, with no
daemon and no socket. It answers the daemon's own requests by method name, and
Code Mode programs it runs reach `apoc.*` in-process.

```rust,no_run
use serde_json::json;

fn main() -> Result<(), String> {
    let apoc = apoc::Apoc::open("/absolute/path/to/app-state")?;
    let state = apoc.call(
        "code.run",
        json!({
            "code": "return (await apoc.execution_command({executable: '/bin/echo', \
                     arg: ['ready'], idempotency_key: 'ready', purpose: 'Check.'})).outcome;",
            "timeout_ms": 60_000,
            "purpose": "Run one command from an embedded core.",
        }),
    )?;
    assert_eq!(state["result"], "passed");
    Ok(())
}
```

`Apoc` blocks the calling thread and owns its own runtime; from async code, use
`apoc::CoreHandle::open(apoc::CoreConfig::new(path)).await` instead. Calling the
blocking API inside an async runtime returns `BLOCKING_FROM_ASYNC` rather than
deadlocking.

An embedded core owns its state root exclusively. Opening a root that another
core or the per-user daemon already owns fails with `STATE_ROOT_BUSY`, because
two owners would cancel each other's work. To work with the daemon's state,
talk to the daemon.

No daemon does not mean no threads. An open core runs process monitors, a
maintenance loop for hooks and lease expiry, and a pool of JavaScript workers,
and commands it starts keep running under their own budgets after a call
returns.

## Configure isolated profiles

Profiles are exclusive durable environments. A command selects one explicit
`--profile`, otherwise the longest matching canonical workspace root, otherwise
the nearest canonical cwd ancestor whose directory name exactly matches an
existing profile, otherwise the per-user default. Durable root mappings take
precedence over directory-name recognition. An explicit profile that disagrees
with either workspace selection fails instead of merging credentials. apoc never
creates a profile from a directory name; with no existing match and no default,
it runs without a profile. Secret values remain unresolved references and
resolve only when apoc constructs a process or provider transport.

```sh
apoc profile create personal --purpose 'Create the personal profile.' --idempotency-key profile-personal
# From /work/personal/project, cwd recognition now selects personal automatically.
apoc profile resolve --purpose 'Resolve this workspace profile.' --format json
# Use an explicit root mapping when the directory name differs from the profile.
apoc profile root add personal /work/client-alias \
  --purpose 'Map the client alias to the personal profile.' \
  --idempotency-key profile-personal-alias
apoc profile default personal --purpose 'Set the default profile.' --idempotency-key profile-default
apoc env set --profile personal RUST_LOG=debug \
  --purpose 'Set durable Rust logging.' --idempotency-key env-rust-log
apoc env secret --profile personal OPENAI_API_KEY env:OPENAI_API_KEY \
  --purpose 'Register the OpenAI key reference.' \
  --idempotency-key env-openai-key
apoc env doctor --profile personal --purpose 'Check whether the profile can resolve.' --format json
```

Each accepted execution pins the selected profile generation for its complete
child graph. Profile-controlled names are removed from daemon inheritance before
that generation is applied, and explicit command or command-unit overrides are
rejected. `env list`, `env doctor`, and `profile show` never return literal
values or secret references. The deprecated `env --global` form targets the
current default profile and creates `legacy-default` only when a compatible
mutation needs one. Every profile and environment mutation requires an
`--idempotency-key`.

## Search invocation history

apoc records each typed CLI, MCP, and Code Mode invocation in its local SQLite
database. Queries are local by default: every directory in one Git worktree
shares a scope, while a directory outside Git has its own exact canonical scope.
Use `--global` only when the task needs history from every recorded workspace.
Normalized arguments and options are stored and searchable. Secret-bearing
fields keep only their destination names; values, providers, and references are
removed before normalized input, search text, and pattern signatures are
written. Literal environment and header values remain recordable, so use
structured secret options for credentials.

```sh
apoc history list --limit 50 --purpose 'List recent local apoc activity.' --format json
apoc history list --error-code EXECUTION_PROGRESS_TIMEOUT --purpose 'List progress-timeout activity.' --format json
apoc history search 'process stop' --purpose 'Find earlier process stops.' --format json
apoc history search 'execution command' --global --purpose 'Find executions across workspaces.' --format json
apoc history list --cwd ../another-worktree --purpose 'List activity in the other worktree.' --format json
apoc history get INVOCATION_ID --purpose 'Read the complete invocation record.' --format json
apoc history patterns --min-count 3 --purpose 'Find repeated apoc workflows.' --format json
apoc history timeline --limit 100 --purpose 'Read apoc activity in event order.' --format json
apoc history query 'SELECT id, purpose FROM history ORDER BY started_at DESC LIMIT 20' --purpose 'Scan recent work narratives.' --format json
```

`list` and `search` return bounded reverse-chronological pages with
`invocations` and `next_cursor`. They accept exact filters for `source`,
`surface`, `command`, `status`, `actor`, linked `execution`, and `error-code`,
plus `since-ms` and `until-ms`. `--global` and `--cwd` cannot be combined. A local query does
not include imported records whose original working directory is unknown.
`timeline` returns complete sanitized records oldest-first. Its opaque cursor
holds a stable acceptance snapshot, so calls accepted after the first page do
not appear later in the same traversal. The default limit is 100 and the
maximum is 500.

`history query` runs one read-only SQL statement against an isolated in-memory
`history` table, never against apoc's durable database. The table exposes
`id`, `purpose`, `started_at`, `updated_at`, `status`, `command_path`, `source`,
`surface`, `actor`, `execution_id`, and `error_code` for filtering and ordering,
but results may contain only `id` and `purpose`. The CLI returns compact
`columns` plus positional `rows`, defaults to 20 rows, and hard-caps at 100 even
when the SQL asks for more. Use `history get ID` only after a purpose identifies
something worth expanding.

Native capture is automatic and does not call DevSQL. Historical shell and
agent transcripts can contain literal credentials, so inspect their retention
and access before importing them. The following explicit command runs DevSQL
once, imports only shell segments that invoke apoc, redacts recognized secret
flags, preserves source provenance, and skips records already imported:

```sh
apoc history import-devsql --purpose 'Import earlier apoc shell observations.' --format json
```

Imported records have `source: "devsql"`. Ordinary capture and every later
history query remain independent of DevSQL.

## React to typed apoc calls

Hooks run Code Mode JavaScript after an exact typed command starts, succeeds, or
fails. Configure the dotted method identity shown by Code Mode, such as
`execution.command`; apoc normalizes the command graph's display path before
matching. A hook is local to the current worktree or canonical directory unless
you pass `--global`. A local hook shadows a global hook with the same name, while
differently named hooks stack.

```sh
apoc hook put build-followups execution.command \
  --on-success 'return await apoc.action_start({provider: "notify", method: "send", input: JSON.stringify({source_invocation: hook.invocation.id}), idempotency_key: hook.delivery.id, purpose: "Send the successful execution notification."});' \
  --on-failure 'return await apoc.execution_start({executable: "collect-diagnostics", arg: [hook.invocation.id], idempotency_key: hook.delivery.id, purpose: "Collect diagnostics for the failed apoc call."});' \
  --max-attempts 3 \
  --purpose 'Install build follow-up automation.' \
  --idempotency-key build-followups-v1

apoc hook deliveries --hook build-followups \
  --purpose 'Inspect build follow-up deliveries.' --format json
```

The hook program receives a frozen `hook` object. `hook.delivery` contains
`id`, `hook`, `generation`, `phase`, `attempt`, and `max_attempts`;
`hook.invocation` is the source invocation snapshot with normalized input and
terminal status when applicable. Use `hook.delivery.id` in nested mutation
idempotency keys so a daemon-interrupted attempt can replay safely.

When invocation history reaches a configured lifecycle transition, matching
deliveries are persisted and run asynchronously in the daemon. Hook success or failure never
changes the source call's verdict. Failed programs retry with bounded exponential
backoff and become durably `failed` after `max_attempts`. Daemon recovery returns
interrupted deliveries to `pending`. Calls made by a hook carry hook depth and do
not create more hook deliveries, preventing accidental recursion. Each attempt
also emits `hook.delivery.started` and `hook.delivery.result` causal events.

Use `hook get`, `list`, `remove`, `delivery`, and `deliveries` to manage and
inspect definitions and outcomes. At least one of `--on-start`, `--on-success`,
or `--on-failure` is required.

## Ask a decider before commands run

A decider is a Code Mode program you register. Before apoc launches a command,
it runs every enabled decider that covers the command's verb, with a frozen
`intent` describing the launch in scope, and waits for
`{decision: "allow" | "refuse" | "pending", reason}`. Any refusal stops the
launch, which fails with `INTENT_REFUSED` and the decider's own reason.

```sh
apoc decider put no-rm \
  --program 'const argv = intent.body.argv || [];
             return argv[0] === "/bin/rm"
               ? {decision: "refuse", reason: "rm is not allowed here"}
               : {decision: "allow"};' \
  --verb execution.command \
  --on-unavailable refuse \
  --timeout-ms 2000 \
  --purpose 'Refuse rm in this workspace.' \
  --idempotency-key decider/no-rm-v1
apoc decider list --purpose 'List registered deciders.' --format json
apoc intent list --purpose 'Read what deciders were asked.' --format json
apoc decider remove no-rm --purpose 'Remove the rm decider.' --idempotency-key decider/no-rm-remove-v1
```

`--on-unavailable` is required: you decide whether a decider that times out,
fails, or returns something malformed lets the command through or refuses it.
Such an intent is recorded as `unchecked`, never as ruled. The decider group is
available on the CLI but not inside Code Mode programs.

What is checked today is every command launch: `execution command` and
`start`, each batch child and pipeline stage, poll command iterations, and
commands run from Code Mode programs, hooks, and recipes. Not yet checked:
process signals and stops, calls into MCP servers and providers, isolated and
provider-backed executions, and debugger sessions.

What an intent can and cannot tell a decider:

- Its targets are only what apoc itself resolved: for a command, the executable
  on the path it will launch. apoc does not parse arguments, so
  `rm -rf $TMPDIR/x` names `/bin/rm` and nothing else.
- A shell string is not analysable: `analysable` is false and its only target
  is `opaque:`. `analysable: true` means apoc did not have to give up on the
  request's form, not that it understood the effect.
- A decider's own commands are not offered back to deciders.
- `pending` currently refuses; nothing yet holds a command open until someone
  answers.

`intent list` records an entry only when at least one decider was asked.

## Build a temporary command namespace

Use recipes when repeated commands should become a small composable interface
without creating a standalone binary. Dotted names form the namespace. A recipe
is local to the current Git worktree, or the exact current directory outside
Git, unless you pass `--global`. Local definitions shadow global definitions
with the same name.

```sh
apoc recipe put release.logs \
  'return await apoc.execution_command({ executable: "tail", arg: ["-n", "100", input.file], purpose: "Read the latest release log.", idempotency_key: input.key });' \
  --input-schema '{"type":"object","required":["file","key"]}' \
  --ttl-ms 86400000 \
  --purpose 'Define the temporary release-log command.' \
  --idempotency-key release-logs-v1

apoc recipe put release.verify \
  'return await recipes.run("release.logs", input);' \
  --dependency release.logs \
  --purpose 'Define the composed release verification command.' \
  --idempotency-key release-verify-v1

apoc recipe run release.verify \
  --input '{"file":"/tmp/release.log","key":"release-log-read"}' \
  --purpose 'Run the temporary release verification command.' \
  --idempotency-key release-verify-run-1 \
  --format json
```

apoc resolves the complete declared dependency graph before execution. Missing,
expired, cyclic, deeper-than-16, and larger-than-64 graphs fail before Code Mode
runs. The resolved functions execute inside one Code Mode program. Draft
2020-12 input and output schemas validate the top-level recipe boundary. Repeat
`--require-env NAME` on `recipe put` when a recipe must fail before Code Mode if
a literal or secret value cannot resolve. Portable bundles include required key
names, never values or references.

The caller LLM can propose a recipe from exact chronological evidence without
making it executable. apoc stores the candidate and rationale; it does not run
an embedded model or infer candidates with built-in heuristics.

```sh
apoc recipe suggest release.verify 'return input;' \
  --positive FIRST_ID..SECOND_ID \
  --positive THIRD_ID..FOURTH_ID \
  --rationale 'The same verified sequence was repeated.' \
  --require-env RELEASE_TOKEN \
  --purpose 'Suggest a temporary release verification command.' \
  --format json

apoc recipe suggestions --purpose 'List pending recipe suggestions.' --format json
apoc recipe suggestion SUGGESTION_ID --purpose 'Read the selected recipe suggestion.' --format json
apoc recipe adopt SUGGESTION_ID \
  --purpose 'Adopt the selected recipe suggestion.' \
  --idempotency-key adopt-release-verify --format json
```

Suggestions remain separate from lookup, dependency resolution, execution
tools, and bundles. Adoption atomically creates the exact candidate and links
the suggestion. The default adopted lifetime is 604800000 ms (7 days); pass a
positive `--ttl-ms` to override it. A different existing generation is a
conflict unless you pass `--replace`.

Expired recipes remain durable but are hidden and cannot run. `recipe pin`
clears one expiry, and `recipe prune` deletes expired recipes in the selected
scope. Both commands require `--idempotency-key`.

```sh
apoc recipe list --prefix release. --include-expired --purpose 'List release recipes including expired entries.' --format json
apoc recipe pin release.verify --purpose 'Keep the release verification recipe.' --idempotency-key release-verify-pin
apoc recipe prune --purpose 'Remove expired local recipes.' --idempotency-key release-prune

apoc recipe export release. --file ./release-recipes.json \
  --purpose 'Export the release recipe namespace.' \
  --idempotency-key release-export
apoc recipe import ./release-recipes.json --ttl-ms 86400000 \
  --purpose 'Import the release recipe namespace.' \
  --idempotency-key release-import
```

`recipe export` writes `RecipeBundleV1` and includes transitive dependencies.
The bundle excludes scope, expiry, timestamps, receipts, and resolved secrets.
`recipe import` validates the whole bundle before one atomic database write and
rejects conflicts unless you pass `--replace`.

## Record ordinary work into a command

Use recordings when the work that should become a recipe is work you are about to
do anyway. Bracket it, run apoc normally, and stop with the name it should take.
apoc transcribes the captured invocations into one Code Mode program and writes
it into the recipe namespace described above.

```sh
apoc recording start deploy.verify \
  --purpose 'Record the deploy verification procedure.' \
  --idempotency-key deploy-record-1

apoc recording param sha=abc123 --purpose 'Pin the commit as a recipe input.'

apoc execution command ./deploy.sh --purpose 'Deploy the recorded commit.' \
  --idempotency-key deploy-1 --expect-exit-code 0 -- --sha abc123
apoc execution command curl --purpose 'Verify the deployed health endpoint.' \
  --idempotency-key health-1 --expect-stdout-regex '"ok"' -- -sf https://example.test/health

apoc recording stop deploy.verify \
  --purpose 'Promote the recorded procedure to a recipe.' \
  --idempotency-key deploy-record-stop-1 --format json

apoc recipe run deploy.verify --input '{"sha":"def456","runKey":"verify-1"}' \
  --purpose 'Verify the newly deployed commit.' --idempotency-key verify-1
```

A recording is local to the current Git worktree, or the exact current directory
outside Git, unless you pass `--global`. One recording is active per scope at a
time. Every typed invocation in that scope joins the recording, reads included,
except the `recording` commands themselves and the nested host calls inside a
`code run` program, which would otherwise emit twice.

Transcription is exact. Each call site is the recorded `command_path` and its
stored normalized input, so `execution command` becomes `apoc.execution_command`.
Options left unset or left at their declared default are omitted, because
omitting them resolves to the same value when the recipe runs. apoc does not run
an embedded model and does not invent steps.

Three sources decide which recorded literals become recipe inputs. Earlier
sources win.

| Source | Declared by | Result |
| --- | --- | --- |
| Explicit holder | `recording param NAME=VALUE` | Required input, substituted wherever that exact value appears. |
| Take difference | A second `recording start` with the same name | Required input for every path whose value changed between takes. |
| Recorded variation | The same normalizer behind `history patterns` | Optional input that falls back to the recorded literal. |

`recording param` compares values as JSON strings; pass `--json` when the holder
should match an exact number, array, or object. `recording literal '$.timeout_ms'`
forces one step-relative path to stay literal in every step.

Recorded idempotency keys never become literals. Each one is rebuilt from a
single required `runKey` input, so rerunning a recipe performs real work instead
of replaying the original receipts. Recorded secret references are redacted in
history and cannot be transcribed, so each redacted destination becomes a
required input holding its `PROVIDER:REFERENCE`.

```sh
apoc recording status --purpose 'Read what the recording would emit.' --format json
apoc recording list --purpose 'List recordings in this scope.' --format json
apoc recording get RECORDING_ID --purpose 'Read one recording and its call sites.' --format json
apoc recording discard --purpose 'Abandon the active recording.' --idempotency-key deploy-record-drop-1
```

Read `recording status` before stopping to see the exact ordered call sites, then
repeat `--skip INVOCATION_ID` on `recording stop` to drop the ones that were
incidental. Adding a take requires the same call sequence; a different length or
a different command at the same position fails with `RECORDING_TAKES_DIVERGED`
and writes nothing.

Stop with `--suggest` instead of a plain stop when the candidate should stay
non-executable. That path stores a `recipe suggestion` with each take as
positive evidence and leaves adoption to `recipe adopt`. It requires at least two
takes, matching the evidence rule for suggestions.

Recorded parallelism is emitted sequentially. A recording captures the order
calls were accepted, not their concurrency, so rewrite the emitted body with
`Promise.all` through `recipe put` when the steps are independent.

## Inspect events and state

apoc appends monotonically ordered lifecycle events. Repeated large payloads are
content-addressed and deduplicated; event metadata remains after payload pruning.

```sh
apoc event query --after 0 --limit 100 --purpose 'List recent lifecycle events.'
apoc event watch --after CURSOR --timeout-ms 30000 --purpose 'Wait for new lifecycle events.'
apoc event export --after 0 --format jsonl --purpose 'Export lifecycle events as JSON lines.'
apoc event payload PAYLOAD_ID --purpose 'Read the selected event payload.'
apoc event pin PAYLOAD_ID --purpose 'Keep the selected event payload.'
apoc event prune-payloads --max-age-ms 2592000000 --purpose 'Remove old unpinned event payloads.'
```

Commands that need durable ownership automatically start one detached daemon per
user.

```sh
apoc daemon start --purpose 'Start the durable apoc daemon.' --idempotency-key daemon/start-v1 --format json
apoc daemon status --purpose 'Check the durable apoc daemon.' --format json
apoc daemon stop --purpose 'Stop the durable apoc daemon.' --idempotency-key daemon/stop-v1 --format json
```

| State | Default macOS path |
| --- | --- |
| Database | `~/Library/Application Support/apoc/apoc.sqlite3` |
| Execution logs | `~/Library/Application Support/apoc/runs/` |
| Daemon log | `~/Library/Application Support/apoc/daemon.log` |
| Socket | `$TMPDIR/apoc-<effective-user-id>/apoc.sock` |

Ordinary consumer work uses the installed per-user controller without setting
`APOC_HOME` or `APOC_RUNTIME_DIR`. Set both only for apoc tests and integration
fixtures, or for an explicitly bounded isolation task. Return to the default
controller after a temporary compatibility workaround is no longer needed;
never carry a dated temporary runtime into later ordinary work.

Set both `APOC_HOME` and `APOC_RUNTIME_DIR` to run a bounded isolated instance. apoc
backs up a non-empty database before each schema migration. The runtime directory
uses mode `0700`; the Unix socket uses mode `0600`. `$TMPDIR` represents the
platform temporary directory returned to the process and is commonly under
`/var/folders/.../T` on macOS. `<effective-user-id>` is the numeric effective
user ID returned by the operating system.

## Cleanup

The daemon runs one cleanup pass every 10 minutes. `apoc gc` runs the same pass
on demand. Without `--apply` it only reports counts and a sample of up to 10 IDs
per category.

```sh
apoc gc --purpose 'Preview stale apoc state.' --idempotency-key gc/preview-1 --format json
apoc gc --apply --purpose 'Clean up stale apoc state.' --idempotency-key gc/apply-1 --format json
```

- **Orphans.** apoc closes a running execution when its process identity (boot ID,
  PID, and start time) is gone and no supervisor owns it. The run becomes
  `interrupted`. The execution becomes `failed` with `EXECUTION_INTERRUPTED` and
  the cause. It is never marked `completed`, and nothing is signaled.
  A Code Mode program that no actor owns any longer is closed the same way.
  First, its execution-owned children are canceled. Work whose owning
  execution finished or vanished, or whose session closed or expired, is
  canceled with `EXECUTION_OWNER_GONE`. Cancellation goes through typed
  cancellation, which re-verifies process identity before it sends a signal.
  The check skips work touched within the last `APOC_GC_ORPHAN_GRACE_MS`
  (default 60000).
- **Unowned background work.** `execution start` with no parent and no session
  gets a lifetime of 24 hours (`APOC_GC_UNOWNED_LIFETIME_MS`). The clock restarts on every get, tree, wait,
  attach, input, signal, or log read. Set `--lifetime-ms N` to change it, or
  `--keep-alive` to opt out. `APOC_GC_UNOWNED=report` (the default) lists
  expired work. `stop` cancels it through typed cancellation with
  `EXECUTION_EXPIRED`. `off` skips the check.
- **History retention.** apoc deletes terminal executions older than
  `APOC_GC_RETENTION_DAYS` (default 30; `0` disables) in batches of 200.
  Deletion includes their events, unpinned payloads, process events, leases,
  invocation records, search rows, observation versions, and run logs. It also
  deletes older terminal invocation records and process events that belong to no
  execution. To keep an execution, its children, and its invocations, label it
  `--label apoc.keep=true`. Recording invocations are always kept.
- **Space.** New databases use incremental auto-vacuum, so deleted pages go back
  to the operating system. An older database reuses its free pages and keeps its
  file size. apoc never runs a full `VACUUM` on its own.

A daemon with a non-default `APOC_HOME` or `APOC_RUNTIME_DIR` exits once it has
had no connected client and no nonterminal work for `APOC_DAEMON_IDLE_EXIT_MS`
(default 1800000; `0` disables). It also exits soon after its `APOC_HOME` is
deleted. The default per-user daemon never exits on its own.
`APOC_GC_INTERVAL_MS` sets the pass period, and `0` disables the periodic pass.
`apoc daemon status` reports `gc` with the last pass's counts and pending
counts.

## Upgrade and verify

```sh
cargo install apoc --version 0.9.1 --locked --force
apoc skill install --purpose 'Install the updated apoc operator skill.' --idempotency-key skill/install-updated-v1
apoc version --purpose 'Check the upgraded apoc version.' --format json
apoc skill status --purpose 'Check the updated apoc skill installation.' --format json
apoc daemon stop --purpose 'Stop the older durable apoc daemon.' --idempotency-key daemon/stop-upgrade-v1 --format json
```

The next durable command starts the current daemon build. `apoc version` reports
the client version and public execution schema. `apoc daemon status` reports the
daemon build and schema when it is running.

## Reference

- [Rust API documentation]https://docs.rs/apoc
- [Packaged architecture]https://docs.rs/crate/apoc/latest/source/docs/architecture.md
- [Packaged source]https://docs.rs/crate/apoc/latest/source/
- [Release history]https://docs.rs/crate/apoc/latest/source/CHANGELOG.md

There is no public issue tracker or support channel. The structured CLI help,
JSON Schemas, embedded operator skill, and packaged source are the public product
contract.

## License

apoc is available under the [MIT License](https://docs.rs/crate/apoc/latest/source/LICENSE).