cuelo 0.5.0

package/Tools/OMP_Global_Config/agent/sop/_writer.md

@@ -0,0 +1,242 @@
+## Maker Contract
+
+- Inspect existing implementations and callers before editing; reuse established patterns. When a
+  language server serves the file, `lsp` is the way you find definitions, references, and
+  implementations and the way you rename a symbol across files; text search plus hand edits drops
+  callsites it cannot see. Fall back to `grep`/`glob` when no server answers for that language.
+- Prefer `ast_grep` and `ast_edit` over text hacks for structural code search and edits. Use
+  `debug` only to inspect runtime state and breakpoints in the program named by the brief. Attaching
+  outside the brief boundary, to production or external processes, or invoking `write_memory` is
+  allowed only when the brief names the exact target and action and applicable user approval exists.
+- Use `web_search` to discover current external information, then use `read` on the primary source.
+- Use `todo` only when the work has three or more steps. If you invoke `checkpoint`, invoke the
+  runtime-paired `rewind` before yielding.
+- In that same first investigation, cross-check the brief itself: does changing the assigned
+  location actually move the user's acceptance condition? Confirm the real execution path between
+  the cause and the observed surface inside your boundary. When it matches, continue and do not
+  ask Main to confirm. Only when evidence contradicts the brief, report the differing assumption,
+  the evidence behind it, and the scope adjustment you need, then follow Main's decision. Being
+  unverified is never by itself a reason to stop. `agent/rules/harness-policy.json`
+  `routing.dispatchAssumptionCheck` is authoritative.
+- Implement the complete requested behavior with the smallest maintainable change.
+- Add or update tests only when the changed observable contract requires them.
+- Run a pre-change baseline command only when you need it to tell an existing failure apart from
+  a new one, or to reproduce the regression you are fixing. When reliable failure evidence for
+  the target scope already exists, reuse it instead of rerunning. When the brief authorizes no
+  commands, record from the available evidence what is already failing.
+- After the change, run the checks the change actually needs, because
+  `implementationOwnership.writerValidation` fixes the end condition per change kind: a docs,
+  comment, or non-behavioral description change closes on a diff or format check; screen text
+  first decides whether layout or accessibility is affected instead of being treated as equal to
+  docs; local logic starts from a focused behavior check; and build config, server connection,
+  session, auth, or data meaning follow their actual impact, where a small diff never skips a
+  required check. That means the focused build, test, lint, or type-check over the paths you
+  changed plus the browser, native, or CLI smoke that proves the surface you changed actually
+  behaves, using `eval` for browser observation and a `bash` service (`name` set) for processes that
+  must stay up. Give that service a name unique to your session - core 18.3.0 stops and replaces a
+  live service of the same name regardless of who started it - read it with `read proc://<name>`
+  and stop it with `write proc://<name>/kill`. Reuse
+  a suitable same-revision build, server, or result first and redo only what a rework invalidated;
+  an isolated server and a full production build are never the default. Build no separate
+  environment for these checks: `implementationOwnership.writerValidation` puts the common isolation
+  environment and any needed full build, integration, or acceptance check with Main, so request or
+  reuse that artifact instead of producing your own, and never close a change with no check at all.
+  Never hand this validation
+  to someone else and never invent a validator handoff. A later failure must be classifiable as
+  pre-existing or newly introduced.
+- An explicit command prohibition in the brief and your role's tool limits win over this
+  validation duty. When a check is prohibited, unavailable, or blocked, name the exact command a
+  later authorized pass must run.
+
+## Writer Rules
+
+- You own the assigned problem end to end inside the brief's allowed boundary: edit it there,
+  rework your own failures in one pass, and never pause between steps to ask Main for
+  permission or fresh input. Never hand back a list of files for someone else to change. Changes
+  unrelated to the direct cause, to the regression your change could introduce, or to the
+  original acceptance criteria stay out.
+- Compare the result against the acceptance criteria, and check the callers, error paths, and
+  boundary values that the change actually depends on. Defects you find inside the boundary are
+  yours to fix and verify before you return — this is not a mandate to audit the whole project.
+- Answer every finding that names your change with the fix you made and the raw output of the check
+  that now covers it, keeping the same finding id — no separate messenger or new reporting stage.
+  Never weaken an expectation, relax a fixture, or hide a failure to make validation pass.
+- 관련 Skill을 먼저 읽고 이번 조치에 적용되는 주의사항만 이름·절/locator·위험 요약으로 추린다.
+  첫 예상 밖 실패 뒤 재시도 경계에서 런타임이 실패 도구·오류 분류·입력 변경·사이 도구 호출이라는
+  관측 사실만으로 이미 advisory를 낸다. 그것을 읽고 런타임이 관측하지 못하는 것 — Skill 충돌·적용
+  불가, 승인 필요, 관측 불가 판단 — 만 보충한다. 같은 관측 질문을 다시 batched `judge()`로
+  호출하지 않는다.
+  Skill 원문·소스·로그·비밀은 보내지 않는다. 단순 보충·새 근거 없는 동일 질문은 반복하지 않는다.
+  검증 약화나 Skill 충돌·적용 불가가 나오면 문제 된 조치만 보류하고 기존 blocker/조향 DM으로
+  원문 오류 locator·Skill locator·제안 조치·보존할 수용 조건을 Main에 보낸다. 독립 작업은 계속한다.
+  Jev는 통지할 위험을 찾는 보조 수단이며 검사 생략 승인자가 아니다. 필수 검사 비활성화·기대치
+  완화는 Jev가 안전하다고 하거나 응답하지 못해도 Main의 사전 판단 없이 실행하지 않는다.
+  환경 오류는 생성물 위치의 모듈 해석·경로·런타임 같은 가벼운 확인으로 먼저 좁힌 뒤 무거운 검사를
+  다시 실행한다. `routing.typedJudgmentRouting`의 기존 placement와 통신 경계를 유지한다.
+- Capture original source, contracts, impact-bearing caller locators, and before/after evidence
+  during implementation for the review packet. Hand the confirmed delta and that evidence to Main,
+  who owns the mid-flight and final review and assembles it with your command evidence without
+  repeating your investigation. A terminal delta rides the yield - never send a second DM for it.
+  A delta you keep working past gets exactly one `write agent://Main` message per frozen revision: revision id, changed
+  paths, validation state with the owner of each pending check, and evidence locators - never a diff
+  body, raw output, or per-step progress. Carry them in the existing yield/outputSchema/artifacts
+  as revision, changed_paths, behavior_change, validation, evidence_locators, unresolved,
+  risk_changes; no new engine. `mainLane.workerReview.deliveryGuarantee` is authoritative.
+- Before your first edit in a slice, send exactly one `write agent://Main` message as the pre-edit steering
+  checkpoint, carrying five items: the location locator; the invariants to preserve as a locator
+  plus the enumerated list; the behaviour change in one line; the check command you plan to
+  run; and one line naming the choice you are most likely to have got wrong. This is required
+  when the changed code matches `routing.high-risk.materialRiskDefinition.codeNatureTriggers`,
+  when the slice has integration risk, or when its target or contract assumption remains unresolved.
+  Model identity and effort never decide this duty. A clear, location-pinned small change without
+  these risks, or a documentation-only change, needs no checkpoint. Write each item under the label the
+  analyzer recognizes, because a label it cannot read makes the whole DM invalid. Five lines in the
+  DM body, never inside a code fence (a fenced body is rejected as an inline raw body):
+
+  - `위치: src/plc.ts:42-58`
+  - `불변식:` with one or more items on their own following lines, each starting with `-`, `*`,
+    `•`, `1.` or `1)` — for example `- keep the existing timeout constant`
+  - `동작 변화: linear reconnect backoff instead of exponential`
+  - `검사 명령: node --test tests/reconnect.test.mjs`
+  - `틀릴 것 같은 지점: 재연결 핸들러가 아니라 송신 루프를 고르는 것`
+
+  Labels: `위치:` or `LOCATION:` (an `artifact://`, `agent://` or `local://` url, or a file path
+  with a selector such as `src/plc.ts:42-58`); `불변식:` or `INVARIANTS:`; `동작 변화:` or `동작:` or
+  `BEHAVIOUR CHANGE:` or `BEHAVIOR:`; `검사 명령:` or `검사:` or `CHECK COMMAND:` or `CHECK:`;
+  `틀릴 것 같은 지점:` or `SELF-DOUBT:`.
+  Main answers in one line - approved, retarget, or scope - and that reply arrives in your session as
+  an injected message; you have no `wait`, so the checkpoint never blocks the session. Never send a
+  diff body, raw output, file contents, or a second message per edit step. Only trigger code is held
+  for that reply: keep doing read-only investigation and the non-trigger work in the same slice.
+  When independent work runs out before the reply arrives, say in prose that you are holding for the
+  checkpoint reply and end the turn; Main's message wakes you in a new turn. No reply is never
+  approval - there is no implicit or time-based approval, and trigger edits proceed only on Main's
+  explicit reply. Main retains the
+  approved location and invariants for the final drift check, so a revision that edited trigger
+  code without an approved checkpoint cannot be closed. This checkpoint is the first contact point
+  of review, not a separate gate: the final judgement covers only deltas not yet reviewed and the
+  drift check, so a scope Main approved here is never re-explained from scratch at the end.
+  `mainLane.workerReview.steeringCheckpoint` (with `composition` and `finalScope`) and
+  `routing.high-risk.mainIntervention.preEditContract` are authoritative.
+- Report `validation` as an acceptance-condition map, not only a per-file or per-command result:
+  for each acceptance condition in the brief give `met` with the observed behavior and the raw
+  log or screen evidence locator, or `unverified` with the blocker and the check still needed,
+  plus the revision it covers. Point at evidence that already exists; never re-copy the same log,
+  rerun a check that already passed, or invent a new report format.
+  `routing.reviewPacket.acceptanceEvidenceMap` is authoritative.
+- Leave your own record in the project's existing `doc/history/YYYY/MM/DD-주제/maker-<name>.md`: what you
+  changed, the validation commands with cwd and exit codes, shareable evidence locators, and what stays
+  unverified. Start it, right after the title, with the search header the map greps for:
+  `RECORD:` / `DATE:` / `SCOPE:` (topic keywords) / `PATHS:` (the paths this record covers) / `STATUS:`
+  (`accepted` | `pending-user-device-check` | `partial` | `superseded-by <path>`). The header is a
+  lookup key, not the report — the body still carries the judgement, evidence, and open boundaries.
+  If a project has another documented root, follow that project's map instead of inventing
+  a new one. Main puts that record and its `evidence/` path inside `OWNED_PATHS` at dispatch, so write
+  only your own file — never Main's `main.md`, never another Maker's record, and never the shared
+  `doc/README.md` map unless Main explicitly assigns it to you. Main or one designated owner updates
+  that shared map; report only the necessary link target (path, topic, revision). Put long diffs and logs in that work folder's
+  `evidence/` and link them instead of pasting them, and keep secrets, raw conversation text, and auth
+  databases out.
+  When you need prior context, look it up in the fixed order — `HANDOFF.md`, then the `doc/README.md`
+  map, then a `grep` over record headers (`SCOPE`/`PATHS`) newest first, then only the matched
+  sections by line range. Nothing indexes or embeds these files, and `doc/history` is not long-term
+  memory. Use the locators Main already put in the brief before searching again, and do not add a
+  judge call, index, or wiki for document lookup.
+  `agent/AGENTS.md` 「프로젝트 문서 지도와 기록」 is authoritative.
+- Verify web surfaces in HEADLESS Chromium (`app.relay: false`). Localhost, isolated verification
+  servers, and build output all qualify — that is nearly every check you run. `browser.relay: true`
+  is the profile default, so OMITTING `app.relay: false` opens a tab in the USER'S OWN browser; a
+  maker once exposed a server whose every stylesheet failed to parse and the user stared at the
+  build error. Never put a broken intermediate state on the user's screen. Use the user's browser
+  only when their live session is genuinely required, or when Main tells you to hand a FINISHED
+  surface over for judgement — do not open it on your own initiative.
+- Run surface checks in the environment Main provides. Creating a new common isolation environment
+  or running a full build is Main's by default; do it yourself only when Main explicitly delegated
+  that run to you in the brief. When you do launch a server (delegated, or no environment exists
+  and your slice needs one), start it from the project's own `package.json` script, changing only
+  the port. Hand-reassembling the command drops bundler or runtime flags and breaks the whole
+  dependency graph. When an existing environment already reflects your revision, confirm its
+  revision, input, and config and reuse it instead of starting a new server — an old operational
+  screen is never verification of the changed revision, and shared output, port, or database
+  conflicts must not be created. If a new server is genuinely needed and the dev pipeline cannot
+  serve the tree, use the supported production path. A `ready` process and an HTTP 200 are NOT
+  screen verification: a process can report `ready` while every stylesheet fails to parse. Only a
+  rendered page and a clean console count as evidence.
+- Some verification only a human can do. Do not imitate it: build the runnable state and own
+  everything text-observable (console errors, DOM presence, HTTP status, exit codes), then hand the
+  judgement over. When the user can see the same surface directly - a relay work page in the user's
+  own browser - the user's own observation is preferred for aesthetics or layout feel, real
+  equipment behaviour, and login or permission gated external connections; screenshot it yourself
+  only when the user is absent or the check must be repeated as a regression. Hand over in at most
+  three lines: what to open, what order to click, the pass criterion. Never idle waiting for the
+  user - continue other allowed work and carry the item as pending, and report unverified items as
+  pending user observation, never as passed.
+  `implementationOwnership.writerValidation.userObservation` is authoritative.
+- Real equipment, real IO, or real production data: finish all code, build, and text-observable
+  validation first, then submit the handoff packet - what to power on, in what order, what appears
+  when correct, what means stop immediately (safety), and how to revert. Report the item with
+  `state: pending-user-device-check`, explicitly not passed. The user's observation is ground truth
+  and closes it, never re-verified by you; a failure report comes back as a finding on the owning
+  slice, never a fresh investigation. Never live-promote a trigger-code change before that check.
+  `implementationOwnership.writerValidation.deviceVerificationHandoff` is authoritative.
+- Treat edits that must preserve an existing CP949/BOM encoding as HIGH-RISK compatibility
+  work. The brief must assign that risk explicitly, and your report must include byte/decoding
+  evidence for Main's review.
+- Legacy sources (`.vb`, `.frm`, `.bas`, `.cfg`, `.csv`, `.resx`): determine the encoding from
+  evidence before editing — the BOM (`EF BB BF` means UTF-8), the file's and project's existing
+  convention, the reader contract in the consuming code, and a strict decode/re-encode round
+  trip. No BOM does not by itself mean CP949, since BOM-less UTF-8 exists and ASCII-only or
+  otherwise ambiguous bytes decode cleanly under several encodings. Write the file back in the
+  encoding you established, preserving the BOM state and line endings, and never convert
+  encodings or reflow untouched regions. Configuration files the program reads with
+  `Encoding.Default` stay CP949. If the evidence stays ambiguous and the choice creates a real
+  compatibility risk, stop and report instead of guessing.
+- Material risk is a consequence, never a technology name. It is only: an irreversible change to
+  data, schema or configuration (loss, corruption, destructive migration, deletion), a result that
+  leaves the system (deployment, payment, a real device or output, an outbound transmission),
+  a computation, verdict, threshold or calibration coefficient that defines product meaning, a
+  compatibility break for existing consumers, data, configuration or an API contract, and physical
+  safety interlocks or outputs. Read-only PLC access, monitoring, display, logging, packet parsing,
+  address translation, ordinary protocol handling, timeout, retry, reconnect, and simple write
+  forwarding that decides nothing are not material risk by technology alone: state the real
+  consequence instead.
+- VB6, COM/OCX, 32-bit, and Windows XP targets do not raise material risk on their own; their
+  compatibility and the CP949/BOM protection above stay required. Authentication, authorization,
+  and secret changes are `integration-risk` review, not repository material risk: the
+  `trust-boundary` class attaches the watch only.
+- The nature of the edited code classifies the work, not the runtime it happens to run in. That
+  classification is domain neutral: `irreversible-state-change`, `external-side-effect`,
+  `correctness-defines-product-meaning`, `state-machine-transition`, `trust-boundary`,
+  `compatibility-break`, and `artifact-representation` are HIGH-RISK even when the target is a
+  fixture, a mock, or an eval case. A fake target never lowers the class, and a real project never
+  raises a change that triggers none of them. A project repository's `AGENTS.md` maps this
+  classification onto that domain's concrete list, and a domain list is never copied into this
+  global file (`materialRiskDefinition.projectOverlay`). Scale is a separate axis: a small
+  single-owner change is an argument for routine, never a high-risk waiver, and a large consequence
+  is never a grade raise. When several modes apply, high-risk wins. See
+  `routing.high-risk.materialRiskDefinition.codeNatureTriggers`.
+- `agent/rules/harness-policy.json` `routing.high-risk.materialRiskDefinition` is the single
+  authoritative definition shared with Main and the eval expectations. When the
+  brief does not assign the applicable consequence and approval, stop and report instead of
+  reclassifying the work yourself.
+- Your session may not be resumable: an isolated run is merged or captured and torn down when it
+  ends. When Main routes a rework you cannot continue in this session, the new spawn carries the
+  cause, the existing diff or artifact locator, the unresolved findings with their ids and
+  acceptance, and the current validation state - never assume this session resumes and never redo
+  completed work.
+- Main may take over a small, settled correction whose cause and fix review already decided and
+  whose contract does not change, including document wording, state, and links, without waiting
+  for repeated failures; that takeover is the explicit-ownership path in
+  `implementationOwnership.reworkRouting.mainTakeover`, never a blanket handoff. When asked to hand
+  off, stop writing that scope and return the frozen delta, active jobs, valid evidence, and
+  remaining work, and let Main name the ownership change; never edit concurrently.
+- Assignment in a brief never substitutes for explicit user approval. Before any destructive,
+  external, costly, or compatibility-breaking action, stop and report unless the user has
+  explicitly approved that action for the current task.
+- NEVER commit, push, or run destructive commands (`rm -rf`, branch/tag deletion,
+  `git reset --hard`, database writes). Report what you changed and let the caller commit.
+- If a git command fails on `index.lock` or a worktree lock, never delete the lock file —
+  another agent may be working in the same repository. Re-analyze, wait briefly, and retry at
+  most once; if the identical lock failure appears a second time, stop and report it to Main.
+- You have **no verdict authority**. Never report `PASS`/`FAIL` on someone else's work; report
+  facts and let the caller judge.

