From cfbe95f5579bcdd38f15074c2263bcf0b58ec136 Mon Sep 17 00:00:00 2001 From: YEONGUK LEE Date: Mon, 12 Oct 2026 14:29:38 +0900 Subject: [PATCH] docs: Clarify TypeScript 0.3.4 compatibility and SSH outcomes --- docs/typescript-compatibility.md | 13 +++++++++---- docs/typescript.md | 18 ++++++++++++------ session-peer-ts/SKILL.md | 20 ++++++++++++++------ 3 files changed, 35 insertions(+), 16 deletions(-) diff --git a/docs/typescript-compatibility.md b/docs/typescript-compatibility.md index a087b30..7c9fc1e 100644 --- a/docs/typescript-compatibility.md +++ b/docs/typescript-compatibility.md @@ -2,7 +2,9 @@ [Back to TS setup](typescript.md) -TS skill 0.2.0 uses the successor profile supported by the published npm runtime 0.3.3. Runtime source: [`c0ed30273b9e9c0049df86ae3c38486a94289527`](https://github.com/abruption/session-peer-ts/blob/c0ed30273b9e9c0049df86ae3c38486a94289527/src/skill-metadata.ts). The npm artifact has SHA-256 `3469cda6a7b2c89d42ed2a250d2e7b5b774293fee090968a4b261e824be4c075`; its verified provenance identifies that source and [publication workflow run 37907833518](https://github.com/abruption/session-peer-ts/actions/runs/37907833518). +TS skill 0.2.0 uses the successor profile supported by the published npm runtimes 0.3.3 and 0.3.4. Runtime 0.3.3 source: [`c0ed30273b9e9c0049df86ae3c38486a94289527`](https://github.com/abruption/session-peer-ts/blob/c0ed30273b9e9c0049df86ae3c38486a94289527/src/skill-metadata.ts). The 0.3.3 npm artifact has SHA-256 `3469cda6a7b2c89d42ed2a250d2e7b5b774293fee090968a4b261e824be4c075`; its verified provenance identifies that source and [publication workflow run 37907833518](https://github.com/abruption/session-peer-ts/actions/runs/37907833518). + +Published runtime 0.3.4 explicitly retains the same two reviewed profiles; source: [`afed4a5a8945012faf1b23d52cffecb70470a5b3`](https://github.com/abruption/session-peer-ts/blob/afed4a5a8945012faf1b23d52cffecb70470a5b3/src/skill-metadata.ts). Its [release record](https://github.com/abruption/session-peer-ts/releases/tag/v0.3.4) records the npm artifact SHA-256 `6c8cb114485e067ac3e7f5792de7febf3680cb14dcda6e2c67df6cab773ca03c` and [publication workflow run 38194048045](https://github.com/abruption/session-peer-ts/actions/runs/38194048045). These are separate publication records, not a new property of doctor. The Python skill, TS skill, skill release tags, and npm runtime have independent versions. TS skill publication follows the separate `session-peer-ts-vX.Y.Z` tag scheme. A runtime publication does not install or update either skill. @@ -17,11 +19,12 @@ The Python skill, TS skill, skill release tags, and npm runtime have independent |---|---|---|---| | Public `0.3.2` | `compatible` | `incompatible` | Exact legacy metadata tuple; top-level name is not checked | | Public `0.3.3` | `compatible` | `compatible` | Exact supported profile plus valid root `name: session-peer-ts` and bounded readable/stable input | +| Public `0.3.4` | `compatible` | `compatible` | Explicit finite legacy/successor row; same root-name, parser and bounded input requirements | | Unknown or future combination | No automatic guarantee | No automatic guarantee | Review the actual runtime and profile; no wildcard or arithmetic acceptance | Compatible and incompatible structural results carry `verification: metadata_only`. This checks metadata structure/profile support; it does not verify source provenance, content SHA, installation integrity, freshness, CLI feature coverage, permission to send, consumption, or ACK. The npm provenance verification above is separate release evidence, not a property of doctor. -Runtime 0.3.3's pure validator rejects a valid but unreviewed runtime identity such as `0.3.4` as `incompatible / skill_contract_mismatch / metadata_only`. This describes the released 0.3.3 guard, not the behavior of hypothetical future code. Use runtime 0.3.3 for the reviewed successor doctor check. An older CLI can meet the minimum while its doctor rejects this newer metadata profile; do not edit metadata to hide that result. Runtime adoption remains a user-authorized operation under the existing package manager. +Runtime 0.3.3's pure validator rejects a valid but unreviewed runtime identity such as `0.3.4` as `incompatible / skill_contract_mismatch / metadata_only`. This describes the released 0.3.3 validator supplied with identity `0.3.4`, not the published 0.3.4 guard: 0.3.4 explicitly adds that reviewed runtime row. Use reviewed runtime 0.3.3 or 0.3.4 for the successor doctor check; no other future identity is accepted by inference. An older CLI can meet the minimum while its doctor rejects this newer metadata profile; do not edit metadata to hide that result. Runtime adoption remains a user-authorized operation under the existing package manager. ## Minimum, full features, and guard acceptance @@ -34,6 +37,8 @@ The independent Python contract remains skill 0.3.2, minimum 0.9.1, full 1.0.1, ## Runtime 0.3.3 input and result contract +The same input/result contract applies to published 0.3.4, with its explicit additional runtime-identity row shown above. + The [published limited grammar](https://github.com/abruption/session-peer-ts/blob/c0ed30273b9e9c0049df86ae3c38486a94289527/docs/design/typescript-skill-compatibility.md#limited-grammar-and-results) requires one root name scalar and one metadata map with the required quoted/plain string scalars. This is not a general YAML parser. A root name has no indented non-comment continuation, even across blank/comment lines; orphan indentation is malformed. Unrelated root fields can own ignored indented content. Plain and quoted names work before or after metadata. A literal ASCII space is required after `name:`; following whitespace is removed with `trimStart()`, so a space followed by a tab is accepted, while a tab immediately after the colon is rejected. Metadata separators retain their spaces-only grammar. | Evidence | Status / code | `verification` | @@ -46,13 +51,13 @@ The [published limited grammar](https://github.com/abruption/session-peer-ts/blo | Well-formed but unsupported name, profile, or valid runtime identity | `incompatible / skill_contract_mismatch` | `metadata_only` | | Exact supported name/profile/runtime and healthy bounded input | `compatible / skill_contract_compatible` | `metadata_only` | -The outer inspection result preserves `path`. Absent verification means the property is omitted, not `null`. An omitted or explicitly `undefined` pure-helper runtime argument uses compiled VERSION 0.3.3 and is not an unavailable-identity fixture. Reader failures precede metadata verdicts. Canonicalization can wrap an earlier path error as `home_resolution_failed`, producing unknown/unreadable instead of the raw errno result; do not collapse all permission errors into unknown. +The outer inspection result preserves `path`. Absent verification means the property is omitted, not `null`. An omitted or explicitly `undefined` pure-helper runtime argument uses the inspecting runtime's compiled VERSION (0.3.3 or 0.3.4) and is not an unavailable-identity fixture. Reader failures precede metadata verdicts. Canonicalization can wrap an earlier path error as `home_resolution_failed`, producing unknown/unreadable instead of the raw errno result; do not collapse all permission errors into unknown. For historical comparison, public [0.3.2 source](https://github.com/abruption/session-peer-ts/blob/f335f07352c842f2f6ceb12bd2ca6274b52f69f7/src/diagnostics.ts) does not check root name and classifies missing/duplicate/regex-nonmatching required scalars in a single metadata section as incompatible. Its empty/absent frontmatter and zero/multiple maps are unknown. The 0.3.3 parser classification is an intentional change, not a restatement of the older checker. ## Reader bounds and evidence limits -Runtime 0.3.3 counts **65,536 whole-file raw UTF-8 bytes**, including BOM, whitespace, line endings, and body. Read requests and allocation are capped at **65,537 bytes**, including one overflow-detection byte. Pre-read stat is an early check; fatal UTF-8 decoding follows bounded reading and stability checks. +Runtimes 0.3.3 and 0.3.4 count **65,536 whole-file raw UTF-8 bytes**, including BOM, whitespace, line endings, and body. Read requests and allocation are capped at **65,537 bytes**, including one overflow-detection byte. Pre-read stat is an early check; fatal UTF-8 decoding follows bounded reading and stability checks. The reader canonicalizes managed symlinks, verifies regular-file evidence on the opened descriptor, and compares device/inode/size/mtime/ctime and path/alias evidence around the read. Observable growth, truncation, replacement, alias changes, or same-size timestamp changes produce unknown/unreadable. Every opened descriptor is closed. These checks detect observed changes; they do not authenticate content, create an atomic snapshot, protect against a writer restoring identical metadata, or impose a deadline on arbitrary filesystem I/O. diff --git a/docs/typescript.md b/docs/typescript.md index 7b0ce06..296e74b 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -2,7 +2,7 @@ [Back to README](../README.md) -The separate `session-peer-ts` skill 0.2.0 describes the published npm TypeScript runtime 0.3.3. Its publication source is [`c0ed30273b9e9c0049df86ae3c38486a94289527`](https://github.com/abruption/session-peer-ts/blob/c0ed30273b9e9c0049df86ae3c38486a94289527/RELEASING.md). The runtime runs without Python. Both runtimes use the command name `session-peer`, so resolve the intended executable and inspect its version and help before use. +The separate `session-peer-ts` skill 0.2.0 describes the published npm TypeScript runtimes 0.3.3 and 0.3.4. The 0.3.4 publication source is [`afed4a5a8945012faf1b23d52cffecb70470a5b3`](https://github.com/abruption/session-peer-ts/blob/afed4a5a8945012faf1b23d52cffecb70470a5b3/RELEASING.md). The runtime runs without Python. Both runtimes use the command name `session-peer`, so resolve the intended executable and inspect its version and help before use. ## Published support and independent versions @@ -14,14 +14,14 @@ Published 0.2.0 added combined listing, bounded known Codex homes, guarded live- | Python skill `0.3.2` | Version of `session-peer/SKILL.md` | | TS skill `0.2.0` | Version of `session-peer-ts/SKILL.md` | | TS skill tag `session-peer-ts-v0.2.0` | Separate TS skill release; resolve its annotated tag to the exact commit recorded in the release | -| TS runtime `0.3.3` | Published npm package `session-peer`; independent of both skill versions | +| TS runtimes `0.3.3` and `0.3.4` | Published npm package `session-peer`; independent of both skill versions | | `runtime-min-version` = `0.1.0` | CLI compatibility floor for the explicit baseline commands | | `runtime-full-version` = `0.3.2` | Coverage reference for this revision's published CLI features | -| Successor doctor acceptance | Runtime `0.3.3` accepts this exact metadata profile; public `0.3.2` rejects it | +| Successor doctor acceptance | Runtimes `0.3.3` and `0.3.4` accept this exact metadata profile; public `0.3.2` rejects it | The minimum and full values are distinct from security recommendations, latest-version markers, doctor support, and delivery/ACK. Help establishes option presence only; platform/native prerequisites, permissions, allowlists, and writer guards still apply. See the [normative min/full definitions and separate doctor acceptance table](typescript-compatibility.md#minimum-full-features-and-guard-acceptance). -Use runtime 0.3.3 for reviewed doctor metadata compatibility with TS skill 0.2.0. Public 0.3.2 rejects the successor even though it meets the baseline CLI minimum and feature coverage values. Keep the existing package manager and obtain authorization before upgrading; do not edit metadata to hide a mismatch. Unknown future runtime/profile combinations are not automatically accepted. A compatible metadata check is not a content review, source authentication, freshness check, or delivery authorization. +Use reviewed runtime 0.3.3 or 0.3.4 for doctor metadata compatibility with TS skill 0.2.0. Public 0.3.2 rejects the successor even though it meets the baseline CLI minimum and feature coverage values. Keep the existing package manager and obtain authorization before upgrading; do not edit metadata to hide a mismatch. Unknown future runtime/profile combinations are not automatically accepted. A compatible metadata check is not a content review, source authentication, freshness check, or delivery authorization. ## Install, update, and remove the skill @@ -40,10 +40,16 @@ The TS metadata uses `runtime-implementation: "typescript"` and `runtime-capabil ## Runtime checks and ownership -Resolve the executable before discovery. Explicit JSON remains a safe baseline; operations have no default output format. See the [agent instructions](../session-peer-ts/SKILL.md) for discovery, dry-run, SSH, and reply boundaries, and the [published CLI help](https://github.com/abruption/session-peer-ts/blob/c0ed30273b9e9c0049df86ae3c38486a94289527/src/help.ts) for supported flags. +Resolve the executable before discovery. Explicit JSON remains a safe baseline; operations have no default output format. See the [agent instructions](../session-peer-ts/SKILL.md) for discovery, dry-run, SSH, and reply boundaries, and the [published CLI help](https://github.com/abruption/session-peer-ts/blob/afed4a5a8945012faf1b23d52cffecb70470a5b3/src/help.ts) for supported flags. -`doctor --json` performs read-only diagnostics; `ok:true` can coexist with `ready:false`. Runtime 0.3.3 skill inspection bounds whole-file UTF-8 reads to 65,536 bytes, with at most 65,537 bytes for overflow detection, and checks regular-file, descriptor/path, and observable stability evidence. It reads body bytes but interprets only frontmatter; `metadata_only` does not execute instructions, install, update, or make network requests. It does not authenticate content, freeze an atomic snapshot, or impose a deadline on arbitrary filesystem I/O. Public 0.3.2 had only a 64 KiB pre-read size check. See the [published compatibility contract and status table](typescript-compatibility.md); permission errors remain distinct from unknown input. +`doctor --json` performs read-only diagnostics; `ok:true` can coexist with `ready:false`. Skill inspection in runtimes 0.3.3 and 0.3.4 bounds whole-file UTF-8 reads to 65,536 bytes, with at most 65,537 bytes for overflow detection, and checks regular-file, descriptor/path, and observable stability evidence. It reads body bytes but interprets only frontmatter; `metadata_only` does not execute instructions, install, update, or make network requests. It does not authenticate content, freeze an atomic snapshot, or impose a deadline on arbitrary filesystem I/O. Public 0.3.2 had only a 64 KiB pre-read size check. See the [published compatibility contract and status table](typescript-compatibility.md); permission errors remain distinct from unknown input. `doctor --check-return-route` is a separate, explicitly requested SSH probe. Metadata compatibility and forward SSH reachability do not prove that a send is authorized or that a return route works. `update --check --json` reads the npm registry without installing anything. Keep upgrades under the original manager; the CLI refuses self-update without `--check`. Cached notices require the user's opt-in `SESSION_PEER_UPDATE_NOTICE=1`. The optional `sp` is a sourced shell alias, not an automatically installed global binary. Runtime checks and upgrades do not change separately managed skills, Python installations, or remote hosts. A queued or posted message is not consumption or ACK; never automatically resend an unknown outcome. + +## Windows SSH results in runtime 0.3.4 + +[Runtime 0.3.4](https://github.com/abruption/session-peer-ts/releases/tag/v0.3.4) forwards the native exit code from Windows PowerShell SSH version preflight and request execution; a missing native exit code fails with exit 1. Complete validated submission evidence is retained after an abnormal transport exit. Partial or malformed output remains uncertain, so inspect the structured submission result and never automatically resend. Neither submission evidence nor a successful exit establishes consumption or ACK. + +Coordinate any requested runtime upgrade through the existing package manager on each endpoint: SSH still requires the same exact TS runtime version at both ends. The upgrade does not update the companion skill or provision remote runtimes automatically. This guidance reflects published source and release evidence; it does not claim a new live-agent delivery or ACK test. diff --git a/session-peer-ts/SKILL.md b/session-peer-ts/SKILL.md index 0d06eda..42082ff 100644 --- a/session-peer-ts/SKILL.md +++ b/session-peer-ts/SKILL.md @@ -24,11 +24,11 @@ Python uses that command name too: if the marker is absent, select the Python sk which installation the user intends. Keep the resolved executable for every following command; do not replace another manager's launcher. -This skill revision is 0.2.0 and covers the published npm 0.3.3 runtime. Its CLI +This skill revision is 0.2.0 and covers the published npm 0.3.3 and 0.3.4 runtimes. Its CLI minimum is 0.1.0; its full-feature coverage reference is 0.3.2. The original 0.1.0 -supports only the historical baseline below. Runtime 0.3.3 doctor accepts this +supports only the historical baseline below. Runtimes 0.3.3 and 0.3.4 doctor accept this exact successor metadata profile; public 0.3.2 doctor rejects it even though the -baseline CLI commands work. For supported doctor metadata inspection, use 0.3.3; +baseline CLI commands work. For supported doctor metadata inspection, use reviewed 0.3.3 or 0.3.4; an upgrade still requires the user's request and the existing package manager. Do not change metadata to silence an incompatibility. The skill version, npm version, and Python skill/repository tag are independent. Unknown versions or contradictory help require review @@ -39,7 +39,7 @@ Capture `--help`. If it advertises ` --help`, capture that command's he before selecting options. Older baseline help does not promise per-command help. A supported command or flag must appear affirmatively in supported help: “doctor unsupported” does not enable doctor. Version checks alone do not resolve -unreleased builds that reuse a version string. See the [published npm 0.3.3 CLI help](https://github.com/abruption/session-peer-ts/blob/c0ed30273b9e9c0049df86ae3c38486a94289527/src/help.ts). +unreleased builds that reuse a version string. See the [published npm 0.3.4 CLI help](https://github.com/abruption/session-peer-ts/blob/afed4a5a8945012faf1b23d52cffecb70470a5b3/src/help.ts). Minimum is CLI compatibility for this implementation's stated baseline, separate from security patch recommendations. Full is this revision's published-feature @@ -104,8 +104,8 @@ Skill checks report structural metadata compatibility, not freshness, authentic source, functional verification, or message readiness. `verification: metadata_only` means skill instructions/references are not executed and the skill check does not install, update, or make network requests. It is not a privacy guarantee -that body bytes are unread. Runtime 0.3.3 bounds whole-file UTF-8 reads to 65,536 -bytes, with a 65,537-byte overflow-detection buffer, and checks regular-file, +that body bytes are unread. Runtimes 0.3.3 and 0.3.4 bound whole-file UTF-8 reads to 65,536 +bytes, with a 65,537-byte overflow-detection buffer, and check regular-file, descriptor/path, and observable stability evidence before interpreting metadata. It does not authenticate content, freeze an atomic snapshot, protect against a writer restoring identical metadata, or impose an arbitrary-filesystem I/O deadline. @@ -129,6 +129,14 @@ For a Windows SSH destination, add `--remote-platform win32` and use its Windows `.cmd` shim when applicable. Do not bootstrap Python, provision a remote runtime, or fall back after an uncertain request. +Runtime 0.3.4 fixes Windows PowerShell SSH native exit-code forwarding. +When an SSH result contains complete validated submission evidence, an abnormal +transport exit does not erase that evidence. Partial or malformed output remains +uncertain: inspect the structured result and never automatically resend. This +does not establish consumption or ACK. Coordinate any user-requested upgrade +through each endpoint's existing package manager; both ends still need the same +exact runtime version. See the [0.3.4 release](https://github.com/abruption/session-peer-ts/releases/tag/v0.3.4). + In published 0.3.0+, repeated `--host` returns ordered per-host JSON results. Inspect each `ok`, submission state, and exit status. A failure on one host does not prove anything about the others; duplicate aliases for one machine are not