[MTRCommissioning] Add watchdog for client failure to advance past PASE

If a client (CHIP framework consumer) implements
commissioning:paseSessionEstablishmentComplete: but then never calls
commissionNodeWithID: or cancelCommissioningForNodeID:, the
MTRCommissioningOperation sits in isWaitingAfterPASEEstablished = YES
forever.  MTRDeviceController_Concrete keeps the operation alive via
currentInternalCommissioning, so every subsequent commissioning attempt
hits the busy check in startWithController and fails with
CHIP_ERROR_BUSY.  User-visible symptom: Matter accessories refuse to
commission until the daemon (or app) is restarted.

Add a 5-minute dispatch_source_t watchdog armed when
isWaitingAfterPASEEstablished is set to YES, cancelled on legitimate
advance, stop, or terminal error.  On expiry, calls
stopCommissioning:forCommissioningID: and routes CHIP_ERROR_TIMEOUT
through the standard _dispatchCommissioningError path so client state
can settle.  Clear isWaitingAfterPASEEstablished BEFORE the controller
stop call so -_cancelCommissioning does not synthesize a CANCELLED
OnCommissioningComplete -- the wedge IS that no notifications arrived,
so suppressing the synthetic CANCELLED avoids a redundant
MATTER_LOG_METRIC_END(kMetricDeviceCommissioning) and a spurious
CANCELLED on _delegateQueue ahead of the TIMEOUT we want to deliver.

Defensive secondary fix in
setupCommissioningSessionWithPayload:newNodeID:error:: if a stale
internally-created commissioning is still parked at the post-PASE
waiting state with a different setup payload, treat the new call as an
implicit cancel of the previous one rather than failing the new call
with BUSY.  Perform the implicit cancel BEFORE
MATTER_LOG_METRIC_BEGIN(kMetricDeviceCommissioning) and the metrics
reset for the new attempt -- otherwise the synthetic CANCELLED end
emitted by the bridge from the stale operation would close out the
new attempt's metric, leaving it without a matching begin/end and
skewing telemetry.  This also keeps the cancel-failure early return
from leaving kMetricDeviceCommissioning open across the returned NO.

Threading hardening from review:
 * atomic test-only watchdog interval override so concurrent TSan setters
   on any queue race-free with the production read in _armPostPASEWatchdog
 * clamp non-finite (NaN / +/-INFINITY) test interval overrides to 0
   (use production interval) so the multiply-by-NSEC_PER_SEC and cast
   to int64_t in -_armPostPASEWatchdog stays defined behavior
 * atomic stop via stopCommissioningAtomically:forCommissioningID:, closing
   the TOCTOU window between currentCommissioning read and StopPairing
 * synchronous _cancelPostPASEWatchdog in -stop so tests can observe the
   teardown immediately after -stop returns

Honor the @Property (copy) declaration on -setupPayload by [copy]'ing
the input in the designated initializer; mutable inputs were aliased.

Regression coverage:
 * test_PostPASEWatchdogIntervalResetToZeroRestoresProductionInterval --
   pins that +setPostPASEWatchdogIntervalForTesting:0 actually restores
   the production interval after a non-zero override.
 * test_ForceArmFailureFlag_ConcurrentSettersAndArmer_NoTSan -- TSan
   smoke test for the per-instance _forceNextArmFailureForTesting flag.
 * test_WatchdogCancel_IsSynchronousOnSelfFire -- pins the round-2
   sync-cancel contract for the watchdog's own fire path;
   -_firePostPASEWatchdog must synchronously tear down _postPASEWatchdog
   at the top of the handler.

Author: woody-apple

src/darwin/Framework/CHIP/MTRCommissioningOperation.mm

@@ -38,14 +38,30 @@ NS_ASSUME_NONNULL_BEGIN
 
 @property (nonatomic, readonly, assign) BOOL isInternallyCreated;
 
+// The commissioning identifier this operation was constructed with (the
+// random "future node ID" we use to track the commissioning flow before the
+// commissionee has been assigned a real node ID).  Exposed so callers like
+// MTRDeviceController_Concrete that need to drive cancellation against this
+// commissioning have something to pass to StopPairing without reaching into
+// private ivars.
+@property (nonatomic, readonly, copy) NSNumber * commissioningID;
+
 // True if the commissioning is waiting to resume after PASE has been
 // established and the delegate chose to be notified about that.
 //
 // This is currently only true if isInternallyCreated, and is readwrite because
 // MTRDeviceController_Concrete helps maintain this state.
 //
