Process provenance

For agents

Send a read-only GET to the local control server using the session's own scoped CLI token:

curl -s -H "Authorization: Bearer $AMC_CLI_TOKEN" \
  http://127.0.0.1:19519/diag/process-provenance

The route permits scoped agent tokens. It starts no process, recurring timer, shell command or WMI fallback. It reuses the shared native process census and allows at most one new census per 30 seconds across agents. The census runs synchronously on the main thread; its cost has not been measured. ETW/Kernel-Process tracing is not the baseline because a prior investigation received access denied under the normal account. No service or elevation is assumed; native snapshots are a live lower bound, not full historical capture.

The route applies an owner-aware projection. A session token sees allowlisted machine metadata for validated app descendants, its own captured event details, and a verifiedOwner only for its own exact launch-bound match or validated descendants of that root. Other verified owners and candidate identities are withheld and contribute only to aggregate counts. The owner CLI credential sees all sampled process rows and up to 256 projected V4/V2 process rows. Launch-bound identity is captured while the spawn worker, synchronous fallback or shared host still holds the child process handle. The shared host's RI2 reply includes its actual native parent PID; legacy R and RI1 replies remain supported without inventing parent evidence. Legacy shared-host audit rows use parent PID 0 as an explicit unknown sentinel. Exact PID, parent PID, milliseconds and FILETIME must uniquely match the current sample and launch record. A shared-host child can appear as trusted-session-root outside the Electron parent tree; validated children of that root can appear as trusted-session-descendant with inherited owner evidence. Candidate matches and conflicting or incomplete evidence remain unknown. Raw FILETIME is stored in the bounded V4 session-root rows and internal index; it is omitted from CLI responses.

The owner CLI credential can also request GET /diag/process-provenance?scope=machine for a paged view of the shared native census across the machine. This is explicitly owner-only; scoped session credentials receive 403. Pages contain at most 100 rows and are ordered by PID. The machine snapshot token is returned as live.machineCensus.snapshotId; pass it as snapshot on later pages. If it no longer matches, the route returns HTTP 409 with the current machine snapshot token so pagination can restart. Rows expose only an allowlisted image base name, PID, parent PID, creation time, cumulative CPU time, working set, an unknown attribution, and whether the PID is connected to the app in this sample. Rows marked not connected may include detached descendants of the app. This is a live snapshot, not complete launch history or reliable ownership attribution.

This machine view reuses the shared census and accepts a sample up to 30 seconds old; other app consumers may refresh it sooner. It adds no idle timer or shell process. The census runs synchronously on the main thread and its runtime cost remains unmeasured.

For session-token responses, otherSessionTotals contains aggregate candidateSessions, candidateProcesses and unownedProcesses counts. It does not identify the other sessions.

The response contains:

