net-snmp 3.26.3 → 3.28.0

package/README.md

@@ -351,6 +351,7 @@ Actions
 - `11 -  EUnexpectedReport`
 - `12 -  EResponseNotHandled`
 - `13 -  EUnexpectedResponse`
+- `14 -  ENotInTimeWindow`
 
 ## snmp.OidFormat
 - `oid - oid`
@@ -1555,7 +1556,11 @@ an object, possibly empty, and can contain the following fields:
 
 The `callback` parameter is a callback function of the form
 `function (error, notification)`.  On an error condition, the `notification`
-parameter is set to `null`.  On successful reception of a notification, the error
+parameter is set to `null`.  Where the error was produced while processing a
+received packet - such as an authorization failure for a community or user
+not in the receiver's local authorization lists - the error will include an
+`rinfo` attribute containing the sender socket details of the offending packet.
+On successful reception of a notification, the error
 parameter is set to `null`, and the `notification` parameter is set as an object
 with the notification PDU details in the `pdu` field and the sender socket details
 in the `rinfo` field.  For example:
@@ -1677,6 +1682,11 @@ an object, possibly empty, and can contain the following fields:
  * `mibOptions` - a MIB options object that is passed to the `Mib` instance - see the MIB section
  for further details on this - defaults to the empty object.
 
