Document proven session-tool workflow checks - #762

Scope

Add source-backed checks for task scratch, downloads, terminal launches, native commands and exports, service lifetime, source identity and effective client settings. Each lesson retains its revision or documented scope and its primary reference.

• Base commit: ecfa112764c664d35377dd66b8cfcb67e5a94d60.
• Lane: lane:foundation.
• Owned paths: docs/token-session-handbook.md; its integrity entry in the final manifests/evidence.json commit.

SOTA sources

Every added handbook paragraph carries its primary source, reread before publication:

• UAPI.9@5ca37902, Context Mode@589d8214, Windows Terminal@dc8ae365, V8's backtracking explanation.
• [email protected] launcher, its web entry point cited in the handbook; Codebase Memory [email protected] stop; [email protected] timeout.
• [email protected] normalized names, sanitizer application and result persistence cited in the handbook; CPython@e848e4b0, with separate read/write paths.
• OmniRoute@c1e30b76 selector and retained public control evidence/artifacts/omniroute-sol-max-20260930/checks/preflight-scratch-port-reproduction.json at main@ecfa1127; independently parsed one/one/zero returned PID counts.
• Official uv configuration, Claude memory, model configuration and CLI flags, reread for the documented procedures.
• native-agent-stack@ecfa112764c664d35377dd66b8cfcb67e5a94d60:docs/acceptance-evidence-policy.md:24-40, docs/lanes.md:94, recipes/README.md:69,95; gitleaks@83d9cd6 README.

Evidence-class table

Local commands run

python3 scripts/validate.py
exit 0: 69 components, 10272 hashed files, 4 profiles, 212 receipts
python3 -m unittest tests.test_install_claude_profile tests.test_adoption_docs_consistency tests.test_context_mode_practice_docs tests.test_token_e2e_preregistration tests.test_codex_agents tests.test_token_lanes_session_start tests.test_token_lanes_subagent_start tests.test_shell_parser_ci
exit 0: 273 tests, 7 skipped
gitleaks git --pre-commit --staged --redact=100 --no-banner --no-color --config .gitleaks.toml --report-format json --report-path <owned-report> .
exit 0: 2742 staged bytes scanned, no findings; 8.30.1 archive matches repository-pinned SHA256
added-text login-name, personal-path, private-identifier, internal-reference and time-zone scans
zero matches
git diff --check
exit 0

Heavy checks ran sequentially at niceness 19 with owned temporary storage. Citation corrections were followed by final validation, doc tests and redacted scanning. Returned skips remain recorded. These checks establish doc/integration consistency, not a new model or provider qualification.

Decision record

Live uv, Claude memory/model/CLI and V8 references were reread on 2026-10-06; native Claude Code version/help identified 2.1.291. Scratch placement follows the existing 2026-09-27 “Assuming a temporary directory is outside every Git repository” and 2026-10-02 “Keeping owned worktrees and unpushed receipts in a directory that is emptied at boot” records in docs/harness-defaults.md:214,306, plus docs/decisions/2026-10-05-disk-headroom-enospc.md:27-33. The guide explicitly requires an owned persistent directory outside every checkout and repository and qualifies the test guard's /tmp example by capacity and placement. The probe/configuration links also name their dated lead phrases.

Owner follow-up: the generated command manifest's Grafana row and active instruction copies still carry health forms without quiet file output. Their owner should update the canonical generator input and active copies, or route the check through ctx_execute, while preserving historical command/output evidence unchanged. This change keeps the handbook's corrected form and records that divergence; those files are outside its owned paths.

Operating lessons with source-revision recheck conditions, rather than a component-selection change. A changed implementation requires rereading its cited path. Historical claims lacking their original controls remain outside the public guidance.

Host evidence

Source review remains distinct from execution evidence; no host receipt or platform-status promotion.

GitHub checks

The original review-head OSV scan reported five advisory identities across five unchanged base lockfiles (native scan):

Ordinary and frozen-macOS scans both exited 1. Dependency repair remains separately owned; green checks on a refreshed base are required after it lands. The prior body omitted three advisories; this table corrects that incomplete summary.

Checklist

• No GitHub Actions or workflow change.
• Added material contains no credential value, personal host path or user quotation.
• No new billing surface.
• Separate owned worktree; peer content preserved.
• Registry committed last; draft for independent exact-head review.