# Work Registration Hook And Contract Matrix

Chunk: 000276
Generated: 2026-05-19
Status: Draft evidence for chunk 000276 close

## Purpose

This report captures the current work-control surface for Runtime Action Panel role/work visibility. It focuses on which calls are expected to create work contracts, which calls are pure inspection, which hooks classify hosted Codex tools, and where gaps remain.

The core rule is: work-producing Runtime entrypoints should register work at the Runtime-owned entrypoint or core function, regardless of whether a hosted Codex hook fires.

## Current Coverage Matrix

| Surface | Representative call | Classification | Work contract behavior | Current status |
| --- | --- | --- | --- | --- |
| Hosted shell read via Codex hook | `rg`, `sed`, `tail`, `head`, `find`, `cat`, `ls`, `git diff` through `functions.exec_command` | `shell_read` | Hook creates/read-only work step when hook is invoked | Covered by hook classifier; hosted hook invocation itself still needs broader proof |
| Hosted file edit via Codex hook | `functions.apply_patch` | `filesystem_write` | Hook classifies as Developer work with `file_change_expected: true` | Covered by classifier and Runtime test |
| Hosted command polling | `functions.write_stdin` | `shell_read` | Hook creates read/poll work step when hook is invoked | Covered by classifier and Runtime test |
| Hosted parallel wrapper | `multi_tool_use.parallel` containing `functions.exec_command` | derived from nested commands | Bridge extracts nested commands before classification | Covered by bridge test |
| Runtime socket CLI work | `summary validate`, `validation graph`, `qa` socket methods | method based | `runtimeSocketRequest()` wraps non-inspection methods with `runtime.cli.socket_request` work | Covered by Runtime test and work-history evidence |
| Runtime validation CLI | `node ai/runtime/dist/cli.js validate --tier chunk` | validation | `withCliValidationWork()` wraps validation run | Covered by Runtime test and work-history evidence |
| Runtime supervisor CLI | `supervisor request`, `supervisor wait`, `supervisor run-once`, `supervisor restart` | supervisor work | `withCliSupervisorWork()` wraps CLI branch as Runtime Supervisor work | Patched in 000276; direct proof captured with request `150cc30c` |
| Supervisor internal action | `runtime_api_build_reload`, service restart actions | supervisor action | supervisor module records `runtime.supervisor_action` | Covered by existing supervisor work records |
| QA executor | `qa review --chunk ...` | QA review | `runChunkQaReview()` wraps typed QA executor with QA work | Covered by Runtime test |
| Direct Runtime test file | `node ai/runtime/test/runtime-test.mjs` | runtime test | entrypoint starts `runtime-test.entrypoint` after the work-session self-test phase | Patched in 000276; needs final clean rerun |
| Runtime work-session APIs | `runtime work-session-start`, API imports | explicit work registration | Directly start/heartbeat/complete/fail sessions and steps | Covered by Runtime tests |
| Browser smoke test runner | `testing runtime-action-panel-browser-smoke` | e2e/browser proof | runner creates its own work evidence and report | Covered by prior chunks; still included in broader entrypoint CFD |
| Workspace spec runner | `testing frontend-specs`, `testing backend-specs` | test execution | runner imports work-session module | Covered by test runner code path; still included in broader entrypoint CFD |

## Pure Inspection Allowlist

Pure inspection commands or methods should not create active role work unless they are part of a larger work-producing entrypoint:

- Runtime snapshots and health inspection.
- Runtime work-session/history inspection.
- Daemon freshness/build/generation inspection.
- Testing/orchestration defaults.
- Telegram status/details.
- Dispatcher status/results/summary.
- Summary schema/default.

## Known Gaps