• live.status, reason, sampleAtMs and sampleAgeMs: whether the native reading answered, why it may be unavailable, and how old the sample is. Unavailable live data can coexist with readable event history.
• live.rows: sampled processes with PID, parent PID, image base name, creation time, cumulative CPU milliseconds, working set bytes, app-instance lineage, owner attribution and evidence fields. candidateKind is a closed subsystem category such as recording, plugin, backend or screenshot, never a free-form command or proof of ownership. The image is a base name; paths, command lines, arguments, environment values, raw source labels, session IDs and request IDs are omitted. The default returns up to 255 highest-CPU child rows; live.root is separate.
• history.rows: at most 128 temporary app-observed events per viewer, selected after session scoping, with PID, parent PID when present, event time, generation and correlation state. live-candidate means a spawn event matches a sampled process by PID, parent PID and creation-time proximity; recorded-only means the event has no such live match, including exit events. The ring retains up to 2,048 events for 15 minutes and is lost at restart. It receives existing spawn-audit events and passive observations from reviewed app launch seams, with no new disk write or reaper enrollment at those seams. Checkout path-index, own-author typecheck, admission/install, operations provisioning, toolchain probes, hook-host and worktree lease observations each cover their direct child only; nested scripts, hooks and compiler work are not inferred. Each exit uses the generation returned for its birth. An active session-root identity index separately retains up to 4,096 session roots until matching exit, PID replacement or capacity eviction. coverage.activeSessionRootEvictedCount and activeSessionRootCapacity report that index's loss and bound. Session views include only their captured history; history.otherObservedEvents aggregates the rest. history.activeEvictedCount reports event-ring active PID eviction; history.droppedEventCount counts overwritten event rows only, not uncaptured process births.
• ledger: reports adapter source, schema version, read fault, truncation, unknown retention and durability. An owner view may include up to 256 combined V4/V2 process rows, each labeled by sourceVersion. Session tokens receive aggregate counts only. V2 rows remain legacy-unverified; V4 token presence is unverified by itself; a current PID match is pid-present-unverified. The 17 registered V4 producer definitions emit 18 process streams because background runner has both resident-host and run-child streams. These named seams do not establish complete family coverage; other doors remain unmeasured. Utility and owned-child-exec asynchronous adapter loading can delay start timestamps while retaining paired lifecycle events.
• coverage: process evidence counts, not Central Launch Registry family coverage. directLineage, descendantLineage, trustedExternalRoot, trustedExternalDescendant, disconnectedCandidate, candidateCorrelated, unknown and droppedRingEventCount may overlap. activeSessionRootEvictedCount and activeSessionRootCapacity describe the separate bounded session-root index.
• boundary: the capture limit for this read.

Running-now lifecycle

runningNow projects the latest V4 event per process from the bounded ledger window, capped at 100 rows. Ended lifecycles are omitted. lost means terminal observation was lost; it does not establish exit. A start is current-in-sample only when PID, parent PID, FILETIME and creation milliseconds match the native sample named by sampleAtMs; sampleAgeMs states its age. This is a sampled match, not instantaneous liveness. Unmatched starts are unknown; identity is verified only when the trusted active session-root marker also matches. Otherwise it is unverified.

The owner CLI credential sees all runningNow rows and gets an owner session ID only on verified rows. A scoped session sees only its own exactly matched verified session-root rows. Other session identities and unknown/candidate owner details are withheld. The view does not expose raw FILETIME.

Querying the sample

Sampled PID lookup: GET /diag/process-provenance?pid=<positive-int>; optionally add &createdAtMs=<positive-int> to compare the row's millisecond creation time. A detected recycled-PID mismatch returns no row and reports live.lookup.creationTimeMismatch, but reuse within the same millisecond can remain ambiguous. This query does not accept raw FILETIME; the service verifies owner identity internally only on a unique launch-bound match of PID, actual parent PID, creation milliseconds and FILETIME. Without createdAtMs, lookup identifies only the PID in the current sample.

Pages: GET /diag/process-provenance?offset=<0..100000>&limit=<1..100>, ordered by PID among visible child rows. The first page returns opaque live.snapshotId; pass it as snapshot=<id> on later pages. If the census, retained events or active-root index changes, the route returns HTTP 409 with data.snapshotId; restart pagination from that snapshot. live.totalCount, offset, limit and hasMore describe the viewer's pageable rows. Session-token queries include validated app descendants, the viewer's exact trusted session root and its verified descendants; other identities are removed and disconnected candidates are excluded. live.root is available only to the owner CLI credential. The default owner page is root plus up to 255 highest-CPU children. PID lookup and pages select from a sampled snapshot; they do not expand process coverage. Unknown, duplicate or invalid parameters are rejected.

Machine pages: GET /diag/process-provenance?scope=machine&offset=<0..100000>&limit=<1..100>. The first page returns live.machineCensus.snapshotId; include it as snapshot=<id> on later pages. A changed machine snapshot returns HTTP 409 with the current machine token. This query requires the owner CLI credential and never grants machine-wide rows to scoped agent-session tokens.

Agent troubleshooting flow