-// This property should generally be written on client queues only, not on the
-// Matter queue.
+// Threading: reads and writes go through the property, which is internally
+// guarded by an os_unfair_lock so the value the setter just wrote is
+// observable to a synchronous reader on any queue.  The paired post-PASE
+// watchdog timer (an internal implementation detail) is owned by the
+// operation's _delegateQueue; the setter clears the flag synchronously and
+// bounces the watchdog teardown side effect onto _delegateQueue.  The
+// watchdog event_handler consults isWaitingAfterPASEEstablished as a
+// late-fire guard to avoid a spurious CHIP_ERROR_TIMEOUT when the client
+// has legitimately advanced past the post-PASE waiting state but a timer
+// block was already enqueued ahead of the cancel.
 @property (nonatomic, readwrite, assign) BOOL isWaitingAfterPASEEstablished;
 
 @end

src/darwin/Framework/CHIP/MTRCommissioningOperation_Internal.h

@@ -0,0 +1,52 @@
+/**
+ *    Copyright (c) 2026 Project CHIP Authors
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#import <Foundation/Foundation.h>
+#import <Matter/MTRCommissioningOperation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+// Production interval after which the post-PASE watchdog fires.  Exposed so
+// tests can assert against the same constant the production code uses.
+extern const NSTimeInterval kMTRPostPASEWatchdogInterval;
+
+@interface MTRCommissioningOperation (PostPASEWatchdogTesting)
+
+// Overrides the post-PASE watchdog interval for all subsequently armed
+// watchdogs in the current process.  Pass 0 to restore the production
+// interval (kMTRPostPASEWatchdogInterval).  Intended only for tests that
+// need to exercise the watchdog without waiting five minutes.
++ (void)setPostPASEWatchdogIntervalForTesting:(NSTimeInterval)interval;
+
+// One-shot fault injection: if set to YES, the next call to the internal
+// _armPostPASEWatchdog helper on this instance will simulate a
+// dispatch_source_create failure and return NO without arming the timer.
+// The flag is cleared as soon as it is observed, so each call to this
+// setter injects exactly one failure.
+- (void)setForceNextArmFailureForTesting:(BOOL)force;
+
+// Test-only accessor for the _postPASEWatchdog dispatch_source ivar.
+// Returns the source under _stateLock so tests can verify synchronous
+// cancel semantics after -stop: returns (the cancel in -stop is now
+// synchronous; tests can read this immediately after -stop returns and
+// expect nil).  Do NOT use this to drive production logic; this exists
+// purely so test_WatchdogCancel_IsSynchronousOnStop can pin the
+// synchronous-cancel contract.
+- (nullable dispatch_source_t)postPASEWatchdogForTesting;
+
+@end
+
+NS_ASSUME_NONNULL_END

src/darwin/Framework/CHIP/MTRCommissioningOperation_Test.h

@@ -255,6 +255,44 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (BOOL)stopCommissioning:(MTRCommissioningOperation *)commissioning forCommissioningID:(NSNumber *)commissioningID;
 
+/**
+ * Outcome of a -stopCommissioningAtomically:forCommissioningID: call.
+ *
+ * Disambiguates the two failure modes of -stopCommissioning:forCommissioningID:
+ * (which collapses both to NO) so the post-PASE watchdog fire path can
+ * decide whether to escalate a CHIP_ERROR_TIMEOUT to the client.
+ */
+typedef NS_ENUM(NSInteger, MTRStopCommissioningOutcome) {
+    /// We were the current commissioning and StopPairing succeeded (or no
+    /// StopPairing was needed because we had not yet reached the C++ layer).
+    MTRStopCommissioningOutcomeStopped,
+    /// Another MTRCommissioningOperation has already taken our slot on the
+    /// controller (currentCommissioning != self).  Caller must NOT dispatch
+    /// a terminal error in this case -- the wedge has already been resolved
+    /// by the replacement and a timeout dispatched here would tear down the
+    /// unrelated successor's delegate state.
+    MTRStopCommissioningOutcomeReplaced,
+    /// We were the current commissioning but StopPairing failed at the CHIP
+    /// layer (e.g. the commissionee fail-safe expired before the watchdog
+    /// fired).  Caller MUST still surface a terminal error so the client can
+    /// settle back to "no commissioning in flight".
+    MTRStopCommissioningOutcomeFailedStillCurrent,
+};
+
+/**
+ * Atomic variant of -stopCommissioning:forCommissioningID: that distinguishes
+ * the "replaced" and "failed-but-still-current" outcomes from the success
+ * outcome.  The replaced-vs-current check and the StopPairing call are
+ * performed under the same controller lock, eliminating the TOCTOU window
+ * between an external check of currentCommissioning and the subsequent stop.
+ *
+ * Used by the post-PASE watchdog fire path to suppress a spurious
+ * CHIP_ERROR_TIMEOUT when the operation slot has already been taken by a
+ * successor.
+ */
+- (MTRStopCommissioningOutcome)stopCommissioningAtomically:(MTRCommissioningOperation *)commissioning
+                                        forCommissioningID:(NSNumber *)commissioningID;
+
 /**
  * Notification that a commissioning operation is done.
  */

