/sap-sm12

name: sap-sm12
description: |
  Lists and safely releases SAP enqueue locks (transaction SM12) over RFC — no
  GUI. Two modes. `list` (read-only) dumps current lock entries via ENQUEUE_READ
  with a computed lock AGE and a best-effort owner-liveness column, filterable by
  user / table / lock argument / client / age. `release` (destructive, gated)
  releases a stale lock ONLY after proving the owner has no session on ANY
  application server (a liveness gate that reads TH_SERVER_LIST + TH_USER_LIST,
  and TH_SYSTEMWIDE_USER_LIST on multi-instance systems), showing the lock
  evidence, requiring the operator to TYPE the owner's user name to confirm,
  deleting via ENQUE_DELETE, then re-reading to verify and writing an audit line.
  It hard-refuses whenever the owner is still live or liveness cannot be proven —
  there is no --force. Automates exactly the risky part of the daily "clear a
  stuck lock" op (the owner-death check operators get wrong on multi-instance
  systems), so it is safer than the manual SM12 path, not just faster.
  Use for: stuck / stale enqueue lock, "lock entry held by", release SM12 lock,
  delete lock entry, "object is locked by user", SM12.
  Prerequisites: an RFC-capable connection profile (/sap-login). `release` also
  needs the generic wrapper Z_GENERIC_RFC_WRAPPER_TBL (deploy via /sap-dev-init)
  for the ENQUE_DELETE call and the multi-instance liveness leg; `list` does not.
argument-hint: "<mode> ...   list [--user=U] [--table=T] [--arg=<GARG pattern>] [--client=C | --all-clients] [--older-than=30m|2h|1d] [--max=N] [--save-output=PATH]   |   release --user=U [--table=T] [--arg=<GARG pattern>] [--client=C]"

SAP SM12 — Enqueue Lock List & Safe Release

You list SAP enqueue locks and — only through a liveness gate + typed confirmation — release a stale one, entirely over RFC (SAP NCo 3.1, 32-bit PowerShell). There is **no GUI automation** in this skill: if RFC is unavailable you fail loud with the manual SM12 path, never a half-automated GUI delete.

Task: $ARGUMENTS

The live enqueue table is memory-resident: it is read with `ENQUEUE_READ` and mutated with `ENQUE_DELETE` (SAP's own enqueue APIs) — **never** with `RFC_READ_TABLE` / SQL on `SEQG3` (Rule 1).

---

Shared Resources

| File | Token | Purpose | |---|---|---| | `<SAP_DEV_CORE_SHARED_DIR>/rules/safety_policy.md` | *(rule)* | **Rule 0 (highest priority)** — environment guard; enforced by Step 0.6 via `sap_safety_gate.ps1` | | `<SAP_DEV_CORE_SHARED_DIR>/rules/skill_operating_rules.md` | *(rule)* | Mandatory operating rules (no SQL writes; no unsolicited deploy; confirm gates) | | `<SAP_DEV_CORE_SHARED_DIR>/rules/error_classes.md` | *(rule)* | `error_class` taxonomy (this skill's `LOCK_*` classes live here) | | `<SKILL_DIR>/references/sap_sm12_lib.ps1` | `%%SM12_LIB_PS1%%` | Shared helpers: generic FM-table reader, lock-age math, server-clock | | `<SKILL_DIR>/references/sap_sm12_list.ps1` | *(reader)* | `list` mode + release-mode re-reader / `-ExpectGone` verifier (ENQUEUE_READ) | | `<SKILL_DIR>/references/sap_sm12_liveness.ps1` | *(gate)* | Owner-liveness verdict (TH_SERVER_LIST + TH_USER_LIST, `-MergeUserList` leg) | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_rfc_lib.ps1` | `%%RFC_LIB_PS1%%` | NCo connect/disconnect; fills `%%SAP_*%%` from the pinned profile | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_artifact_lib.ps1` | `%%ARTIFACT_LIB_PS1%%` | Register `list`/`release` outputs for /sap-evidence-pack | | `/sap-rfc-wrapper` (skill) | — | `release` delegates the ENQUE_DELETE and TH_SYSTEMWIDE_USER_LIST calls here (both FMs are not remote-enabled) | | `/sap-dev-init` (skill) | — | Deploys `Z_GENERIC_RFC_WRAPPER_TBL` (release prerequisite) — suggest, never auto-run |

This skill drives no SAP GUI, so it has no VBS, no golden-screen baseline, no session lock and no GUI-Security sidecar.

---

Step 0 — Resolve Work Directory

Resolve `work_dir` (and `log_dir` for the audit trail) via the env-aware helper — do NOT read `settings.json` directly:

powershell -NoProfile -ExecutionPolicy Bypass -Command ". '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_settings_lib.ps1'; . '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'; Write-Output ('WORK_DIR=' + (Get-SapWorkDir)); Write-Output ('LOG_DIR=' + (Get-SapSettingValue 'log_dir' ((Get-SapWorkDir) + '\logs')))"

Set `{WORK_TEMP}` = `{work_dir}\temp` (create if missing) and `{RUN_TEMP}` = `Get-SapRunTemp` (per-run scratch — all generated `*_run.ps1` go here):

powershell -NoProfile -ExecutionPolicy Bypass -Command ". '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'; Write-Output ('RUN_TEMP=' + (Get-SapRunTemp))"

---

Step 0.5 — Start Logging

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_sm12_run.json" -Skill sap-sm12 -ParamsJson "{\"mode\":\"<MODE>\"}"

State file `{RUN_TEMP}\sap_sm12_run.json`. Best-effort.

---

Step 0.6 — Safety Gate (Rule 0 — `safety_policy.md`)

The `release` mode mutates runtime state (deletes an enqueue lock) and runs the environment gate first; `list` is read-only and skips it. The owner-liveness gate and typed owner-name confirmation below still apply after ALLOW/ALLOW_CONFIRMED:

powershell -NoProfile -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_safety_gate.ps1" -Action assert -Skill sap-sm12

| Verdict (last line) | Exit | Action | |---|---|---| | `SAFETY: ALLOW ...` | 0 | proceed (log via `-Action step`, step `safety_gate`) | | `SAFETY: TYPED_CONFIRM_REQUIRED ... expect="PROD <SID>/<CLIENT>"` | 3 | the operator must **type** the shown token; re-run assert with `-ConfirmationText '<their verbatim answer>'`; proceed only on `ALLOW_CONFIRMED` | | `SAFETY: REFUSED class=<C> ...` | 1 | **STOP.** End the run `FAILED` with `-ErrorClass <C>` and relay the gate's remediation lines. Never bypass, soften, retry, or drive the transaction manually instead — Ru