+As for the receiver, errors that the agent produces while processing a received
+packet - such as an authorization failure, or a request the agent cannot serve -
+include an `rinfo` attribute containing the sender socket details of the offending
+packet.
+
 The `mib` parameter is optional, and sets the agent's singleton `Mib` instance.
 If not supplied, the agent creates itself a new empty `Mib` singleton.  If supplied,
 the `Mib` instance needs to be created and populated as per the [Mib Module](#mib-module)
@@ -1723,7 +1733,9 @@ receiver's community authorization list, the receiver will not accept the notifi
 instead returning a error of class `RequestFailedError` to the supplied callback
 function.  Similarly, if a v3 notification is received with a user whose name is
 not in the receiver's user authorization list, the receiver will return a
-`RequestFailedError`.  If the `disableAuthorization` option is supplied for the
+`RequestFailedError`.  These errors include an `rinfo` attribute containing the
+sender socket details of the unauthorized packet, so that its origin can be
+identified.  If the `disableAuthorization` option is supplied for the
 receiver on start-up, then these local authorization list checks are disabled for
 community notifications and noAuthNoPriv user notifications.  Note that even with
 this setting, the user list is *still checked* for authNoPriv and authPriv notifications,
@@ -3755,6 +3767,18 @@ Example programs are included under the module's `example` directory.
 
  * Document how MIB scalar and table handlers should interact with `mibRequest.instanceNode.value` for Get vs Set operations
 
+# Version 3.27.0 - 11/09/2026
+
+ * Fix SNMPv3 requests being rejected with `usmStatsNotInTimeWindows` once a session has been open for a while - the authoritative engine time is now advanced with a monotonic local clock and resynchronised from every authenticated response, instead of staying frozen at the value learned during discovery
+
+ * Discard SNMPv3 responses that fall outside the USM time window, reported as the new `ResponseInvalidCode.ENotInTimeWindow`
+
+# Version 3.28.0 - 11/09/2026
+
+ * Add an `rinfo` attribute to errors that a receiver or agent produces while processing a received packet - covering unknown community and unknown user authorization failures, authentication and privacy level mismatches, digest and decryption failures, and unsupported PDU type rejections - so the sender of an offending packet can be identified
+
+ * Replace `.npmignore` with a `files` allowlist in `package.json`, so the published package ships only the module, its libraries, examples and reference files
+
 # License
 
 Copyright (c) 2020 Mark Abrahams <mark@abrahams.co.nz>

package/index.js

@@ -9,10 +9,13 @@ const util = require ("util");
 const crypto = require ("crypto");
 const mibparser = require ("./lib/mib");
 const Buffer = require('buffer').Buffer;
+const { performance } = require ("perf_hooks");
 
 var DEBUG = false;
 var STRICT_INT_RANGE_CHECKS = false;
 
+const USM_TIME_WINDOW_SECONDS = 150;
+
 const MIN_SIGNED_INT32 = -2147483648;
 const MAX_SIGNED_INT32 = 2147483647;
 const MIN_UNSIGNED_INT32 = 0;
@@ -280,7 +283,8 @@ var ResponseInvalidCode = {
 	10: "ECommunityNoMatch",
 	11: "EUnexpectedReport",
 	12: "EResponseNotHandled",
-	13: "EUnexpectedResponse"
+	13: "EUnexpectedResponse",
+	14: "ENotInTimeWindow"
 };
 
 _expandConstantObject (ResponseInvalidCode);
@@ -2084,6 +2088,18 @@ var Session = function (target, authenticator, options) {
 	this.reqs = {};
 	this.reqCount = 0;
 
+	// Local notion of the authoritative (remote) engine's snmpEngineBoots and
+	// snmpEngineTime, per RFC 3414 section 2.3.  engineTimeBase is the
+	// snmpEngineTime learned at engineTimeReceivedAt (a monotonic millisecond
+	// reading), and the current notion is derived from the two by
+	// getEngineTime().  latestReceivedEngineTime is the highest snmpEngineTime
+	// ever received from the authoritative engine, and exists solely to stop a
+	// replayed message from holding our notion of time back.
+	this.engineTimeBoots = null;
+	this.engineTimeBase = null;
+	this.engineTimeReceivedAt = null;
+	this.latestReceivedEngineTime = null;
+
 	const dgramMod = options.dgramModule || dgram;
 	this.dgram = dgramMod.createSocket (this.transport);
 	this.dgram.unref();
@@ -2425,6 +2441,21 @@ Session.prototype.onMsg = function (buffer) {
 	if ( ! message.processIncomingSecurity (this.user, req.responseCb) )
 		return;
 
+	// RFC 3414 sections 2.3 and 3.2 step 7b: synchronise our notion of the
+	// authoritative engine's time from this message, then discard the message if
+	// it falls outside the time window.  Both are no-ops for SNMPv1 and v2c, and
+	// for v3 messages which were not authenticated.
+	this.setEngineTime (message);
+	if ( ! this.isInTimeWindow (message) ) {
+		req.responseCb (new ResponseInvalidError ("Message with engineBoots '"
+				+ message.msgSecurityParameters.msgAuthoritativeEngineBoots
+				+ "' and engineTime '" + message.msgSecurityParameters.msgAuthoritativeEngineTime
+				+ "' is outside the time window of engineBoots '" + this.engineTimeBoots
+				+ "' and engineTime '" + this.getEngineTime ().engineTime + "'",
+				ResponseInvalidCode.ENotInTimeWindow));
+		return;
+	}
+
 	if (message.version != req.message.version) {
 		req.responseCb (new ResponseInvalidError ("Version in request '"
 				+ req.message.version + "' does not match version in "
@@ -2974,7 +3005,93 @@ Session.prototype.walk  = function () {
 	return this;
 };
 
+// RFC 3414 section 2.3: between authentic messages, the non-authoritative
+// engine's notion of the authoritative engine's snmpEngineTime advances with
+// the local clock.  A monotonic clock source is used, so that a step of the
+// system clock cannot move our notion of time.  Returns null while no notion
+// has been established.
+Session.prototype.getEngineTime = function () {
+	if ( this.engineTimeReceivedAt == null )
+		return null;
+	var elapsedSeconds = Math.floor ((performance.now () - this.engineTimeReceivedAt) / 1000);
+	var engineBoots = this.engineTimeBoots;
+	var engineTime = this.engineTimeBase + elapsedSeconds;
+	// RFC 3414 section 2.2.2: when snmpEngineTime reaches its maximum value,
+	// snmpEngineBoots is incremented and snmpEngineTime is reset to zero.
+	// snmpEngineBoots latches at its maximum value and never wraps.
+	if ( engineTime > MAX_SIGNED_INT32 ) {
+		engineBoots = Math.min (engineBoots + Math.floor (engineTime / (MAX_SIGNED_INT32 + 1)),
+				MAX_SIGNED_INT32);
+		engineTime = engineTime % (MAX_SIGNED_INT32 + 1);
+	}
+	return {
+		engineBoots: engineBoots,
+		engineTime: engineTime
+	};
+};
+
+// RFC 3414 section 3.2 step 7b(1): update our notion of the authoritative
+// engine's time from an authentic message, but only when that message advances
+// it - either snmpEngineBoots has increased, or snmpEngineTime is higher than
+// any snmpEngineTime yet seen for the current snmpEngineBoots.  The latter
+// comparison is against the highest value received rather than against our
+// locally advanced notion, so that a fast local clock cannot lock the session
+// out of ever resynchronising.
+Session.prototype.setEngineTime = function (message) {
+	var params = message.msgSecurityParameters;
+	if ( ! params || ! message.hasAuthentication () )
+		return;
+	var engineBoots = params.msgAuthoritativeEngineBoots;
+	var engineTime = params.msgAuthoritativeEngineTime;
+	var advances = this.engineTimeBoots == null
+			|| engineBoots > this.engineTimeBoots
+			|| ( engineBoots == this.engineTimeBoots
+				&& engineTime > this.latestReceivedEngineTime );
+	if ( ! advances )
+		return;
+	this.engineTimeBoots = engineBoots;
+	this.engineTimeBase = engineTime;
+	this.latestReceivedEngineTime = engineTime;
+	this.engineTimeReceivedAt = performance.now ();
+};
+
+// RFC 3414 section 3.2 step 7b(2): an authentic message from the authoritative
+// engine is outside the time window - and so must be discarded - if our notion
+// of its snmpEngineBoots has latched at its maximum value, if the message
+// disagrees with our notion of snmpEngineBoots, or if it disagrees with our
+// notion of snmpEngineTime by more than the time window.  This must be
+// evaluated after setEngineTime (), so that a message which legitimately
+// advances our notion of time is never rejected by it.
+Session.prototype.isInTimeWindow = function (message) {
+	var params = message.msgSecurityParameters;
+	if ( ! params || ! message.hasAuthentication () )
+		return true;
+	var notion = this.getEngineTime ();
+	if ( ! notion )
+		return true;
+	if ( notion.engineBoots == MAX_SIGNED_INT32 )
+		return false;
+	if ( params.msgAuthoritativeEngineBoots != notion.engineBoots )
+		return false;
+	return Math.abs (params.msgAuthoritativeEngineTime - notion.engineTime)
+			<= USM_TIME_WINDOW_SECONDS;
+};
+
+// RFC 3414 section 2.3: an outgoing request carries our current notion of the
+// authoritative engine's snmpEngineBoots and snmpEngineTime, not the values
+// learned when the session was first synchronised.
+Session.prototype.advanceEngineTime = function () {
+	if ( ! this.msgSecurityParameters )
+		return;
+	var notion = this.getEngineTime ();
+	if ( ! notion )
+		return;
+	this.msgSecurityParameters.msgAuthoritativeEngineBoots = notion.engineBoots;
+	this.msgSecurityParameters.msgAuthoritativeEngineTime = notion.engineTime;
+};
+
 Session.prototype.sendV3Req = function (pdu, feedCb, responseCb, options, port, allowReport) {
+	this.advanceEngineTime ();
 	var message = Message.createRequestV3 (this.user, this.msgSecurityParameters, pdu);
 	var reqOptions = options || {};
 	var req = new Req (this, message, feedCb, responseCb, reqOptions);
@@ -3141,6 +3258,17 @@ Listener.formatCallbackData = function (pdu, rinfo) {
 	};
 };
 
+// Returns a callback that annotates errors with the origin of the packet being
+// processed, so consumers can identify the source of unauthorized or invalid messages
+Listener.rinfoErrorCallback = function (target, rinfo) {
+	return function (error, data) {
+		if ( error && rinfo && ! error.rinfo ) {
+			error.rinfo = rinfo;
+		}
+		target.callback (error, data);
+	};
+};
+
 Listener.processIncoming = function (buffer, authorizer, callback) {
 	var message = Message.createFromBuffer (buffer);
 	var community;
@@ -3447,12 +3575,13 @@ Receiver.prototype.getAuthorizer = function () {
 
 Receiver.prototype.onMsg = function (socket, buffer, rinfo) {
 
+	const callback = Listener.rinfoErrorCallback (this, rinfo);
 	let message;
 
 	try {
-		message = Listener.processIncoming (buffer, this.authorizer, this.callback);
+		message = Listener.processIncoming (buffer, this.authorizer, callback);
 	} catch (error) {
-		this.callback (new ProcessingError ("Failure to process incoming message", error, rinfo, buffer));
+		callback (new ProcessingError ("Failure to process incoming message", error, rinfo, buffer));
 		return;
 	}
 
@@ -3469,13 +3598,13 @@ Receiver.prototype.onMsg = function (socket, buffer, rinfo) {
 	// The only GetRequest PDUs supported are those used for SNMPv3 discovery
 	if ( message.pdu.type == PduType.GetRequest ) {
 		if ( message.version != Version3 ) {
-			this.callback (new RequestInvalidError ("Only SNMPv3 discovery GetRequests are supported"));
+			callback (new RequestInvalidError ("Only SNMPv3 discovery GetRequests are supported"));
 			return;
 		} else if ( message.hasAuthentication() ) {
-			this.callback (new RequestInvalidError ("Only discovery (noAuthNoPriv) GetRequests are supported but this message has authentication"));
+			callback (new RequestInvalidError ("Only discovery (noAuthNoPriv) GetRequests are supported but this message has authentication"));
 			return;
 		} else if ( ! message.isReportable () ) {
-			this.callback (new RequestInvalidError ("Only discovery GetRequests are supported and this message does not have the reportable flag set"));
+			callback (new RequestInvalidError ("Only discovery GetRequests are supported and this message does not have the reportable flag set"));
 			return;
 		}
 		let reportMessage = message.createReportResponseMessage (this.engine, this.context, UsmErrorType.UNKNOWN_ENGINE_ID);
@@ -3486,16 +3615,16 @@ Receiver.prototype.onMsg = function (socket, buffer, rinfo) {
 	// Inform/trap processing
 	// debug (JSON.stringify (message.pdu, null, 2));
 	if ( message.pdu.type == PduType.Trap || message.pdu.type == PduType.TrapV2 ) {
-		this.callback (null, this.formatCallbackData (message, rinfo) );
+		callback (null, this.formatCallbackData (message, rinfo) );
 	} else if ( message.pdu.type == PduType.InformRequest ) {
 		message.pdu.type = PduType.GetResponse;
 		message.buffer = null;
 		message.setReportable (false);
 		this.listener.send (message, rinfo, socket);
 		message.pdu.type = PduType.InformRequest;
-		this.callback (null, this.formatCallbackData (message, rinfo) );
+		callback (null, this.formatCallbackData (message, rinfo) );
 	} else {
-		this.callback (new RequestInvalidError ("Unexpected PDU type " + message.pdu.type + " (" + PduType[message.pdu.type] + ")"));
+		callback (new RequestInvalidError ("Unexpected PDU type " + message.pdu.type + " (" + PduType[message.pdu.type] + ")"));
 	}
 };
 
@@ -5043,12 +5172,13 @@ Agent.prototype.tableRowStatusHandlerInternal = function (createRequest) {
 
 Agent.prototype.onMsg = function (socket, buffer, rinfo) {
 
+	const callback = Listener.rinfoErrorCallback (this, rinfo);
 	let message;
 
 	try {
-		message = Listener.processIncoming (buffer, this.authorizer, this.callback);
+		message = Listener.processIncoming (buffer, this.authorizer, callback);
 	} catch (error) {
-		this.callback (new ProcessingError ("Failure to process incoming message", error, rinfo, buffer));
+		callback (new ProcessingError ("Failure to process incoming message", error, rinfo, buffer));
 		return;
 	}
 
@@ -5083,7 +5213,7 @@ Agent.prototype.onMsg = function (socket, buffer, rinfo) {
 	} else if ( message.pdu.type == PduType.GetBulkRequest ) {
 		this.getBulkRequest (socket, message, rinfo);
 	} else {
-		this.callback (new RequestInvalidError ("Unexpected PDU type " +
+		callback (new RequestInvalidError ("Unexpected PDU type " +
 			message.pdu.type + " (" + PduType[message.pdu.type] + ")"));
 	}
 };

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "net-snmp",
-  "version": "3.26.3",
+  "version": "3.28.0",
   "description": "JavaScript implementation of the Simple Network Management Protocol (SNMP)",
   "author": "Mark Abrahams <mark@abrahams.co.nz>",
   "license": "MIT",
   "main": "index.js",
+  "files": [
+    "index.js",
+    "lib/",
+    "example/",
+    "ref/",
+    "CONTRIBUTING.md",
+    "README.cn.md",
+    "!example/test.js"
+  ],
   "directories": {
     "example": "example"
   },

package/.claude/skills/git-commit/SKILL.md

@@ -1,54 +0,0 @@
----
-name: git-commit
-description: Creates a git commit summarizing all current working tree changes (staged and unstaged). Use when the user asks to commit, save progress, or invoke /git-commit.
----
-
-# Git Commit
-
-## When to use
-
-- When the user asks to commit current changes.
-- When invoked via `/git-commit`.
-
-## Arguments
-
-- `dry-run` — perform steps 1–3 only (gather context, identify files, draft commit message) and then **ask the user** whether to proceed with the actual commit or cancel. Do **not** stage or commit until the user confirms.
-
-## Workflow
-
-1. **Gather context** — run these commands in parallel:
-   - `git status` — to see all tracked modifications and untracked files.
-   - `git diff` and `git diff --cached` — to see unstaged and staged changes.
-   - `git log --oneline -10` — to match the repository's commit message style.
-
-2. **Stage all relevant changes** — add all modified and untracked files that are part of the current work. Use specific file paths rather than `git add -A`. Do **not** stage files that likely contain secrets (`.env`, credentials, etc.) — warn the user if any are present.
-
-3. **Draft the commit message** — analyse the diff and write a concise commit message:
-   - One summary line (imperative mood, under 72 characters) describing the *why* / *what* of the change.
-   - If the change is non-trivial, add a blank line followed by bullet points elaborating key changes.
-   - **Don't pad small commits**: if the summary line already captures the change, omit the body entirely. Most single-purpose commits need only the summary line.
-   - **Stay high-level**: never reference code-level details like variable names, function names, method calls, or file paths in the commit message. Describe *what changed for the user or system*, not *which functions were modified*.
-   - Match the style and conventions visible in the recent git log.
-
-4. **Commit** — create the commit using a heredoc for the message:
-   ```bash
-   git commit -m "$(cat <<'EOF'
-   <summary line>
-
-   <optional body>
-   EOF
-   )"
-   ```
-
-5. **Verify** — run `git status` after the commit to confirm it succeeded and the working tree is clean (or shows only intentionally unstaged files).
-
-6. **Show the commit** — run `git log -1` and display the **entire** commit message (summary line and body) to the user so they can review it. Do not truncate or abbreviate — if the message has bullet points or a multi-line body, include all of it in your response.
-
-## Rules
-
-- Never amend an existing commit unless the user explicitly asks.
-- Never push to the remote unless the user explicitly asks.
-- Never use `--no-verify` or skip pre-commit hooks.
-- If a pre-commit hook fails, fix the issue, re-stage, and create a **new** commit (do not amend).
-- Never stage `.env`, credential files, or other secrets.
-- Never add `Co-Authored-By`, `Authored-By`, `Made-with` or any other attribution trailer to commit messages.

package/.claude/skills/prepare-release/SKILL.md

@@ -1,97 +0,0 @@
----
-name: prepare-release
-description: Prepare a release by running lint + tests, bumping the package.json version, and appending a version summary to README.md. Use when the user asks to "prepare a release", "cut a release", or invokes /prepare-release. Stops immediately on lint/test failure so the user can fix issues before continuing.
----
-
-# Prepare Release
-
-## When to use
-
-- User asks to prepare / cut a release.
-- User invokes `/prepare-release`.
-- Immediately before the release commit — this skill stages no files and creates no commit; hand off to `/git-commit` afterwards.
-
-## Release model
-
-The release content is the union of **(a)** commits since the last tag and **(b)** uncommitted user-facing changes in the working tree. Both are valid sources; the typical flow is that the fix being released sits uncommitted alongside the version bump and README update, and the user then commits them all together in a single release commit.
-
-Consequences:
-- Do **not** object to uncommitted changes in the working tree — they are expected and are part of what is being released. Treat them as release content, not as a blocker.
-- Do **not** require at least one committed change since the last tag. The release may consist entirely of working-tree changes that have not yet been committed.
-- When drafting the README bullets in step 5, summarise the user-facing changes visible across **both** sources (committed commits since the last tag **and** the diff of the working tree before this skill began modifying it).
-- The only changes this skill itself creates are in `package.json`, `package-lock.json`, and `README.md`. Everything else in the working tree was already the user's in-progress release content.
-
-## Arguments
-
-- `patch` (default) — bumps the patch component, e.g. `3.26.1` → `3.26.2`.
-- `minor` — bumps the minor component and resets patch, e.g. `3.26.1` → `3.27.0`.
-- `major` — bumps the major component and resets minor/patch, e.g. `3.26.1` → `4.0.0`.
-
-If the user supplies anything else, stop and ask for clarification.
-
-## Workflow
-
-Run steps in order. **If any step fails, stop immediately, report the failure, and do not proceed.** Do not modify `package.json`, `package-lock.json`, or `README.md` until lint and tests pass.
-
-### 1. Pre-flight checks (parallel)
-
-- `git status --short` — capture the working tree state. Per the release model above, treat uncommitted changes as part of the release content, not as a blocker. Still surface the list to the user so they can spot anything that looks unintended (e.g. a modified file they don't remember touching) before the eventual release commit.
-- `git rev-parse --abbrev-ref HEAD` — confirm the current branch. If it is not `master`, warn the user and ask whether to continue.
-- `git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || git log --format=%H | tail -1)..HEAD` — collect commits since the last tag (or since the beginning if no tags exist). These feed the README summary in step 5 alongside the working-tree diff.
-- `git diff` and `git diff --cached` — capture the uncommitted user-facing changes. These also feed the README summary in step 5.
-- Read current version from `package.json`.
-
-Only stop at pre-flight if **both** the commit list and the uncommitted diff are empty — in that case there is genuinely nothing to release.
-
-### 2. Lint
-
-Run `npm run lint`. **Stop on non-zero exit.** Report the linter output verbatim and do not continue.
-
-### 3. Tests
-
-Run `npm test`. **Stop on non-zero exit.**
-
-Exception: the `Subagent` tests in `test/subagent.test.js` require a locally-running AgentX master (`snmpd`) and will fail with `ECONNREFUSED` if one is not present. If the only failures are Subagent `ECONNREFUSED` failures, report them and ask the user whether to proceed (they may have intentionally skipped running snmpd). All other failures are hard stops.
-
-### 4. Bump version
-
-Run `npm version <patch|minor|major> --no-git-tag-version`. This updates both `package.json` and `package-lock.json` atomically without creating a commit or tag. Capture the new version string for the README entry.
-
-If the argument was omitted, default to `patch`.
-
-### 5. Append README version summary
-
-- Read `README.md`.
-- Locate the `# License` heading near the end.
-- Insert a new version section **immediately before** `# License`, separated by a blank line above and below, in exactly this format:
-
-```
-# Version X.Y.Z - DD/MM/YYYY
-
- * <concise user-facing summary of change 1>
-
- * <concise user-facing summary of change 2>
-```
-
-Notes:
-- Date is **today's date** in `DD/MM/YYYY` (day/month/year) — use the date from the environment, not a hardcoded value.
-- Each bullet begins with a single space, then `*`, then a space. There is a blank line between bullets (match the style of the existing entries).
-- Bullets describe **user-visible changes** — not refactors, lint fixes, test additions, or internal tidy-ups. Write them like release notes, not commit subjects. Draw from **both** the commit list gathered in step 1 and the uncommitted working-tree diff; merge/reword where helpful so each line stands on its own.
-- If there is only one user-visible change, include just one bullet.
-- Do not touch any other part of `README.md`.
-
-### 6. Summary
-
-Report to the user, concisely:
-- New version number.
-- Bullets added to `README.md`.
-- The full list of uncommitted files now staged for the release commit — both the pre-existing working-tree changes and the three files this skill modified (`package.json`, `package-lock.json`, `README.md`). Flag anything that looks unexpected.
-
-Do **not** run `git add`, `git commit`, `git tag`, or `npm publish` — those are the user's decision. The next step is typically `/git-commit`.
-
-## Things to watch for
-
-- If `npm version` fails because the working tree is dirty, it has not been run with `--no-git-tag-version` correctly — re-check the command.
-- If the README insertion point (`# License`) cannot be found, stop and ask the user — do not guess.
-- If the lint or test commands are missing from `package.json`, stop and report.
-- Never bypass a failing check with `--no-verify`, `SKIP=`, or similar; the user must fix the underlying issue.

package/.claude/skills/propose-action/SKILL.md

@@ -1,111 +0,0 @@
----
-name: propose-action
-description: Review a GitHub issue or PR by number and propose a concrete action plan — either a reasoned recommendation not to action it, or the code and test changes required to action it. Use when the user asks to "propose an action" for an issue/PR, "look at issue/PR #N", or invokes /propose-action with an issue or PR number. Ends by asking whether to proceed, proceed with modifications, or abandon.
----
-
-# Propose Action
-
-## When to use
-
-- The user asks to review a GitHub issue or PR and recommend what to do about it.
-- The user invokes `/propose-action <number>`.
-
-This skill **plans only** for steps 1–5 — it does not edit code, run tests, commit, push, or comment on the issue/PR during the proposal phase. Implementation happens after the user approves the plan in step 5's closing question. Once the user has approved and you have carried out the agreed actions, step 6 produces a ready-to-paste reply to the issue/PR aligned with what was actually done — but never posts it.
-
-## Arguments
-
-- `<number>` (required) — the GitHub issue or PR number. Bare integer, or `#N`, or a full GitHub URL are all acceptable forms.
-
-If the number is missing, ambiguous, or does not resolve to an issue/PR in the current repository, stop and ask the user to clarify.
-
-## Workflow
-
-### 1. Identify the target
-
-- Determine the current repository: `gh repo view --json nameWithOwner -q .nameWithOwner`.
-- Resolve the number to either an issue or a PR. GitHub numbers them in the same namespace, so try PR first, then issue:
-  - `gh pr view <number> --json number,title,state,author,body,headRefName,baseRefName,isDraft,mergeable,additions,deletions,changedFiles,labels,comments,reviews`
-  - If that fails, `gh issue view <number> --json number,title,state,author,body,labels,comments,assignees`
-- Record whether the target is an **issue** or a **PR** — the two branches below differ.
-
-### 2a. If the target is an issue
-
-Gather context in parallel:
-- The issue body and all comments (from the `gh issue view` JSON above).
-- `gh issue view <number> --json linkedPullRequests` — check for linked PRs that may already address it.
-- Identify the files or subsystems the issue points at. Search the repo (`Grep`, `Glob`, `Read`) for the relevant code. Do not guess — read the actual files the issue describes.
-- If the issue references specific OIDs, error messages, function names, or SNMP behaviours, locate them in the source.
-
-### 2b. If the target is a PR
-
-Gather context in parallel:
-- PR body, comments, and reviews (from the `gh pr view` JSON above).
-- `gh pr diff <number>` — the full diff.
-- `gh pr view <number> --json files -q '.files[].path'` — changed files.
-- Read the **current** version of each changed file on the base branch so you understand what the PR is replacing, not just what it adds.
-- If the PR closes or references an issue (via `Fixes #N`, `Closes #N`, etc.), also fetch that issue for context.
-- Check CI status if available: `gh pr checks <number>`.
-
-### 3. Form a judgement
-
-Decide which of these recommendations fits, and be willing to recommend **against** actioning:
-
-- **Do not action** — the issue is invalid, already fixed, out of scope, based on a misunderstanding, a duplicate, or the PR is the wrong approach / would regress behaviour / conflicts with project direction. Explain *why* clearly, citing the code or prior commits that support the conclusion.
-- **Action as-is** — the issue is valid and the fix is clear, or the PR is correct and should be merged as submitted.
-- **Action with modifications** — the issue is valid but the obvious fix is wrong; or the PR has the right idea but needs specific changes before it can be merged.
-- **Needs more information** — the report is plausible but underspecified. List the exact questions to ask the reporter / author before any code change is possible.
-
-Base the judgement on what the code actually does today, not on what the issue/PR claims. If the two disagree, surface the disagreement.
-
-### 4. Draft the proposal
-
-Structure the written proposal in this order. Keep it concrete — name files, line numbers, function names, and the specific behaviours being changed.
-
-1. **Target** — `Issue #N: <title>` or `PR #N: <title>`, plus one sentence on its state (open/closed/draft/merged, CI status for PRs).
-2. **Summary of the report** — one short paragraph in your own words describing what the reporter is asking for or proposing. Do not just quote the body.
-3. **Findings** — what the code currently does, whether the report is accurate, and any related context (linked issues/PRs, prior commits, existing tests covering this area). Cite `file:line` locations.
-4. **Recommendation** — one of the four options from step 3, stated plainly in a sentence or two.
-5. **Proposed changes** (omit if the recommendation is *do not action* or *needs more information*):
-   - **Code** — for each file to change, list the edit as a bullet: `path/to/file.js:<line-range> — <what changes and why>`. For non-trivial edits, include a short before/after sketch (a few lines, not a full diff).
-   - **Tests** — list tests to **add**, **modify**, or **delete**, each with the file and a one-line description of what the test asserts. If no test changes are needed, say so explicitly and justify (e.g. "covered by existing test at `test/x.test.js:42`").
-   - **Docs / README** — note any README or inline-doc updates required. Release-note bullets are handled by `/prepare-release`; do not pre-empt them here.
-6. **Risks and unknowns** — anything that could make the plan wrong: behaviours you could not verify, edge cases the tests would not catch, compatibility concerns, or assumptions about the reporter's environment.
-7. **Out of scope** — closely-related issues you noticed while investigating but are **not** proposing to fix in this action. Keeps the scope honest.
-
-### 5. Closing question
-
-End the response with exactly one question, offering three choices:
-
-> Proceed with this plan as-is, proceed with modifications (tell me what to change), or abandon it?
-
-Do not start implementing until the user answers. If the user says "proceed", begin implementing the plan in the next turn. If the user asks for modifications, revise the proposal and ask the same question again. If the user says to abandon, stop and skip step 6.
-
-### 6. Ready-to-paste issue/PR reply
-
-After the agreed actions have been carried out (code edits, tests, docs, or a reasoned decision not to action), produce a single ready-to-paste reply for the issue/PR. This is the **last** thing you output, rendered in a fenced block or delimited by `---` so the user can copy it cleanly.
-
-The reply must be aligned with **what actually happened**, not with the original plan — if the user asked for modifications during implementation, reflect the modified outcome. If a step was skipped or failed, say so honestly; do not describe work that was not done.
-
-Tailor the content to the recommendation from step 3:
-
-- **Action as-is / with modifications** — acknowledge the report, give the user a short, concrete summary of the fix (with the key code change or snippet inline if it helps them adopt it), point at the files/sections that changed (e.g. "updated in `README.md` under *Scalar providers*"), and note when it will ship (e.g. "will land in the next release" — do not invent a version number unless `package.json` has already been bumped). If there's a workaround the reporter can apply before the release, include it.
-- **Do not action** — explain the reasoning in the reporter's terms, citing the code or prior history that supports the decision. Be respectful: the reporter put effort into the report. Offer an alternative path if one exists (a different API, a related issue, a config change). If the issue should be closed, say so; do not close it yourself.
-- **Needs more information** — list the specific questions you need answered, each as its own bullet. Explain briefly *why* each is needed so the reporter can see what would unblock progress.
-
-Style:
-
-- Match the tone of prior replies in this repository if they are visible in the issue/PR thread — don't suddenly adopt a different register.
-- Write as the maintainer would: first person, conversational, no corporate voice, no marketing copy, no emoji unless the repo's existing replies use them.
-- Do not include a signature, do not add attribution trailers (no "generated by", no `Co-Authored-By`), do not tag the reporter more than once.
-- Keep it focused — one screen of text is almost always enough. If the reply needs code blocks, prefer short, complete snippets over long diffs.
-
-Hand the reply to the user with one sentence above it saying where to paste it (e.g. "Ready-to-paste reply for issue #297:"). Do **not** run `gh issue comment` / `gh pr comment` / `gh issue close` / `gh pr merge` — the user posts it.
-
-## Rules
-
-- **Never** edit files, run tests, or modify git state during steps 1–5. Planning only.
-- **Never** post a comment on the issue/PR, add labels, request reviews, merge, or close — not in step 6, not ever within this skill. Those are the user's decision.
-- **Never** fabricate line numbers or function names — if you cite `file:line`, you must have read it.
-- If `gh` is not authenticated or the number does not exist, stop and report the error verbatim.
-- If the issue/PR is in a different repository than the current working directory, stop and confirm with the user before proceeding — the plan would target the wrong codebase.
-- Keep the proposal focused. A plan that touches ten files for a one-line bug is a signal to re-read the issue, not to write a bigger plan.