src/darwin/Framework/CHIP/MTRDeviceController_Concrete.h

@@ -146,6 +146,19 @@ @implementation MTRDeviceController_Concrete {
     // Keep track of dns-sd resolution objects for shutdown-time cleanup.
     os_unfair_lock _deviceConnectivityMonitorLock;
     NSHashTable<MTRDeviceConnectivityMonitor *> * _weakSetOfDeviceConnectivityMonitors;
+
+    // Guards the read-currentCommissioning + StopPairing sequence in
+    // -stopCommissioningAtomically:forCommissioningID:.  Without this,
+    // the post-PASE watchdog fire path has a TOCTOU between checking
+    // `currentCommissioning != self` (the "replaced" gate) and the
+    // subsequent StopPairing call: a concurrent
+    // setupCommissioningSessionWithPayload: on another thread can swap
+    // currentCommissioning between the two reads and the watchdog
+    // either dispatches a spurious CHIP_ERROR_TIMEOUT to a now-detached
+    // delegate or fails to release a still-current C++ commissioning
+    // slot.  This lock makes the check-and-act sequence atomic w.r.t.
+    // any other writer of currentCommissioning that also acquires it.
+    os_unfair_lock _currentCommissioningLock;
 }
 
 // TODO: Figure out whether the work queue storage lives here or in the superclass
@@ -205,6 +218,7 @@ - (nullable instancetype)initWithFactory:(MTRDeviceControllerFactory *)factory
         _currentCommissioning = nil;
         _commissioningQueue = dispatch_queue_create("org.csa-iot.matter.framework.commissioning.workqueue", DISPATCH_QUEUE_SERIAL_WITH_AUTORELEASE_POOL);
         _deviceConnectivityMonitorLock = OS_UNFAIR_LOCK_INIT;
