docs: tokenless (token-optional, local-only) path spec — ENG-1329

[jadoonf]

Summary

Spec-only draft (no product code): docs/tokenless-path-spec.md designs the token-optional, local-only path for the action — ENG-1329 and the fallback half of ENG-1346.

Key positions taken (for review/discussion):

• Control-plane audit: the token has exactly three uses — createAgent, mergedNetPoliciesAsYAML, and Jibril's sensor upload. The whole post-step pipeline (profile JSON → Step Summary → standalone PR comment) is already local; Jibril already runs offline via GARNET_SAR=true with a bundled default netpolicy. Phase 1 needs no Jibril or control-plane changes.
• Behavior matrix: api_token absent → local-only mode (skip registration + policy fetch, keep bundled observe-only policy, omit token lines from /etc/default/jibril, empty report_url/agent_id, fork PRs become tokenless runs instead of failures). Token present-but-invalid still fails loudly — no silent downgrade.
• Contract discipline (the point of ENG-1346): tokenless output is NOT a new "local shape" — it's the v6.1 contract with the permalink slots rendering an upgrade CTA + a labeled local-only marker, ratified as a v6.2 amendment in the testbed (ENG-1346 Option-B sequencing with this spec as the written trigger). Everything else stays byte-identical.
• Sequencing: land after the ENG-1355 v6.x renderer port (v2.3.0); tokenless ships as v2.4.0. Designed for the future where UI Run Profile reports are always private — the local path becomes the permanent public surface.

Open questions in §9 (CTA vocab lock, waiting state, App+tokenless comment coexistence, jibril_version gate, phase-2 OIDC trigger).

Link to Devin session: https://app.devin.ai/sessions/4a7d213fd3174d2ea66412fe594480a4
Requested by: @jadoonf

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

@tixxdz requesting your review/discussion on this tokenless-path spec (ENG-1329 / fallback half of ENG-1346).

The positions I'd most like your take on:

1. Local mode mechanics (§2/§6): skip createAgent + netpolicy fetch when api_token is empty, rely on GARNET_SAR=true offline mode + Jibril's bundled observe-only default netpolicy. Anything Jibril-side I'm missing (minimum version, default policy behavior)?
2. Contract discipline (§5): tokenless output stays on the v6.1 contract with only the permalink slots swapped for an upgrade CTA + a local-only marker, ratified as a v6.2 testbed amendment — not a separate "local shape".
3. Fail-loudly rule (§4): absent token → local mode; present-but-invalid token → loud failure, never silent downgrade.
4. Open questions in §9, especially App+tokenless comment coexistence and the fork-PR story.

Happy to iterate here or take it to the §7 ratification session.

[jadoonf]

Automated review-assist (agent-generated, advisory — not an approval or block).

Verified against main: doc-only as titled (one new file, docs/tokenless-path-spec.md). The §2 audit is accurate — the token's only uses are createAgent (src/action.js:159), mergedNetPoliciesAsYAML (src/action.js:183), and the sensor upload via /etc/default/jibril; the real tokenless gate is the throw at src/action.js:37; the post-step pipeline is fully local; GARNET_SAR defaults to "true" (src/action.js:219) and jibril's agent engine skips registration under SAR. Contract fit is sound: no permalink is promised without the API — report_url goes empty ("omit rather than mislabel", ux-contract §1.1), and the CTA/local-only marker is correctly routed through a v6.2 testbed amendment, since v6.1 §1.7 locks fold subtext to "only the single garnet permalink — nothing else". Sequencing after the ENG-1355 port (v2.3.0 → tokenless in v2.4.0) is right; no file overlap with the port.

Two factual corrections:

1. §4 footnote + Q3: the action already marker-scans — src/pr-comment-plan.js:41 (containsControlPlaneComment) returns blocked-by-control-plane against CONTROL_PLANE_MARKERS (src/runtime-review.js:68). A tokenless run on a PR that already has an App comment stands down today. Q3 reduces to the ordering race (tokenless posts first, App posts later), which control-plane reconciliation already converges.
2. §4 "keep bundled observe-only policy": unverified — jibril's bundled sample (jibril/etc/config/netpolicy.yaml) ships deny rules (example.com, uol.com.br, 2.2.2.2). Recommend hardening Q4 into a phase-1 requirement: in tokenless mode the action writes a known observe-only policy rather than trusting whatever the resolved jibril version bundles.

Nit: "fails loudly" for present-but-invalid tokens = today's warn-and-continue (core.warning, job not failed); keep that meaning through implementation so it doesn't become setFailed.

CI: Build/dist verify ✅; smoke jobs skipped (docs-only).

[devin-ai-integration]

Folded the review-assist corrections into the spec (07599aa):

1. Marker-scan (§4 footnote + Q3): now cites planPullRequestComment/blocked-by-control-plane (src/pr-comment-plan.js, CONTROL_PLANE_MARKERS in src/runtime-review.js); Q3 reduced to the ordering race, noting control-plane reconciliation already converges it.
2. Observe-only policy is now a phase-1 requirement (§2/§4/§6/§7, Q4): jibril's bundled sample netpolicy ships deny rules, so tokenless mode writes a vendored observe-only policy from this repo instead of trusting the bundled default. Q4 rewritten to ask about its exact contents + refresh discipline.
3. "Fail loudly" clarified (§4): means today's visible core.warning + no monitoring — the job is not failed; no setFailed introduced.