feat(audit): detect and report out-of-band workflow-state and workspace mutations #867

New Issue

2026-07-24T00:06:04-05:00

jcwalker3 commented

2026-07-24 00:06:04 -05:00

Summary

Detect and report out-of-band workflow-state and workspace mutations to ensure complete auditability, provenance tracking, and tamper resistance across all Gitea-Tools workflows.

Problem Statement & Operational Impact

Unsanctioned out-of-band shell operations (such as direct Git commits, branch resets, or wildcard file deletions) can mutate repository state or task workspaces outside of sanctioned MCP control-plane guardrails. When mutations occur outside of sanctioned tooling, the control plane cannot authoritatively determine which paths were affected, leading to untracked workspace drift, unprovable data loss, and ambiguous workflow state.

Factual Incident Evidence

This issue preserves the factual evidence from the observed out-of-band mutation incident:

Unauthorized shell Git commit: A direct Git commit was executed via shell outside sanctioned MCP author tooling.
Shell branch reset: A shell branch reset command altered the active HEAD position without workflow authorization.
Wildcard rm -f deletion command: A wildcard deletion (rm -f ...) was executed in the workspace.
Inability to determine authoritatively deleted paths: Because wildcard deletion commands do not output explicit pre- and post-deletion path manifests, the system could not determine which exact files were removed.
Inability to reconstruct exact workflow impact: The command pattern alone was insufficient to reconstruct the precise impact on workflow state, task leases, or dirty workspace provenance.

Distinction from Dirty-Orphan Recovery (#860 / PR #861)

Issue #860 / PR #861 (Dirty-Orphan Recovery): Provides a sanctioned recovery primitive for same-claimant author sessions with dirty registered worktrees under dead/malformed locks.
This Issue (Out-of-Band Auditability & Detection): Provides detection, tamper-evident auditing, and exact-path reporting for unsanctioned out-of-band shell Git operations and wildcard file deletions. It does not replace or alter dirty-orphan recovery in #860.

Acceptance Criteria

Tamper-Evident Audit: Implement a tamper-evident audit and diagnostic mechanism that detects and logs all unsanctioned out-of-band workspace and Git mutations.
Exact-Path Reporting: Ensure all workspace file operations produce exact-path manifests so that affected files can be authoritatively enumerated, avoiding unprovable wildcard globs.
Sanctioned-Operation Provenance: Validate that all state-modifying operations carry authorized MCP provenance (session identity, active profile, role kind, and worktree binding).
Fail-Closed Behavior: Fail closed (BLOCKED + DIAGNOSE) immediately if unsanctioned Git commits, branch resets, or unverified path deletions are detected in the active workspace.
Protected-Work Preservation: Ensure protected work and dirty registered worktrees cannot be silently wiped or reset by out-of-band commands.
Diagnostic Capability: Expose clear diagnostic reporting detailing the exact nature, timestamp, and affected paths of any detected out-of-band tampering.
Security & Concurrency Testing: Include comprehensive synthetic test coverage verifying:
- Detection of out-of-band shell Git commits and resets.
- Detection and rejection of unmanifested wildcard deletion commands (rm -f).
- Audit trail integrity under concurrent tool invocation.
- Preservation of existing dirty-orphan recovery semantics (#860 / PR #861).

Non-Goals

Modifying or replacing dirty-orphan recovery (#860 / PR #861).
Weakening registered-worktree or branches-only preflight guards.
Permitting unsanctioned shell Git fallbacks in scheduled runs.

## Summary Detect and report out-of-band workflow-state and workspace mutations to ensure complete auditability, provenance tracking, and tamper resistance across all Gitea-Tools workflows. ## Problem Statement & Operational Impact Unsanctioned out-of-band shell operations (such as direct Git commits, branch resets, or wildcard file deletions) can mutate repository state or task workspaces outside of sanctioned MCP control-plane guardrails. When mutations occur outside of sanctioned tooling, the control plane cannot authoritatively determine which paths were affected, leading to untracked workspace drift, unprovable data loss, and ambiguous workflow state. ## Factual Incident Evidence This issue preserves the factual evidence from the observed out-of-band mutation incident: 1. **Unauthorized shell Git commit**: A direct Git commit was executed via shell outside sanctioned MCP author tooling. 2. **Shell branch reset**: A shell branch reset command altered the active HEAD position without workflow authorization. 3. **Wildcard `rm -f` deletion command**: A wildcard deletion (`rm -f ...`) was executed in the workspace. 4. **Inability to determine authoritatively deleted paths**: Because wildcard deletion commands do not output explicit pre- and post-deletion path manifests, the system could not determine which exact files were removed. 5. **Inability to reconstruct exact workflow impact**: The command pattern alone was insufficient to reconstruct the precise impact on workflow state, task leases, or dirty workspace provenance. ## Distinction from Dirty-Orphan Recovery (#860 / PR #861) - **Issue #860 / PR #861 (Dirty-Orphan Recovery)**: Provides a sanctioned recovery primitive for same-claimant author sessions with dirty registered worktrees under dead/malformed locks. - **This Issue (Out-of-Band Auditability & Detection)**: Provides detection, tamper-evident auditing, and exact-path reporting for unsanctioned out-of-band shell Git operations and wildcard file deletions. It does not replace or alter dirty-orphan recovery in #860. ## Acceptance Criteria 1. **Tamper-Evident Audit**: Implement a tamper-evident audit and diagnostic mechanism that detects and logs all unsanctioned out-of-band workspace and Git mutations. 2. **Exact-Path Reporting**: Ensure all workspace file operations produce exact-path manifests so that affected files can be authoritatively enumerated, avoiding unprovable wildcard globs. 3. **Sanctioned-Operation Provenance**: Validate that all state-modifying operations carry authorized MCP provenance (session identity, active profile, role kind, and worktree binding). 4. **Fail-Closed Behavior**: Fail closed (`BLOCKED + DIAGNOSE`) immediately if unsanctioned Git commits, branch resets, or unverified path deletions are detected in the active workspace. 5. **Protected-Work Preservation**: Ensure protected work and dirty registered worktrees cannot be silently wiped or reset by out-of-band commands. 6. **Diagnostic Capability**: Expose clear diagnostic reporting detailing the exact nature, timestamp, and affected paths of any detected out-of-band tampering. 7. **Security & Concurrency Testing**: Include comprehensive synthetic test coverage verifying: - Detection of out-of-band shell Git commits and resets. - Detection and rejection of unmanifested wildcard deletion commands (`rm -f`). - Audit trail integrity under concurrent tool invocation. - Preservation of existing dirty-orphan recovery semantics (#860 / PR #861). ## Non-Goals - Modifying or replacing dirty-orphan recovery (#860 / PR #861). - Weakening registered-worktree or branches-only preflight guards. - Permitting unsanctioned shell Git fallbacks in scheduled runs.

sysadmin referenced this issue

2026-07-24 00:29:52 -05:00

fix(author): bootstrap recovery for dirty orphaned issue worktrees (#860) #861

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#867