schema_version: work-registration-entrypoint-inventory-v1
chunk_id: "000276"
generated_at: "2026-05-19T19:18:00Z"
status: draft_evidence
purpose: >-
  Inventory relevant hook calls, Runtime work-contract functions, CLI/module
  entrypoints, known gaps, and carry-forward details needed to close work
  visibility gaps in the Runtime Action Panel role/work projection.

repository:
  root: /workspace
  active_chunk: ai/chunks/active/chunk-000276-qa-executor-evidence-enforcement.md
  related_completed_chunks:
    - ai/chunks/completed/chunk-000272-qa-test-requirement-resolver-behavior-proof-gate.md
    - ai/chunks/completed/chunk-000273-research-gated-system-mechanism-policy.md
    - ai/chunks/completed/chunk-000274-runtime-action-panel-connection-recovery-state-model.md
    - ai/chunks/completed/chunk-000275-deterministic-adversarial-state-machine-tests.md

work_contract_storage:
  current_state: .tmp/runtime-work-session/current.json
  history: .tmp/runtime-work-session/history.json
  journal_surface: runtime_work_session
  health_projection: apps/frontend Action Panel live-work-session and role-activity rows

work_contract_functions:
  core:
    - name: startRuntimeWorkSession
      file: ai/runtime/src/modules/health/work-session.ts
      purpose: create_authoritative_session
    - name: startRuntimeWorkStep
      file: ai/runtime/src/modules/health/work-session.ts
      purpose: create_authoritative_step
    - name: heartbeatRuntimeWorkSession
      file: ai/runtime/src/modules/health/work-session.ts
      purpose: keep_session_fresh
    - name: heartbeatRuntimeWorkStep
      file: ai/runtime/src/modules/health/work-session.ts
      purpose: keep_step_fresh
    - name: completeRuntimeWorkSession
      file: ai/runtime/src/modules/health/work-session.ts
      purpose: mark_session_complete
    - name: completeRuntimeWorkStep
      file: ai/runtime/src/modules/health/work-session.ts
      purpose: mark_step_complete
    - name: failRuntimeWorkSession
      file: ai/runtime/src/modules/health/work-session.ts
      purpose: mark_session_failed
    - name: failRuntimeWorkStep
      file: ai/runtime/src/modules/health/work-session.ts
      purpose: mark_step_failed
  wrappers:
    - name: runRuntimeRoleWorkPreflight
      file: ai/runtime/src/api/runtime.ts
      coverage: role-owned Runtime/API mutation preflight and optional auto-registration
    - name: withAutomaticRuntimeWork
      file: ai/runtime/src/api/runtime.ts
      coverage: Runtime API function wrappers such as QA review and summary validation
    - name: withCliRuntimeWork
      file: ai/runtime/src/cli.ts
      coverage: direct CLI branches that do not use socket method dispatch
    - name: withCliValidationWork
      file: ai/runtime/src/cli.ts
      coverage: cli validate command
    - name: withCliSupervisorWork
      file: ai/runtime/src/cli.ts
      coverage: supervisor request/wait/run-once/restart direct CLI branches
    - name: runtimeSocketRequest
      file: ai/runtime/src/cli.ts
      coverage: non-inspection Runtime socket CLI method requests
    - name: runChunkQaReview
      file: ai/runtime/src/api/runtime.ts
      coverage: typed QA executor work registration

codex_hook_surface:
  config: .codex/hooks.json
  bridge: ai/commands/codex-hook.mjs
  classifier: ai/runtime/src/modules/codex-hooks/work-registration-hooks.ts
  events:
    - UserPromptSubmit
    - PreToolUse
    - PermissionRequest
    - PostToolUse
    - Stop
  hosted_tool_names:
    - exec_command
    - functions.exec_command
    - write_stdin
    - functions.write_stdin
    - apply_patch
    - functions.apply_patch
    - multi_tool_use.parallel
  command_classification:
    filesystem_write:
      commands:
        - apply_patch
        - functions.apply_patch
      expected_role: Developer
      file_change_expected: true
    shell_read:
      commands:
        - rg
        - sed
        - tail
        - head
        - ls
        - cat
        - find
        - pwd
        - git status
        - git diff
        - git show
        - nl
        - wc
      expected_role: Codex
      file_change_expected: false
    validation_execute:
      patterns:
        - summary validate
        - validate-governance
        - runtime state-journal-validate
        - validate --tier
      expected_role: Runtime Executor
    test_execute:
      patterns:
        - jest
        - vitest
        - playwright
        - test:e2e
        - yarn test
        - npm test
        - runtime-daemon-tests
        - runtime-broad-tests
      expected_role: Runtime Executor
    service_action:
      patterns:
        - supervisor
        - restart
        - dev_server_restart
        - service-resurrection
        - health-read-model-warm
      expected_role: Runtime Supervisor
    authority_sensitive:
      patterns:
        - close_commit
        - dispatcher
        - approved-action
        - executor-transition
        - complete-chunk
        - activate-chunk
        - git commit
      expected_role: Dispatcher

