Claims scope before changing it. Paths and globs are repository-relative; a module is resolved through the code map where the project is indexed, else the –paths you give, else the claim is refused without guessing. Under the project’s policy an overlapping claim by another agent is queued behind it (serialise, the default), refused (exit 5) or allowed with a warning. Records your branch and head so the pre-merge check can compare them. The lease ends if you stop renewing it.
Usage
overlane claim acquire --task TASK [--path PATH...] [--glob GLOB...] [--module NAME...] [--paths A,B] [--mode MODE] [--agent NAME] [--lease-seconds N] [--dry-run]Flags
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--task |
string | yes | The task this work belongs to | |
--path |
string (repeatable) | no | A file or directory to claim (a directory claims everything under it); repeat for more | |
--glob |
string (repeatable) | no | A glob such as ‘src/billing/**’; repeat for more | |
--module |
string (repeatable) | no | A module, resolved through the code map where indexed; repeat for more | |
--paths |
string | no | For a module the code map does not know: the paths it covers (comma separated) | |
--mode |
one of exclusive, shared |
no | exclusive (default) or shared read access | |
--agent |
string | no | A label such as codex or claude | |
--lease-seconds |
string | no | Lease length, 60 to 14400; the project default otherwise | |
--dry-run |
boolean | no | Print the requests and file changes this command would make, then stop. Needs no credentials. |
Examples
overlane claim acquire --task task-12 --path apps/api-worker/src/billing/
overlane claim acquire --task task-12 --module billing --glob 'docs/billing/**'Behavior
- Effect:
write(changes local or hosted state). - Needs credentials: yes. Uses the network: yes.
- Supports
--dry-run: yes. Accepts--force: no. - Machine-readable description:
overlane schema claim acquire.
Result
With --json (the default when stdout is not a terminal) the command prints this JSON Schema’s shape on stdout.
{
"anyOf": [
{
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
"description": "tenant identifier"
},
"projectId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
"description": "project identifier"
},
"decision": {
"type": "string",
"enum": [
"granted",
"queued",
"refused"
]
},
"claim": {
"anyOf": [
{
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
"description": "tenant identifier"
},
"projectId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
"description": "project identifier"
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"taskId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"holder": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"agent": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"mode": {
"type": "string",
"enum": [
"exclusive",
"shared"
]
},
"status": {
"type": "string",
"enum": [
"active",
"queued",
"released",
"expired"
]
},
"scopes": {
"minItems": 1,
"maxItems": 32,
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"path",
"glob",
"module"
]
},
"value": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"paths": {
"maxItems": 128,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
}
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
}
},
"patterns": {
"minItems": 1,
"maxItems": 128,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
}
},
"resolvedFrom": {
"type": "string",
"enum": [
"given",
"code-map"
]
},
"branch": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"headSha": {
"type": "string",
"pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
},
"sequence": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"leaseExpiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"maxExpiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"waitingOn": {
"default": [],
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"releasedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"releaseReason": {
"type": "string",
"enum": [
"done",
"released",
"expired",
"queue_timeout",
"forced",
"refused"
]
}
},
"required": [
"tenantId",
"projectId",
"id",
"taskId",
"holder",
"mode",
"status",
"scopes",
"patterns",
"resolvedFrom",
"sequence",
"leaseExpiresAt",
"maxExpiresAt",
"waitingOn",
"createdAt",
"updatedAt"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"overlaps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"claimId": {
"type": "string"
},
"taskId": {
"type": "string"
},
"holder": {
"type": "string"
},
"agent": {
"type": "string"
},
"patterns": {
"type": "array",
"items": {
"type": "string"
}
},
"leaseExpiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"required": [
"claimId",
"taskId",
"holder",
"patterns",
"leaseExpiresAt"
],
"additionalProperties": false
}
},
"position": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"policy": {
"type": "string",
"enum": [
"serialise",
"refuse",
"allow"
]
},
"message": {
"type": "string",
"minLength": 1
},
"nextCommand": {
"type": [
"string",
"null"
]
},
"replay": {
"default": false,
"type": "boolean"
}
},
"required": [
"tenantId",
"projectId",
"decision",
"claim",
"overlaps",
"position",
"policy",
"message",
"nextCommand",
"replay"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"dryRun": {
"type": "boolean",
"const": true
},
"service": {
"type": "string"
},
"requests": {
"type": "array",
"items": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"path": {
"type": "string"
},
"body": {},
"note": {
"type": "string"
}
},
"required": [
"method",
"path"
],
"additionalProperties": false
}
},
"commands": {
"type": "array",
"items": {
"type": "string"
}
},
"writes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"action": {
"type": "string",
"enum": [
"write",
"append",
"delete"
]
},
"description": {
"type": "string"
}
},
"required": [
"path",
"action",
"description"
],
"additionalProperties": false
}
},
"notes": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"dryRun",
"requests",
"commands",
"writes",
"notes"
],
"additionalProperties": false
}
]
}See exit codes for the status the process returns.