| Gap | Evidence | Tracking |
| --- | --- | --- |
| Hosted non-shell tool invocation can bypass project-local hooks depending on platform behavior | User observed `sed`/`node`/`validate` visibility gaps even after hook policy existed; hook adapter can only act when invoked | `cfd-0029`, `cfd-0034` |
| Entry point coverage is not globally audited | Runtime CLI and direct test file gaps were discovered reactively | `cfd-0034` |
| Direct module imports can perform work without a CLI wrapper | Runtime tests and internal API calls can call functions directly | `cfd-0034` |
| Long-running direct Node test lacked continuous top-level work visibility | `node ai/runtime/test/runtime-test.mjs` passed but panel lost active work during the run | Patched in 000276; final rerun required |
| Legacy lifecycle shell activation still owns Backlog -> Active compatibility path | `executor-transition` does not support Backlog -> Active | `cfd-0032` |

## Hook Classification Details

| Tool or command | Current class | Expected role | Notes |
| --- | --- | --- | --- |
| `functions.apply_patch` | `filesystem_write` | Developer | Always Developer work; does not rely on active chunk owner being Developer |
| `apply_patch` | `filesystem_write` | Developer | Same as hosted namespaced form |
| `functions.exec_command` + `rg/sed/tail/head/find/cat/ls/pwd/nl/wc/git status/git diff/git show` | `shell_read` | Codex by default | Read-only work visibility when hook fires |
| `functions.exec_command` + validation command | `validation_execute` | Runtime Executor | Hook maps to Runtime Executor |
| `functions.exec_command` + test command | `test_execute` | Runtime Executor | Hook maps to Runtime Executor |
| `functions.exec_command` + supervisor/restart command | `service_action` | Runtime Supervisor | Hook maps to Runtime Supervisor or waiting when blocked |
| `functions.write_stdin` | `shell_read` | Codex by default | Used for polling running command output |
| `multi_tool_use.parallel` | derived | derived | Bridge extracts nested command text before classification |

## Work Contract Functions

| Function | File | Purpose |
| --- | --- | --- |
| `startRuntimeWorkSession` | `ai/runtime/src/modules/health/work-session.ts` | Create authoritative current work session |
| `startRuntimeWorkStep` | `ai/runtime/src/modules/health/work-session.ts` | Create authoritative current work step |
| `heartbeatRuntimeWorkSession` | `ai/runtime/src/modules/health/work-session.ts` | Keep session fresh |
| `heartbeatRuntimeWorkStep` | `ai/runtime/src/modules/health/work-session.ts` | Keep step fresh |
| `completeRuntimeWorkSession` | `ai/runtime/src/modules/health/work-session.ts` | Mark session complete |
| `completeRuntimeWorkStep` | `ai/runtime/src/modules/health/work-session.ts` | Mark step complete |
| `failRuntimeWorkSession` | `ai/runtime/src/modules/health/work-session.ts` | Mark session failed |
| `failRuntimeWorkStep` | `ai/runtime/src/modules/health/work-session.ts` | Mark step failed |
| `runRuntimeRoleWorkPreflight` | `ai/runtime/src/api/runtime.ts` | Validate or auto-register role work before role-owned mutation |
| `withCliRuntimeWork` | `ai/runtime/src/cli.ts` | CLI-local wrapper for direct commands that do not go through socket methods |
| `withCliValidationWork` | `ai/runtime/src/cli.ts` | Validation-specific CLI work wrapper |
| `withCliSupervisorWork` | `ai/runtime/src/cli.ts` | Supervisor-specific CLI work wrapper |
| `runtimeSocketRequest` | `ai/runtime/src/cli.ts` | Socket-method wrapper for non-inspection Runtime requests |
| `runChunkQaReview` | `ai/runtime/src/api/runtime.ts` | Runtime-owned QA executor work wrapper |

## Recommended Next Analysis

1. Build an entrypoint registry listing all CLI branches, shell helpers, direct Node test files, supervisor actions, Runtime API exports, and method handlers.
2. For each entrypoint, classify as `pure_inspection`, `work_producing`, or `authority_sensitive`.
3. Require work-producing entrypoints to have one of:
   - direct work wrapper,
   - role preflight,
   - existing test runner work contract,
   - explicit documented exemption.
4. Add a validator that fails high-confidence missing work contracts and warns on ambiguous imported functions.
5. Add Action Panel browser proof that runs a representative long command and verifies the active role/work row remains visible until completion.