---
url: >-
  https://adk.nht.io/api/@nhtio/adk/batteries/orchestration/interfaces/PlanLock.md
description: A single execution lease on one plan.
---

# Interface: PlanLock

Defined in: [src/batteries/orchestration/locks.ts:49](https://github.com/NHTIO/ADK/blob/v1.20260906.0/src/src/batteries/orchestration/locks.ts#L49)

A single execution lease on one plan.

A `PlanLock` is a TTL lease (coordination, not mutual exclusion — see the module docs). It is
held by the process driving a run and released when the run settles or the lease expires. It
does not fence: a partitioned or GC-stalled holder can continue past expiry while a second
executor legitimately acquires the lease, so a node may still be double-invoked; the per-node
`onIndeterminate` policy plus `replaySafe` are the real defence against that ambiguity.

## Methods

### acquire()

```ts
acquire(o?: {
  retry?: {
     attempts?: number;
     delay?: number;
     timeout?: string | number;
  };
}): Promise<boolean>;
```

Defined in: [src/batteries/orchestration/locks.ts:59](https://github.com/NHTIO/ADK/blob/v1.20260906.0/src/src/batteries/orchestration/locks.ts#L59)

Acquire the lease, retrying on contention.

Returns `true` when this process now holds the lease, `false` when it could not acquire it
within the retry budget. `retry.timeout` bounds the whole attempt (a number of milliseconds
or a duration string), `retry.delay` is the pause between attempts, and `retry.attempts`
caps the number of tries. A caller that gets `false` must treat the run as executing
elsewhere and not start a duplicate.

#### Parameters

| Parameter           | Type                                                                                                |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| `o?`                | { `retry?`: { `attempts?`: `number`; `delay?`: `number`; `timeout?`: `string` | `number`; }; } |
| `o.retry?`          | { `attempts?`: `number`; `delay?`: `number`; `timeout?`: `string` | `number`; }                  |
| `o.retry.attempts?` | `number`                                                                                            |
| `o.retry.delay?`    | `number`                                                                                            |
| `o.retry.timeout?`  | `string` | `number`                                                                                |

#### Returns

`Promise`<`boolean`>

***

### acquireImmediately()

```ts
acquireImmediately(): Promise<boolean>;
```

Defined in: [src/batteries/orchestration/locks.ts:69](https://github.com/NHTIO/ADK/blob/v1.20260906.0/src/src/batteries/orchestration/locks.ts#L69)

Acquire the lease with a single, non-retrying attempt.

Returns `true` when this process now holds the lease, `false` when it is held elsewhere.
Useful for a fast, best-effort check before committing to a run.

#### Returns

`Promise`<`boolean`>

***

### extend()

```ts
extend(duration?: string | number): Promise<void>;
```

Defined in: [src/batteries/orchestration/locks.ts:97](https://github.com/NHTIO/ADK/blob/v1.20260906.0/src/src/batteries/orchestration/locks.ts#L97)

Extend the lease's TTL.

Exists so a long `call` node keeps its lease alive past the original TTL. `duration` is the
new remaining time (a number of milliseconds or a duration string); when omitted, the lease
is extended by its configured TTL. A no-op if this process no longer holds the lease.

#### Parameters

| Parameter   | Type                 |
| ----------- | -------------------- |
| `duration?` | `string` | `number` |

#### Returns

`Promise`<`void`>

***

### getOwner()

```ts
getOwner(): string;
```

Defined in: [src/batteries/orchestration/locks.ts:120](https://github.com/NHTIO/ADK/blob/v1.20260906.0/src/src/batteries/orchestration/locks.ts#L120)

The identity of the current holder, or an empty string when the lease is free.

Synchronous and best-effort — it reflects the last observed state, not a fresh read.

#### Returns

`string`

***

### getRemainingTime()

```ts
getRemainingTime(): Promise<number>;
```

Defined in: [src/batteries/orchestration/locks.ts:105](https://github.com/NHTIO/ADK/blob/v1.20260906.0/src/src/batteries/orchestration/locks.ts#L105)

The lease's remaining time-to-live in milliseconds.

Exists so a long `call` node can decide whether to `extend()` before the lease lapses. A
non-positive value means the lease has expired (or is held elsewhere).

#### Returns

`Promise`<`number`>

***

### isLocked()

```ts
isLocked(): Promise<boolean>;
```

Defined in: [src/batteries/orchestration/locks.ts:113](https://github.com/NHTIO/ADK/blob/v1.20260906.0/src/src/batteries/orchestration/locks.ts#L113)

Whether the lease is currently held (by any process).

A best-effort liveness probe; it does not tell the caller whether THIS process holds the
lease, and it is subject to the same partition/GC blind spot as every TTL lease.

#### Returns

`Promise`<`boolean`>

***

### release()

```ts
release(): Promise<void>;
```

Defined in: [src/batteries/orchestration/locks.ts:78](https://github.com/NHTIO/ADK/blob/v1.20260906.0/src/src/batteries/orchestration/locks.ts#L78)

Release the lease.

Idempotent and safe to call when the lease is already expired or held by another process —
it must not release a lease this process does not hold. Called when a run settles or is
abandoned.

#### Returns

`Promise`<`void`>

***

### run()

```ts
run<T>(fn: () => Promise<T>): Promise<[boolean, T]>;
```

Defined in: [src/batteries/orchestration/locks.ts:88](https://github.com/NHTIO/ADK/blob/v1.20260906.0/src/src/batteries/orchestration/locks.ts#L88)

Run `fn` while holding the lease.

Returns `[executed, result]` as a tuple: `[false]` when the lease is held elsewhere, so a
second process reports "already executing elsewhere" rather than starting a duplicate; on
success it returns `[true, result]` with `fn`'s resolved value. The lease is released when
`fn` settles, whether it resolves or rejects.

#### Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

#### Parameters

| Parameter | Type                   |
| --------- | ---------------------- |
| `fn`      | () => `Promise`<`T`> |

#### Returns

`Promise`<\[`boolean`, `T`]>

***

### serialize()

```ts
serialize(): string;
```

Defined in: [src/batteries/orchestration/locks.ts:129](https://github.com/NHTIO/ADK/blob/v1.20260906.0/src/src/batteries/orchestration/locks.ts#L129)

Serialize the lease to a string.

Exists so a lease can be handed from the process that started a run to the one resuming it:
the resuming process passes the serialized lease to `PlanLockFactory.restoreLock` and
continues holding the same lease rather than racing to re-acquire it.

#### Returns

`string`