+        _currentCommissioningLock = OS_UNFAIR_LOCK_INIT;
 
         if (storageDelegate != nil) {
             if (storageDelegateQueue == nil) {
@@ -861,18 +875,58 @@ - (BOOL)setupCommissioningSessionWithPayload:(MTRSetupPayload *)payload
 
     MTR_LOG("%@ Setting up commissioning session for device ID 0x%016llX with setup payload %@", self, newNodeID.unsignedLongLongValue, payload);
 
+    // Compute the pairing code first so we can compare against any stale
+    // post-PASE commissioning before we touch metrics state.
+    NSString * earlyPairingCode = [payload qrCodeString:nil];
+    if (earlyPairingCode == nil) {
+        earlyPairingCode = [payload manualEntryCode];
+    }
+
+    // If we have a stale internally-created commissioning still parked at the
+    // post-PASE waiting state for a *different* setup payload, treat the new
+    // setupCommissioningSessionWithPayload: call as an implicit cancel of the
+    // previous one.  Otherwise the new call would fail with CHIP_ERROR_BUSY
+    // (0xDB) because the controller still considers the prior commissioning
+    // in flight, and the user would be stuck until a process restart.
+    //
+    // IMPORTANT: do this BEFORE resetting/beginning kMetricDeviceCommissioning
+    // for the new attempt.  -_cancelCommissioning routes through the bridge,
+    // which calls MATTER_LOG_METRIC_END(kMetricDeviceCommissioning, ...) -- if
+    // we had already begun the new attempt's metric, the synthetic CANCELLED
+    // from the stale operation would close out the new attempt's metric,
+    // leaving it without a matching begin/end and skewing telemetry.  Also
+    // bail out early on cancel failure here, before any new-attempt metric
+    // state is touched, so we never leave kMetricDeviceCommissioning open
+    // across a returned-NO failure.
+    auto * staleCommissioning = self.currentCommissioning;
+    if (staleCommissioning && staleCommissioning.isInternallyCreated
+        && staleCommissioning.isWaitingAfterPASEEstablished
+        && earlyPairingCode != nil
+        && ![staleCommissioning.setupPayload isEqualToString:earlyPairingCode]) {
+        MTR_LOG("%@ implicitly cancelling stale post-PASE commissioning %@ before starting a new one with a different payload", self, staleCommissioning);
+        NSError * cancelError = nil;
+        BOOL cancelled = [self _cancelCommissioning:staleCommissioning forNodeID:staleCommissioning.commissioningID error:&cancelError];
+        if (!cancelled) {
+            // StopPairing failed on the CHIP layer; surface the error
+            // rather than silently starting a new commissioning that is
+            // about to hit the very CHIP_ERROR_BUSY we just failed to
+            // clear.  No new-attempt metrics have been begun yet, so
+            // there is nothing to MATTER_LOG_METRIC_END here.
+            MTR_LOG_ERROR("%@ failed to implicitly cancel stale commissioning %@: %@", self, staleCommissioning, cancelError);
+            if (error) {
+                *error = cancelError ?: [MTRError errorForCHIPErrorCode:CHIP_ERROR_BUSY];
+            }
+            return NO;
+        }
+    }
+
     [[MTRMetricsCollector sharedInstance] resetMetrics];
 
     // Track overall commissioning
     MATTER_LOG_METRIC_BEGIN(kMetricDeviceCommissioning);
     emitMetricForSetupPayload(payload);
 
-    // Try to get a QR code if possible (because it has a better
-    // discriminator, etc), then fall back to manual code if that fails.
-    NSString * pairingCode = [payload qrCodeString:nil];
-    if (pairingCode == nil) {
-        pairingCode = [payload manualEntryCode];
-    }
+    NSString * pairingCode = earlyPairingCode;
     if (pairingCode == nil) {
         CHIP_ERROR errorCode = CHIP_ERROR_INVALID_ARGUMENT;
         MATTER_LOG_METRIC_END(kMetricDeviceCommissioning, errorCode);
@@ -1357,6 +1411,42 @@ - (BOOL)stopCommissioning:(MTRCommissioningOperation *)commissioning forCommissi
     return [self _cancelCommissioning:currentCommissioning forNodeID:commissioningID error:nil];
 }
 
+- (MTRStopCommissioningOutcome)stopCommissioningAtomically:(MTRCommissioningOperation *)commissioning
+                                        forCommissioningID:(NSNumber *)commissioningID
+{
+    // Hold _currentCommissioningLock across BOTH the "are we still the
+    // current commissioning?" gate check AND the StopPairing call so a
+    // concurrent setter of currentCommissioning cannot swap the slot out
+    // from under us between the two operations.  This eliminates the
+    // TOCTOU window the watchdog fire path used to have when it did the
+    // check and the stop as two independent reads of currentCommissioning.
+    //
+    // The lock-order concern here is whether StopPairing (via
+    // syncRunOnWorkQueue on the Matter queue) can call back into a path
+    // that re-acquires _currentCommissioningLock and deadlocks.  In
+    // practice it cannot: the only callbacks that mutate currentCommissioning
+    // (commissioningDone: -> _commissioningDone:) are delivered via
+    // dispatch_async on _commissioningQueue, so they cannot re-enter
+    // synchronously under this lock; they will simply queue behind us
+    // and acquire the lock after we have returned.
+    os_unfair_lock_lock(&_currentCommissioningLock);
+    if (self.currentCommissioning != commissioning) {
+        os_unfair_lock_unlock(&_currentCommissioningLock);
+        MTR_LOG("%@ stopCommissioningAtomically: commissioning %@ was already replaced; no-op", self, commissioning);
+        return MTRStopCommissioningOutcomeReplaced;
+    }
+
+    NSError * stopError = nil;
+    BOOL ok = [self _cancelCommissioning:commissioning forNodeID:commissioningID error:&stopError];
+    os_unfair_lock_unlock(&_currentCommissioningLock);
+
+    if (!ok) {
+        MTR_LOG_ERROR("%@ stopCommissioningAtomically: StopPairing failed for commissioning %@: %@", self, commissioning, stopError);
+        return MTRStopCommissioningOutcomeFailedStillCurrent;
+    }
+    return MTRStopCommissioningOutcomeStopped;
+}
+
 - (BOOL)_cancelCommissioning:(MTRCommissioningOperation *)commissioning forNodeID:(NSNumber *)nodeID error:(NSError * __autoreleasing *)error
 {
     BOOL isWaitingAfterPASEEstablished = commissioning.isWaitingAfterPASEEstablished;