Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
fix: reconcile stale submodule checkouts without an agent
[._.]/ Adam Eivy5903d2555b6d
diff --git a/client/src/components/apps/tabs/RepositorySourcePanel.jsx b/client/src/components/apps/tabs/RepositorySourcePanel.jsxindex 6d6d391eac..e2831f9046 100644--- a/client/src/components/apps/tabs/RepositorySourcePanel.jsx+++ b/client/src/components/apps/tabs/RepositorySourcePanel.jsx@@ -106,7 +106,7 @@ function RepositoryCard({ source }) {{source.branch || 'detached'} @ {source.shortHead || 'unknown'}</code><span className={source.clean === false ? 'text-port-warning' : 'text-gray-500'}>- {source.clean === true ? 'clean checkout' : source.clean === false ? 'local changes' : 'worktree unknown'}+ {source.submodulesOnly ? 'submodules need updating' : source.clean === true ? 'clean checkout' : source.clean === false ? 'local changes' : 'worktree unknown'}</span></div>@@ -240,7 +240,8 @@ export default function RepositorySourcePanel({ appId, appName, onUpdated, refre|| (source.origin?.isFork && source.forkVsUpstream?.available === false)));const canUpdate = sources.every((source) => source.present) && status?.updatePullsAll;- const needsRecovery = hasLocalChanges || sources.some(source => source.clean === false || source.localVsOrigin?.state === 'diverged');+ const needsRecovery = (hasLocalChanges && !primary?.submodulesOnly)+ || sources.some(source => (source.clean === false && !source.submodulesOnly) || source.localVsOrigin?.state === 'diverged');const shouldOfferUpdate = status?.updateAvailable || remoteUnknown;const primaryLabel = forkNeedsSync? 'Sync fork & update app'diff --git a/client/src/components/apps/tabs/RepositorySourcePanel.test.jsx b/client/src/components/apps/tabs/RepositorySourcePanel.test.jsxindex 79a324ef74..e0c1527e17 100644--- a/client/src/components/apps/tabs/RepositorySourcePanel.test.jsx+++ b/client/src/components/apps/tabs/RepositorySourcePanel.test.jsx@@ -112,6 +112,19 @@ beforeEach(() => {afterEach(() => cleanup());describe('managed app repository sources', () => {+ it('updates stale submodules through the managed flow without a recovery agent', async () => {+ const status = canonicalStatus();+ status.sources = [{ ...status.sources[0], clean: false, submodulesOnly: true, localVsOrigin: { ahead: 0, behind: 0, state: 'current' } }];+ api.getAppRepositorySources.mockResolvedValue(status);+ render(<RepositorySourcePanel appId="portos-default" appName="PortOS" hasLocalChanges />);+ expect(await screen.findByText('submodules need updating')).toBeInTheDocument();+ expect(screen.queryByRole('button', { name: 'Resolve with agent' })).not.toBeInTheDocument();+ fireEvent.click(screen.getByRole('button', { name: 'Update app' }));+ fireEvent.click(within(screen.getByRole('dialog')).getByRole('button', { name: 'Update app' }));+ expect(useAppOperation().startUpdate).toHaveBeenCalledWith('portos-default', 'PortOS', { syncFork: false });+ expect(api.addCosTask).not.toHaveBeenCalled();+ });+it('explains and versions both independent checkouts', async () => {render(<RepositorySourcePanel appId="app-example" appName="Example App" />);diff --git a/docs/SELF_UPDATE.md b/docs/SELF_UPDATE.mdindex 29b2067763..02f8972edd 100644--- a/docs/SELF_UPDATE.md+++ b/docs/SELF_UPDATE.md@@ -190,12 +190,19 @@ non-conflicting local changes. The unattended readiness gate refuses until thecheckout is on the default branch and clean, because a stash nobody is toldabout reads as lost work.-Two remedies run without asking, because neither can destroy work:+These remedies run without asking, because they preserve local work:- **switch to the default branch** from a CLEAN feature branch (the commits stay on thebranch ref), and- **restore modified auto-generated lockfiles** (`npm install` rewrites them; the update- reinstalls anyway). Restored by explicit path, never `-- .`.+ reinstalls anyway). Restored by explicit path, never `-- .`, and+- **update stale submodule checkouts to their parent gitlinks** when the checkouts+ are clean ancestors of the pins, including recursively stale children. Staged+ gitlinks, edits, untracked files, ahead/divergent commits and unreadable state+ remain blockers. Repository Sources uses the same read-only classification to+ offer **Update app** for this drift, even when the parent is already current,+ rather than requiring **Resolve with agent**. The managed updater then runs+ its existing pinned submodule update; it never uses `--remote` or `--force`.Everything else — uncommitted work, a local commit not on origin, an interruptedrebase/merge, conflict markers — queues ONE high-priority CoS task (deduped on a constantdiff --git a/server/services/gitPinnedSubmodules.js b/server/services/gitPinnedSubmodules.jsnew file mode 100644index 0000000000..f9f59ac866--- /dev/null+++ b/server/services/gitPinnedSubmodules.js@@ -0,0 +1,39 @@+import { join } from 'path';+import { execGitSafe } from '../lib/execGit.js';++/**+ * Read-only classification of stale gitlinks. Only clean checkouts at an+ * ancestor of the parent's pin are mechanical repairs. Staged pointers, local+ * commits, edits, untracked files and unreadable state retain the dirty guard.+ * Porcelain v2's NUL framing preserves spaces and non-ASCII submodule paths.+ */+export async function inspectPinnedSubmoduleDrift(repoPath) {+ const status = await execGitSafe([+ 'status', '--porcelain=v2', '-z', '--ignore-submodules=none', '--untracked-files=all',+ ], repoPath, { env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } });+ if (status.exitCode !== 0) return { repairablePaths: [], onlyRepairable: false };++ const records = status.stdout.split('\0').filter(Boolean);+ const repairablePaths = [];+ for (const record of records) {+ // Ordinary, unstaged gitlink changes only. The index must still match HEAD.+ const match = /^1 \.M S[C.][M.][U.] 160000 160000 160000 ([a-f0-9]+) \1 (.+)$/s.exec(record);+ if (!match) continue;+ const [, pin, path] = match;+ const dir = join(repoPath, path);+ const head = await execGitSafe(['rev-parse', '--verify', 'HEAD'], dir);+ if (head.exitCode !== 0) continue;+ if (head.stdout.trim() !== pin) {+ const ancestor = await execGitSafe(['merge-base', '--is-ancestor', 'HEAD', pin], dir);+ if (ancestor.exitCode !== 0) continue;+ }+ const nested = await inspectPinnedSubmoduleDrift(dir);+ // A clean submodule has no records; recursively stale children are safe too.+ if (nested.clean || nested.onlyRepairable) repairablePaths.push(path);+ }+ return {+ clean: records.length === 0,+ repairablePaths,+ onlyRepairable: records.length > 0 && repairablePaths.length === records.length,+ };+}diff --git a/server/services/managedAppRepositories.js b/server/services/managedAppRepositories.jsindex d2a3a368c1..ab11b058e2 100644--- a/server/services/managedAppRepositories.js+++ b/server/services/managedAppRepositories.js@@ -7,6 +7,7 @@ import { execGitSafe, fetchOrigin, isFetchFresh, resolveForgeForRepo } from './gimport { execGh } from './github.js';import { forgeMissingScopesOf } from '../lib/forgeAccessErrors.js';import { forgeScopeMissingError } from './forgeScopeRefresh.js';+import { inspectPinnedSubmoduleDrift } from './gitPinnedSubmodules.js';const GH_TIMEOUT_MS = 60_000;@@ -174,6 +175,8 @@ async function inspectCheckout({ id, label, repoPath }) {const branch = branchName && branchName !== 'HEAD' ? branchName : null;const head = headResult.exitCode === 0 ? headResult.stdout.trim() : null;const clean = worktreeResult.exitCode === 0 ? worktreeResult.stdout.trim().length === 0 : null;+ const submodulesOnly = clean === false+ && (await inspectPinnedSubmoduleDrift(repoPath)).onlyRepairable;// Skip the network hop when this checkout's remote refs were already// refreshed inside the freshness window — the refs really are current, so// `fresh: true` stays truthful. This read used to be reachable only from the@@ -205,6 +208,7 @@ async function inspectCheckout({ id, label, repoPath }) {head,shortHead: head?.slice(0, 7) || null,clean,+ submodulesOnly,origin: {...topology.origin,url: topology.origin.originUrl,@@ -287,7 +291,7 @@ export async function getManagedAppRepositorySources(app) {// its own origin, plus a fork behind upstream that PortOS is allowed to// fast-forward. A fork PortOS can only read stays visible on the Git tab// but never claims an update is available.- updateAvailable: sources.some((source) => source.localVsOrigin?.behind > 0+ updateAvailable: sources.some((source) => source.submodulesOnly || source.localVsOrigin?.behind > 0|| (source.forkSyncable && (source.forkVsUpstream?.behind || 0) > 0)),updatePullsAll: true,updateRestartsApp: Array.isArray(app?.pm2ProcessNames) && app.pm2ProcessNames.length > 0,diff --git a/server/services/managedAppRepositories.test.js b/server/services/managedAppRepositories.test.jsindex a2c0b460fb..3c5a7438d8 100644--- a/server/services/managedAppRepositories.test.js+++ b/server/services/managedAppRepositories.test.js@@ -9,6 +9,7 @@ const mock = vi.hoisted(() => ({isFetchFresh: vi.fn(),resolveForgeForRepo: vi.fn(),execGh: vi.fn(),+ inspectPinnedSubmoduleDrift: vi.fn(),}));vi.mock('../lib/fileUtils.js', async (importOriginal) => ({@@ -27,6 +28,7 @@ vi.mock('./git.js', () => ({resolveForgeForRepo: mock.resolveForgeForRepo,}));vi.mock('./github.js', () => ({ execGh: mock.execGh }));+vi.mock('./gitPinnedSubmodules.js', () => ({ inspectPinnedSubmoduleDrift: mock.inspectPinnedSubmoduleDrift }));import {getManagedAppRepositorySources,@@ -52,6 +54,7 @@ const forkOrigin = {describe('managed app repository topology', () => {beforeEach(() => {vi.clearAllMocks();+ mock.inspectPinnedSubmoduleDrift.mockResolvedValue({ repairablePaths: [], onlyRepairable: false });mock.pathExists.mockResolvedValue(true);mock.getOriginInfo.mockResolvedValue(forkOrigin);mock.readRemoteUrl.mockResolvedValue(null);@@ -140,6 +143,19 @@ describe('managed app repository topology', () => {expect(mock.fetchOrigin).toHaveBeenCalledWith(REPO);});+ it('offers an update for stale submodules even when the parent is current', async () => {+ mock.execGit.mockImplementation(async (args) => {+ if (args[0] === 'status') return { exitCode: 0, stdout: ' M lib/dep\n' };+ if (args[0] === 'rev-list') return { exitCode: 0, stdout: '0\t0\n' };+ return { exitCode: 0, stdout: args.includes('--abbrev-ref') ? 'main\n' : `${'1'.repeat(40)}\n` };+ });+ mock.execGh.mockResolvedValue('{}');+ mock.getOriginInfo.mockResolvedValue({ ...forkOrigin, isUpstream: true });+ mock.inspectPinnedSubmoduleDrift.mockResolvedValue({ repairablePaths: ['lib/dep'], onlyRepairable: true });+ const result = await getManagedAppRepositorySources(app);+ expect(result).toMatchObject({ updateAvailable: true, sources: [{ clean: false, submodulesOnly: true }] });+ });+// The Eidoverse page runs this read on every visit, so an ungated fetch would// be a network hop per mount for refs that were just refreshed.it('skips the network fetch for refs already refreshed inside the freshness window', async () => {diff --git a/server/services/updateRepoReadiness.js b/server/services/updateRepoReadiness.jsindex 5f5e0a65e1..30a23f5366 100644--- a/server/services/updateRepoReadiness.js+++ b/server/services/updateRepoReadiness.js@@ -11,13 +11,15 @@** So the auto-updater refuses to start until the checkout is ON the default* branch and CLEAN, and this module is what decides that — plus what can be put- * right mechanically. Two remedies are safe enough to run unattended, because- * neither can destroy work:+ * right mechanically. These remedies are safe enough to run unattended, because+ * each preserves local work:** - checking out the default branch from a CLEAN feature branch (the commits* stay on the branch ref; nothing is discarded), and* - restoring modified auto-generated lockfiles (`npm install` rewrites them- * as a side effect, and the update reinstalls anyway).+ * as a side effect, and the update reinstalls anyway), and+ * - checking out pinned submodule commits when their current checkouts are+ * clean ancestors of those pins (including recursively stale children).** Everything else — uncommitted work, an unpushed commit, an interrupted* rebase/merge, conflict markers — is judgement no script should make on a@@ -33,6 +35,7 @@ import * as gitService from './git.js';import { countAheadBehind, detectOperationInProgress } from './repoSync.js';import { classifyWorktreeDirt } from './worktreeManager.js';import { PORTOS_APP_ID } from '../lib/appIdentity.js';+import { inspectPinnedSubmoduleDrift } from './gitPinnedSubmodules.js';/** First line of the repair task — stable so `addTask`'s dedup collapses reruns. */export const REPO_REPAIR_TASK_DESCRIPTION = 'Restore the PortOS checkout to a clean default branch so automatic updates can run';@@ -57,6 +60,7 @@ const REASON_LABELS = {const REPAIRABLE_LABELS = {'restore-lockfiles': 'auto-generated lockfiles need restoring','checkout-default': 'the checkout needs switching back to the default branch',+ 'update-submodules': 'submodule checkouts need updating to their pinned commits',};const describe = (code) => REASON_LABELS[code] || REPAIRABLE_LABELS[code] || code;@@ -99,7 +103,7 @@ export async function checkUpdateRepoReadiness({ repoPath, fetch = false } = {})return {repoPath: dir,branch: null, defaultBranch: null, interrupted: null, ahead: null, behind: null,- lockfilePaths: [],+ lockfilePaths: [], submodulePaths: [],...fields,reasons,repairable,@@ -146,7 +150,10 @@ export async function checkUpdateRepoReadiness({ repoPath, fetch = false } = {})return verdict({ defaultBranch, reasons: ['git-unreadable'] });}- const dirt = classifyWorktreeDirt(porcelain);+ const { repairablePaths: submodulePaths } = porcelain.trim()+ ? await inspectPinnedSubmoduleDrift(dir)+ : { repairablePaths: [] };+ const dirt = classifyWorktreeDirt(porcelain, { ignoredPaths: submodulePaths });const conflicted = porcelain.split('\n').some((line) => /^(DD|AU|UD|UA|DU|AA|UU) /.test(line));const detached = branch === 'HEAD';const onDefaultBranch = Boolean(defaultBranch) && branch === defaultBranch;@@ -166,6 +173,7 @@ export async function checkUpdateRepoReadiness({ repoPath, fetch = false } = {})if (conflicted) reasons.push('conflicted-files');if (dirt.hasRealChanges) reasons.push('uncommitted-changes');else if (!dirt.clean) repairable.push('restore-lockfiles');+ if (submodulePaths.length) repairable.push('update-submodules');if (detached) reasons.push('detached-head');else if (defaultBranch && !onDefaultBranch) {// A clean feature branch is a mechanical checkout away from ready; a dirty@@ -193,6 +201,7 @@ export async function checkUpdateRepoReadiness({ repoPath, fetch = false } = {})ahead,behind,lockfilePaths: dirt.lockfilePaths,+ submodulePaths,reasons,repairable,});@@ -212,9 +221,16 @@ export async function prepareUpdateRepo({ repoPath = PATHS.root } = {}) {// No fetch: the one caller reads with `fetch: true` before its idle gate and// then calls this, so a second network hop would only re-answer that read.const before = await checkUpdateRepoReadiness({ repoPath: dir, fetch: false });- if (before.ready || before.repairable.length === 0) return { verdict: before, actions: [] };+ if (before.ready || before.reasons.length || before.repairable.length === 0) return { verdict: before, actions: [] };const actions = [];+ if (before.repairable.includes('update-submodules')) {+ const sync = await execGitSafe(['submodule', 'sync', '--recursive'], dir);+ const update = sync.exitCode === 0 && await execGitSafe([+ 'submodule', 'update', '--init', '--recursive', '--checkout', '--', ...before.submodulePaths,+ ], dir, { timeout: 120000 });+ if (update.exitCode === 0) actions.push('updated submodules to their pinned commits');+ }if (before.repairable.includes('restore-lockfiles') && before.lockfilePaths.length) {// By explicit path, never `-- .`: the classifier proved these specific// paths are auto-generated lockfiles, and a pathspec of `.` would discarddiff --git a/server/services/updateRepoReadiness.test.js b/server/services/updateRepoReadiness.test.jsindex 7bad32cd8f..7d44730c49 100644--- a/server/services/updateRepoReadiness.test.js+++ b/server/services/updateRepoReadiness.test.js@@ -40,6 +40,24 @@ function makeRepo() {return clone;}+function makeStaleSubmodule() {+ const dependency = makeRepo();+ const repo = makeRepo();+ const path = 'lib/dép with spaces';+ git(repo, '-c', 'protocol.file.allow=always', 'submodule', 'add', dependency, path);+ git(repo, 'commit', '-am', 'add dependency');+ writeFileSync(join(dependency, 'README.md'), 'new dependency revision\n');+ git(dependency, 'commit', '-am', 'advance dependency');+ const pin = git(dependency, 'rev-parse', 'HEAD').trim();+ const checkout = join(repo, path);+ git(checkout, 'fetch', 'origin');+ // Same state as pulling a parent gitlink bump without updating submodules.+ git(repo, 'update-index', '--cacheinfo', `160000,${pin},${path}`);+ git(repo, 'commit', '-m', 'pin new dependency');+ git(repo, 'push', 'origin', 'main');+ return { repo, checkout, pin, path };+}+beforeEach(() => vi.restoreAllMocks());// Fail-fast cancellation can finish Vitest's wrapper while its Git subprocess// still owns the checkout. Drain those bodies before deleting the fixtures.@@ -50,6 +68,55 @@ afterAll(async () => {});describe('update repo readiness', () => {+ it('repairs a clean stale submodule without an agent, even with quoted paths', async () => {+ const { repo, checkout, pin, path } = makeStaleSubmodule();+ const before = await checkUpdateRepoReadiness({ repoPath: repo });+ expect(before).toMatchObject({ ready: false, needsAgent: false, reasons: [], repairable: ['update-submodules'], submodulePaths: [path] });+ const { verdict, actions } = await prepareUpdateRepo({ repoPath: repo });+ expect(verdict.ready).toBe(true);+ expect(actions).toEqual(['updated submodules to their pinned commits']);+ expect(git(checkout, 'rev-parse', 'HEAD').trim()).toBe(pin);+ });++ it('repairs a stale nested checkout without moving its already-pinned parent', async () => {+ const { repo: dependency, checkout, pin, path } = makeStaleSubmodule();+ const old = git(checkout, 'rev-parse', 'HEAD').trim();+ const repo = makeRepo();+ git(repo, '-c', 'protocol.file.allow=always', 'submodule', 'add', dependency, 'lib/outer');+ git(repo, '-c', 'protocol.file.allow=always', 'submodule', 'update', '--init', '--recursive');+ git(repo, 'commit', '-am', 'add nested dependency');+ git(repo, 'push', 'origin', 'main');+ const outer = join(repo, 'lib/outer');+ const nested = join(outer, path);+ const outerHead = git(outer, 'rev-parse', 'HEAD');+ git(nested, 'checkout', old);+ const { verdict } = await prepareUpdateRepo({ repoPath: repo });+ expect(verdict).toMatchObject({ ready: true, needsAgent: false });+ expect(git(nested, 'rev-parse', 'HEAD').trim()).toBe(pin);+ expect(git(outer, 'rev-parse', 'HEAD')).toBe(outerHead);+ });++ for (const kind of ['edit', 'untracked', 'staged-pointer', 'local-commit']) it(`preserves submodule ${kind} as real work`, async () => {+ const { repo, checkout, pin, path } = makeStaleSubmodule();+ if (kind === 'edit') writeFileSync(join(checkout, 'README.md'), 'local edit\n');+ if (kind === 'untracked') writeFileSync(join(checkout, 'local.txt'), 'local file\n');+ if (kind === 'staged-pointer') git(repo, 'add', path);+ if (kind === 'local-commit') {+ git(checkout, 'checkout', pin);+ git(checkout, 'config', 'user.email', '[email protected]');+ git(checkout, 'config', 'user.name', 'Example Tester');+ writeFileSync(join(checkout, 'README.md'), 'local commit\n');+ git(checkout, 'commit', '-am', 'unpublished dependency work');+ }+ const head = git(checkout, 'rev-parse', 'HEAD');+ const status = git(repo, 'status', '--porcelain');+ const { verdict, actions } = await prepareUpdateRepo({ repoPath: repo });+ expect(verdict).toMatchObject({ ready: false, needsAgent: true, reasons: ['uncommitted-changes'] });+ expect(actions).toEqual([]);+ expect(git(checkout, 'rev-parse', 'HEAD')).toBe(head);+ expect(git(repo, 'status', '--porcelain')).toBe(status);+ });+it('reports a clean checkout on the default branch as ready', async () => {const verdict = await checkUpdateRepoReadiness({ repoPath: makeRepo() });expect(verdict).toMatchObject({ ready: true, needsAgent: false, branch: 'main', defaultBranch: 'main', reasons: [], repairable: [] });