# Status

[Documentation index](README.md) · [Discovery](2026-10-06-discovery.md) · [Receipt semantics](2026-10-06-safety-and-receipts.md)

`plastic_status` observes pending items or standard merge hints. Choose a source deliberately; unsupported/failed output is not retried in another mode.

## Choose a source

| Source | Select it with | Provides | Important boundary |
|---|---|---|---|
| Standard | Default, or `source="text"` | Short-output summary and text-derived merge hints | Read completeness unknown; not machine-verified conflict counts |
| Machine | `machineReadable=true` or `source="machine"` | Parsed item rows, optional revision/source path, counts and diagnostics | Requested CLI scope, partial/lossy reads possible; no standard merge-state observation |
| XML | `source="xml"` | Strict UTF-8 absolute pending paths and moved source paths | Opt-in workspace-wide snapshot; no base revisions; Windows CM 11 source validation |

Tool-call examples:

```text
plastic_status(source="xml", maxItems=20)
plastic_status(source="machine", maxItems=20, includeRevId=true)
plastic_status(format="text")
```

`format="text"|"json"` changes presentation, not the native DTO. `source` is independent of presentation. Omitting `source` preserves `machineReadable` behavior.

Conflicting controls fail before execution:

- `source="text"` or `source="xml"` with `machineReadable=true`.
- `source="machine"` with explicit `machineReadable=false`.
- XML with `short=true` or `includeRevId=true`.

## Common result fields

Status declares `action="status"`. Standard/machine routes use `schemaVersion: 1`; XML uses `schemaVersion: 2`. Inspect `ok`, `completeness`, `data.mode`, diagnostics, summary basis, and returned/omitted counts.

Rows default to 100 and cap at 500. Identity fields are excluded or rejected when unsupported, never clipped into plausible paths/revisions. A summary can describe more parsed records than the returned projection.

| Concept | Meaning |
|---|---|
| `completeness.read` | Complete/incomplete/unknown source interpretation |
| `completeness.capture` | Complete/unknown capture evidence for these routes |
| `completeness.projection` | Whether the declared projection is complete |
| Summary basis | Distinguishes parsed records from short-output classification |
| Diagnostics | Evidence counters; a row can be both parsed and malformed/unsupported |

A successful partial read is not a complete clean workspace. Native errors contain bounded sanitized code/message; unsupported CLI output is `command_failed`, not guessed capability absence.

## XML

XML yields `data.mode="xml"`, absolute CLI-observed paths, `pathBasis="absolute"`, and workspace-wide scope even when workdir is a subdirectory. Moved `Path` is the destination and `OldPath` is the source.

