mandrel 2.92.0 → 2.93.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/docs/configuration.md +35 -1
- package/.agents/scripts/lib/config/github.js +18 -0
- package/.agents/scripts/lib/config-resolver.js +2 -2
- package/.agents/scripts/lib/orchestration/lease-guard-shared.js +2 -2
- package/.agents/scripts/lib/orchestration/single-story-lease-guard.js +2 -1
- package/.agents/scripts/lib/orchestration/ticket-lease.js +69 -18
- package/docs/CHANGELOG.md +7 -0
- package/package.json +1 -1
|
@@ -506,7 +506,7 @@ number of keys.
|
|
|
506
506
|
| `delivery.quality.gates.maintainability.targetDirs` | `[".agents/scripts", "tests"]` | `["src"]` | Root scans the framework's own source tree; consumer template scans the conventional `src/`. |
|
|
507
507
|
| `delivery.quality.gates.crap.targetDirs` | `[".agents/scripts"]` | `["src"]` | Same reason as maintainability above. |
|
|
508
508
|
| `github.owner` / `.repo` / `.projectNumber` | Populated for `dsj1984/mandrel` | `[OWNER]` / `[REPO]` / `null` | Shared repo identifiers; placeholders in the template are replaced by `node .agents/scripts/bootstrap.js` (or by hand). |
|
|
509
|
-
| `github.operatorHandle` | Committed as the `@[USERNAME]` placeholder; each contributor overrides it in gitignored `.agentrc.local.json` | `@[USERNAME]` | Schema-required, but per-contributor: the committed placeholder resolves to null and the lease guards fail closed until you set your own handle locally (see [Per-machine local overrides](#per-machine-local-overrides)). |
|
|
509
|
+
| `github.operatorHandle` | Committed as the `@[USERNAME]` placeholder; each contributor overrides it in gitignored `.agentrc.local.json`, or with `GH_OPERATOR_HANDLE` where there is no overlay (cloud sessions) | `@[USERNAME]` | Schema-required, but per-contributor: the committed placeholder resolves to null and the lease guards fail closed until you set your own handle locally (see [Per-machine local overrides](#per-machine-local-overrides)). |
|
|
510
510
|
| `delivery.worktreeIsolation.nodeModulesStrategy` | `clone` | `clone` | Platform default on darwin/linux (copy-on-write clone of donor `node_modules`); Windows dogfood/template use `per-worktree`. |
|
|
511
511
|
|
|
512
512
|
When a consumer runs `/mandrel-update`, the
|
|
@@ -664,6 +664,39 @@ makes one developer the fallback identity for everyone else.
|
|
|
664
664
|
Otherwise a developer without an overlay silently seeds Story branches from,
|
|
665
665
|
and opens PRs against, `main`.
|
|
666
666
|
|
|
667
|
+
**Environment override.** `GH_OPERATOR_HANDLE` beats both files: when it is
|
|
668
|
+
set, the resolver uses it as `github.operatorHandle`, so precedence is
|
|
669
|
+
`GH_OPERATOR_HANDLE` → `.agentrc.local.json` → `.agentrc.json`. A bare login
|
|
670
|
+
gets its `@` prefix added, an empty value is ignored, and a `.env` entry
|
|
671
|
+
works too. The override only applies when the config already has a `github`
|
|
672
|
+
block. It is the same variable `bootstrap.js` reads for the handle.
|
|
673
|
+
|
|
674
|
+
#### Claude Code cloud environments
|
|
675
|
+
|
|
676
|
+
A cloud session clones the repo without the gitignored `.agentrc.local.json`,
|
|
677
|
+
so it has only the committed `@[USERNAME]` placeholder, or whatever handle
|
|
678
|
+
the team committed. Each person has their own cloud environment, so one
|
|
679
|
+
environment variable identifies one person:
|
|
680
|
+
|
|
681
|
+
- Add `GH_OPERATOR_HANDLE=your-github-login` to your cloud environment's
|
|
682
|
+
**Environment variables**. Use your own user login, never an Organization
|
|
683
|
+
or team. Don't write `.agentrc.local.json` from a setup script instead: the
|
|
684
|
+
script runs once, and later sessions start from a cached snapshot that
|
|
685
|
+
skips it.
|
|
686
|
+
- Leave `GITHUB_TOKEN` and `GH_TOKEN` unset. Every GitHub request from a
|
|
687
|
+
hosted cloud session goes through the Claude Code GitHub proxy, which
|
|
688
|
+
supplies your connected GitHub account's credential for REST calls.
|
|
689
|
+
|
|
690
|
+
The proxy answers **all** GitHub GraphQL with HTTP 403, even when you set
|
|
691
|
+
your own token. Projects v2 is GraphQL-only, so board Status never syncs
|
|
692
|
+
from a cloud session. Labels stay authoritative, and each skipped Status flip
|
|
693
|
+
is reported as a warning.
|
|
694
|
+
|
|
695
|
+
The handle has to be a user who can be assigned. GitHub's add-assignees
|
|
696
|
+
endpoint silently ignores a login it cannot assign, such as an Organization,
|
|
697
|
+
a team, or a user with no access to the repo. When that happens the Story
|
|
698
|
+
lease refuses with `not-assignable` rather than running a Story nobody holds.
|
|
699
|
+
|
|
667
700
|
### Adding a new top-level key (framework change)
|
|
668
701
|
|
|
669
702
|
This is a framework-level change, not a project-level one. The path is:
|
|
@@ -699,6 +732,7 @@ Claude Code web environment-variables UI for web sessions.
|
|
|
699
732
|
| Variable | Required? | Purpose |
|
|
700
733
|
| -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
701
734
|
| `GITHUB_TOKEN` | Yes\* | GitHub API auth for all ticketing operations. `GH_TOKEN` is accepted as a synonym. `gh auth token` is a fallback for local sessions. |
|
|
735
|
+
| `GH_OPERATOR_HANDLE` | No | Overrides `github.operatorHandle` (the lease owner and @mention handle). Set it where there is no `.agentrc.local.json`, such as a Claude Code cloud environment. See [Claude Code cloud environments](#claude-code-cloud-environments). |
|
|
702
736
|
| `NOTIFICATION_WEBHOOK_URL` | No | POST target for in-band Notifier events (Make.com / Slack / Discord). Unset disables the webhook channel; the GitHub comment channel still fires. |
|
|
703
737
|
| `WEBHOOK_SECRET` | No | Shared secret used to sign outbound webhook payloads as `X-Signature-256: sha256=<hmac>`. Unset ships unsigned payloads. |
|
|
704
738
|
| `MANDREL_ALLOW_TEST_WEBHOOKS` | No | Set to `1` to keep `NOTIFICATION_WEBHOOK_URL` live inside `npm test` / `npm run test:profile`. Default behaviour scrubs the env var from the test child so no URL resolves and the webhook never fires (see below). |
|
|
@@ -3,6 +3,8 @@
|
|
|
3
3
|
* `/agents-bootstrap-github` registers as required-status checks.
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
|
+
import { isObject } from '../json-utils.js';
|
|
7
|
+
|
|
6
8
|
/** Keep in sync with the job names in `.github/workflows/ci.yml`. */
|
|
7
9
|
export const DEFAULT_REQUIRED_CHECKS = Object.freeze([
|
|
8
10
|
Object.freeze({
|
|
@@ -107,3 +109,19 @@ export function getGitHub(config) {
|
|
|
107
109
|
},
|
|
108
110
|
};
|
|
109
111
|
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* `GH_OPERATOR_HANDLE` beats `github.operatorHandle` (cloud sessions have no
|
|
115
|
+
* `.agentrc.local.json`). Only an existing `github` block is touched: a lone
|
|
116
|
+
* handle would fail its required `owner` / `repo`.
|
|
117
|
+
*/
|
|
118
|
+
export function applyOperatorHandleEnv(read, env = process.env) {
|
|
119
|
+
const handle = String(env.GH_OPERATOR_HANDLE ?? '').trim();
|
|
120
|
+
const github = read.raw?.github;
|
|
121
|
+
if (handle.length === 0 || !isObject(github)) return read;
|
|
122
|
+
const operatorHandle = handle.startsWith('@') ? handle : `@${handle}`;
|
|
123
|
+
return {
|
|
124
|
+
...read,
|
|
125
|
+
raw: { ...read.raw, github: { ...github, operatorHandle } },
|
|
126
|
+
};
|
|
127
|
+
}
|
|
@@ -13,7 +13,7 @@ import {
|
|
|
13
13
|
import { getCiDelivery } from './config/ci.js';
|
|
14
14
|
import { getCommands } from './config/commands.js';
|
|
15
15
|
import { overlayRoot, resolveAgentrcRoot } from './config/git-roots.js';
|
|
16
|
-
import { getGitHub } from './config/github.js';
|
|
16
|
+
import { applyOperatorHandleEnv, getGitHub } from './config/github.js';
|
|
17
17
|
import { resolvePaths } from './config/paths.js';
|
|
18
18
|
import { validateOrchestrationConfig } from './config/validate-orchestration.js';
|
|
19
19
|
import { getWorktreeIsolation } from './config/worktree-isolation.js';
|
|
@@ -217,7 +217,7 @@ export function resolveConfig(opts) {
|
|
|
217
217
|
}
|
|
218
218
|
ensureEnvLoaded(root);
|
|
219
219
|
const resolved = finalizeConfig(
|
|
220
|
-
readRawConfig(injectedFs ?? fs, root),
|
|
220
|
+
applyOperatorHandleEnv(readRawConfig(injectedFs ?? fs, root)),
|
|
221
221
|
validate,
|
|
222
222
|
);
|
|
223
223
|
if (!injectedFs) _cacheByKey.set(key, resolved);
|
|
@@ -37,7 +37,7 @@ export function resolveOperatorFromCandidates({
|
|
|
37
37
|
|
|
38
38
|
/**
|
|
39
39
|
* Acquire a lease; a foreign claim without `steal` throws the surface's
|
|
40
|
-
* refusal.
|
|
40
|
+
* refusal; a result's own `message` wins.
|
|
41
41
|
*
|
|
42
42
|
* @param {object} opts
|
|
43
43
|
* @param {object} opts.provider
|
|
@@ -62,7 +62,7 @@ export async function acquireLeaseFailClosed({
|
|
|
62
62
|
steal,
|
|
63
63
|
});
|
|
64
64
|
if (!result.acquired) {
|
|
65
|
-
throw new Error(renderRefusal(result, ticketId));
|
|
65
|
+
throw new Error(result.message ?? renderRefusal(result, ticketId));
|
|
66
66
|
}
|
|
67
67
|
return result;
|
|
68
68
|
}
|
|
@@ -26,7 +26,8 @@ export function resolveOperator(config) {
|
|
|
26
26
|
'github.operatorHandle is unset or still the shipped `@[USERNAME]` ' +
|
|
27
27
|
'placeholder, so the standalone Story lease has no owner. Set your own ' +
|
|
28
28
|
'handle in .agentrc.local.json (e.g. { "github": { "operatorHandle": ' +
|
|
29
|
-
'"@your-login" } })
|
|
29
|
+
'"@your-login" } }), or GH_OPERATOR_HANDLE in the environment where ' +
|
|
30
|
+
'there is no .agentrc.local.json (cloud sessions), and re-run.',
|
|
30
31
|
});
|
|
31
32
|
}
|
|
32
33
|
|
|
@@ -42,6 +42,12 @@ export function currentOwner(assignees) {
|
|
|
42
42
|
return assignees[0];
|
|
43
43
|
}
|
|
44
44
|
|
|
45
|
+
/** GitHub returns the canonical-case login; the configured handle may differ. */
|
|
46
|
+
function sameLogin(a, b) {
|
|
47
|
+
if (typeof a !== 'string' || typeof b !== 'string') return false;
|
|
48
|
+
return a.toLowerCase() === b.toLowerCase();
|
|
49
|
+
}
|
|
50
|
+
|
|
45
51
|
/**
|
|
46
52
|
* @param {string} op
|
|
47
53
|
* @param {object} opts
|
|
@@ -74,9 +80,10 @@ function normaliseOpts(op, opts) {
|
|
|
74
80
|
* @param {boolean} [opts.steal=false] Transfer a foreign claim.
|
|
75
81
|
* @returns {Promise<{
|
|
76
82
|
* acquired: boolean,
|
|
77
|
-
* owner: string,
|
|
83
|
+
* owner: string|null,
|
|
78
84
|
* previousOwner: string|null,
|
|
79
|
-
* reason: 'unclaimed'|'already-held'|'stolen'|'held'|'lost-race',
|
|
85
|
+
* reason: 'unclaimed'|'already-held'|'stolen'|'held'|'lost-race'|'not-assignable',
|
|
86
|
+
* message?: string,
|
|
80
87
|
* }>}
|
|
81
88
|
*/
|
|
82
89
|
export async function acquireLease(opts) {
|
|
@@ -96,7 +103,7 @@ export async function acquireLease(opts) {
|
|
|
96
103
|
});
|
|
97
104
|
}
|
|
98
105
|
|
|
99
|
-
if (owner
|
|
106
|
+
if (sameLogin(owner, operator)) {
|
|
100
107
|
return {
|
|
101
108
|
acquired: true,
|
|
102
109
|
owner: operator,
|
|
@@ -123,18 +130,6 @@ export async function acquireLease(opts) {
|
|
|
123
130
|
});
|
|
124
131
|
}
|
|
125
132
|
|
|
126
|
-
/**
|
|
127
|
-
* Write, then re-read with `fresh: true`; on a foreign co-assignee, back out
|
|
128
|
-
* and report `lost-race` so the loser never builds the winner's worktree.
|
|
129
|
-
*
|
|
130
|
-
* @param {object} args
|
|
131
|
-
* @param {object} args.provider
|
|
132
|
-
* @param {number} args.ticketId
|
|
133
|
-
* @param {string} args.operator
|
|
134
|
-
* @param {string|null} args.previousOwner
|
|
135
|
-
* @param {string} args.reason Success reason when the claim holds.
|
|
136
|
-
* @returns {Promise<{ acquired: boolean, owner: string, previousOwner: string|null, reason: string }>}
|
|
137
|
-
*/
|
|
138
133
|
/**
|
|
139
134
|
* Additive for an unowned ticket — a replacing PATCH would evict a
|
|
140
135
|
* simultaneous claimer, hiding the collision verify keys on. Replacing only
|
|
@@ -149,6 +144,55 @@ function claimMutation(operator, previousOwner) {
|
|
|
149
144
|
return { assignees: [operator] };
|
|
150
145
|
}
|
|
151
146
|
|
|
147
|
+
function notAssignableMessage(operator, ticketId) {
|
|
148
|
+
return (
|
|
149
|
+
`ticket lease: GitHub silently dropped @${operator} as an assignee of ` +
|
|
150
|
+
`#${ticketId} — the handle is an Organization or team, or has no access ` +
|
|
151
|
+
'to the repo, so the lease cannot be held. Set github.operatorHandle (or ' +
|
|
152
|
+
'GH_OPERATOR_HANDLE in a cloud environment) to the GitHub user who runs ' +
|
|
153
|
+
'this session, and re-run.'
|
|
154
|
+
);
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** No foreign login: an empty re-read means GitHub dropped the operator. */
|
|
158
|
+
async function settleUncontested({
|
|
159
|
+
provider,
|
|
160
|
+
ticketId,
|
|
161
|
+
operator,
|
|
162
|
+
previousOwner,
|
|
163
|
+
reason,
|
|
164
|
+
assignees,
|
|
165
|
+
}) {
|
|
166
|
+
if (assignees.length > 0) {
|
|
167
|
+
return { acquired: true, owner: operator, previousOwner, reason };
|
|
168
|
+
}
|
|
169
|
+
if (previousOwner !== null) {
|
|
170
|
+
await provider
|
|
171
|
+
.updateTicket(ticketId, { assignees: [previousOwner] })
|
|
172
|
+
.catch(() => undefined);
|
|
173
|
+
}
|
|
174
|
+
return {
|
|
175
|
+
acquired: false,
|
|
176
|
+
owner: null,
|
|
177
|
+
previousOwner,
|
|
178
|
+
reason: 'not-assignable',
|
|
179
|
+
message: notAssignableMessage(operator, ticketId),
|
|
180
|
+
};
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Write, then re-read with `fresh: true`; on a foreign co-assignee, back out
|
|
185
|
+
* and report `lost-race` so the loser never builds the winner's worktree. An
|
|
186
|
+
* empty re-read is `not-assignable`: GitHub ignores an unassignable login.
|
|
187
|
+
*
|
|
188
|
+
* @param {object} args
|
|
189
|
+
* @param {object} args.provider
|
|
190
|
+
* @param {number} args.ticketId
|
|
191
|
+
* @param {string} args.operator
|
|
192
|
+
* @param {string|null} args.previousOwner
|
|
193
|
+
* @param {string} args.reason Success reason when the claim holds.
|
|
194
|
+
* @returns {Promise<{ acquired: boolean, owner: string|null, previousOwner: string|null, reason: string }>}
|
|
195
|
+
*/
|
|
152
196
|
async function claimAndVerify({
|
|
153
197
|
provider,
|
|
154
198
|
ticketId,
|
|
@@ -160,10 +204,17 @@ async function claimAndVerify({
|
|
|
160
204
|
|
|
161
205
|
const after = await provider.getTicket(ticketId, { fresh: true });
|
|
162
206
|
const assignees = Array.isArray(after?.assignees) ? after.assignees : [];
|
|
163
|
-
const foreign = assignees.filter((login) => login
|
|
207
|
+
const foreign = assignees.filter((login) => !sameLogin(login, operator));
|
|
164
208
|
|
|
165
209
|
if (foreign.length === 0) {
|
|
166
|
-
return {
|
|
210
|
+
return settleUncontested({
|
|
211
|
+
provider,
|
|
212
|
+
ticketId,
|
|
213
|
+
operator,
|
|
214
|
+
previousOwner,
|
|
215
|
+
reason,
|
|
216
|
+
assignees,
|
|
217
|
+
});
|
|
167
218
|
}
|
|
168
219
|
|
|
169
220
|
// Lost the race: leave the winner as sole assignee.
|
|
@@ -196,7 +247,7 @@ export async function releaseLease(opts) {
|
|
|
196
247
|
const ticket = await provider.getTicket(ticketId);
|
|
197
248
|
const owner = currentOwner(ticket?.assignees);
|
|
198
249
|
|
|
199
|
-
if (owner
|
|
250
|
+
if (!sameLogin(owner, operator)) {
|
|
200
251
|
return { released: false, owner, reason: 'not-held' };
|
|
201
252
|
}
|
|
202
253
|
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,13 @@ All notable changes to this project will be documented in this file.
|
|
|
15
15
|
-->
|
|
16
16
|
<!-- markdownlint-disable-file MD004 MD012 MD037 -->
|
|
17
17
|
|
|
18
|
+
## [2.93.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.92.0...mandrel-v2.93.0) (2026-10-19)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* fail the Story lease closed when GitHub silently drops the operator, and let cloud sessions supply the operator handle via GH_OPERATOR_HANDLE ([#5788](https://github.com/dsj1984/mandrel/issues/5788)) ([#5789](https://github.com/dsj1984/mandrel/issues/5789)) ([6acb901](https://github.com/dsj1984/mandrel/commit/6acb901cf34ef312f7eb18e0f3eb3053697f65f0))
|
|
24
|
+
|
|
18
25
|
## [2.92.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.91.0...mandrel-v2.92.0) (2026-10-18)
|
|
19
26
|
|
|
20
27
|
|
package/package.json
CHANGED