feat(cli): add guarded private descriptor transport

[andrei-hasna]

Tracks Todos task b042f78b-bf20-4528-9a18-edf9a40983b7.

Summary:

• add package-owned guarded descriptor create, query, and exact readback helpers
• keep private payloads and results on anonymous inherited descriptors only
• fail closed on public argv, stdin, regular files, named FIFOs, malformed frames, duplicate operations, and timeouts
• reserve package version 0.2.104 because draft PR chore(release): @hasna/knowledge 0.2.103 #89 owns 0.2.103

Verification:

• guarded integration: 1 pass, 22 assertions
• guarded CLI refusal lane: 1 pass, 35 assertions
• package release tests: 7 pass, 109 assertions
• TypeScript, build, generated-artifact verification, pack validation, diff check, and secret scans pass
• independent adversarial review: REVIEW: GO

This PR does not merge or publish the package.

[andrei-hasna]

[REVIEW] NO_GO — #91 @ acb9d77 — lens: correctness+security+gates, reviewer unresolved-account002 (1 of 1)

Reviewed the exact candidate against fresh base origin/main=9a1732e0fa0fe71797438d5088be659d89bc1751.

What I read:

• git log --oneline origin/main..HEAD — exit 0; one commit, acb9d77 feat(cli): add guarded private descriptor transport.
• git diff origin/main...HEAD --stat — exit 0; 14 changed files, 1,069 insertions and 13 deletions.
• Full textual diff for every changed source, test, declaration, documentation, and generated JavaScript file; bin/knowledge.js is a generated binary artifact.
• Surrounding argument parsing and command dispatch in src/cli.ts, all of new src/guarded-cli.ts, the descriptor/validation/result primitives in src/guarded-write-contract.ts, the guarded writer execution/query/readback paths in src/guarded-writer.ts, package scripts, and .github/workflows/ci.yml.

Gates and probes:

• bun install — exit 0; setup only, 156 packages installed. This is not reported as the test result.
• bun run test — exit 0; 488 pass, 2 skip, 0 fail, 4,171 expectations across 52 files.
• The repository declares no typecheck script; none was invented or run.
• Safe projected check-state read for this exact head — exit 0; test-matrix (macos-latest, bun), test (macos-latest, node), and test-matrix (windows-latest, bun) are completed failures.

Blocking findings:

1. P1 — The new guarded descriptor transport breaks the repository's required macOS and Windows test lanes. privateFd() verifies FIFOs only through Linux-specific /proc/self/fd/<fd>. On macOS, the exact-head annotation shows request_fd_anonymous_pipe_identity_unverified where the test expected the named-FIFO refusal, and the macOS Node lane fails in the new request path with guarded_cli_private_request_failed. On Windows, the new guarded CLI test reaches KnowledgeGuardedCliDescriptorError: guarded_cli_timeout. This is a currently reached public helper and required-gate failure, not a speculative portability concern. Replace the Linux-only descriptor identity check and synchronous descriptor I/O with a portable anonymous-pipe implementation, preserve rejection of named FIFOs/regular files, then rerun the affected macOS and Windows lanes.

Non-blocking follow-ups:

• P2 misuse resistance: guarded execute-descriptor rejects --content, but known public flags omitted from publicBodyFlagsPresent are accepted and ignored. A synthetic --api-key synthetic-noncredential-sentinel probe reached FD validation rather than guarded_descriptor_public_input_refused (exit 1 in both probes). Prefer an explicit allowlist containing only --request-fd, --result-fd, and --json. The exported helper does not emit these extra flags, so this does not add a second blocker.

Verdict: NO_GO until the portable descriptor transport passes the existing macOS and Windows CI lanes. The Linux declared test gate is green, and I found no other concrete reachable in-scope P0/P1 defect.

[andrei-hasna]

[REVIEW] NO_GO — #91 @ acb9d77 — lens: correctness+isolation+wiring, reviewer codewith-sol-reviewer (1 of 1)

P0: None found.

P1 — src/guarded-cli.ts:414-457: the new anonymous-FD client is not reliable on supported CI platforms. At this exact head, the macOS test (macos-latest, node) lane reaches the public executeKnowledgeGuardedCliWrite path and fails while ending FD 3 with guarded_cli_private_request_failed / ERR_SOCKET_CLOSED_BEFORE_CONNECTION. The Windows Bun lane hangs the same create/update/query/readback test for 60 seconds and ends in guarded_cli_timeout. This makes the exported guarded CLI helpers fail or stall on real supported runners, so the cross-process write/readback path is not mergeable as-is.

P1 — tests/cli.test.ts:468 and src/guarded-cli.ts:114-120: the required macOS Bun suite is red because a named FIFO produces request_fd_anonymous_pipe_identity_unverified, while the regression requires request_fd_must_be_anonymous_pipe_or_socket. This is current exact-head evidence that the platform-specific FD classification and its required gate disagree; both macOS test jobs are therefore non-green.

P2/P3: None recorded; optional hardening and documentation were not treated as blockers.

Could not verify an authenticated production Knowledge write/readback, generated-artifact byte equality, or Windows/macOS behavior locally. The current exact-head GitHub checks show Ubuntu Bun success, macOS Bun failure, macOS node-lane failure, Windows Bun failure, and cancellation of the remaining required test jobs before generated-artifact verification.

[andrei-hasna]

[REVIEW] GO — #91 @ dc9ed27 — lens: correctness+security+gates, reviewer unresolved-account001 (1 of 1)

Reviewed the exact two-commit delta from fresh base 9a1732e through dc9ed27. I read every changed source, declaration, documentation, and test diff; traced the guarded descriptor helpers through the CLI parser, IPC worker, opaque descriptor materialization, writer/query/readback paths, proof validation, and surrounding tests; and verified the generated bundle against that source.

Commands and results:

• bun install — exit 0; 156 packages installed. Setup only, not counted as the test gate.
• bun run test — exit 0; 489 pass, 2 skip, 0 fail; 491 tests across 52 files; 4,180 assertions.
• bun run verify:generated — exit 0; all 6 generated bundles rebuilt byte-identically and carried no stale generated code.
• This repository declares no typecheck script; none was invented or run.

Blocking P0/P1 findings: none. The guarded helper keeps descriptor payloads off argv, stdin, environment variables, files, stdout, and stderr; direct invocation without inherited IPC fails closed; request/result digests and the public acknowledgement are cross-checked; writes retain binding, precondition, replay, exact-readback, and receipt checks.

Non-blocking follow-up: guarded execute-descriptor rejects known body-bearing flags but still parses unrelated global flags such as --api-key; a direct synthetic probe still failed closed at exit 1 with guarded_descriptor_private_ipc_required, and the exported fixed-argument helper never passes that flag, so there is no currently reachable P0/P1 path. A future hardening change can replace the body-flag list with a strict per-command flag allowlist.