- Supported codes: CH, AD, CO, CP, RP, DE, LD, MV, LM, PR; types: enTextFile/enBinaryFile/enDirectory. LM observations retain source/destination and optional fractional similarity; see [inferred moves](2026-10-21-observed-workflow-profiles.md#inferred-local-moves).
- Unsupported codes/types, duplicates, foreign/unknown important structures, malformed XML, warnings/errors, nonempty stderr, or command/capture failure reject the observation.
- `baseRevisionAvailability="unavailable"`: changeset, size, and similarity never become per-item revisions.
- Exact Unicode code points and emitted path spelling remain unchanged, including observed drive-letter case; no normalization/encoding guessing.
- Text/JSON is synthesized from this one XML snapshot. No text/version commands are added.

`@xmldom/xmldom` 0.9.12 parses strict application/xml, rejects warnings/errors, and conservatively rejects DTD/entity declaration tokens even in comments/CDATA. Literal U+FFFD is unsupported by the parser policy, not automatically evidence of CLI decoding loss. Numeric references use the same strict parser policy.

`includeRaw=true` adds bounded, source-labelled XML to presentation only with a privacy warning. It may expose repository/server/workspace metadata; it never enters the compact native DTO.

### XML bounds

| Bound | Limit |
|---|---|
| Stdout/document | 1 MiB raw bytes |
| Stderr | 64 KiB |
| Process timeout | 30 seconds |
| Element depth | 16 |
| Source records | 20,000 |
| Path/source path | 4,096 UTF-16 code units |
| Status code | 64 code units |
| Accumulated other scalar text | 8,192 code units |
| Returned rows | 100 default, 500 maximum |
| Compact DTO | 131,072 UTF-8 bytes |

Invalid UTF-8, declaration/BOM disagreement, overflow, abort, or failed capture withholds reusable identities. Whole-document parsing is synchronous: depth/record/string checks follow DOM allocation and cancellation checks occur at parse boundaries, not midparse. The raw-byte cap bounds that phase; the process deadline is not a hard JS parser deadline.

## Machine

Machine yields `data.mode="machine"`, requestedShort, parsed-record summary, parse diagnostics, and itemCount. Rows include statusCode/kind/path/isDirectory and, when observed, decimal revisionId and moved sourcePath. Paths can be absolute; they are deliberately CLI-observed identities.

- `parsed` counts all parsed records; returned/omitted/excluded/overCap describe projection and identity exclusions.
- Summary totals precede projection. They are not independently verified workspace-wide counts.
- Header repository/server identities, cwd, internal normalized paths, and raw output are not canonical DTO fields.
- Recognized blank/header records are not pending items.
- The CLI no-base revision `-1` is omitted, not reusable. Malformed tokens such as `41.5` withhold revision identity and make the read incomplete; a numeric prefix is never recovered.
- Captured seven-field LM observations retain distinct source/destination paths and fractional similarity, including non-100% moves. This does not expand mutation/selection admission or authorize inferred renames.
- Malformed/unsupported records or ambiguous legacy moves can produce a successful partial read, not complete status.
- Successful stderr makes read/capture unknown without publishing stderr.

### Encoding limitations

U+FFFD in a path/source path causes exclusion from reusable identities and incomplete read. This also excludes literal replacement-character filenames because capture cannot distinguish them from loss.

On Windows, `?` in identity-bearing paths is also excluded: the tested CM machine formatter substituted unsupported characters before capture. POSIX `?` filenames remain supported.

The tested Windows client emitted OEM 437 bytes for some Latin text and replaced Japanese/emoji with `?`. `--encoding=utf-8` did not change that machine-output behavior; it is documented for XML. Streaming UTF-8 decoding preserves multibyte boundaries, but does not convert OEM bytes or recover originals. No XML fallback or general Windows Unicode round-trip guarantee is implied.

### Machine bounds

Paths: 4,096 characters; revision IDs: 128; status codes: 64; returned rows: 100 default/500 maximum; compact DTO: 131,072 UTF-8 bytes. Unsupported identity-bearing fields are excluded, not clipped. DTO overflow fails closed.

### Registered-tool presentation contract

These presentation limits are separate from the unchanged native DTO/domain/resource limits above:

| Channel / admitted facts | Limit / overflow policy |
|---|---|
| Direct text or parseable JSON, also retained as renderer `details.rawResult` | 32,768 UTF-8 bytes; remove whole trailing rows/lines, disclose presentation returned/omitted counts; never clip an identity |
| Machine/XML presentation rows | Only validated native rows (100 default/500 maximum); path/source/revision/status bounds unchanged |
| Standard presentation lines | 100 default/500 maximum, 4,096 code units per whole line; exclude lossy/oversized lines, preserve exact remaining text and disclose omissions |
| Opt-in raw diagnostic excerpt | 8,192 UTF-8 bytes, whole lines only, source-labelled with privacy warning and omission counts; machine raw withheld if native read/projection is incomplete |
| Native DTO | Unchanged 131,072 UTF-8 bytes; overflow remains a structured failure |

Presentation carries summary, source/read/capture uncertainty, native projection omissions and standard merge-hint counts independently of the DTO. Direct JSON `itemCount` describes its displayed rows; `nativeItemCount` retains the unchanged DTO row accounting, and `presentation` reports additional selection/exclusion. Additional presentation omissions do not change native completeness. Standard lines are external text, not verified reusable path records or conflict/readiness evidence. `includeRaw` never bypasses identity exclusions; omit it for normal agent use. Registered JSON presentation adds no version lookup. The exported legacy `status` operation keeps its existing presentation interface.

Outcome mapping is unchanged: successful partial machine reads remain `ok:true`; standard read is unknown; strict XML rejects unsupported/unsafe source data; operation/capture/DTO failures return `isError:true` and bounded `ok:false`. Presentation does not rerun commands, change effects, or authorize replay.

## Standard

Standard yields short-output classifications (`summaryBasis="short_output_classification"`) and text hints (`mergeHints.basis="text_hints"`). Counts include `other`; merge hints are not machine-verified conflict/readiness counts.

Read completeness is unknown. Both existing status commands must succeed; there is no alternate-source fallback/retry. `requestedShort` describes requested scope, not unselected pending items.

## Failures and follow-up

Public codes include `command_failed`, `aborted`, `capture_incomplete`, `invalid_producer_data`, and `output_overflow`. XML schemaVersion 2 additionally emits `unsupported_source` for structurally valid but unadmitted record codes/types, and `malformed_output` for invalid XML or observation-contract data. Parser bounds use `output_overflow`; transport truncation/timeouts use `capture_incomplete`. Unsupported records are not admitted or partially projected; malformed/unsafe data takes precedence over unsupported profiles. Errors expose only fixed messages/codes, not XML, record values or workdir paths, even with `includeRaw=true`.

Parser rejections retain `read="incomplete"`, `capture="complete"`, `projection=false`: bytes were captured, not accepted as a complete read. Command/capture failures retain unknown capture. `invalid_producer_data` remains reserved for unexpected producer/internal DTO validation failures. This is an additive extension of the v2 error-code union (enum consumers must handle the new codes); v1 and successful v2 shapes are unchanged, and existing v2 error envelopes remain valid. Generic historical failures without retained XML do not establish a particular unsupported type. Inspect host-native rejection as well as DTO `ok`.

Use the declared scope/completeness to choose a further authorized inspection. The separate strict XML/base protocol in [diff](2026-10-06-diffs-and-patches.md#loaded-bases-and-snapshots) is not a status-tool fallback; checkin and merge readiness have their own source admission.