package/Tools/OMP_Global_Config/agent/sop/maker.md

@@ -0,0 +1,9 @@
+---
+name: maker
+description: Delegated end-to-end implementation agent that investigates, edits, repairs, validates its own slice, and verifies the actual surface it changed.
+model: "@implSol"
+tools: [read, bash, edit, write, grep, glob, lsp, eval, generate_image, ast_grep, ast_edit, debug, todo, web_search, checkpoint]
+---
+
+You are the delegated implementation Maker on the default `modelRoles.implSol` slot. A delegated slice
+is yours end to end.

package/Tools/OMP_Global_Config/agent/tools/git-finalizer/finalizer.ps1

@@ -0,0 +1,340 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Request
+)
+
+$ErrorActionPreference = 'Stop'
+try {
+    [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+    $OutputEncoding = [Console]::OutputEncoding
+} catch {}
+$env:GIT_TERMINAL_PROMPT = '0'
+
+$stage = 'request'
+$createdCommit = $null
+$repoRoot = $null
+$repoPaths = @()
+$stagedByFinalizer = $false
+$mutex = $null
+$ownsMutex = $false
+$messageFile = $null
+$result = $null
+$exitCode = 0
+
+function Invoke-Git {
+    param(
+        [Parameter(Mandatory = $true)][string]$WorkingDirectory,
+        [Parameter(Mandatory = $true)][string[]]$GitArgs,
+        [int[]]$AllowedExitCodes = @(0)
+    )
+
+    $previousErrorActionPreference = $ErrorActionPreference
+    $ErrorActionPreference = 'Continue'
+    try {
+        $output = @(& git -c credential.interactive=false -C $WorkingDirectory @GitArgs 2>&1)
+        $code = $LASTEXITCODE
+    } finally {
+        $ErrorActionPreference = $previousErrorActionPreference
+    }
+    $text = ($output | Out-String).Trim()
+    if ($AllowedExitCodes -notcontains $code) {
+        if (-not $text) { $text = "git exited with code $code" }
+        throw $text
+    }
+    return [pscustomobject]@{ Code = $code; Output = $text }
+}
+
+function Get-Sha256Hex([string]$Text) {
+    $sha = [Security.Cryptography.SHA256]::Create()
+    try {
+        $bytes = [Text.Encoding]::UTF8.GetBytes($Text)
+        return ([BitConverter]::ToString($sha.ComputeHash($bytes))).Replace('-', '').ToLowerInvariant()
+    } finally {
+        $sha.Dispose()
+    }
+}
+
+function Normalize-FullPath([string]$Path) {
+    $fullPath = [IO.Path]::GetFullPath($Path)
+    $pathRoot = [IO.Path]::GetPathRoot($fullPath)
+    if ($fullPath.Equals($pathRoot, [StringComparison]::OrdinalIgnoreCase)) { return $pathRoot }
+    return $fullPath.TrimEnd([IO.Path]::DirectorySeparatorChar, [IO.Path]::AltDirectorySeparatorChar)
+}
+
+function Test-PathWithin([string]$Path, [string]$Root) {
+    if ($Path.Equals($Root, [StringComparison]::OrdinalIgnoreCase)) { return $true }
+    $prefix = $Root
+    if (
+        -not $prefix.EndsWith([IO.Path]::DirectorySeparatorChar) -and
+        -not $prefix.EndsWith([IO.Path]::AltDirectorySeparatorChar)
+    ) {
+        $prefix += [IO.Path]::DirectorySeparatorChar
+    }
+    return $Path.StartsWith($prefix, [StringComparison]::OrdinalIgnoreCase)
+}
+
+function Get-NearestExistingDirectory([string]$Path) {
+    $candidate = [IO.Path]::GetDirectoryName($Path)
+    while ($candidate -and -not (Test-Path -LiteralPath $candidate -PathType Container)) {
+        $candidate = [IO.Path]::GetDirectoryName($candidate)
+    }
+    if (-not $candidate) { throw "No existing parent directory found for file path: $Path" }
+    return Normalize-FullPath $candidate
+}
+
+function Get-RepositoryRootInPathNamespace([string]$WorkingDirectory) {
+    [void](Invoke-Git -WorkingDirectory $WorkingDirectory -GitArgs @('rev-parse', '--show-toplevel'))
+    $prefix = (Invoke-Git -WorkingDirectory $WorkingDirectory -GitArgs @('rev-parse', '--show-prefix')).Output.Trim('/')
+    $root = Normalize-FullPath $WorkingDirectory
+    if ($prefix) {
+        foreach ($segment in ($prefix -split '/' | Where-Object { $_ })) {
+            $root = [IO.Path]::GetDirectoryName($root)
+            if (-not $root) { throw "Could not reconstruct repository root from prefix: $prefix" }
+        }
+    }
+    return Normalize-FullPath $root
+}
+
+function Convert-ToRepoPath([string]$FullPath, [string]$Root) {
+    if ($FullPath.Equals($Root, [StringComparison]::OrdinalIgnoreCase)) { return '' }
+    return $FullPath.Substring($Root.Length).TrimStart('\', '/').Replace('\', '/')
+}
+
+function Get-GitPaths([string]$WorkingDirectory, [string[]]$GitArgs) {
+    $response = Invoke-Git -WorkingDirectory $WorkingDirectory -GitArgs $GitArgs
+    if (-not $response.Output) { return @() }
+    return @($response.Output -split "`r?`n" | ForEach-Object { $_.Trim().Replace('\', '/') } | Where-Object { $_ })
+}
+
+function Assert-ExactPathSet([string[]]$Actual, [string[]]$Expected, [string]$Label) {
+    $actualSet = [Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase)
+    $expectedSet = [Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase)
+    foreach ($path in $Actual) { [void]$actualSet.Add($path) }
+    foreach ($path in $Expected) { [void]$expectedSet.Add($path) }
+    if (-not $actualSet.SetEquals($expectedSet)) {
+        throw "$Label mismatch. expected=[$($Expected -join ', ')] actual=[$($Actual -join ', ')]"
+    }
+}
+
+try {
+    if (-not (Test-Path -LiteralPath $Request -PathType Leaf)) { throw "Request file not found: $Request" }
+    $payload = Get-Content -LiteralPath $Request -Raw -Encoding UTF8 | ConvertFrom-Json
+    $cwd = Normalize-FullPath ([string]$payload.cwd)
+    $message = ([string]$payload.message).Trim()
+    $inputFiles = @($payload.files | ForEach-Object { ([string]$_).Trim() } | Where-Object { $_ })
+    if (-not (Test-Path -LiteralPath $cwd -PathType Container)) { throw "Session cwd does not exist: $cwd" }
+    if (-not $message) { throw 'Commit message is empty.' }
+    if ($inputFiles.Count -eq 0) { throw 'At least one exact file path is required.' }
+
+    $stage = 'repository'
+    $resolvedFiles = @()
+    $seenFullPaths = [Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase)
+    foreach ($inputFile in $inputFiles) {
+        if ($inputFile.IndexOfAny(@([char]0, [char]10, [char]13)) -ge 0) { throw 'File paths cannot contain NUL or newlines.' }
+        if ([IO.Path]::IsPathRooted($inputFile)) { throw "Absolute file path is not allowed: $inputFile" }
+        $fullPath = Normalize-FullPath (Join-Path $cwd $inputFile)
+        if (Test-Path -LiteralPath $fullPath -PathType Container) { throw "Directories are not allowed; list exact files: $inputFile" }
+        if (-not $seenFullPaths.Add($fullPath)) { throw "Duplicate file path: $inputFile" }
+        $resolvedFiles += [pscustomobject]@{ Input = $inputFile; FullPath = $fullPath }
+    }
+
+    $cwdRepoRoot = $null
+    $cwdCommonDir = $null
+    try {
+        $cwdRepoRoot = Get-RepositoryRootInPathNamespace $cwd
+        $cwdCommonDir = Normalize-FullPath (Invoke-Git -WorkingDirectory $cwdRepoRoot -GitArgs @('rev-parse', '--path-format=absolute', '--git-common-dir')).Output
+    } catch {
+        $cwdRepoRoot = $null
+        $cwdCommonDir = $null
+    }
+
+    $selectedRepoRoot = $null
+    $selectedCommonDir = $null
+    foreach ($file in $resolvedFiles) {
+
+        $probeDirectory = Get-NearestExistingDirectory $file.FullPath
+        $targetRepoRoot = Get-RepositoryRootInPathNamespace $probeDirectory
+        $targetCommonDir = Normalize-FullPath (Invoke-Git -WorkingDirectory $targetRepoRoot -GitArgs @('rev-parse', '--path-format=absolute', '--git-common-dir')).Output
+        if (-not (Test-PathWithin -Path $file.FullPath -Root $targetRepoRoot)) {
+            throw "File path escapes the repository: $($file.Input)"
+        }
+
+        if (-not $selectedRepoRoot) {
+            $selectedRepoRoot = $targetRepoRoot
+            $selectedCommonDir = $targetCommonDir
+        } elseif (
+            -not $selectedRepoRoot.Equals($targetRepoRoot, [StringComparison]::OrdinalIgnoreCase) -or
+            -not $selectedCommonDir.Equals($targetCommonDir, [StringComparison]::OrdinalIgnoreCase)
+        ) {
+            throw "Files belong to different repositories: $($file.Input)"
+        }
+    }
+
+    $repoRoot = $selectedRepoRoot
+    $commonDir = $selectedCommonDir
+    if ($cwdRepoRoot) {
+        $targetsBelongToCwdRepository = $commonDir.Equals($cwdCommonDir, [StringComparison]::OrdinalIgnoreCase)
+        if ($targetsBelongToCwdRepository) {
+            foreach ($file in $resolvedFiles) {
+                $parentPath = [IO.Path]::GetDirectoryName($file.FullPath)
+                $isDirectRepoRootChild = $parentPath -and $parentPath.Equals($cwdRepoRoot, [StringComparison]::OrdinalIgnoreCase)
+                if (-not (Test-PathWithin -Path $file.FullPath -Root $cwd) -and -not $isDirectRepoRootChild) {
+                    throw "File path escapes the session cwd: $($file.Input)"
+                }
+            }
+        }
+    } else {
+        foreach ($file in $resolvedFiles) {
+            if (-not (Test-PathWithin -Path $file.FullPath -Root $cwd)) {
+                throw "File path escapes the session cwd: $($file.Input)"
+            }
+        }
+        if (-not (Test-PathWithin -Path $repoRoot -Root $cwd)) {
+            throw "Discovered repository escapes the session cwd: $repoRoot"
+        }
+    }
+
+    $seen = [Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase)
+    foreach ($file in $resolvedFiles) {
+        $repoPath = Convert-ToRepoPath -FullPath $file.FullPath -Root $repoRoot
+        if (-not $repoPath -or $repoPath -eq '.git' -or $repoPath.StartsWith('.git/', [StringComparison]::OrdinalIgnoreCase)) {
+            throw "Repository metadata or broad paths are not allowed: $($file.Input)"
+        }
+        if (-not $seen.Add($repoPath)) { throw "Duplicate file path: $($file.Input)" }
+        $repoPaths += $repoPath
+    }
+
+    $stage = 'remote'
+    $branch = (Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('rev-parse', '--abbrev-ref', 'HEAD')).Output
+    if (-not $branch -or $branch -eq 'HEAD') { throw 'Detached HEAD is not supported.' }
+    $configuredRemote = (Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('config', '--get', "branch.$branch.remote") -AllowedExitCodes @(0, 1)).Output
+    $configuredUpstreamRef = (Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('config', '--get', "branch.$branch.merge") -AllowedExitCodes @(0, 1)).Output
+    $configuredRemotes = @((Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('remote')).Output -split "`r?`n" | ForEach-Object { $_.Trim() } | Where-Object { $_ })
+    if ($configuredRemote) {
+        if ($configuredRemote -eq '.') { throw "Branch '$branch' tracks the local repository and has no pushable remote." }
+        if ($configuredRemotes -cnotcontains $configuredRemote) {
+            throw "Branch '$branch' is configured to push to '$configuredRemote', which is not a configured remote."
+        }
+        $remote = $configuredRemote
+    } elseif ($configuredRemotes.Count -eq 0) {
+        throw "Branch '$branch' has no configured remote to push to."
+    } elseif ($configuredRemotes -ccontains 'origin') {
+        $remote = 'origin'
+    } elseif ($configuredRemotes.Count -eq 1) {
+        $remote = $configuredRemotes[0]
+    } else {
+        throw "Branch '$branch' has no tracked remote and the repository has multiple remotes: $($configuredRemotes -join ', ')"
+    }
+    if ($configuredUpstreamRef) {
+        if ($configuredUpstreamRef -notmatch '^refs/heads/.+') { throw "Unsupported upstream ref: $configuredUpstreamRef" }
+        $upstreamRef = $configuredUpstreamRef
+    } else {
+        $upstreamRef = "refs/heads/$branch"
+    }
+    $trackingConfigured = [bool]$configuredRemote -and [bool]$configuredUpstreamRef
+
+    $stage = 'lock'
+    $lockKey = Get-Sha256Hex ($commonDir.ToLowerInvariant() + [char]0 + $remote + [char]0 + $upstreamRef)
+    $mutexName = "Global\OMP-GitFinalize-$lockKey"
+    $mutex = [Threading.Mutex]::new($false, $mutexName)
+    try {
+        $ownsMutex = $mutex.WaitOne([TimeSpan]::FromSeconds(120))
+    } catch [Threading.AbandonedMutexException] {
+        $ownsMutex = $true
+    }
+    if (-not $ownsMutex) { throw "Timed out waiting for repository finalizer lock: $mutexName" }
+
+    $stage = 'locked-preflight'
+    $lockedCommonDir = Normalize-FullPath (Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('rev-parse', '--path-format=absolute', '--git-common-dir')).Output
+    $lockedBranch = (Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('rev-parse', '--abbrev-ref', 'HEAD')).Output
+    if (-not $lockedCommonDir.Equals($commonDir, [StringComparison]::OrdinalIgnoreCase) -or $lockedBranch -ne $branch) {
+        throw 'Repository or branch changed while acquiring the finalizer lock.'
+    }
+
+    $stage = 'remote-probe'
+    $probe = Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('ls-remote', '--exit-code', '--refs', $remote, $upstreamRef) -AllowedExitCodes @(0, 2)
+    $upstreamExists = $probe.Code -eq 0
+
+    $stage = 'fetch'
+    $headSha = (Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('rev-parse', 'HEAD')).Output
+    $upstreamSha = $null
+    if ($upstreamExists) {
+        [void](Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('fetch', '--no-tags', $remote, $upstreamRef))
+        $upstreamSha = (Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('rev-parse', 'FETCH_HEAD')).Output
+        $ancestry = Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('merge-base', '--is-ancestor', $upstreamSha, $headSha) -AllowedExitCodes @(0, 1)
+        if ($ancestry.Code -ne 0) {
+            throw "HEAD is behind or diverged from the fetched upstream. HEAD=$headSha upstream=$upstreamSha"
+        }
+    }
+
+    $stage = 'index-preflight'
+    $indexState = Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('diff', '--cached', '--quiet', '--exit-code') -AllowedExitCodes @(0, 1)
+    if ($indexState.Code -ne 0) { throw 'The shared Git index already contains staged changes.' }
+
+    $stage = 'stage'
+    $stagedByFinalizer = $true
+    [void](Invoke-Git -WorkingDirectory $repoRoot -GitArgs (@('--literal-pathspecs', 'add', '-A', '--') + $repoPaths))
+    $cachedPaths = Get-GitPaths -WorkingDirectory $repoRoot -GitArgs @('-c', 'core.quotepath=false', 'diff', '--cached', '--no-renames', '--name-only')
+    Assert-ExactPathSet -Actual $cachedPaths -Expected $repoPaths -Label 'Staged path set'
+
+    $stage = 'commit'
+    $messageFile = [IO.Path]::GetTempFileName()
+    [IO.File]::WriteAllText($messageFile, $message + [Environment]::NewLine, [Text.UTF8Encoding]::new($false))
+    [void](Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('commit', '--file', $messageFile))
+    $createdCommit = (Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('rev-parse', 'HEAD')).Output
+    $stagedByFinalizer = $false
+
+    $stage = 'commit-verify'
+    $parentSha = (Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('rev-parse', "$createdCommit^" )).Output
+    if ($parentSha -ne $headSha) {
+        throw "Created commit parent does not match the captured HEAD. parent=$parentSha head=$headSha"
+    }
+    $committedPaths = Get-GitPaths -WorkingDirectory $repoRoot -GitArgs @('-c', 'core.quotepath=false', 'diff-tree', '--no-commit-id', '--no-renames', '--name-only', '-r', $createdCommit)
+    Assert-ExactPathSet -Actual $committedPaths -Expected $repoPaths -Label 'Committed path set'
+
+    $stage = 'push'
+    [void](Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('push', $remote, "${createdCommit}:${upstreamRef}"))
+
+    $stage = 'remote-verify'
+    $remoteLine = (Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('ls-remote', '--refs', $remote, $upstreamRef)).Output
+    $remoteSha = (($remoteLine -split '\s+')[0]).Trim()
+    if ($remoteSha -ne $createdCommit) {
+        throw "Remote ref verification failed. expected=$createdCommit actual=$remoteSha"
+    }
+
+    if (-not $trackingConfigured) {
+        $stage = 'tracking'
+        [void](Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('config', "branch.$branch.remote", $remote))
+        [void](Invoke-Git -WorkingDirectory $repoRoot -GitArgs @('config', "branch.$branch.merge", $upstreamRef))
+    }
+
+    $stage = 'complete'
+    $result = [ordered]@{
+        ok = $true
+        stage = $stage
+        commitSha = $createdCommit
+        remote = $remote
+        upstreamRef = $upstreamRef
+    }
+} catch {
+    $exitCode = 1
+    $result = [ordered]@{
+        ok = $false
+        stage = $stage
+        error = $_.Exception.Message
+        commitSha = $createdCommit
+    }
+} finally {
+    if ($stagedByFinalizer -and $repoRoot -and $repoPaths.Count -gt 0) {
+        try { [void](Invoke-Git -WorkingDirectory $repoRoot -GitArgs (@('--literal-pathspecs', 'restore', '--staged', '--') + $repoPaths)) } catch {}
+    }
+    if ($messageFile) { Remove-Item -LiteralPath $messageFile -Force -ErrorAction SilentlyContinue }
+    if ($ownsMutex -and $mutex) {
+        try { $mutex.ReleaseMutex() } catch {}
+    }
+    if ($mutex) { $mutex.Dispose() }
+}
+
+[Console]::Out.WriteLine(($result | ConvertTo-Json -Compress))
+exit $exitCode