1. Read the default response and check live.status and live.sampleAgeMs. unavailable is not a healthy zero-process result.
2. Use ?pid=<pid>&createdAtMs=<creationTimeMs> for a row from the sample, or paginate visible rows. On HTTP 409, restart pagination with the returned data.snapshotId.
3. Treat candidateOwner as uncertain. A live verifiedOwner requires one unique exact launch-bound match on PID, actual parent PID, creation milliseconds and FILETIME. The scoped response exposes it only to the matching session; other identities are aggregated. V2 rows are legacy-unverified; pid-present-unverified means only that the PID appears in the sampled live rows.
4. Compare the evidence with GET /diag/background, GET /diag/resources and GET /ops/jobs. Those answer declared-work and resource questions that process lineage alone cannot settle.

Reading the evidence

lineage: root is the app process, direct is a child whose parent is that app process, and descendant is connected through a validated parent chain. trusted-session-root is a session root whose unique launch-bound identity matches the live PID, actual parent PID, creation milliseconds and FILETIME; a shared-host root can use this classification outside the Electron parent tree. trusted-session-descendant is connected by validated parent edges to a verified root outside the Electron tree and inherits its owner evidence. Descendants that also connect to Electron keep descendant lineage but inherit trusted-root-lineage owner evidence. disconnected-candidate has a nearby launch observation but no complete current chain or exact launch-bound match, so its parentEdgesValidated field is false. Each validated parent edge requires creation times and a parent born no later than its child. Missing timestamps, recycled parent PIDs, cycles, self-links or a chain beyond depth 16 stop lineage attribution.

At a trusted session-root launch, the spawn worker or synchronous fallback captures creation time and exact native FILETIME while its process handle still pins the launched child. The shared host captures the same identity from its suspended child handle and sends RI2 with the actual host parent PID; the app continues to accept legacy R and RI1 frames, which may lack parent evidence and use parent PID 0 as an audit sentinel. The bounded active index keeps launch-bound identity with its session owner until matching exit or eviction; it is lost at restart. A unique match on sampled PID, actual parent PID, creation milliseconds and FILETIME verifies the owner, including a shared-host root outside the app tree. Validated descendants inherit that verified owner through actual parent edges. Without that exact launch-bound match, token and millisecond correspondences remain candidates and conflicting tokens block fallback. The raw token is omitted from CLI responses but is stored in session-root V4 ledger rows and the internal index. Other launch observations use wall-clock times and remain candidates. Legacy V2 rows have PID but no creation token, so they always remain legacy-unverified; PID, timestamp or invocation ancestry cannot prove which process lifetime they describe. An image name or PID by itself is not ownership evidence.

The shared native census runs on demand for process provenance, not on a new recurring timer; it may reuse a sample up to 30 seconds old. The default projection remains centered on the current app instance, with exact trusted session roots admitted by the launch-bound join. These narrow V4 producers do not provide complete process history or family coverage. Short-lived unobserved grandchildren, other process doors, external scheduled tasks, other app instances and work that begins and exits between samples may be absent. A non-app row can include a detached app descendant; unknown attribution is not an ownership conclusion. A missing row is not proof that a process exited, and a parentless process is not thereby an orphan. unavailable means the live census did not answer; it is not a zero-process result or a family coverage state. Runtime verification and CPU/query cost measurements were not run for this change.

The Central Launch Registry has six launch-family states: registered and enforced, registered and observed, legacy exception, outside the boundary, not exercised and unmeasured. A process row, source inventory or provenance count cannot promote a family between those states. GET /operations/catalog is the canonical declaration catalog, not proof of observed execution: its 14 process-door declarations comprise 11 not-exercised and 3 outside the boundary; runtimeVerified remains false. Do not read the 17 registered V4 producer definitions or their 18 streams as complete runtime coverage. Runtime behavior and CPU/query cost remain unmeasured. The central schema has a strict V4 event API and bounded writer/reader with separate launch and bulk retention. FILETIME is stored only in session-root canonical rows and internal indexes, never returned raw.

Use with other diagnostics

• GET /diag/background shows declared background work, its owner declaration and budget measurements. It is not a process census.
• GET /diag/resources provides the existing resource monitor view and its process metrics.
• GET /ops/jobs reports registered scheduled jobs and their run state.

Use provenance for sampled process lineage and the current temporary event projection. Use the Central Launch Registry as authority for launch records and family coverage. Use the Background Registry to inspect declared work.