cli_entrypoints:
  socket_wrapped:
    wrapper: runtimeSocketRequest
    examples:
      - summary validate
      - validation graph
      - validation run
      - qa socket methods
      - dispatcher run
    pure_inspection_allowlist_examples:
      - runtime health-snapshot
      - runtime work-session
      - runtime work-history
      - runtime daemon-freshness
      - testing defaults
      - orchestration defaults
      - telegram status
      - dispatcher status
      - summary schema
  direct_wrapped:
    - command: validate --tier
      wrapper: withCliValidationWork
      role: Runtime Executor
    - command: supervisor request
      wrapper: withCliSupervisorWork
      role: Runtime Supervisor
    - command: supervisor wait
      wrapper: withCliSupervisorWork
      role: Runtime Supervisor
    - command: supervisor run-once
      wrapper: withCliSupervisorWork
      role: Runtime Supervisor
    - command: supervisor restart
      wrapper: withCliSupervisorWork
      role: Runtime Supervisor
    - command: qa review
      wrapper: runChunkQaReview
      role: QA
  direct_entrypoints_requiring_audit:
    - ai/runtime/test/runtime-test.mjs
    - ai/runtime/test/runtime-daemon-test.mjs
    - ai/runtime/test/runtime-supervisor-test.mjs
    - ai/commands/activate-chunk.sh
    - ai/commands/complete-chunk.sh
    - ai/commands/validate.sh
    - ai/commands/runtime-action-panel-browser-smoke.mjs
    - ai/commands/service-readiness-check.mjs
    - ai/runtime/src/methods/index.ts exported method handlers
    - ai/runtime/src/api/runtime.ts exported direct module functions

patched_in_chunk_000276:
  qa_executor:
    - QA review renders categories, required evidence, provided evidence, missing evidence, override fields, and final clean run state.
    - Required-evidence override requires resolver permission and qa_override_risk.
    - Stateful/live categories include final_clean_pass requirements.
  work_visibility:
    - Runtime supervisor direct CLI request/wait/run-once/restart are wrapped with withCliSupervisorWork.
    - Runtime test entrypoint starts continuous runtime-test.entrypoint work after self-testing work-session mechanics.
    - Hook shell-read command list includes tail and head.
    - apply_patch classification always maps to Developer for filesystem_write.
  cfd:
    - cfd-0034 added for complete entrypoint audit.

known_gaps:
  - id: hosted_hook_invocation_not_guaranteed
    detail: Hosted Codex tool invocations may not always invoke project-local hooks for every tool shape.
    cfd: cfd-0029
  - id: entrypoint_audit_incomplete
    detail: Not every Runtime CLI branch, shell helper, direct test file, and exported API function has been audited.
    cfd: cfd-0034
  - id: direct_module_call_bypass
    detail: Imported Runtime API/module functions can do work without CLI hook mediation.
    cfd: cfd-0034
  - id: lifecycle_activation_compatibility_shell
    detail: Backlog to Active still uses guarded legacy shell compatibility path.
    cfd: cfd-0032

recommended_validator:
  name: work_registration_entrypoint_coverage
  mode: advisory_initially
  checks:
    - every CLI case is classified pure_inspection or work_producing
    - work_producing direct CLI cases call a work wrapper
    - direct Node test files either use a continuous work contract or are marked fixture-only
    - shell helpers either delegate to Runtime work wrappers or are emergency compatibility only
    - exported Runtime API methods that mutate state use withAutomaticRuntimeWork or role preflight
    - browser proof verifies live-work-session visibility for a representative long-running test

acceptance_notes_for_future_fix:
  - Do not manually register around a missing path as proof.
  - Fix registration at the entrypoint or core function that owns the work.
  - Keep pure inspection from creating false active role states.
  - Long-running commands need continuous heartbeat or a stale threshold longer than expected duration.
  - Completion/failure must clear or terminalize the same session that was started.
